Skip to content

Instantly share code, notes, and snippets.

@abathur

abathur/1_rst_for_sphinx Secret

Last active July 23, 2017 22:14
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save abathur/b3d3d25885303eb216e0ffa2d2604034 to your computer and use it in GitHub Desktop.
Save abathur/b3d3d25885303eb216e0ffa2d2604034 to your computer and use it in GitHub Desktop.
Download ZIP
Here's a pared-down example. The RST file (#1) goes into Sphinx, which generates a Doxygen-ready markdown page (#2). File #3 shows Doxygen's XML output and file #4 shows the corresponding value from the SQLite3 database. File #5 clips some relevant code from sqlite3gen and xmlgen. Files #6 and #7 show a complex memberdef in sql and xml formats.
Raw
1_rst_for_sphinx
.. overview:: Administrating an ldmud
:name: admin
Do all kinds of stuff to admin this ldmud.
.. subtopic:: Administration tasks
.. toctree::
:maxdepth: 1
:glob:
*
Raw
2_sphinx_generated_markdown_for_doxygen
Administrating an ldmud {#driver_admin_overview}
================================================
Do all kinds of stuff to admin this ldmud.
## Administration tasks #
- @subpage driver_admin_ed "ed"
- @subpage driver_admin_invocation "Starting LDMud"
Raw
3_doxygen_output.xml
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.8.14">
<compounddef id="d1/de5/driver_admin_overview" kind="page">
<compoundname>driver_admin_overview</compoundname>
<title>Administrating an ldmud</title>
<innerpage refid="da/d9d/driver_admin_ed">ed</innerpage>
<innerpage refid="d7/d6b/driver_admin_invocation">Starting LDMud</innerpage>
<detaileddescription>
<para>Do all kinds of stuff to admin this ldmud.</para>
<para><heading level="2">Administration tasks</heading></para>
<para>
<itemizedlist>
<listitem><para><ref refid="da/d9d/driver_admin_ed" kindref="compound">ed</ref></para></listitem>
<listitem><para><ref refid="d7/d6b/driver_admin_invocation" kindref="compound">Starting LDMud</ref></para></listitem>
</itemizedlist>
</para>
</detaileddescription>
</compounddef>
</doxygen>
Raw
4_doxygen_detaileddesc_before_output
sqlite> select detaileddescription from compounddef where name='driver_admin_overview';
'Do all kinds of stuff to admin this ldmud.
<h2>Administration tasks</h2>
- @subpage driver_admin_ed "ed"
- @subpage driver_admin_invocation "Starting LDMud"'
Raw
5_relevant_code.md

I'm inserting the page's description from generateSqlite3ForPage with:

bindTextParameter(compounddef_insert,":detaileddescription", pd->documentation(),FALSE);

Which I cribbed from what you used in generateSqlite3ForMember:

bindTextParameter(memberdef_insert,":detaileddescription",md->documentation(),FALSE);

FWIW, the equivalent section in generateXMLForPage passes this value directly through an XML converter:

writeXMLDocBlock(t,pd->docFile(),pd->docLine(),pd,0,pd->documentation());
Raw
6a_memberdef_example (naive)
sqlite> .mode line
sqlite> select * from memberdef where name='xml_generate';
rowid = 455
refid = 441
name = xml_generate
definition = string efun.xml_generate
type = string
argsstring = (mixed  *xml)
scope = efun
initializer =
bitfield =
read =
write =
prot = 3
static = 0
const = 0
explicit = 0
inline = 0
final = 0
sealed = 0
new = 0
optional = 0
required = 0
volatile = 0
virt = 0
mutable =
initonly =
attribute =
property =
readonly =
bound =
constrained =
transient =
maybevoid =
maybedefault =
maybeambiguous =
readable =
writable =
gettable =
privategettable =
protectedgettable =
settable =
privatesettable =
protectedsettable =
accessor =
addable =
removable =
raisable =
kind = 1
bodystart =
bodyend =
id_bodyfile =
id_file = 329
line = 76
column = 1
detaileddescription = The \p xml argument array must have the following structure:
It must contain tag arrays of three elements, with the following indices:
string <tt>XML_TAG_NAME</tt>
The name of the XML tag.
mapping <tt>XML_TAG_ATTRIBUTES</tt>
All attributes given to the XML tag as a mapping where the key is the attribute name and the value is its string value.
If the xml tag does not contain any attributes, this element is set to 0.
mixed * <tt>XML_TAG_CONTENTS</tt>
The contents of this xml tag as an array. This array may contain either strings, or arrays of sub-tags again with three elements. (see example)
If the xml tag does not contain anything, the element is set to 0.
In case the parameter does not follow these rules, errors are raised. The method returns a valid XML string otherwise.
The function is available only if the driver is compiled with Iksemel support. In that case, @ref driver_topics_predefined "__XML_DOM__" is defined.
@par Synopsis:
@code
string xml_generate(mixed *xml)
@endcode
@par Usage:
@parblock
For starters, here's how you can generate individual tags:
@code{c}
xml_generate(({ "abc", 0, 0 })); // "<abc/>"
xml_generate(({ "abc", ([ "xyz" : "cde" ]), 0 })); // "<abc xyz="cde"/>"
@endcode
Nested tags get complicated (and hard to read) quickly, so it's important to format them consistently:
@code{c}
mixed *xml = ({ "book"
, ([ "language" : "common" ])
, ({ ({ "title"
, 0
, ({ "This is a title" })
})
, ({ "chapter"
, 0
, ({ "This is a chapter" })
})
, ({ "chapter"
, 0
, ({ "We want "
, ({ "b"
, 0
, ({ "bold" })
})
, "here"
})
})
})
});
xml_generate(xml); // "<book language="common"><title>This is the title</title><chapter>This is a chapter</chapter><chapter>We want <b>bold</b> here.</chapter></book>"
@endcode
@endparblock
@par History:
@code
introduced (3.3.718)
@endcode
@see efun::xml_parse()
briefdescription = Converts the given \p xml array into an XML conformant string, if possible.
inbodydescription =
Raw
6b_memberdef_example (descriptions converted to XML)
sqlite> .mode line
sqlite> select * from memberdef where name='xml_generate';
rowid = 455
refid = 441
name = xml_generate
definition = string efun.xml_generate
type = string
argsstring = (mixed  *xml)
scope = efun
initializer =
bitfield =
read =
write =
prot = 3
static = 0
const = 0
explicit = 0
inline = 0
final = 0
sealed = 0
new = 0
optional = 0
required = 0
volatile = 0
virt = 0
mutable =
initonly =
attribute =
property =
readonly =
bound =
constrained =
transient =
maybevoid =
maybedefault =
maybeambiguous =
readable =
writable =
gettable =
privategettable =
protectedgettable =
settable =
privatesettable =
protectedsettable =
accessor =
addable =
removable =
raisable =
kind = 1
bodystart =
bodyend =
id_bodyfile =
id_file = 329
line = 76
column = 1
detaileddescription = <para>The <computeroutput>xml</computeroutput> argument array must have the following structure:</para><para>It must contain tag arrays of three elements, with the following indices:</para><para>string <computeroutput>XML_TAG_NAME</computeroutput> The name of the XML tag.</para><para>mapping <computeroutput>XML_TAG_ATTRIBUTES</computeroutput> All attributes given to the XML tag as a mapping where the key is the attribute name and the value is its string value.</para><para>If the xml tag does not contain any attributes, this element is set to 0.</para><para>mixed * <computeroutput>XML_TAG_CONTENTS</computeroutput> The contents of this xml tag as an array. This array may contain either strings, or arrays of sub-tags again with three elements. (see example)</para><para>If the xml tag does not contain anything, the element is set to 0.</para><para>In case the parameter does not follow these rules, errors are raised. The method returns a valid XML string otherwise.</para><para>The function is available only if the driver is compiled with Iksemel support. In that case, <ref refid="dc/d46/driver_topics_predefined" kindref="compound">__XML_DOM__</ref> is defined.</para><para><simplesect kind="par"><title>Synopsis:</title><para><programlisting><codeline><highlight class="normal">string<sp/>xml_generate(mixed *xml)</highlight></codeline>
</programlisting></para></simplesect>
<simplesect kind="par"><title>Usage:</title><para><parblock><para>For starters, here's how you can generate individual tags:</para><para><programlisting><codeline><highlight class="normal">xml_generate(({<sp/></highlight><highlight class="stringliteral">"abc"</highlight><highlight class="normal">,<sp/>0,<sp/>0<sp/>}));<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>"<abc/>"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">xml_generate(({<sp/></highlight><highlight class="stringliteral">"abc"</highlight><highlight class="normal">,<sp/>([<sp/></highlight><highlight class="stringliteral">"xyz"</highlight><highlight class="normal"><sp/>:<sp/></highlight><highlight class="stringliteral">"cde"</highlight><highlight class="normal"><sp/>]),<sp/>0<sp/>}));<sp/></highlight><highlight class="comment">//<sp/>"<abc<sp/>xyz="cde"/>"</highlight></codeline>
</programlisting> Nested tags get complicated (and hard to read) quickly, so it's important to format them consistently:</para><para><programlisting><codeline><highlight class="normal">mixed<sp/>*xml<sp/>=<sp/>({<sp/></highlight><highlight class="stringliteral">"book"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>([<sp/></highlight><highlight class="stringliteral">"language"</highlight><highlight class="normal"><sp/>:<sp/></highlight><highlight class="stringliteral">"common"</highlight><highlight class="normal"><sp/>])</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/>({<sp/></highlight><highlight class="stringliteral">"title"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"This<sp/>is<sp/>a<sp/>title"</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"chapter"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"This<sp/>is<sp/>a<sp/>chapter"</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"chapter"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"We<sp/>want<sp/>"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"b"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"bold"</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/></highlight><highlight class="stringliteral">"here"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>});</highlight></codeline>
<codeline><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">xml_generate(xml);<sp/></highlight><highlight class="comment">//<sp/>"<book<sp/>language="common"><title>This<sp/>is<sp/>the<sp/>title</title><chapter>This<sp/>is<sp/>a<sp/>chapter</chapter><chapter>We<sp/>want<sp/><b>bold</b><sp/>here.</chapter></book>"</highlight></codeline>
</programlisting></para><para></para></parblock></para></simplesect>
</para><para><simplesect kind="par"><title>History:</title><para><programlisting><codeline><highlight class="normal">introduced<sp/>(3.3.718)</highlight></codeline>
</programlisting></para></simplesect>
<simplesect kind="see"><para>efun::xml_parse() </para></simplesect>
</para>
briefdescription = <para>Converts the given <computeroutput>xml</computeroutput> array into an XML conformant string, if possible. </para>
inbodydescription =
Raw
7_memberdef_example.xml
<memberdef kind="function" id="dd/d40/classefun_1a522a28bfff281a6c0c47f26f75d056d4" prot="package" static="no" const="no" explicit="no" inline="no" virt="non-virtual">
<type>string</type>
<definition>string efun.xml_generate</definition>
<argsstring>(mixed  *xml)</argsstring>
<name>xml_generate</name>
<param>
<type>mixed  *</type>
<declname>xml</declname>
</param>
<briefdescription>
<para>Converts the given <computeroutput>xml</computeroutput> array into an XML conformant string, if possible. </para>
</briefdescription>
<detaileddescription>
<para>The <computeroutput>xml</computeroutput> argument array must have the following structure:</para>
<para>It must contain tag arrays of three elements, with the following indices:</para>
<para>string <computeroutput>XML_TAG_NAME</computeroutput> The name of the XML tag.</para>
<para>mapping <computeroutput>XML_TAG_ATTRIBUTES</computeroutput> All attributes given to the XML tag as a mapping where the key is the attribute name and the value is its string value.</para>
<para>If the xml tag does not contain any attributes, this element is set to 0.</para>
<para>mixed * <computeroutput>XML_TAG_CONTENTS</computeroutput> The contents of this xml tag as an array. This array may contain either strings, or arrays of sub-tags again with three elements. (see example)</para>
<para>If the xml tag does not contain anything, the element is set to 0.</para>
<para>In case the parameter does not follow these rules, errors are raised. The method returns a valid XML string otherwise.</para>
<para>The function is available only if the driver is compiled with Iksemel support. In that case, <ref refid="dc/d46/driver_topics_predefined" kindref="compound">__XML_DOM__</ref> is defined.</para>
<para>
<simplesect kind="par">
<title>Synopsis:</title>
<para>
<programlisting>
<codeline><highlight class="normal">string<sp/>xml_generate(mixed *xml)</highlight></codeline>
</programlisting>
</para>
</simplesect>
<simplesect kind="par">
<title>Usage:</title>
<para>
<parblock>
<para>For starters, here&apos;s how you can generate individual tags:</para>
<para>
<programlisting>
<codeline><highlight class="normal"><ref refid="dd/d40/classefun_1a522a28bfff281a6c0c47f26f75d056d4" kindref="member">xml_generate</ref>(({<sp/></highlight><highlight class="stringliteral">&quot;abc&quot;</highlight><highlight class="normal">,<sp/>0,<sp/>0<sp/>}));<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>&quot;&lt;abc/&gt;&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><ref refid="dd/d40/classefun_1a522a28bfff281a6c0c47f26f75d056d4" kindref="member">xml_generate</ref>(({<sp/></highlight><highlight class="stringliteral">&quot;abc&quot;</highlight><highlight class="normal">,<sp/>([<sp/></highlight><highlight class="stringliteral">&quot;xyz&quot;</highlight><highlight class="normal"><sp/>:<sp/></highlight><highlight class="stringliteral">&quot;cde&quot;</highlight><highlight class="normal"><sp/>]),<sp/>0<sp/>}));<sp/></highlight><highlight class="comment">//<sp/>&quot;&lt;abc<sp/>xyz=&quot;cde&quot;/&gt;&quot;</highlight></codeline>
</programlisting>
Nested tags get complicated (and hard to read) quickly, so it&apos;s important to format them consistently:
</para>
<para>
<programlisting>
<codeline><highlight class="normal">mixed<sp/>*xml<sp/>=<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;book&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>([<sp/></highlight><highlight class="stringliteral">&quot;language&quot;</highlight><highlight class="normal"><sp/>:<sp/></highlight><highlight class="stringliteral">&quot;common&quot;</highlight><highlight class="normal"><sp/>])</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;title&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;This<sp/>is<sp/>a<sp/>title&quot;</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;chapter&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;This<sp/>is<sp/>a<sp/>chapter&quot;</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;chapter&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;We<sp/>want<sp/>&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;b&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">&quot;bold&quot;</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/></highlight><highlight class="stringliteral">&quot;here&quot;</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>});</highlight></codeline>
<codeline><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><ref refid="dd/d40/classefun_1a522a28bfff281a6c0c47f26f75d056d4" kindref="member">xml_generate</ref>(xml);<sp/></highlight><highlight class="comment">//<sp/>&quot;&lt;book<sp/>language=&quot;common&quot;&gt;&lt;title&gt;This<sp/>is<sp/>the<sp/>title&lt;/title&gt;&lt;chapter&gt;This<sp/>is<sp/>a<sp/>chapter&lt;/chapter&gt;&lt;chapter&gt;We<sp/>want<sp/>&lt;b&gt;bold&lt;/b&gt;<sp/>here.&lt;/chapter&gt;&lt;/book&gt;&quot;</highlight></codeline>
</programlisting>
</para>
<para></para>
</parblock>
</para>
</simplesect>
</para>
<para>
<simplesect kind="par">
<title>History:</title>
<para>
<programlisting><codeline><highlight class="normal">introduced<sp/>(3.3.718)</highlight></codeline></programlisting>
</para>
</simplesect>
<simplesect kind="see"><para>efun::xml_parse() </para></simplesect>
</para>
</detaileddescription>
<inbodydescription></inbodydescription>
<location file="obj/doxy_guide/driver/efun/xml_generate.c" line="76" column="1"/>
</memberdef>
Raw
8a_detaileddescription (raw)
The \p xml argument array must have the following structure:
It must contain tag arrays of three elements, with the following indices:
string <tt>XML_TAG_NAME</tt>
The name of the XML tag.
mapping <tt>XML_TAG_ATTRIBUTES</tt>
All attributes given to the XML tag as a mapping where the key is the attribute name and the value is its string value.
If the xml tag does not contain any attributes, this element is set to 0.
mixed * <tt>XML_TAG_CONTENTS</tt>
The contents of this xml tag as an array. This array may contain either strings, or arrays of sub-tags again with three elements. (see example)
If the xml tag does not contain anything, the element is set to 0.
In case the parameter does not follow these rules, errors are raised. The method returns a valid XML string otherwise.
The function is available only if the driver is compiled with Iksemel support. In that case, @ref driver_topics_predefined "__XML_DOM__" is defined.
@par Synopsis:
@code
string xml_generate(mixed *xml)
@endcode
@par Usage:
@parblock
For starters, here's how you can generate individual tags:
@code{c}
xml_generate(({ "abc", 0, 0 })); // "<abc/>"
xml_generate(({ "abc", ([ "xyz" : "cde" ]), 0 })); // "<abc xyz="cde"/>"
@endcode
Nested tags get complicated (and hard to read) quickly, so it's important to format them consistently:
@code{c}
mixed *xml = ({ "book"
, ([ "language" : "common" ])
, ({ ({ "title"
, 0
, ({ "This is a title" })
})
, ({ "chapter"
, 0
, ({ "This is a chapter" })
})
, ({ "chapter"
, 0
, ({ "We want "
, ({ "b"
, 0
, ({ "bold" })
})
, "here"
})
})
})
});
xml_generate(xml); // "<book language="common"><title>This is the title</title><chapter>This is a chapter</chapter><chapter>We want <b>bold</b> here.</chapter></book>"
@endcode
@endparblock
@par History:
@code
introduced (3.3.718)
@endcode
@see efun::xml_parse()
Raw
8b_detaileddescription (converted to XML)
<para>The <computeroutput>xml</computeroutput> argument array must have the following structure:</para><para>It must contain tag arrays of three elements, with the following indices:</para><para>string <computeroutput>XML_TAG_NAME</computeroutput> The name of the XML tag.</para><para>mapping <computeroutput>XML_TAG_ATTRIBUTES</computeroutput> All attributes given to the XML tag as a mapping where the key is the attribute name and the value is its string value.</para><para>If the xml tag does not contain any attributes, this element is set to 0.</para><para>mixed * <computeroutput>XML_TAG_CONTENTS</computeroutput> The contents of this xml tag as an array. This array may contain either strings, or arrays of sub-tags again with three elements. (see example)</para><para>If the xml tag does not contain anything, the element is set to 0.</para><para>In case the parameter does not follow these rules, errors are raised. The method returns a valid XML string otherwise.</para><para>The function is available only if the driver is compiled with Iksemel support. In that case, <ref refid="dc/d46/driver_topics_predefined" kindref="compound">__XML_DOM__</ref> is defined.</para><para><simplesect kind="par"><title>Synopsis:</title><para><programlisting><codeline><highlight class="normal">string<sp/>xml_generate(mixed *xml)</highlight></codeline>
</programlisting></para></simplesect>
<simplesect kind="par"><title>Usage:</title><para><parblock><para>For starters, here's how you can generate individual tags:</para><para><programlisting><codeline><highlight class="normal">xml_generate(({<sp/></highlight><highlight class="stringliteral">"abc"</highlight><highlight class="normal">,<sp/>0,<sp/>0<sp/>}));<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>"<abc/>"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">xml_generate(({<sp/></highlight><highlight class="stringliteral">"abc"</highlight><highlight class="normal">,<sp/>([<sp/></highlight><highlight class="stringliteral">"xyz"</highlight><highlight class="normal"><sp/>:<sp/></highlight><highlight class="stringliteral">"cde"</highlight><highlight class="normal"><sp/>]),<sp/>0<sp/>}));<sp/></highlight><highlight class="comment">//<sp/>"<abc<sp/>xyz="cde"/>"</highlight></codeline>
</programlisting> Nested tags get complicated (and hard to read) quickly, so it's important to format them consistently:</para><para><programlisting><codeline><highlight class="normal">mixed<sp/>*xml<sp/>=<sp/>({<sp/></highlight><highlight class="stringliteral">"book"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>([<sp/></highlight><highlight class="stringliteral">"language"</highlight><highlight class="normal"><sp/>:<sp/></highlight><highlight class="stringliteral">"common"</highlight><highlight class="normal"><sp/>])</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/>({<sp/></highlight><highlight class="stringliteral">"title"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"This<sp/>is<sp/>a<sp/>title"</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"chapter"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"This<sp/>is<sp/>a<sp/>chapter"</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"chapter"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"We<sp/>want<sp/>"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"b"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>0</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/>({<sp/></highlight><highlight class="stringliteral">"bold"</highlight><highlight class="normal"><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>,<sp/></highlight><highlight class="stringliteral">"here"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>})</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>});</highlight></codeline>
<codeline><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">xml_generate(xml);<sp/></highlight><highlight class="comment">//<sp/>"<book<sp/>language="common"><title>This<sp/>is<sp/>the<sp/>title</title><chapter>This<sp/>is<sp/>a<sp/>chapter</chapter><chapter>We<sp/>want<sp/><b>bold</b><sp/>here.</chapter></book>"</highlight></codeline>
</programlisting></para><para></para></parblock></para></simplesect>
</para><para><simplesect kind="par"><title>History:</title><para><programlisting><codeline><highlight class="normal">introduced<sp/>(3.3.718)</highlight></codeline>
</programlisting></para></simplesect>
<simplesect kind="see"><para>efun::xml_parse() </para></simplesect>
</para>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment