Well, it depends on from where you copy&paste the example. Now you
copy&paste the same from the browser or the file source. If you apply
this change, it will be better in the browser, but will not be useable
from the source (actually with some more search&replace it will work).
The idea behind the current solution is to be able to copy from the
source. I am not against changing this, just pointing out the reasons :)
Goba
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>
+ <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>
A simple paragraph that can not contain anything that requires
fancy layout.
- </simpara>
- <para>
+ </simpara>
+ <para>
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
+ <example>
+ <title>Code examples</title>
+ <programlisting role="php">
+<![CDATA[
-/* Use a role="php" only for PHP codes. See <screen>
+/* Use a role="php" only for PHP codes. See <screen>
* 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>
+]]>
+ </programlisting>
+ </example>
The text in a paragraph may continue after the example as well.
Here is how to make lists:
- <itemizedlist>
- <listitem>
- <simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>
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>
+ </simpara>
+ </listitem>
- <listitem>
- <simpara>
+ <listitem>
+ <simpara>
List items must contain simple paragraphs or paragraphs.
- </simpara>
- </listitem>
- </itemizedlist>
+ </simpara>
+ </listitem>
+ </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
+ <itemizedlist>
+ <listitem>
+ <para>
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>
+ <orderedlist>
+ <listitem><simpara> first list item</simpara></listitem>
+ <listitem><simpara> second list item</simpara></listitem>
+ </orderedlist>
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>
+ <orderedlist>
+ <listitem><simpara> third list item</simpara></listitem>
+ <listitem><simpara> fourth list item</simpara></listitem>
+ </orderedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
- </para>
- <simpara>
+ </para>
+ <simpara>
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>
-]]>
+ </simpara>
+ <simpara>
+ See also <function>stripslashes</function> and
+ <function>quotemeta</function>.
+ </simpara>
+ </refsect1>
+ </refentry>
</programlisting>
</example>
</para>
<para>
- For technical reasons, the CDATA start tag: <literal><![CDATA[</literal>
- and the CDATA end tag: <literal>]]></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
