<?xml version="1.0" encoding="iso-8859-1"?>

 <chapter id="chapter-files">
  <title>File Overview</title>

  <para>
   There are many files used to produce the several output
   formats, and to store the many text and information needed
   to generate the files. These are the most important ones,
   you should know about:
   <variablelist>
    <varlistentry>
     <term><filename>manual.xml</filename></term>
     <listitem>
      <simpara>
       The main file for the documentation. It is supposed
       to be only a "glue" between the other parts, containing
       only part titles and entity references to chapters.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>entities/chapters.ent</filename></term>
     <listitem>
      <simpara>
       Contains entity definitions for all chapters and
       appendices. Entities for the XML files are generated
       by configure, so <emphasis>you should not edit this file</emphasis>.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>entites/global.ent</filename></term>
     <listitem>
      <simpara>
       Global internal text entities for all the XML
       files. This is where all the external links,
       email addresses, and "macros" are stored.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>dsssl/*</filename></term>
     <listitem>
      <simpara>
       DSSSL style sheets we use to generate the available
       formats of the manual.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>xsl/*</filename></term>
     <listitem>
      <simpara>
       XSL style sheets to generate HTML, HTMLHelp and print
       output from the manual XML sources.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>your_language/language-defs.ent</filename></term>
     <listitem>
      <simpara>
       Contains local entities used by this language.
       Some common ones are the main part titles, but
       you should also put entities used only by this
       language's files here.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>your_language/language-snippets.ent</filename></term>
     <listitem>
      <simpara>
       Longer often used XML snippets translated to this
       language. Including common warnings, notes, etc.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </chapter>
 
 <chapter id="chapter-conventions">
  <title>Conventions</title>

  <para>
   When you work on <literal>phpdoc</literal> XML files,
   you should stick to these conventions, to ease the team
   work in the repository.
  </para>
  
  <para>
   <orderedlist>
    <listitem><simpara>
     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.
    </simpara></listitem>
    <listitem><simpara>
     Function reference IDs look like this (case should
     be consistent with the rest of the function naming
     standards, i.e. lowercase): <literal>function.mysql-connect</literal>.
     Please note that since underscores cannot be used
     in IDs, they should be replaced by minus signs (-).
    </simpara></listitem>
    <listitem><simpara>
     Function reference section IDs
     (<literal>&lt;reference id="..."></literal>) look
     like this: 'ref.category', for example: 'ref.ftp'.
    </simpara></listitem>
    <listitem><simpara>
     Add PHP example code programlistings always
     with a role attribute set to "php". Never add any
     other programlisting or PHP output with such
     a role. It is reserved for PHP source code only.
     This role is used to detect PHP code and highlight.
    </simpara></listitem>
    <listitem><simpara>
     The contents of examples with programlistings
     start on column 0 in the XML code.
    </simpara></listitem>
    <listitem><simpara>
     All examples use the <literal>&lt;?php ... ?&gt;</literal>
     form instead of <literal>&lt;? ... ?&gt;</literal>. Use
     <literal>&lt;![CDATA[ ... ]]&gt;</literal>
     for examples, since it eliminates the need to change 
     <literal>&lt;</literal> to <literal>&amp;lt;</literal>, etc.
     Examples look much better, and easily manageable.
    </simpara></listitem>
    <listitem><simpara>
     <!-- Indenting, bracketing and naming conventions in
     examples should adhere to the PEAR coding standards
     (it's in the manual). --> Deprecated aliases and syntax
     should not be used in examples.
    </simpara></listitem>
    <listitem><para>
     If an example uses arguments specific to a newer version of
     PHP, it is helpful to note this in the example:
     <programlisting role="php">
foo("bar", "baz"); // second argument was added in PHP 4.0.3
     </programlisting>
     New arguments are denoted in the main text of the
     entry using the form
     <programlisting>
<![CDATA[
<note>
 <simpara>
  The second parameter was added in PHP 4.0.3.
 </simpara>
</note>
]]>
      </programlisting>
    </para></listitem>
    <listitem><simpara>
     The language constants true, false and null
     should be written as <literal>&amp;true;</literal>,
     <literal>&amp;false;</literal> and
     <literal>&amp;null;</literal>.
    </simpara></listitem>
    <listitem><simpara>
     All English XML files should have a <literal>&lt;!--
     &dollar;Revision --></literal> comment as the second line
     after the <literal>&lt;?xml</literal> tag.
     This comment is not necessary for non-English files.
    </simpara></listitem>
    <listitem><simpara>
     Whitespace changes in the English tree should be
     prevented as much as possible: it is more important
     to keep a good change-history of real changes, because
     of the translations. If a whitespace change is
     <emphasis>really</emphasis> needed, do it at least
     in a separate commit, with a clear comment such as
     'WS fix' or 'Whitespace fix'.
    </simpara></listitem>
    <listitem><simpara>
     Never use tabs, not even in example program
     listings. XML should be indented with one
     space character for each level of indentation;
     example code uses four spaces <!-- (see PEAR standards) -->.
    </simpara></listitem>
    <listitem><simpara>
     Always use LF (Line Feed) for the only newline
     character in files, this is the Unix standard.
     Never use CR LF (Windows) or CR (Mac) even, when
     editing Windows specific files (such as
     *.bat). It eases the editing works.
    </simpara></listitem>
    <listitem>
     <simpara>
      In the docs, the types are denoted as:
      <literal>boolean</literal> (<literal>bool</literal>
      in prototypes), <literal>integer</literal>
      (<literal>int</literal> in prototypes),
      <literal>float</literal> (<emphasis>not
      double!</emphasis>), <literal>array</literal>,
      <literal>object</literal> (<emphasis>not class!</emphasis>),
      <literal>resource</literal> and <literal>null</literal>
      (all lowercase).
     </simpara>

     <simpara>
      In prototypes, you can also use <literal>mixed</literal>
      (various types), or <literal>number</literal> (either
      integer or float), or <literal>scalar</literal> (boolean,
      integer, float or string). A callback is denoted as
      <literal>mixed</literal> <footnote><simpara>Better
      suggestions? I don't really like it this way... not
      simply <literal>function</literal>, or something alike?
      --Jeroen</simpara></footnote>, since it can be either
      array or string.
     </simpara>
     
     <simpara>
      Do not use <literal>mixed</literal>, if the return
      value is of a certain (not boolen) type, and FALSE
      only on error. Provide the primary return type as
      the return type of the function, and write down in
      the explanation, that it returns FALSE on error.
      Use <literal>&amp;return.success;</literal> if the
      function returns TRUE on success, and FALSE on
      failure.
     </simpara>

     <simpara>
      If a function requires no arguments, use
      <literal>&lt;void/></literal> instead of 
      <literal>&lt;parameter>void&lt;/parameter></literal>,
      since the former is the correct DocBook XML tag.
     </simpara>
     
     <simpara>
      If a function has an undefined return-value, use
      the word <literal>void</literal>.
     </simpara>
    </listitem>
    <listitem><simpara>
     In a prototype, if there are multiple - really
     distinct - possibilities, simply make it two!
     See <literal>math.xml:min()</literal> for an example.
    </simpara></listitem>
    <listitem><simpara>
     Aliases: in refpurpose, put:
     <literal>Alias of &lt;function>realfunc&lt;/function></literal>.
     <emphasis>Do not specify a function prototype synopsis, and
     nothing but simply the text:</emphasis>
     <literal>This function is an alias of
     &lt;function>realfunc&lt;/function></literal>.
     This way, people can click to realfunc
     straight from the <literal>ref.foo</literal> page.
    </simpara></listitem>
   </orderedlist>
  </para>
 </chapter>

 <chapter id="chapter-what-to-document">
  <title>What to Document?</title>

  <para>
   <orderedlist>
    <listitem>
     <simpara>
      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. The
      <filename>aliases.xml</filename> appendix
      is the place to store aliases not documented elsewhere.
     </simpara>
       
     <simpara>
      For example <literal>mysql_db_name</literal> and
      <literal>mysql_dbname</literal> will be documented as the same
      function, with the latter being listed as an alias of the 
      former, while <literal>show_source</literal> and
      <literal>highlight_file</literal> 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.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Function names should be created, and documented, in lowercase
      format with an underscore separating the name components. Names
      without underscores are often only kept for backward
      compatibilty. Document the function named with underscores
      separating components, and mention the old one as an alias.
     </simpara>
     <note>
      <para>
       It is up to the PHP developers to give names to functions.
       A PHP documentation writer only uses the name provided to
       document the function. If you think that a function name is
       not appropriate, open a discussion on the
       <ulink url="&email.phpdev;">&email.phpdev;</ulink> list, by
       sending a mail to that address.
      </para>
     </note>
     <simpara>
      Good: <literal>mcrypt_enc_self_test</literal>,
      <literal>mysql_list_fields</literal>
     </simpara>
     <simpara>
      OK: <literal>mcrypt_module_get_algo_supported_key_sizes</literal>
      (could be <literal>mcrypt_mod_get_algo_sup_key_sizes</literal>?),
      <literal>get_html_translation_table</literal>
      (could be <literal>html_get_trans_table</literal>?)
     </simpara>
     <simpara>
      Bad: <literal>hw_GetObjectByQueryCollObj</literal>,
      <literal>pg_setclientencoding</literal>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      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. Also see
      the appendix <filename>aliases.xml</filename>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Short but complete 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.
      This example can hold code for other functions in the same chapter.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      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.
      <footnote><simpara>Noone complained about too much documentation
      in any section till now, so be brave to add longer explanations,
      and more than one example per function. :)</simpara></footnote>
     </simpara>
    </listitem>
   </orderedlist>
  </para>
 </chapter>
 
 <chapter id="chapter-skeletons">
  <title>Documentation Skeletons</title>

  <para>
   Below are some "skeletons" to copy and paste from when adding
   documentation.
  </para>
  <para>
   <example>
    <title>Function reference file in lang/functions/</title>
    <programlisting>
<![CDATA[
 <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
-->
]]>    
    </programlisting>
   </example>
  </para>

  <para>
   <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>
      <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>
]]>    
    </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 program code above, just the place of them are marked. Use these
   tags to be able to write clearer example codes.
  </para>
 </chapter>

 <chapter id="chapter-translation">
  <title>Information for Translators</title>

  <para>
   There are many active translations out there of the PHP
   documentation. Some lanaguages are being maintaned by
   a group of translators (eg. the German), some are one person
   projects (eg. the Japanese). There are quite many things for
   translators to know, though these are simple.
  </para>
  
  <sect1 id="translation-starting">
   <title>Staring a New Translation</title>
   <para>
    Starting a new language translation comes down to
    the following simple steps now.
    <itemizedlist>
     <listitem>
      <simpara>
       Consult the <link linkend="chapter-maillist">mailing
       list</link> to see if the translation is already in progress.
       If it is, disregard the following and coordinate with the
       other translators on the list.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <link linkend="cvs-account">Ask for a CVS account</link>.
       Mention, that you would like to start a new translation.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Create a sudirectory with the appropriate language
       code, or ask for help about how you can do this on the
       list. Appropriate languages codes can be found at
       <ulink url="&url.langcodes;">&url.langcodes;</ulink>.
       See the CVS chapter about <link linkend="cvs-add">how
       to add a file or directory</link>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Copy <filename>en/language-defs.ent</filename> and
       <filename>en/language-snippets.ent</filename> to the
       new directory and translate the contents of them.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Copy over files from the English tree and start to
       work on them, (do not check in untranslated files)
       and rerun configure each time you add a file.
       See the section about
       <link linkend="translation-revtrack">revision
       tracking</link> for help about
       how can you ease your work of tracking the English
       versions, and your languages versions.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Some important issues to consider when building
    a new translation:
    <itemizedlist>
     <listitem>
      <simpara>
       Can you set up and translate the whole manual
       yourself? If not, can you set up a team to
       work on the language?
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Have you made sure that your language or glyph
       (lettering, font, or characters) is supported
       by the DocBook stylesheets? Please ask on the
       <link linkend="chapter-maillist">mailing list</link>
       if you don't know.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>

  <sect1 id="translation-joining">
   <title>Joining To a Translation</title>
   <para>
    If you see that a manual for your language is set
    up, and you would like to join the group, please
    ask on the <link linkend="chapter-maillist">mailing
    list</link> about who is reponsible to manage that
    translation.
   </para>
   <para>
    If you are new to the PHP project, and you have no
    CVS account, you need to <link linkend="cvs-account">request
    one account</link>, before you can join the work. Although
    there are some translations where just a few people have
    CVS accounts, and they are responsible for comitting the
    other's works, this may not be ideal.
   </para>
  </sect1>

  <sect1 id="translation-practical">
   <title>Practical Advice for Translators</title>
   <para>
    Here is some advice we collected for translators:
    <itemizedlist>
     <listitem>
      <simpara>
       Only commit translated files in your language's directory.
       The build process is responsible for adding English
       files in place of the files you have not committed.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Use a system to coordinate with the translators
       in your language. Currently we have two systems
       used paralelly, the Translators files and the
       Revision comments. See the section about
       <link linkend="translation-revtrack">revision
       tracking</link> to learn more about this subject.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       While translating, you will find errors in the
       English manual. If you are sure about an error,
       that should be corrected, please correct the
       found errors yourself. If you are not sure,
       whether you found an error or not, please ask
       on the <link linkend="chapter-maillist">mailing
       list</link>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       We have the global entities used all over
       the manuals in <filename>global.ent</filename>.
       If you would like to define entities only used
       in your language, an ideal place for these
       is <filename>your_language/language-defs.ent</filename>.
       See <filename>hu/language-defs.ent</filename> for
       an example.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Do not translate entity names, such as &amp;true;
       or &amp;return.success;. These are there to be
       replaced by their relevant text. Translating them
       only cause errors. Similarly do not translate any
       tags (eg. &lt;computeroutput&gt;) to your language.
       The contents of comments (eg. the bottom of every
       file) are not to be translated.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Always make sure, that the modifications you
       made to your language's files, are correct.
       You may introduce illegal characters. Please
       always do a <link linkend="chapter-validating">make
       test</link> before commiting. Introducing an
       error in your languages manual can stop the
       automatic updates online until you correct the
       error.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       If your manual is online at the PHP mirror
       sites, you can check out the building log
       of the several downloadable formats and
       online manuals by downloading the
       <filename>build.log.gz</filename> file of your
       language. For the German translation, this file is:
       <ulink url="&url.buildlog.de;">&url.buildlog.de;</ulink>.
       Substitute "de" with your own language code to
       see the information about your manual. This file
       provides you information about the build times,
       and errors (if there were any). If the manual is
       not updated online, it is a good idea, to look
       into this file and see what was the error.
      </simpara>
      <simpara>
       Note, that some browsers like MSIE may
       uncompress the gz file on the fly and show
       the log file in the browser window as text.
       This also means, that if you download this gz
       file with MSIE, the downloaded file name will
       still hold the gz extension, while it will be
       a simple text log file.       
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>
  
  <sect1 id="translation-revtrack">
   <title>Revision Tracking</title>
   <para>
    Working on the translations is not just translating
    an English file and commiting the results. Much of
    the work is needed to update the already translated
    ones, to get in sync with the content of the English
    files. To follow the modifications in the English
    tree, you should subscribe to the
    <link linkend="chapter-maillist">mailing list</link>,
    or read the archives. If you never update your files,
    the translations can get useless.
   </para>
   <para>
    Updating a foreign language file can get difficult,
    as you may not know when and who translated that file,
    so you may not know where you should look for the
    updates needed. We have two (plus one) system for tracking
    the revisions and modification dates of the files in
    <literal>phpdoc</literal>.
   </para>

   <sect2 id="translation-revcheck-translators">
    <title>The Translators Files</title>
    
    <para>
     Nearly all translations are currently using a
     <filename>Translators</filename> file just in the
     root of their translation's tree. This file
     can contain the names, email addresses, and CVS
     user names of the contributors of this translation,
     and the list of files translated.
    </para>
    
    <para>
     Along with the XML file names, associations between
     translators and files, revision numbers, and status
     information can also be stored. One sample Translators
     file, for the imaginary xx language can look like this:
     <programlisting>
=============================================================================
CVS User  Name                 Contact email address
=============================================================================
joedoe    Joe Doe              joe@hotmail.com
jane      Jane Smith           jsmith@yahoo.com
...

=============================================================================
Filename                    Translator      Revision
=============================================================================
bookinfo.xml                jane            1.16
language-defs.ent           jane            1.7
language-snippets.ent       joedoe          1.8
preface.xml
------- appendices ----------------------------------------------------------
aliases.xml                 joedoe          working
debugger.xml
escaping.xml
history.xml                 jane            1.2
...
     </programlisting>
     In this example you can see the listing of translators, and
     the first few lines of the list of files. Here you can store
     the assignment of the file, the revision number (what English
     file this translation was based on), and if there is no revision
     number yet, a status (eg. working).
    </para>
    <para>
     When it is time to update a file (eg. bookinfo.xml jumped to
     1.20 as time passed), you can ask for a diff between 1.16 and
     1.20, and you'll see what modifications you need to port to
     the translated file. You can ask for diffs by using the diff
     CVS command, or using the web interface at <ulink url="&url.php.cvs;">
     &url.php.cvs;</ulink>. The web interface can generate really
     visual diffs, so you can easily spot what needs to be deleted,
     added and modified where.
    </para>
    <para>
     If you choose this method, do not forget to update the revision
     numbers stored in the <filename>Translators</filename> as
     you update files in your language's tree.
    </para>
   </sect2>

   <sect2 id="translation-revcheck-comments">
    <title>The Revision Comments</title>
    
    <para>
     There is another way of tracking versions instead of
     using the method descibed above. You can decide yourself,
     as this is the better method for you or not. Some
     languages use the Revision comments and Translators files
     paralelly, some use only one of these. It is better to
     decide, and not to use two systems, as things can get
     messy this way.
    </para>
    <para>
     Instead of storing all responsibilities in a central file,
     the revision comment system stores them in the files they
     provide information about. Consider the <link
     linkend="translation-revcheck-translators">Translators</link>
     example above. Now we spread the revision and association
     informations in the files mentioned there. Let's see what
     would be in the header of the <filename>bookinfo.xml</filename>
     file in this case:
     <programlisting>
&lt;!-- EN-Revision: 1.16 Maintainer: jane Status: ready --&gt;
     </programlisting>
    </para>
    <para>
     You can see we loose no information here, but we can also
     add some other status information in the case it is needed
     (eg. "partial" for incomplete translations). This revision
     comment system is basically about storing the information in
     the XML files, and not in a central place.
    </para>
    <para>
     Currently all the three information is needed. Maintainer
     is intended to be a CVS user name, or some nickname without
     a space, status can be anything without a space. Note, that
     this header is not updated by CVS (as
     <literal>$Revision</literal> is updated automatically). This
     is only updated when you edit the contents of the comment.
    </para>
    <para>
     You may see this as a good thing, but using these comments,
     you loose the quick look on the whole list of your
     files. No, you do not loose this, but get much more! If
     you would like to build a list similar to the
     <filename>Translators</filename> file given above, you
     can go to the scripts directory and run:
     <programlisting>
./revcheck.php xx > revcheck.html
     </programlisting>
     Here <literal>xx</literal> is the imaginary language code.
     After running this script you'll get a
     <filename>revcheck.html</filename> in the same directory.
     You can find revision comparisions and links to diffs
     for all the files in this language. You can also
     add a furter restriction parameter, the maintainer name,
     so the script will only list the files corresponding to
     the given maintaner. This HTML file gives you much more
     than the <filename>Translators</filename> file. See it
     yourself for example with the Italian translation (code:
     it). You can also easily run this with <literal>make
     revcheck</literal> in the phpdoc root directory, in 
     case you issued a 
     <literal>./configure --with-lang=xx</literal> before.
    </para>
    
    <para>
     As this system gets popular in many translation groups,
     the automatic build process also generates a
     <filename>revcheck.html</filename> at the end of the
     build process for that language. It is available online
     in the languages manual directory, as
     <filename>build.log.gz</filename> is also there.
     See the Italian translation's file online:
     <ulink url="&url.revcheck.it;">&url.revcheck.it;</ulink>.
    </para>
    
    <para>
     There are some extensions introduced for this script,
     as need arised to port all contents of the
     <filename>Translators</filename> files to be available
     in this generated HTML page. This is why the
     <filename>translation.xml</filename> files are
     introduced. Here comes a simple
     <filename>translation.xml</filename> file
     for the imaginary xx language (contents ported from
     the <filename>Translators</filename> example above):
     <programlisting>
<![CDATA[
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE translation SYSTEM "../dtds/translation.dtd">

<translation>

 <intro>
  This is some introductory text for the xx language translators
  about who is the manager of the translation, and where to find
  more information. This paragraph is printed on the top of the
  generated revcheck.html page.
 </intro>

 <translators>
  <person name="Joe Doe"     email="joe@hotmail.com"  nick="joedoe" cvs="yes"/>
  <person name="Jane Smith"  email="jsmith@yahoo.com" nick="jane"   cvs="yes"/>
  <person name="Joe Forever" email="joe@forever.net"  nick="joefo"  cvs="no"/>
 </translators>
 
 <work-in-progress>
  <file name="appendices/aliases.xml" person="joedoe" type="working"/>
  <file name="functions/dbx.xml"      person="joefo"  type="working"/>
 </work-in-progress>

</translation>
]]>
     </programlisting>
     As you can see, this file can store exactly the same content,
     as a <filename>Translators</filename> file. What is new in this
     file, is that you can add users without a CVS account, and can
     assign ready documents or work-in-progress files to them. The
     biggest advantage of using this addon is that all this information
     is used to generate dynamic tables of translators and files in
     the <filename>revcheck.html</filename> file. All translators
     are linked to from the individual files they are assigned
     to, and there is a nice table showing the state of files for
     all the translators.
    </para>
    
    <para>
     There are two optional parameters you can add to a &lt;file&gt;,
     if you would like to record it: the <literal>date</literal>
     and <literal>revision</literal>. Date is assumed to be the date
     when the work was started, revision is the checked out revision
     of the English file used to start the work (denoted as
     CO-Revision in the generated table).
    </para>
    
    <para>
     Another addon to this system is just to give credit to all people
     worked on one file, and not just the current maintainer. To achive
     this goal, we added the credit comments. One credit comment in
     eg. <filename>history.xml</filename> may look like this (in case
     Joe Doe translated the file initally, but Jane followed him to
     be the maintainer):
     <programlisting>
&lt;!-- CREDITS: joedoe --&gt;
     </programlisting>
     The credits comment can contain a comma separated list. These
     comments only affect the display of the translators table in
     <filename>revcheck.html</filename>.
    </para>
   </sect2>

   <sect2 id="translation-revcheck-status">
    <title>The Online Status Script</title>
    
    <para>
     Rasmus Lerdorf developed on online status checking script.
     This script is most useful for files without revision comments,
     so if you use the Revision comments, use the specific script
     <link linkend="translation-revcheck-comments">mentioned above</link>.
    </para>
    <para>
     You can access the script at: <ulink url="&url.status;">&url.status;</ulink>.
     Visiting this page, you need to wait for some time to generate,
     as it builds a whole table of file and dates information about
     all translations. If you would like to restrict the table to only
     one translation, you can provide the <literal>?l=langcode</literal>
     URL parameter, so to view the Hungarian status, visit:
     <ulink url="&url.status.hu;">&url.status.hu;</ulink>.
    </para>
    <para>
     This script tries to decide whether a file is up to date or not
     from the last modification date. The results are not correct if
     you modify your languages file, fixing typos, as this script thinks
     you modified the file to get in sync with the English one, and will
     mark your file as up to date. Although this script can help some
     to track files without <link linkend="translation-revcheck-comments">revision
     comments</link>, if you use revision comments, you can get more
     accurate results than this script, and much more than that.
    </para>
   </sect2>
  </sect1>
 </chapter>

 <chapter id="chapter-maillist">
  <title>The phpdoc, php-doc-chm and php-notes Mailing Lists</title>
  
  <para>
   The XML content of <literal>phpdoc</literal> files is
   updated from day to day, and on busy days from hour to
   hour. To follow the updates in the English tree and
   any other language's tree and also participate in
   the discussions, it is highly recommended that you
   subscribe to the <email>&email.phpdoc;</email> mailing
   list. You can subscribe by sending a blank mail to
   <ulink url="&url.docsubscribe;">&url.docsubscribe;</ulink>.
   Similarly you can unsubscribe by sending a blank mail to
   <ulink url="&url.docunsubscribe;">&url.docunsubscribe;</ulink>.
   There is a web interface for these tasks at <ulink
   url="&url.maillists;">&url.maillists;</ulink>.
  </para>
  <para>
   Currently this list receives messages from the following senders:
   <itemizedlist>
    <listitem>
     <simpara>
      Members of the list: discussion threads about anything
      related to the phpdoc team.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The CVS server: diffs about every small modification
      in the English or any languages XML files, or other
      support files placed in the <literal>phpdoc</literal>
      repository.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The PHP bug tracking system: bug follow ups classified
      as "Documentation Problem" in the bug system.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Other senders: the posting to list is not restricted,
      so people not on the list can also post messages. This
      way we got bug reports and suggestions by plain mails
      on the list.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      SPAM: this is not a common piece of mail, thanks to
      our SPAM protection system.
     </simpara>
    </listitem>
   </itemizedlist>
   This long list of mail types can be scaring for someone,
   who can't process the many mails posted to the list. For
   this reason the team is thinking about separating the list
   to language specific list, so commits in the foreign
   languages trees won't posted to the main list. Although
   this is just a plan now.
  </para>
  <para>
   If you can't handle the load of this mailing list in
   your mailbox, you can read the messages three ways:
   <itemizedlist>
    <listitem>
     <simpara>
      On the web, in the archives at
      <ulink url="&url.listarchive;">&url.listarchive;</ulink>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      With a news reader at
      <ulink url="&url.listnews;">&url.listnews;</ulink>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      On the web, with the experimental news interface at
      <ulink url="&url.listnewshttp;">&url.listnewshttp;</ulink>
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   You can also set up some filter on incoming mail messages,
   so you get the most important things, and can participate
   in the discussions while do not need to read big diff
   messages. To ease the filtering the commit messages coming
   from the CVS server, that are larger then 8kb, are put
   into attachements. You can always see the commit message
   and file list in the body, but the diff is in an
   attachement.
  </para>
  <para>
   As the Windows HTMLHelp Edition of the manual is evolving
   in an incredible way, there is a separate mailing list for
   CHM related discussions and announcements. You can subscribe
   to this mailing list at <ulink
   url="&url.maillists;">&url.maillists;</ulink> using the
   web interface.
  </para>
  <para>
   There is also a mailing list named <literal>php-notes</literal>.
   You can access it the same way as the <literal>phpdoc</literal>
   list (just substitute <literal>phpdoc</literal> with
   <literal>php-notes</literal>). This list is the place where
   all the manual notes are posted. You may consider subscribing
   to this mailing list if you would like to help manage the notes.
  </para>
 </chapter>

 <chapter id="chapter-misc">
  <title>Miscellaneous Notes</title>

  <para>
   Misc. notes that don't need a full section. (stuff like
   http://www.zend.com/phpfunc/, etc.)
  </para>
 </chapter>

<!-- 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:"howto.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
-->