CDATA in howto

Do someone have objections against this patch which replace "Use CDATA here, see the bottom of this page" message from howto/working.xml? Jakub Vrana

Index: working.xml =================================================================== RCS file: /repository/phpdoc/howto/working.xml,v retrieving revision 1.40 diff -u -r1.40 working.xml --- working.xml 26 Jun 2004 15:55:27 -0000 1.40 +++ working.xml 19 Jul 2004 13:09:59 -0000 @@ -517,42 +517,41 @@ <example> <title>Function reference entry</title> <programlisting> -<![CDATA[ - <refentry id="function."> - <refnamediv> - <refname></refname> - <refpurpose></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>RETURNTYPE</type> <methodname>FUNCTIONNAME</methodname> - <methodparam><type>ARGTYPE1</type> <parameter>ARGNAME1</parameter></methodparam> - <methodparam><type>ARGTYPE2</type> <parameter>ARGNAME2</parameter></methodparam> - <!-- optional parameter --> - <methodparam choice='opt'> - <type>ARGTYPE3</type> <parameter>ARGNAME3</parameter> - </methodparam> - <!-- optional parameter with default value, choice='opt' is default in this case --> - <methodparam> - <type>ARGTYPE3</type> - <parameter>ARGNAME3</parameter> - <initializer>default-value</initializter> - </methodparam> - <!-- use <void /> if you have no parameters at all --> - </methodsynopsis> - <simpara> + &lt;refentry id="function."&gt; + &lt;refnamediv&gt; + &lt;refname&gt;&lt;/refname&gt; + &lt;refpurpose&gt;&lt;/refpurpose&gt; + &lt;/refnamediv&gt; + &lt;refsect1&gt; + &lt;title&gt;Description&lt;/title&gt; + &lt;methodsynopsis&gt; + &lt;type&gt;RETURNTYPE&lt;/type&gt; &lt;methodname&gt;FUNCTIONNAME&lt;/methodname&gt; + &lt;methodparam&gt;&lt;type&gt;ARGTYPE1&lt;/type&gt; &lt;parameter&gt;ARGNAME1&lt;/parameter&gt;&lt;/methodparam&gt; + &lt;methodparam&gt;&lt;type&gt;ARGTYPE2&lt;/type&gt; &lt;parameter&gt;ARGNAME2&lt;/parameter&gt;&lt;/methodparam&gt; + &lt;!-- optional parameter --&gt; + &lt;methodparam choice='opt'&gt; + &lt;type&gt;ARGTYPE3&lt;/type&gt; &lt;parameter&gt;ARGNAME3&lt;/parameter&gt; + &lt;/methodparam&gt; + &lt;!-- optional parameter with default value, choice='opt' is default in this case --&gt; + &lt;methodparam&gt; + &lt;type&gt;ARGTYPE3&lt;/type&gt; + &lt;parameter&gt;ARGNAME3&lt;/parameter&gt; + &lt;initializer&gt;default-value&lt;/initializter&gt; + &lt;/methodparam&gt; + &lt;!-- use &lt;void /&gt; if you have no parameters at all --&gt; + &lt;/methodsynopsis&gt; + &lt;simpara&gt; A simple paragraph that can not contain anything that requires fancy layout. - </simpara> - <para> + &lt;/simpara&gt; + &lt;para&gt; A normal paragraph that can contain lots of stuff. For example - <example> - <title>Code examples</title> - <programlisting role="php"> -// Use CDATA here, see the bottom of this page + &lt;example&gt; + &lt;title&gt;Code examples&lt;/title&gt; + &lt;programlisting role="php"&gt; +&lt;![CDATA[ -/* Use a role="php" only for PHP codes. See <screen> +/* Use a role="php" only for PHP codes. See &lt;screen&gt; * and other DocBook elements to express other * types of listings. Use other role attributes for * other type of programlistings, like: sql, httpd, ini, @@ -580,68 +579,61 @@ echo "No foo, no bar"; } -// Include end of CDATA, if you started with CDATA, see below - </programlisting> - </example> +]]&gt; + &lt;/programlisting&gt; + &lt;/example&gt; The text in a paragraph may continue after the example as well. Here is how to make lists: - <itemizedlist> - <listitem> - <simpara> + &lt;itemizedlist&gt; + &lt;listitem&gt; + &lt;simpara&gt; List items must contain a container element such as simpara or para (there are plenty of others too, see the DocBook reference for the listitem element). - </simpara> - </listitem> + &lt;/simpara&gt; + &lt;/listitem&gt; - <listitem> - <simpara> + &lt;listitem&gt; + &lt;simpara&gt; List items must contain simple paragraphs or paragraphs. - </simpara> - </listitem> - </itemizedlist> + &lt;/simpara&gt; + &lt;/listitem&gt; + &lt;/itemizedlist&gt; - <itemizedlist> - <listitem> - <para> + &lt;itemizedlist&gt; + &lt;listitem&gt; + &lt;para&gt; If you plan on making sub-lists, you must use para - <orderedlist> - <listitem><simpara> first list item</simpara></listitem> - <listitem><simpara> second list item</simpara></listitem> - </orderedlist> + &lt;orderedlist&gt; + &lt;listitem&gt;&lt;simpara&gt; first list item&lt;/simpara&gt;&lt;/listitem&gt; + &lt;listitem&gt;&lt;simpara&gt; second list item&lt;/simpara&gt;&lt;/listitem&gt; + &lt;/orderedlist&gt; You can also continue an ordered list you just left off - <orderedlist> - <listitem><simpara> third list item</simpara></listitem> - <listitem><simpara> fourth list item</simpara></listitem> - </orderedlist> - </para> - </listitem> - </itemizedlist> + &lt;orderedlist&gt; + &lt;listitem&gt;&lt;simpara&gt; third list item&lt;/simpara&gt;&lt;/listitem&gt; + &lt;listitem&gt;&lt;simpara&gt; fourth list item&lt;/simpara&gt;&lt;/listitem&gt; + &lt;/orderedlist&gt; + &lt;/para&gt; + &lt;/listitem&gt; + &lt;/itemizedlist&gt; - </para> - <simpara> + &lt;/para&gt; + &lt;simpara&gt; The documentation for a function should be wrapped up with a "See also" list like this: - </simpara> - <simpara> - See also <function>stripslashes</function> and - <function>quotemeta</function>. - </simpara> - </refsect1> - </refentry> -]]> + &lt;/simpara&gt; + &lt;simpara&gt; + See also &lt;function&gt;stripslashes&lt;/function&gt; and + &lt;function&gt;quotemeta&lt;/function&gt;. + &lt;/simpara&gt; + &lt;/refsect1&gt; + &lt;/refentry&gt; </programlisting> </example> </para> <para> - For technical reasons, the CDATA start tag: <literal>&lt;![CDATA[</literal> - and the CDATA end tag: <literal>]]&gt;</literal> is not included - in the listing above, just the place of them are marked. Use these - tags to be able to write clearer example codes. - </para> - <para> For parts we have no skeleton here, please look at existing files in the <filename>phpdoc</filename> CVS module. If you are not sure a specific file is good for a start, please ask on the <link linkend="chapter-maillist">phpdoc