Chapter 8. Documentation Skeletons

Below are some "skeletons" to copy and paste from when adding documentation.

Example 8-1. Function reference file in lang/functions/

<reference>
  <title></title>
  <titleabbrev></titleabbrev>

 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

Example 8-2. Function reference entry

<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>
      <methodparam choice='opt'><type>ARGTYPE3</type> <parameter>ARGNAME3</parameter></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>
     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

/* Use a role="php" only for PHP codes. See <screen>
 * and other DocBook elements to express other
 * types of listings.
 */

/* Do all indentation with spaces, not tabs, just to be sure.
 * Don't try pushing the code to the right by adding spaces in
 * front, this is the style sheet's job.
 */
 
// a function example
function some_code($foo)
{
    // use four spaces of indentation
}

// an example of bracket usage and spacing, always use
// brackets, even when they are physically not needed
if (some_code($foo) == "foo") {
    echo "foo";
} elseif (some_code($foo) == "bar") {
    echo "bar";
} else {
    echo "No foo, no bar";
}

// Include end of CDATA, if you started with CDATA, see below
      </programlisting>
     </example>

     The text in a paragraph may continue after the example as well.
     Here is how to make lists:

     <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>

      <listitem>
       <simpara>
        List items must contain simple paragraphs or paragraphs.
       </simpara>
      </listitem>
     </itemizedlist>
     
     <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>
        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>

    </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>

For technical reasons, the CDATA start tag: <![CDATA[ and the CDATA end tag: ]]> is not included in the program code above, just the place of them are marked. Use these tags to be able to write clearer example codes.