# File Overview

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:

`manual.xml`

- 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. It is generated from `manual.xml.in` when you run configure.

`entities/file-entities.ent`

- Contains entity definitions for all files. Entities for the XML files are generated by configure, so you should not edit this file.

`entities/global.ent`

- Global internal text entities for all the XML files. This is where all the external links, email addresses, and "macros" are stored.

`dsssl/*`

- DSSSL style sheets we use to generate the available formats of the manual.

`xsl/*`

- XSL style sheets to generate HTML, phpweb, HTMLHelp and print output from the manual XML sources.

`your_language/language-defs.ent`

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

`your_language/language-snippets.ent`

- Longer often used XML snippets translated to this language. Including common warnings, notes, etc.

`your_language/translation.xml`

- This file is used to store all central translation info, like a small intro text for translators, the persons list, and the files under translation / modification. This file is not present in the English tree.

`your_language/some_directory`

- The PHP Manual XML source is organized into directories. The biggest part is the extension reference, which is stored in the `reference` directory of your language.

## Conventions

When you work on `phpdoc` XML files, you should stick to these conventions, to ease the team work in the module.

1. Please read and follow the Nomenclature and Style Guide.

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

3. Function reference IDs look like this (case should be consistent with the rest of the function naming standards, i.e. lowercase): `function.mysql-connect`. Please note that since underscores cannot be used in IDs, they should be replaced by minus signs (-).

4. Methods reference IDs look like this: `domcharacterdata.deletedata` (for `DOMCharacterData::deleteData`. Leading underscores are removed, e.g. `PDO::__construct` has ID `pdo.construct`.

5. Function reference section IDs (`<reference xml:id="...">`) look like this: 'ref.category', for example: 'ref.ftp'.

6. 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 it.

7. The contents of examples with programlistings start on column 0 in the XML code. Indenting, bracketing and naming conventions in examples should adhere to the PEAR coding standards.

8. All examples use the `<?php ... ?>` form instead of `<? ... ?>`. Use `<![CDATA[ ... ]]>` for examples, since it eliminates the need to change `<` to `&lt;`, etc. Examples look much better, and easily manageable.

9. Deprecated aliases and syntax should not be used in examples.

10. Use the <note> when a function is not available in some special cases, or when the parameter list of a function has changed, but not for every little thing like mentioning that the function also can accept 'foo' instead of 'bar' as value to a parameter. Use notes with care.

    Make sure note elements are always children of the main element in a file, unless the note belongs to a specific item in the text, such as an example:

          <para>
           <example>
            <title />
            <programlisting/>
            <para>
             The output is:
            </para>
            <screen />
            <note>
             <simpara>
              This example only works on Unices.
             </simpara>
            </note>
           </example>
          </para>

    If there is something dangerous to document such as the `chroot`, or when something can be seen as a weirdness in the language such as weird auto-conversion of types, use the <caution> element.

    The <tip> can be used in cases where you might want to document a performance issue.

11. For comments in example, use `//` for single line comments (preferable above the lines of code the comment comments on), and use `/* .. */` for multiline comments:

        <programlisting role="php">
        // This line execute foo
        foo();

        /* The next few lines also execute foo, but in a
         * weird way */
        $var = 'foo';
        $var();
        </programlisting>

12. If an example uses arguments specific to a newer version of PHP, it is helpful to note this in the example:

        foo("bar", "baz"); // second argument was added in PHP 4.0.3

    New arguments are denoted in the main text of the entry using the form:

        <note>
         <simpara>
          The second parameter was added in PHP 4.0.3.
         </simpara>
        </note>

13. The language constants true, false and null should be written as `&true;`, `&false;` and `&null;`. There are other shortcuts, such as `&php.ini;`. These are stored in `global.ent`.

14. All English XML files should have a `<!-- $Revision$ -->` comment as the second line after the `<?xml` tag. This comment is not necessary for non-English files.

15. 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 really needed, do it at least in a separate commit, with a clear comment such as 'WS fix' or 'Whitespace fix'.

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

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

18. In the docs, the types are denoted as: `boolean` (`bool` in prototypes), `integer` (`int` in prototypes), `float` (not double!), `array`, `object` (not class!), `resource` and `null` (all lowercase). For objects different from `stdClass`, use the class name instead of `object`.

    In prototypes, you can also use `mixed` (various types), or `number` (either integer or float). A callback is denoted as `callable`.

    Do not use `mixed`, if the return value is of a certain (not boolean) 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 `&return.success;` if the function returns TRUE on success, and FALSE on failure.

    If a function requires no arguments, use `<void/>` instead of `<parameter>void</parameter>`, since the former is the correct DocBook XML tag.

    If a function has an undefined return-value, use the word `void`.

19. In a prototype, if there are multiple - really distinct - possibilities, simply make it two! See `en/reference/math/functions/min.xml` for an example.

20. Aliases: in refpurpose, put: `Alias of <function>realfunc</function>`. Do not specify a function prototype synopsis, and nothing but simply the text: `This function is an alias of <function>realfunc</function>`. This way, people can go to realfunc straight from the `ref.foo` page.

21. Document examples always with the following structure:

        <para>
         <example>
          <title />
          <programlisting>
        <![CDATA[
        <?php
        echo "foo\n";
        ?>
        ]]>
          </programlisting>
          <para>
           The output is:
          </para>
          <screen>
        <![CDATA[
        foo
        ]]>
          </screen>
         </example>
        </para>

## 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. The `aliases.xml` appendix is the place to store aliases not documented elsewhere.

   For example `mysql_db_name` and `mysql_dbname` will be documented as the same function, with the latter being listed as an alias of the former, while `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 lowercase format with an underscore separating the name components. Names without underscores are often only kept for backward compatibility. Document the function named with underscores separating components, and mention the old one as an alias.

   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 &email.internals; list, by sending a mail to that address.

   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. Also see the appendix `aliases.xml`.

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

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.

   No one complained about too much documentation in any section until now, so be brave to add longer explanations, and more than one example per function. :)

## Documentation Skeletons

Below are some "skeletons" to copy and paste from when adding documentation. All of these files should end with a line ending ("\n"). If a section does not exist (like a ChangeLog), simply don't include that refsect1 inside the documentation.

The documentation skeletons below are new, from around August of 2004.

## A function skeleton (`func-name.xml`)

    <?xml version="1.0" encoding="utf-8"?>
    <!-- $Revision$ -->
    <refentry xml:id="function.func-name" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
     <refnamediv>
      <refname>func_name</refname>
      <refpurpose>The func_name purpose</refpurpose>
     </refnamediv>
     <refsect1 role="description">
      &reftitle.description;
      <methodsynopsis>
       <!-- Example: All functions have this -->
       <type>thereturned type</type><methodname>func_name</methodname>
       <!-- Example: Required parameter -->
       <methodparam><type>int</type><parameter>firstparameter</parameter></methodparam>
       <!-- Example: Optional parameter -->
       <methodparam choice="opt"><type>string</type><parameter>secondparameter</parameter></methodparam>
       <!-- Example: Passed by reference -->
       <methodparam><type>bool</type><parameter role="reference">thirdparameter</parameter></methodparam>
       <!-- Example: If no methodparams exist (void), use this -->
       <void />
      </methodsynopsis>
      <para>
       The functions description goes here.
      </para>
     </refsect1>

     <refsect1 role="parameters">
      &reftitle.parameters;
      <para>
       <variablelist>
        <varlistentry>
         <term><parameter>firstparameter</parameter></term>
         <listitem>
          <para>
           Its description
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>secondparameter</parameter></term>
         <listitem>
          <para>
           Its description
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </refsect1>

     <refsect1 role="returnvalues">
      &reftitle.returnvalues;
      <para>
       What this function returns, first on success, then failure.  If simply
       true on success and false on failure, just use &return.success; here.
      </para>
     </refsect1>

     <refsect1 role="errors">
      &reftitle.errors;
      <para>
       When does this function issue E_* level errors, or throw exceptions?
      </para>
     </refsect1>

     <refsect1 role="unicode">
      &reftitle.unicode;
      <para>
       Unicode information (introduced in PHP 6) goes here.
      </para>
     </refsect1>

     <refsect1 role="changelog">
      &reftitle.changelog;
      <para>
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>&Version;</entry>
           <entry>&Description;</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>Write the PHP version here (Ex. PHP 5.2.0)</entry>
           <entry>
            Describe the change
           </entry>
          </row>
          <row>
           <entry>...</entry>
           <entry>
            ...
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </refsect1>

     <refsect1 role="examples">
      &reftitle.examples;
      <para>
       <example>
        <title><function>functionname</function> example</title>
        <programlisting role="php">
    <![CDATA[
    <?php
    if ($anexample === true) {
        echo 'Use the PEAR Coding standards';
    }
    if ($thereisoutput === 'and it is multiple lines') {
        echo 'Use a screen like we did below';
    }
    ?>
    ]]>
        </programlisting>
        &example.outputs.similar;
        <screen>
    <![CDATA[
    Use the PEAR Coding standards
    Use a screen like we did below
    ]]>
        </screen>
       </example>
      </para>
     </refsect1>

     <refsect1 role="notes">
      &reftitle.notes;
      <para>
       Any notes that don't fit anywhere else should go here.
       90% of the time, notes, warnings or cautions are better placed in the
       parameters section. Consider that before using this section!
      </para>
     </refsect1>

     <refsect1 role="seealso">
      &reftitle.seealso;
      <para>
       <simplelist>
        <member><function>somefunc</function></member>
        <member><function>another_func</function></member>
        <member>The <link linkend="something">something appendix</link></member>
       </simplelist>
      </para>
     </refsect1>
    </refentry>

    <!-- 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:"~/.phpdoc/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
    -->

## A `reference.xml` skeleton

    <?xml version="1.0" encoding="utf-8"?>
    <!-- $Revision$ -->
    <!-- Purpose: xx -->
    <!-- Membership: xx -->
    <!-- State: xx -->
    <reference xml:id="ref.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
     <title>Extname &Functions;</title>
     <titleabbrev>Extname</titleabbrev>

     <partintro>
      <section xml:id="extname.intro">
       &reftitle.intro;
       <para>

       </para>
      </section>

      <section xml:id="extname.requirements">
       &reftitle.required;
       <para>

       </para>
      </section>

      &reference.extname.configure;
      &reference.extname.ini;

      <section xml:id="extname.resources">
       &reftitle.resources;
       &no.resource;
      </section>

      &reference.extname.constants;
     </partintro>

     &reference.extname.functions;

    </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:"~/.phpdoc/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
    -->

There are several PECL related entities inside of `language-snippets.ent`. Be sure to include information on where Windows users can find the DLL.

## A `configure.xml` skeleton

    <?xml version="1.0" encoding="utf-8"?>
    <!-- $Revision$ -->
    <section xml:id="extname.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
     &reftitle.install;
     <para>
      To enable extname support, configure PHP with
      <option role="configure">theconfigoption</option>
     </para>
     <para>
      Windows users ...
     </para>
    </section>

    <!-- 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:"~/.phpdoc/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
    -->

## A `constants.xml` skeleton

    <?xml version="1.0" encoding="utf-8"?>
    <!-- $Revision$ -->
    <section xml:id="extname.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
     &reftitle.constants;
     &extension.constants;
     <para>
      <variablelist>
       <varlistentry>
        <term>
         <constant>CONSTANT_NAME</constant>
         (<type>itstype</type>)
        </term>
        <listitem>
         <simpara>

         </simpara>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </section>

    <!-- 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:"~/.phpdoc/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
    -->

## A `ini.xml` skeleton

    <?xml version="1.0" encoding="utf-8"?>
    <!-- $Revision$ -->
    <section xml:id="extname.configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
     &reftitle.runtime;
     &extension.runtime;
     <para>
      <table>
       <title>Extname &ConfigureOptions;</title>
       <tgroup cols="4">
        <thead>
         <row>
          <entry>&Name;</entry>
          <entry>&Default;</entry>
          <entry>&Changeable;</entry>
          <entry>Changelog</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>theini_option</entry>
          <entry>itsvalue</entry>
          <entry>its PHP_INI_* value</entry>
          <entry>leave this blank. it will be filled automatically</entry>
         </row>
        </tbody>
       </tgroup>
      </table>

      &php_ini_constants;
     </para>

     &ini.descriptions.title;

     <para>
      <variablelist>
       <varlistentry xml:id="ini.extname.theini-option">
        <term>
         <parameter>theini_option</parameter>
         <type>thetype</type>
        </term>
        <listitem>
         <para>

         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </section>

    <!-- 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:"~/.phpdoc/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
    -->

## Information for Translators

There are many active translations out there of the PHP documentation. Some languages are being maintained by a group of translators (eg. the German), some are one person projects (eg. the Japanese). There are quite a few things for translators to know, though these are simple.

## Starting a New Translation

Starting a new language translation comes down to the following simple steps:

- Consult the phpdoc mailing list to see if the translation is already in progress. If it is, read our tips for that case, disregard the following and coordinate with the other translators on the translation mailing list.

- Let the php doc mailing list (&email.phpdoc;) know that you are interested in starting a new translation.

- Once approved, ask for a SVN account. Mention that you would like to start a new translation and be sure to include the name of the translation in this request.

- The PHP documentation group will then ask &email.systems.php; to create a new translation. This involves setting up a new mailing list (`doc-LANGCODE@lists.php.net`), a newsgroup (`php.doc.LANGCODE`), and a SVN module (`phpdoc-LANGCODE`). At this point the LANGCODE should also be added to the `docweb` system.

- Check out the modules named `phpdoc` and `phpdoc-LANGCODE` (using the `phpdoc-LANGCODE-dir` alias) as described in the SVN chapter of this HOWTO.

- Copy `en/language-defs.ent` and `en/language-snippets.ent` to the new directory (visible as `phpdoc/LANGCODE` in your file system) and translate the contents of them.

- 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 revision tracking for help about how can you ease your work of tracking the English version and your language's version.

- After the translation makes a good start, its LANGCODE is added to the other PHP SVN modules like `phpweb`, `livedocs`, and to this howto. After doing so the new translation will be online!

Some important issues to consider when building a new translation:

- Can you set up and translate the whole manual yourself? If not, can you set up a team to work on the language (recommended!)?

- Have you made sure that your language or glyph (lettering, font, or characters) is supported by the DocBook stylesheets? Please ask on the mailing list if you don't know.

## Joining a Translation

If you see that a manual for your language is set up, and you would like to join the group, please ask on the appropriate mailing list about who is responsible for managing that translation.

If you are new to the PHP project, and you have no SVN account, please introduce yourself to the existing translation team and send in patches of your translations, so that they get to know you, and can endorse you later, when you request a SVN account to more seriously work on the translation. Note that there are some translations where just a few people have SVN accounts, and they are responsible for committing other's works.

## Practical Advice for Translators

Here is some advice we collected for translators:

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

- Do not commit translated files into the English tree. Double check your files before committing, to be sure that you are committing to the right place.

- Use a system to coordinate with the translators in your language. Currently we have two systems used in parallel, the Translators files and the Revision comments. See the section about revision tracking to learn more about this subject.

- 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 phpdoc mailing list.

- We have the global entities used all over the manuals in `global.ent`. If you would like to define entities only used in your language, an ideal place for these is `your_language/language-defs.ent`. See `hu/language-defs.ent` for an example.

- Do not translate entity names, such as &true; or &return.success;. These are there to be replaced by their relevant text. Translating them only cause errors. Similarly do not translate any tags (eg. <computeroutput>) to your language. The contents of comments (eg. the bottom of every file) are also not to be translated.

- Always make sure, that the modifications you made to your language's files, are correct. You may introduce illegal characters. Please always do a make test before committing. Introducing an error in your language's manual can stop the automatic updates online until you correct the error.

- If a documentation build process sends an error report to the translation mailing list, examine the problems, and try to fix them before the next build. If you have 'cross reference to paragraphs not supported' errors, you probably have old translated files around. Since paragraphs are generated by the build system for the missing ids not yet in those old files, these errors are inevitable. Either update your translation, or remove the offending files, thus allowing the English originals to take precedence.

## Revision Tracking

Working on the translations is not just translating an English file and committing 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 phpdoc mailing list, or read the archives. If you never update your files, the translations can get useless. You should also subscribe to your language's mailing list (if it's not English), to get SVN commit messages and participate in language specific discussions.

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 `phpdoc`. There is also a simple script to check parameters count/type/opt/reference in translated `<methodsynopsis>` - `scripts/check-trans-params.php`.

### The Translators Files

Some translations are using a `Translators` file in the root of their translation's tree for revision tracking. This file can contain the names, email addresses, and SVN user names of the contributors of this translation, and the list of files translated.

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:

    =============================================================================
    SVN 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
    ...

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

When it is time to update a file (eg. the English 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 SVN command, or using the web interface at &url.php.svn;. The web interface can generate really visual diffs, so you can easily spot what needs to be deleted, added, or modified, and where.

If you choose this method, do not forget to update the revision numbers stored in the `Translators` as you update files in your language's tree.

This system is hard to maintain with the current `phpdoc` layout, as tracking the revisions of more then 4000 files in one text file can be very hard. Consider using the revision comment method described below, where you only need to work on one file if you make updates in your language.

### The Revision Comments

There is another way of tracking versions instead of using the method described above. You can decide yourself, if this is the better method for you or not. Some languages use the Revision comments and `Translators` files in parallel, some use only one of these. It is better to decide, and not to use two systems, as things can get very messy this way.

Instead of storing all responsibilities in a central file, the revision comment system stores them in the files they provide information about. Consider the Translators example above. Now we spread the revision and association information in the files mentioned there. Let's see what would be in the header of the `bookinfo.xml` file in this case:

    <!-- EN-Revision: 1.16 Maintainer: jane Status: ready -->

You can see we lose 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. This is extremely convenient now, as there are more than 4000 files in the English tree.

Currently, all three fields (English revision, Maintainer, Status) are needed. Maintainer is intended to be a SVN user name, or some nickname without a space, status can be anything without a space. Note, that this header is not updated by SVN (in contrast with `$Revision`, which is updated automatically). This is only updated when you edit the contents of the comment yourself.

You may see this as a good thing, but using these comments, you lose the quick look on the whole list of your files. No, you do not lose this, but get much more! If you would like to build a list similar to the `Translators` file given above, you can go to the scripts directory and run:

    ./revcheck.php xx > revcheck.html

Here `xx` is the imaginary language code. After running this script you'll get a `revcheck.html` in the same directory. You can find revision comparisons and links to diffs for all the files in this language. You can also add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintainer. This HTML file gives you much more than the `Translators` file. See it yourself for an example with the Italian translation (code: it). You can also easily run this with `make revcheck` in the phpdoc root directory, in case you issued a `./configure --with-lang=xx` before.

As this system gets popular in many translation groups, the automatic build process also generates a `revcheck.html.gz` at the beginning of the build process for that language. It is available online in the languages manual directory. See the Italian translation's file online: &url.revcheck.it;.

There are some extensions introduced for this script, as need arised to port all contents of the `Translators` files to be available in this generated HTML page. This is why the `translation.xml` files are introduced. Here comes a simple `translation.xml` file for the imaginary xx language (contents ported from the `Translators` example above):

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

     <chmindex>
      This file was generated: <datetime/><br/>
      Go to <a href="http://www.php.net/download-docs">http://www.php.net/download-docs</a>
      to get the actual version.
     </chmindex>

     <translators>
      <person name="Joe Doe"     email="joe@hotmail.com"  nick="joedoe" svn="yes" editor="yes"/>
      <person name="Jane Smith"  email="jsmith@yahoo.com" nick="jane"   svn="yes"/>
      <person name="Joe Forever" email="joe@forever.net"  nick="joefo"  svn="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>

As you can see, this file can store exactly the same content, as a `Translators` file. What is new in this file, is that you can add users without a SVN account, and can assign ready documents or work-in-progress files to them. The biggest advantage of using this add-on is that all this information is used to generate dynamic tables of translators and files in the `revcheck.html` 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. Assigning ready files may be needed if a time consuming update is in progress on that file.

There are two CHM format related elements in this XML file. The first is the <chmindex> element, where you can specify your text to display on the CHM index page, with a link to the actual versions. The editor parameter of a <person> is also used in the grouping of translators on the CHM index page. These are optional, but are vital for every translation where the readers use the CHM format (all translations ;). Note that these are not used for current CHM manual generation, but will be important for the "next generation" CHMs, which are currently under heavy testing and development.

There are two optional parameters you can add to a <file>, if you would like to record it: the `date` and `revision`. 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). There is currently no fixed format for the `date` parameter.

Another add-on to this system is just to give credit to all people who worked on one file, and not just the current maintainer. To achieve this goal, we added the credit comments. One credit comment in eg. `history.xml` may look like this (in case Joe Doe translated the file initially, but Jane followed him to be the maintainer):

    <!-- CREDITS: joedoe -->

The credits comment can contain a comma-separated list. These comments only affect the display of the translators table in `revcheck.html.gz`.

Revision comments can be used also to print a diff between the current English file and the file used for the translation. Script `scripts/diff_en_rev.php` was created for this purpose.

## Mailing Lists, Newsgroups and SVN Modules

The PHP documentation is actively worked on each day, and the quality of work is enhanced by both peer review (reviewing each others commits) and communication. There are several mailing lists used to meet these goals including:

- &email.phpdoc; is used for general communication regarding the PHP documentation. This list is used when making decisions that affect the manual.

- &email.doc.vcs; receives each commit made to both the English tree of the documentation, and build system. Following this list is important for peer review and all are encouraged to subscribe.

- &email.doc.bugs; receives all documentation related bug activity from &url.php.bugs;. This also includes bugs for the build system and translations.

You may subscribe to a mailing list by sending a blank email that utilizes the appropriate `subscribe` command. For example, to subscribe to the main list, write a blank mail to &url.docsubscribe;. Similarly you may unsubscribe by sending a blank mail to &url.docunsubscribe;. There is a web interface for these tasks at &url.maillists;.

There are also separate mailing lists for translation groups, where native language discussions may go on and where language specific SVN commits are posted to. These mailing lists are named in the form of `doc-LANGCODE` where LANGCODE is the same language code used in the SVN module name. You can subscribe to / unsubscribe from these mailing lists the same way as above explained, substituting `phpdoc` in the email addresses with your list name. A sample list name is `doc-zh` for the Simplified Chinese list.

Currently these translation lists receive messages from the following senders:

- Members of the list: discussion threads about anything related to the given translation.

- The SVN server: diffs for commits made to the translation to their corresponding module's XML files.

- Other senders: posting to the list is not restricted, so people not on the list can also post messages. This way we can receive reports and suggestions by plain mail on the list.

As there are many posters to the lists including some automatic postings (bugs, svn commits) you should only subscribe to those lists in which you are interested in. We recommend that if you only work on the English version, you subscribe to the three main lists (phpdoc, doc-cvs, doc-bugs) and redirect them to whichever folder you see fit using filters within your email client. If you are also a member of a translation group, then you should additionally subscribe to the translation's mailing list. Reading the main mailing lists mails enables you to know what is going on in the English tree, what needs to be updated, and what changed in the build system.

You should be able to handle the traffic of the mailing lists you are subscribed to, but just in case you need to go for a long summer break, and you need to unsubscribe, there are other methods to read the messages after you come back:

- Read the messages on the web, in the archives at &url.listarchive; (this only works for the main phpdoc list!).

- Download the messages with a news reader at &url.listnews;.

- Read the messages on the web, with the news interface at &url.listnewshttp;.

The commit messages coming from the SVN server, that are larger then 8kb, are put into attachments. You can always see the commit message and file list in the body, but the diff is in an attachment.

The Windows HTMLHelp Edition of the manual has a separate mailing list for CHM related discussions and announcements. You can subscribe to this mailing list at &url.maillists; using the web interface.

There is also a mailing list named `php-notes`. You can access it the same way as the `phpdoc` list (just substitute `phpdoc` with `php-notes`). 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. See the next section for more information on note editing guidelines.

There is also a list named `doc-license`, which is set up for those who would like to get involved in the process of deciding who can do what with the PHP manual. The common rule is that, in addition to the rules set forth in the license, we try to get people publishing modified versions of the manual to contribute some improvements into the manual, fix errors they find, etc. You can subscribe to this list as described at chapter-maillist.

Finally, the doc.php.net site is forming on the `doc-web` mailing list. This site is supposed to be the meeting point for documentation authors of any of the projects developed on PHP.net.

The following table documents the relations between the different SVN modules, websites, mailing lists and newsgroups. Note that not all documentation sources are built to be available online.

## SVN Modules, Mailing lists and Newsgroups

Project Name | SVN Locations | Mailing List | Newsgroup | On the web
General Communication | N/A | phpdoc | php.doc | manual/en
Documentation Bugs | N/A | doc-bugs | php.doc.bugs | Open Doc Bugs
SVN Repository | phpdoc and phd | doc-cvs | php.doc.cvs | N/A
PHP Documentation Licensing | N/A | doc-license | php.doc.license | N/A
Extended CHM PHP Documentation | phpdoc/htmlhelp | doc-chm | php.doc.chm | &url.php.docs-echm;
PHP Documentation Website | docweb, funclist | doc-web | php.doc.web | &url.php.docweb;
Documentation User Notes | N/A | php-notes | php.notes | N/A
Arabic translation | phpdoc-ar | doc-ar | php.doc.ar | manual/ar
Bulgarian translation | phpdoc-bg | doc-bg | php.doc.bg | manual/bg
Catalan translation | phpdoc-ca | doc-ca | php.doc.ca | manual/ca
Czech translation | phpdoc-cs | doc-cs | php.doc.cs | manual/cs
Danish translation | phpdoc-da | doc-da | php.doc.da | manual/da
German translation | phpdoc-de | doc-de | php.doc.de | manual/de
Greek translation | phpdoc-el | doc-el | php.doc.el | manual/el
Spanish translation | phpdoc-es | doc-es | php.doc.es | manual/es
Persian (Farsi) translation | phpdoc-fa | doc-fa | php.doc.fa | manual/fa
Finnish translation | phpdoc-fi | doc-fi | php.doc.fi | manual/fi
French translation | phpdoc-fr | doc-fr | php.doc.fr | manual/fr
Hebrew translation | phpdoc-he | doc-he | php.doc.he | manual/he
Chinese (Hong Kong Cantonese) translation | phpdoc-hk | doc-hk | php.doc.hk | manual/hk
Hungarian translation | phpdoc-hu | doc-hu | php.doc.hu | manual/hu
Indonesian translation | phpdoc-id | doc-id | php.doc.id | manual/id
Italian translation | phpdoc-it | doc-it | php.doc.it | manual/it
Japanese translation | phpdoc-ja | doc-ja | php.doc.ja | manual/ja
Korean translation | phpdoc-kr | doc-kr | php.doc.kr | manual/kr
Lithuanian translation | phpdoc-lt | doc-lt | php.doc.lt | manual/lt
Dutch translation | phpdoc-nl | doc-nl | php.doc.nl | manual/nl
Norwegian translation | phpdoc-no | doc-no | php.doc.no | manual/no
Polish translation | phpdoc-pl | doc-pl | php.doc.pl | manual/pl
Portuguese translation | phpdoc-pt | doc-pt | php.doc.pt | manual/pt
Brazilian Portuguese translation | phpdoc-pt_BR | doc-pt-br | php.doc.pt-br | manual/pt_BR
Romanian translation | phpdoc-ro | doc-ro | php.doc.ro | manual/ro
Russian translation | phpdoc-ru | doc-ru | php.doc.ru | manual/ru
Slovak translation | phpdoc-sk | doc-sk | php.doc.sk | manual/sk
Slovenian translation | phpdoc-sl | doc-sl | php.doc.sl | manual/sl
Swedish translation | phpdoc-sv | doc-sv | php.doc.sv | manual/sv
Turkish translation | phpdoc-tr | doc-tr | php.doc.tr | manual/tr
Chinese (Traditional) translation | phpdoc-tw | doc-tw | php.doc.tw | manual/tw
Chinese (Simplified) translation | phpdoc-zh | doc-zh | php.doc.zh | manual/zh

## User Note Editing Guidelines

These are some guidelines to follow when editing user notes in the manual.

To begin editing user notes in the manual, you must have SVN commit access to the manual, and you must either:

- Subscribe to the `php-notes` mailing list or newsgroup as described at chapter-maillist. As a user submits a new user note, it will appear as a message on the mailing list with links in the footer of the email that enable you to delete, edit, or reject that particular note.

- Log on to the server at &url.notes.admin; using your SVN user ID and password. The user notes administration interface enables you to search for user notes that match particular strings and edit or change the status of particular notes directly through the Web interface.

The thing that seems to confuse the most people is the difference between 'rejecting' and 'deleting' a note. Basically, they both remove the note from the manual, but 'rejecting' sends the user an email about the rejection with links to support links and other information. Here are some guidelines of when to use each. This section is mostly an edited version of Jesus M. Castagnetto's email, with a few additions and re-phrases. The code for managing user notes can be seen here: &url.user-notes;. You can also view the exact text of the rejection email there.

- If the note is asking for help (support request, 'Does this work...?', etc.) or if the person is reporting a bug, 'reject' the note. The email will show them the proper place to report such issues.

- If the note contains useful information appropriate for the manual proper, you may incorporate the information into the manual and then 'delete' the note.

- If the note is in the wrong place, incorrect, a giant block of silly, unnecessary code, poorly written, an answer to another person's question, or just overall confusing, 'delete' it. If it was an answer to a question, hunt down that note and 'reject' it.

- If the note is in a language other than English, 'delete' the note.

- If the note submitter's email address is obviously bogus, don't 'reject' the note, just 'delete' it. Rejecting the note just gives the mail server more work trying to send an email to a non-existent address, which doesn't help anything.

If for some reason you need to add to a note, first ask yourself if it's worth it. Make sure you're not answering a user's question; if you are, then the note doesn't belong there (see above). If you're clarifying a point, see if it is appropriate to add the clarification to the manual proper; if it is, add it and 'delete' the note (see above). If you still feel that adding your addition to the note will be the best option, then go ahead and add it. Usually, editors add their note in a "Editor's Note" block at the top. Unless you are correcting a minor error, make it obvious that you edited the note.

If you have some free time and commit access to phpdoc, try going through some of the manual pages and adding some of the better notes into the documentation proper. Be sure to 'delete' these notes after they're implemented.

If you are in doubt about what to do with a note, you may ask for help on the php-notes mailing list (or phpdoc, if what you're doing involves the documentation proper).

&howto.scripts;

## Miscellaneous Notes

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