---------------------------------------------------------------------------   
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, look at:
        http://www.php.net/docs

---------------------------------------------------------------------------   
HOW TO WRITE PHPDOC FILES
---------------------------------------------------------------------------   
    If you are interested in information about how to
    set up the tools needed, how to work with CVS and
    DocBook on Linux or Windows, or what conventions you
    should follow when writing phpdoc files, please refer
    to the PHP Documentation HOWTO.
     
    You can read the HOWTO online at:
        http://php.net/dochowto
        
    Or download a tar.gz containing the whole contents:
        http://php.net/get/dochowto
    
    If you are already working with the phpdoc module,
    then you can find its XML source in the howto directory
    of the module, and build it yourself with:

        make howto
        cd howto/html/

---------------------------------------------------------------------------   
FILE LOCATIONS
---------------------------------------------------------------------------
    The old archived phpdoc files still live in the phpdoc module 
    for historical purposes, do NOT edit them.  For example:
    
    OLD:  All function definitions and reference info for extensions
          used to be stored in single xml files:

          {lang}/functions/{extension}.xml
    	  
    NOW:  They are now separate and the format looks like so:
            
          {lang}/reference/{extension}/functions/{function}.xml
                                      /configure.xml
                                      /constants.xml
                                      /ini.xml
                                      /reference.xml

                                      /functions.xml (autogenerated)

---------------------------------------------------------------------------
QUICK REFERENCE
---------------------------------------------------------------------------
  [[edits]]
    
    a) Make the change.  Use spaces not tabs.  Be sure to carefully 
       watch your whitespace!

    b) Look at your unified diff, make sure it looks right and that 
       whitespace changes aren't mixed in:
	 
           cvs diff -u path/to/file.xml
	 
    c) Make sure no errors are present, so at the command line in your 
       phpdoc source directory run:

           make test
	   
       Always 'make test' before commit!

    d) Commit your changes
      
           cvs commit path/to/file.xml
	 
    Read the HOWTO for more information.  After reading the HOWTO,
    email the phpdoc mailing list (phpdoc@lists.php.net) with questions 
    and concerns.

  [[new functions]]
  
    a) Copy an existing xml file or use a skeleton from the HOWTO.
       Rename and place it into the appropriate directory.

    b) Edit.  Be sure no leftover text exists.  No tabs either.

    c) Now test locally before commit by first running
       ./configure along with 'make test' as usual.
    
    d) cvs add path/to/yourfile.xml
    
    e) cvs commit path/to/yourfile.xml
  
    Note that ./configure adds your function to functions.xml as
    this allows 'make test' to test your new function.  Also, note 
    that version numbers are taken care of elsewhere (don't worry 
    about them)

   [[some popular tags and entities]]
   
    <filename>          filenames
    <constant>          constants
    <varname>           variables
    <parameter>         a function's parameter/argument
    <function>          functions, this links to function pages or bolds if 
                        already on the function's page.  it also adds ().
    
    <literal>           teletype/mono-space font <tt>
    <emphasis>          italics
    <example>           see HOWTO, includes many other tags.
    <link>              internal manual links
                        <link linkend="language.variables">variables</link>
    
    <url>               external links via global.ent
                        <ulink url="&spec.cookies;">mmm cookies</ulink>                        
    
    <type>              types, this links to the given types manual
                        page: <type>object</type> -> php.net/types.object
    

    &return.success;    see: language-snippets.ent
    &true;              <constant>TRUE</constant>
    &false;             <constant>FALSE</constant>
    &php.ini;           <filename>php.ini</filename>

    Be sure to check out globals.ent and language-snippets.ent for
    more information for entities and urls.

---------------------------------------------------------------------------
