READ THIS FIRST

    This directory contains source files and a setup for converting
    PHP's XML documentation into presentation formats like HTML and
    RTF.  You should not have to bother with this unless you are
    writing documentation yourself, or if you simply are curious about
    how the XML stuff works.

    If you just want to read the documentation, download it from
    http://www.php.net/docs.php

INTRODUCTION

    All the documentation is written with XML using the DocBook 3.0
    DTD. See:
    
        http://www.oasis-open.org/docbook/
    
    If you want to produce something viewable, you need Jade and
    Norman Walsh's modular DocBook stylesheets. See:
    
        http://www.jclark.com/jade/
        http://nwalsh.com/docbook/dsssl/
    
    There is a DTD reference for DocBook at
    
        http://www.ora.com/homepages/dtdparse/docbook/3.0/

    RPMs with the necessary software can be found at
    ftp://sourceware.cygnus.com/pub/docbook-tools/

    Most major linux distributions should already come with 
    ready to use packages.

CONVENTIONS

    1.  Insert ID attributes in all major section tags such
        as part, chapter, sect1 etc.  The HTML stylesheet will
        name the HTML files after these IDs.

    2.  Function reference IDs look like this (case does not matter):
        `function.imageloadfont'.  Please note that underscores cannot
        be used in IDs, they should be replaced by minus signs (-).

    3.  Function section titles (<reference><title>...</>...) look
        like this: `ref.category'.

    4.  The contents of examples with program listings start on column
        0 in the XML code.

    5. All examples use the <?php ... ?> form instead of <? ... ?>

    6. The <refsect1><title> tag was set incorrectly when
       converting from sgml-tools.  For normal function reference, the
       text "Description" should be used instead of the function name.

WHAT TO DOCUMENT
   
    1. Only major functions should be documented, functions which are
       deprecated variants may be mentioned, but should not be
       documented as separate functions. They instead should be
       referenced in the parent function as an alias. Functions which
       have completely different names, however, should be documented as
       separate entries, for ease of reference.
       
       Examples:
       mysql_db_name and mysql_dbname will be documented as the same
       function, with the latter being listed as an alias of the 
       former.
       
       show_source and highlight_file will be documented as two
       different functions (one as an alias), as the names are
       completely different, and one name is not likely to be found
       if looking for the name of the other.
    
    2. Function names should be created, and documented, in lower-case
       format with an underscore separating the name components. If
       there are several variants, use the one with the least amount
       of components.
       
       Good:
       'mcrypt_enc_self_test'
       'mysql_list_fields'
       
       Ok:
       'mcrypt_module_get_algo_supported_key_sizes'
       (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
       'get_html_translation_table'
       (could be 'html_get_trans_table'?) 

       Bad:
       'hw_GetObjectByQueryCollObj'
       'pg_setclientencoding'
       
    3. Functions which are kept only for backwards compatibility should
       be listed under their current parent names, and not documented as
       separate functions. Backwards compatible functions and
       documentation for them should be maintained as long as the code
       can be reasonably kept as part of the PHP codebase.
    
    4. Short code examples are much more desirable than long ones.
       If a function is extremely complex, a suitable place to put
       a longer example is in the chapter introduction.
       
    5. Brevity is appreciated. Long winded descriptions of each and
       every function are not appropriate for the reference sections.
       Using the errata comments as guidelines, it's easier to tell when
       more documentation is needed, as well as the inverse, when too
       much documentation in one section has increased confusion. 
    
SKELETONS

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

FUNCTION REFERENCE FILE IN 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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

END OF SKELETON


FUNCTION REFERENCE ENTRY:

  <refentry id="function.">
   <refnamediv>
    <refname></refname>
    <refpurpose></refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>RETURNTYPE <function>FUNCTIONNAME</function></funcdef>
      <paramdef>ARGTYPE1 <parameter>ARGNAME1</parameter></paramdef>
      <paramdef>ARGTYPE2 <parameter>ARGNAME2</parameter></paramdef>
      <paramdef>ARGTYPE3 <parameter><optional>ARGNAME3</optional></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     A simple paragraph that can not contain anything that requires
     fancy layout.

    <para>
     A normal paragraph that can contain lots of stuff.  For example
     <example>
      <title>Code examples</title>
      <programlisting>
/* 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.
 */
function some_code($foo)
{
    /* we all agree that four spaces of indentation is good? */
}
</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.

      <listitem><simpara>
        List items must contain simple paragraphs or paragraphs.

      <listitem><para>
        If you plan on making sub-lists, you must use para 

        <orderedlist>
         <listitem><simpara> first list item
         <listitem><simpara> second list item
        </orderedlist>

        You can also continue an ordered list you just left off

        <orderedlist>
         <listitem><simpara> third list item
         <listitem><simpara> fourth list item
        </orderedlist>

    <simpara>
     The documentation for a function should be wrapped up with
     a "See also" list like this:

    <simpara>
     See also <function>stripslashes</function> and
     <function>quotemeta</function>.

   </refsect1>
  </refentry>


END OF SKELETON

Stig Bakken <stig@php.net>