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

 <chapter xml:id="chapter-files" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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.
       It is generated from <filename>manual.xml.in</filename>
       when you run configure.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>entities/file-entities.ent</filename></term>
     <listitem>
      <simpara>
       Contains entity definitions for all files. Entities for the
       XML files are generated by configure, so
       <emphasis>you should not edit this file</emphasis>.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>entities/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, phpweb,
       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>
    <varlistentry>
     <term><filename>your_language/translation.xml</filename></term>
     <listitem>
      <simpara>
       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.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>your_language/some_directory</filename></term>
     <listitem>
      <simpara>
       The PHP Manual XML source is organized into directories.
       The biggest part is the extension reference, which is
       stored in the <filename>reference</filename> directory
       of your language.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </chapter>
 
 <chapter xml:id="chapter-conventions" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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 module.
  </para>
  
  <para>
   <orderedlist>
    <listitem><simpara>
     Please read and follow the
     <link xlink:href="&url.nomenclature;">Nomenclature and Style Guide</link>.
    </simpara></listitem>
    <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>
     Unlike function reference IDs method reference IDs are
     case-sensitive. Special operators <literal>::</literal>, 
     <literal>-></literal> and underscores are replaced by the same
     minus signs (-). For example <literal>function.DOMCharacterData-deleteData</literal>
     is an ID for <literal>DOMCharacterData->deleteData</literal> and
     <literal>function.ArrayObject-constructor</literal>
     is for <literal>ArrayObject::__constructor</literal>
     method accordingly. Note an exception when operators <literal>::</literal>
     and <literal>-></literal> followed by two underscores are replaced with
     one minus sign (-).
    </simpara></listitem>
    <listitem><simpara>
     Function reference section IDs
     (<literal>&lt;reference xml: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 it.
    </simpara></listitem>
    <listitem><simpara>
     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. 
    </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>
     Deprecated aliases and syntax should not be used in examples.
    </simpara></listitem>

    <listitem>
     <simpara>
      Use the &lt;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.
     </simpara>
     <para>
      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:
     <programlisting>
<![CDATA[
  <para>
   <example>
    <title />
    <programlisting/>
    <para>
     The output is:
    </para>
    <screen />
    <note>
     <simpara>
      This example only works on Unices.
     </simpara>
    </note>
   </example>
  </para>
]]>
      </programlisting>
     </para>

     <simpara>
      If there is something dangerous to document such as the
      <function>chroot</function>, or when something can be seen as a
      weirdness in the language such as weird auto-conversion of types, use the
      &lt;caution> element.
     </simpara>
     <simpara>
      The &lt;tip> can be used in cases where you might want to document a
      performance issue.
     </simpara>
    </listitem>

    <listitem>
     <para>
      For comments in example, use <literal>//</literal> for single line
      comments (preferable above the lines of code the comment comments on),
      and use <literal>/* .. */</literal> for multiline comments:
      <programlisting role="xml">
<![CDATA[
<programlisting role="php">
// This line execute foo
foo();

/* The next few lines also execute foo, but in a
 * weird way */
$var = 'foo';
$var();
</programlisting>
]]>
      </programlisting>
     </para>
    </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 role="xml">
<![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>. There are other
     shortcuts, such as <literal>&amp;php.ini;</literal>.
     These are stored in <filename>global.ent</filename>.
    </simpara></listitem>
    <listitem><simpara>
     All English XML files should have a <literal>&lt;!--
     &#36;Revision&#36; --></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.
    </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). For objects different from <literal>stdClass</literal>,
      use the class name instead of <literal>object</literal>.
     </simpara>

     <simpara>
      In prototypes, you can also use <literal>mixed</literal>
      (various types), or <literal>number</literal> (either
      integer or float). A callback is denoted as
      <literal>callback</literal>.
     </simpara>
     
     <simpara>
      Do not use <literal>mixed</literal>, 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 <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>en/reference/math/functions/min.xml</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 go to realfunc
     straight from the <literal>ref.foo</literal> page.
    </simpara></listitem>

    <listitem><para>
     Document examples always with the following structure:
     <programlisting role="xml">
&lt;para&gt;
 &lt;example&gt;
  &lt;title /&gt;
  &lt;programlisting&gt;
&lt;![CDATA[
&lt;?php
echo "foo\n";
?&gt;
]]&gt;
  &lt;/programlisting&gt;
  &lt;para&gt;
   The output is:
  &lt;/para&gt;
  &lt;screen&gt;
&lt;![CDATA[
foo
]]&gt;
  &lt;/screen&gt;
 &lt;/example&gt;
&lt;/para&gt;
     </programlisting>
    </para></listitem>
   </orderedlist>
  </para>
 </chapter>

 <chapter xml:id="chapter-what-to-document" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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
      compatibility. 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
       <link xlink:href="&email.internals;">&email.internals;</link> 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>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. :)</simpara></footnote>
     </simpara>
    </listitem>
   </orderedlist>
  </para>
 </chapter>
 
 <chapter xml:id="chapter-skeletons" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Documentation Skeletons</title>
  <para>
   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.
  </para>
  <note>
   <para>
   The documentation skeletons below are new, from around August of 2004.
   </para>
  </note>
  <para>
   <example>
    <title>A function skeleton (<filename>func-name.xml</filename>)</title>
    <programlisting role="xml">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- &#36;Revision$ --&gt;
&lt;refentry xml:id="function.func-name" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"&gt;
 &lt;refnamediv&gt;
  &lt;refname&gt;func_name&lt;/refname&gt;
  &lt;refpurpose&gt;The func_name purpose&lt;/refpurpose&gt;
 &lt;/refnamediv&gt;
 &lt;refsect1 role="description"&gt;
  &amp;reftitle.description;
  &lt;methodsynopsis&gt;
   &lt;!-- Example: All functions have this --&gt;
   &lt;type&gt;thereturned type&lt;/type&gt;&lt;methodname&gt;func_name&lt;/methodname&gt;
   &lt;!-- Example: Required parameter --&gt;
   &lt;methodparam&gt;&lt;type&gt;int&lt;/type&gt;&lt;parameter&gt;firstparameter&lt;/parameter&gt;&lt;/methodparam&gt;
   &lt;!-- Example: Optional parameter --&gt;
   &lt;methodparam choice="opt"&gt;&lt;type&gt;string&lt;/type&gt;&lt;parameter&gt;secondparameter&lt;/parameter&gt;&lt;/methodparam&gt;
   &lt;!-- Example: Passed by reference --&gt;
   &lt;methodparam&gt;&lt;type&gt;bool&lt;/type&gt;&lt;parameter role="reference"&gt;thirdparameter&lt;/parameter&gt;&lt;/methodparam&gt;
   &lt;!-- Example: If no methodparams exist (void), use this --&gt;
   &lt;void /&gt;
  &lt;/methodsynopsis&gt;
  &lt;para&gt;
   The functions description goes here.
  &lt;/para&gt;
 &lt;/refsect1&gt;
 
 &lt;refsect1 role="parameters"&gt;
  &amp;reftitle.parameters;
  &lt;para&gt;
   &lt;variablelist&gt;
    &lt;varlistentry&gt;
     &lt;term&gt;&lt;parameter&gt;firstparameter&lt;/parameter&gt;&lt;/term&gt;
     &lt;listitem&gt;
      &lt;para&gt;
       Its description
      &lt;/para&gt;
     &lt;/listitem&gt;
    &lt;/varlistentry&gt;
    &lt;varlistentry&gt;
     &lt;term&gt;&lt;parameter&gt;secondparameter&lt;/parameter&gt;&lt;/term&gt;
     &lt;listitem&gt;
      &lt;para&gt;
       Its description
      &lt;/para&gt;
     &lt;/listitem&gt;
    &lt;/varlistentry&gt;
   &lt;/variablelist&gt;
  &lt;/para&gt;
 &lt;/refsect1&gt;
 
 &lt;refsect1 role="returnvalues"&gt;
  &amp;reftitle.returnvalues;
  &lt;para&gt;
   What this function returns, first on success, then failure.  If simply
   true on success and false on failure, just use &amp;return.success; here.
  &lt;/para&gt;
 &lt;/refsect1&gt;
 
 &lt;refsect1 role="errors"&gt;
  &amp;reftitle.errors;
  &lt;para&gt;
   When does this function issue E_* level errors, or throw exceptions?
  &lt;/para&gt;
 &lt;/refsect1&gt;

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

 &lt;refsect1 role="changelog"&gt;
  &amp;reftitle.changelog;
  &lt;para&gt;
   &lt;informaltable&gt;
    &lt;tgroup cols="2"&gt;
     &lt;thead&gt;
      &lt;row&gt;
       &lt;entry&gt;&amp;Version;&lt;/entry&gt;
       &lt;entry&gt;&amp;Description;&lt;/entry&gt;
      &lt;/row&gt;
     &lt;/thead&gt;
     &lt;tbody&gt;
      &lt;row&gt;
       &lt;entry&gt;Write the PHP version here (Ex. PHP 5.2.0)&lt;/entry&gt;
       &lt;entry&gt;
        Describe the change
       &lt;/entry&gt;
      &lt;/row&gt;
      &lt;row&gt;
       &lt;entry&gt;...&lt;/entry&gt;
       &lt;entry&gt;
        ...
       &lt;/entry&gt;
      &lt;/row&gt;
     &lt;/tbody&gt;
    &lt;/tgroup&gt;
   &lt;/informaltable&gt;
  &lt;/para&gt;
 &lt;/refsect1&gt;
 
 &lt;refsect1 role="examples"&gt;
  &amp;reftitle.examples;
  &lt;para&gt;
   &lt;example&gt;
    &lt;title&gt;&lt;function&gt;functionname&lt;/function&gt; example&lt;/title&gt;
    &lt;programlisting role="php"&gt;
&lt;![CDATA[
&lt;?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';
}
?&gt;
]]&gt;
    &lt;/programlisting&gt;
    &amp;example.outputs.similar;
    &lt;screen&gt;
&lt;![CDATA[
Use the PEAR Coding standards
Use a screen like we did below
]]&gt;
    &lt;/screen&gt;
   &lt;/example&gt;
  &lt;/para&gt;
 &lt;/refsect1&gt;

 &lt;refsect1 role="notes"&gt;
  &amp;reftitle.notes;
  &lt;para&gt;
   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!
  &lt;/para&gt;
 &lt;/refsect1&gt;
 
 &lt;refsect1 role="seealso"&gt;
  &amp;reftitle.seealso;
  &lt;para&gt;
   &lt;simplelist&gt;
    &lt;member&gt;&lt;function&gt;somefunc&lt;/function&gt;&lt;/member&gt;
    &lt;member&gt;&lt;function&gt;another_func&lt;/function&gt;&lt;/member&gt;
    &lt;member&gt;The &lt;link linkend="something"&gt;something appendix&lt;/link&gt;&lt;/member&gt;
   &lt;/simplelist&gt;
  &lt;/para&gt;
 &lt;/refsect1&gt;
&lt;/refentry&gt;

&lt;!-- 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
--&gt;

    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>A <filename>reference.xml</filename> skeleton</title>
    <programlisting role="xml">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- &#36;Revision$ --&gt;
&lt;!-- Purpose: xx --&gt;
&lt;!-- Membership: xx --&gt;
&lt;!-- State: xx --&gt;
&lt;reference xml:id="ref.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"&gt;
 &lt;title&gt;Extname &amp;Functions;&lt;/title&gt;
 &lt;titleabbrev&gt;Extname&lt;/titleabbrev&gt;

 &lt;partintro&gt;
  &lt;section xml:id="extname.intro"&gt;
   &amp;reftitle.intro;
   &lt;para&gt;
     
   &lt;/para&gt;
  &lt;/section&gt;

  &lt;section xml:id="extname.requirements"&gt;
   &amp;reftitle.required;
   &lt;para&gt;
     
   &lt;/para&gt;
  &lt;/section&gt;

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

  &lt;section xml:id="extname.resources"&gt;
   &amp;reftitle.resources;
   &amp;no.resource;
  &lt;/section&gt;

  &amp;reference.extname.constants;
 &lt;/partintro&gt;

 &amp;reference.extname.functions;

&lt;/reference&gt;

&lt;!-- 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
--&gt;

    </programlisting>
   </example>
  </para>
  <para>
   There are several PECL related entities inside of
   <filename>language-snippets.ent</filename>. Be sure to include information
   on where Windows users can find the DLL.
   <example>
    <title>A <filename>configure.xml</filename> skeleton</title>
    <programlisting role="xml">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- &#36;Revision$ --&gt;
&lt;section xml:id="extname.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"&gt;
 &amp;reftitle.install;
 &lt;para&gt;
  To enable extname support, configure PHP with 
  &lt;option role="configure"&gt;theconfigoption&lt;/option&gt;
 &lt;/para&gt;
 &lt;para&gt;
  Windows users ...
 &lt;/para&gt;
&lt;/section&gt;

&lt;!-- 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
--&gt;

    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>A <filename>constants.xml</filename> skeleton</title>
    <programlisting role="xml">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- &#36;Revision$ --&gt;
&lt;section xml:id="extname.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"&gt;
 &amp;reftitle.constants;
 &amp;extension.constants;
 &lt;para&gt;
  &lt;variablelist&gt;
   &lt;varlistentry&gt;
    &lt;term&gt;
     &lt;constant&gt;CONSTANT_NAME&lt;/constant&gt; 
     (&lt;type&gt;itstype&lt;/type&gt;)
    &lt;/term&gt;
    &lt;listitem&gt;
     &lt;simpara&gt;
     
     &lt;/simpara&gt;
    &lt;/listitem&gt;
   &lt;/varlistentry&gt;
  &lt;/variablelist&gt;
 &lt;/para&gt;
&lt;/section&gt;

&lt;!-- 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
--&gt;

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

  &amp;php_ini_constants;
 &lt;/para&gt;
 
 &amp;ini.descriptions.title;
 
 &lt;para&gt;
  &lt;variablelist&gt;
   &lt;varlistentry xml:id="ini.extname.theini-option"&gt;
    &lt;term&gt;
     &lt;parameter&gt;theini_option&lt;/parameter&gt;
     &lt;type&gt;thetype&lt;/type&gt;
    &lt;/term&gt;
    &lt;listitem&gt;
     &lt;para&gt;
     
     &lt;/para&gt;
    &lt;/listitem&gt;
   &lt;/varlistentry&gt;
  &lt;/variablelist&gt;
 &lt;/para&gt;
&lt;/section&gt;

&lt;!-- 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
--&gt;

    </programlisting>
   </example>
  </para>
 </chapter>

 <chapter xml:id="chapter-translation" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Information for Translators</title>

  <para>
   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.
  </para>
  
  <sect1 xml:id="translation-starting">
   <title>Starting a New Translation</title>
   <para>
    Starting a new language translation comes down to
    the following simple steps:
    <itemizedlist>
     <listitem>
      <simpara>
       Consult the <link linkend="chapter-maillist">phpdoc mailing
       list</link> to see if the translation is already in progress.
       If it is, read <link linkend="translation-joining">our tips
       for that case</link>, disregard the following and coordinate
       with the other translators on the translation mailing list.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Let the php doc mailing list (&email.phpdoc;) know that you are
       interested in starting a new translation.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Once approved, <link linkend="svn-account">ask for a SVN account</link>.
       Mention that you would like to start a new translation and be sure to 
       include the name of the translation in this request.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       The PHP documentation group will then ask 
       <link xlink:href="mailto:&email.systems.php;">&email.systems.php;</link>
       to create a new translation. This involves setting up a new mailing
       list (<literal>doc-LANGCODE@lists.php.net</literal>), a newsgroup 
       (<literal>php.doc.LANGCODE</literal>), and a SVN module 
       (<literal>phpdoc-LANGCODE</literal>). At this point the LANGCODE 
       should also be added to the <literal>docweb</literal> system.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Check out the modules named <filename>phpdoc</filename>
       and <literal>phpdoc-LANGCODE</literal> (using the 
       <literal>phpdoc-LANGCODE-dir</literal> alias) as
       described in the <link linkend="chapter-svn">SVN chapter</link>
       of this HOWTO.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Copy <filename>en/language-defs.ent</filename> and
       <filename>en/language-snippets.ent</filename> to the
       new directory (visible as <literal>phpdoc/LANGCODE</literal>
       in your file system) 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
       version and your language's version.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       After the translation makes a good start, its LANGCODE is added 
       to the other PHP SVN modules like <literal>phpweb</literal>, 
       <literal>livedocs</literal>, and to this 
       <link linkend="chapter-maillist">howto</link>. After doing so
       the new translation will be online!
      </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 (recommended!)?
      </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 xml:id="translation-joining">
   <title>Joining 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 appropriate <link linkend="chapter-maillist">mailing
    list</link> about who is responsible for managing that
    translation.
   </para>
   <para>
    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 <link linkend="svn-account">request a SVN account</link>
    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.
   </para>
  </sect1>

  <sect1 xml: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>
       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.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       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
       <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 phpdoc <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 also 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 committing. Introducing an
       error in your language's manual can stop the
       automatic updates online until you correct the
       error.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       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.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>
  
  <sect1 xml:id="translation-revtrack">
   <title>Revision Tracking</title>
   <para>
    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
    <link linkend="chapter-maillist">mailing list</link>,
    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.
   </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>.
    There is also a simple script to check parameters count/type/opt/reference
    in translated <literal>&lt;methodsynopsis&gt;</literal> -
    <filename>scripts/check-trans-params.php</filename>.
   </para>

   <sect2 xml:id="translation-revcheck-translators">
    <title>The Translators Files</title>
    
    <para>
     Some translations are using a <filename>Translators</filename>
     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.
    </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>
=============================================================================
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
...
     </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. 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 <link xlink:href="&url.php.svn;">
     &url.php.svn;</link>. The web interface can generate really
     visual diffs, so you can easily spot what needs to be deleted,
     added, or modified, and 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>
    <note>
     <para>
      This system is hard to maintain with the current <filename>phpdoc</filename>
      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.
     </para>
    </note>
   </sect2>

   <sect2 xml:id="translation-revcheck-comments">
    <title>The Revision Comments</title>
    
    <para>
     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 <filename>Translators</filename>
     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.
    </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
     information 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 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.
    </para>
    <para>
     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 
     <literal>$Revision</literal>, which is updated automatically).
     This is only updated when you edit the contents of the comment
     yourself.
    </para>
    <para>
     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
     <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 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 <filename>Translators</filename> file. See it
     yourself for an 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.gz</filename> 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:
     <link xlink:href="&url.revcheck.it;">&url.revcheck.it;</link>.
    </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>
 
 <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>
]]>
     </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 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 <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. Assigning ready files may be needed if
     a time consuming update is in progress on that file.
    </para>
    
    <para>
     There are two CHM format related elements in this XML file. The
     first is the &lt;chmindex&gt; 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 &lt;person&gt; 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.
    </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). There is currently no
     fixed format for the <literal>date</literal> parameter.
    </para>
    
    <para>
     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. <filename>history.xml</filename> may look like this (in case
     Joe Doe translated the file initially, 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.gz</filename>.
    </para>
    
    <para>
     Revision comments can be used also to print a diff between the current
     English file and the file used for the translation. Script
     <filename>scripts/diff_en_rev.php</filename> was created for this
     purpose.
    </para>
   </sect2>
  </sect1>
 </chapter>

 <chapter xml:id="chapter-maillist" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Mailing Lists, Newsgroups and SVN Modules</title>
  
  <para>
   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:
   <itemizedlist>   
    <listitem>
     <simpara>
      <email>&email.phpdoc;</email> is used for general communication
      regarding the PHP documentation. This list is used when making 
      decisions that affect the manual.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <email>&email.doc.vcs;</email> 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.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <email>&email.doc.bugs;</email> receives all documentation related bug activity 
      from &url.php.bugs;. This also includes bugs for the build system and translations.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   You may subscribe to a mailing list by sending a blank email that
   utilizes the appropriate <literal>subscribe</literal> command. For
   example, to subscribe to the main list, write a blank mail to
   <link xlink:href="&url.docsubscribe;">&url.docsubscribe;</link>.
   Similarly you may unsubscribe by sending a blank mail to
   <link xlink:href="&url.docunsubscribe;">&url.docunsubscribe;</link>.
   There is a web interface for these tasks at <link
   xlink:href="&url.maillists;">&url.maillists;</link>.
  </para>
  <para>
   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 <literal>doc-LANGCODE</literal> 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
   <literal>phpdoc</literal> in the email addresses with your list
   name. A sample list name is <literal>doc-zh</literal> for the
   Simplified Chinese list.
  </para>
  <para>
   Currently these translation lists receive messages from the following 
   senders:
   <itemizedlist>
    <listitem>
     <simpara>
      Members of the list: discussion threads about anything
      related to the given translation.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The SVN server: diffs for commits made to the translation to 
      their corresponding module's XML files. 
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      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.
     </simpara>
    </listitem>
   </itemizedlist>
   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.
  </para>
  <para>
   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:
   <itemizedlist>
    <listitem>
     <simpara>
      Read the messages on the web, in the archives at
      <link xlink:href="&url.listarchive;">&url.listarchive;</link>
      (this only works for the main phpdoc list!).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Download the messages with a news reader at
      <link xlink:href="&url.listnews;">&url.listnews;</link>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Read the messages on the web, with the news interface at
      <link xlink:href="&url.listnewshttp;">&url.listnewshttp;</link>.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   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.
  </para>
  <para>
   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 <link
   xlink:href="&url.maillists;">&url.maillists;</link> 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.
   See the next section for more information on note editing guidelines.
  </para>
  <para>
   There is also a list named <literal>doc-license</literal>, 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 <xref linkend="chapter-maillist"/>.
  </para>
  <para>
   Finally, the doc.php.net site is forming on the <literal>doc-web</literal>
   mailing list. This site is supposed to be the meeting point for documentation
   authors of any of the projects developed on PHP.net.
  </para>
  <para>
   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.
   <table>
    <title>SVN Modules, Mailing lists and Newsgroups</title>
    <tgroup cols="5">
     <thead>
      <row>
       <entry>Project Name</entry>
       <entry>SVN Locations</entry>
       <entry>Mailing List</entry>
       <entry>Newsgroup</entry>
       <entry>On the web</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>General Communication</entry>
       <entry>N/A</entry>
       <entry><link xlink:href="mailto:&email.phpdoc;">phpdoc</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc">php.doc</link></entry>
       <entry><link xlink:href="&url.php.manual;en/">manual/en</link></entry>
      </row>
      <row>
       <entry>Documentation Bugs</entry>
       <entry>N/A</entry>
       <entry><link xlink:href="mailto:&email.doc.bugs;">doc-bugs</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.bugs">php.doc.bugs</link></entry>
       <entry><link xlink:href="&url.php.bugs.doc;">Open Doc Bugs</link></entry>
      </row>
      <!-- FIXME: we still use doc-cvs for doc-svn... deal with this -->
      <row>
       <entry>SVN Repository</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/">phpdoc</link> and 
        <link xlink:href="&url.php.svn;phd/">phd</link>
       </entry>
       <entry><link xlink:href="mailto:&email.doc.vcs;">doc-cvs</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.vcs">php.doc.cvs</link></entry>
       <entry>N/A</entry>
      </row>
      <row>
       <entry>PHP Documentation Licensing</entry>
       <entry>N/A</entry>
       <entry><link xlink:href="mailto:doc-license&email.lists;">doc-license</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.license">php.doc.license</link></entry>
       <entry>N/A</entry>
      </row>
      <row>
       <entry>Extended CHM PHP Documentation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/htmlhelp/">phpdoc/htmlhelp</link>
       </entry>
       <entry><link xlink:href="mailto:doc-chm&email.lists;">doc-chm</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.chm">php.doc.chm</link></entry>
       <entry><link xlink:href="&url.php.docs-echm;">&url.php.docs-echm;</link></entry>
      </row>
      <row>
       <entry>PHP Documentation Website</entry>
       <entry>
        <link xlink:href="&url.php.svn;docweb/">docweb</link>,
        <link xlink:href="&url.php.svn;funclist/">funclist</link>
       </entry>
       <entry><link xlink:href="mailto:doc-web&email.lists;">doc-web</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.web">php.doc.web</link></entry>
       <entry><link xlink:href="&url.php.docweb;">&url.php.docweb;</link></entry>
      </row>
      <row>
       <entry>Documentation User Notes</entry>
       <entry>N/A</entry>
       <entry><link xlink:href="mailto:php-notes&email.lists;">php-notes</link></entry>
       <entry><link xlink:href="&url.newsserver;php.notes">php.notes</link></entry>
       <entry>N/A</entry>
      </row>
      <row>
       <entry>Arabic translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/ar/">phpdoc-ar</link>
       </entry>
       <entry><link xlink:href="mailto:doc-ar&email.lists;">doc-ar</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.ar">php.doc.ar</link></entry>
       <entry><link xlink:href="&url.php.manual;ar/">manual/ar</link></entry>
      </row>
      <row>
       <entry>Bulgarian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/bg/">phpdoc-bg</link>
       </entry>
       <entry><link xlink:href="mailto:doc-bg&email.lists;">doc-bg</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.bg">php.doc.bg</link></entry>
       <entry><link xlink:href="&url.php.manual;bg/">manual/bg</link></entry>
      </row>
      <row>
       <entry>Catalan translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/ca/">phpdoc-ca</link>
       </entry>
       <entry><link xlink:href="mailto:doc-ca&email.lists;">doc-ca</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.ca">php.doc.ca</link></entry>
       <entry><link xlink:href="&url.php.manual;ca/">manual/ca</link></entry>
      </row>
      <row>
       <entry>Czech translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/cs/">phpdoc-cs</link>
       </entry>
       <entry><link xlink:href="mailto:doc-cs&email.lists;">doc-cs</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.cs">php.doc.cs</link></entry>
       <entry><link xlink:href="&url.php.manual;cs/">manual/cs</link></entry>
      </row>
      <row>
       <entry>Danish translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/da/">phpdoc-da</link>
       </entry>
       <entry><link xlink:href="mailto:doc-da&email.lists;">doc-da</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.da">php.doc.da</link></entry>
       <entry><link xlink:href="&url.php.manual;da/">manual/da</link></entry>
      </row>
      <row>
       <entry>German translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/de/">phpdoc-de</link>
       </entry>
       <entry><link xlink:href="mailto:doc-de&email.lists;">doc-de</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.de">php.doc.de</link></entry>
       <entry><link xlink:href="&url.php.manual;de/">manual/de</link></entry>
      </row>
      <row>
       <entry>Greek translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/el/">phpdoc-el</link>
       </entry>
       <entry><link xlink:href="mailto:doc-el&email.lists;">doc-el</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.el">php.doc.el</link></entry>
       <entry><link xlink:href="&url.php.manual;el/">manual/el</link></entry>
      </row>
      <row>
       <entry>Spanish translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/es/">phpdoc-es</link>
       </entry>
       <entry><link xlink:href="mailto:doc-es&email.lists;">doc-es</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.es">php.doc.es</link></entry>
       <entry><link xlink:href="&url.php.manual;es/">manual/es</link></entry>
      </row>
      <row>
       <entry>Persian (Farsi) translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/fa/">phpdoc-fa</link>
       </entry>
       <entry><link xlink:href="mailto:doc-fa&email.lists;">doc-fa</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.fa">php.doc.fa</link></entry>
       <entry><link xlink:href="&url.php.manual;fa/">manual/fa</link></entry>
      </row>
      <row>
       <entry>Finnish translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/fi/">phpdoc-fi</link>
       </entry>
       <entry><link xlink:href="mailto:doc-fi&email.lists;">doc-fi</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.fi">php.doc.fi</link></entry>
       <entry><link xlink:href="&url.php.manual;fi/">manual/fi</link></entry>
      </row>
      <row>
       <entry>French translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/fr/">phpdoc-fr</link>
       </entry>
       <entry><link xlink:href="mailto:doc-fr&email.lists;">doc-fr</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.fr">php.doc.fr</link></entry>
       <entry><link xlink:href="&url.php.manual;fr/">manual/fr</link></entry>
      </row>
      <row>
       <entry>Hebrew translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/he/">phpdoc-he</link>
       </entry>
       <entry><link xlink:href="mailto:doc-he&email.lists;">doc-he</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.he">php.doc.he</link></entry>
       <entry><link xlink:href="&url.php.manual;he/">manual/he</link></entry>
      </row>
      <row>
       <entry>Chinese (Hong Kong Cantonese) translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/hk/">phpdoc-hk</link>
       </entry>
       <entry><link xlink:href="mailto:doc-hk&email.lists;">doc-hk</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.hk">php.doc.hk</link></entry>
       <entry><link xlink:href="&url.php.manual;hk/">manual/hk</link></entry>
      </row>
      <row>
       <entry>Hungarian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/hu/">phpdoc-hu</link>
       </entry>
       <entry><link xlink:href="mailto:doc-hu&email.lists;">doc-hu</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.hu">php.doc.hu</link></entry>
       <entry><link xlink:href="&url.php.manual;hu/">manual/hu</link></entry>
      </row>
      <row>
       <entry>Indonesian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/id/">phpdoc-id</link>
       </entry>
       <entry><link xlink:href="mailto:doc-id&email.lists;">doc-id</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.id">php.doc.id</link></entry>
       <entry><link xlink:href="&url.php.manual;id/">manual/id</link></entry>
      </row>
      <row>
       <entry>Italian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/it/">phpdoc-it</link>
       </entry>
       <entry><link xlink:href="mailto:doc-it&email.lists;">doc-it</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.it">php.doc.it</link></entry>
       <entry><link xlink:href="&url.php.manual;it/">manual/it</link></entry>
      </row>
      <row>
       <entry>Japanese translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/ja/">phpdoc-ja</link>
       </entry>
       <entry><link xlink:href="mailto:doc-ja&email.lists;">doc-ja</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.ja">php.doc.ja</link></entry>
       <entry><link xlink:href="&url.php.manual;ja/">manual/ja</link></entry>
      </row>
      <row>
       <entry>Korean translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/kr/">phpdoc-kr</link>
       </entry>
       <entry><link xlink:href="mailto:doc-kr&email.lists;">doc-kr</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.kr">php.doc.kr</link></entry>
       <entry><link xlink:href="&url.php.manual;kr/">manual/kr</link></entry>
      </row>
      <row>
       <entry>Lithuanian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/lt/">phpdoc-lt</link>
       </entry>
       <entry><link xlink:href="mailto:doc-lt&email.lists;">doc-lt</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.lt">php.doc.lt</link></entry>
       <entry><link xlink:href="&url.php.manual;lt/">manual/lt</link></entry>
      </row>
      <row>
       <entry>Dutch translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/nl/">phpdoc-nl</link>
       </entry>
       <entry><link xlink:href="mailto:doc-nl&email.lists;">doc-nl</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.nl">php.doc.nl</link></entry>
       <entry><link xlink:href="&url.php.manual;nl/">manual/nl</link></entry>
      </row>
      <row>
       <entry>Norwegian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/no/">phpdoc-no</link>
       </entry>
       <entry><link xlink:href="mailto:doc-no&email.lists;">doc-no</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.no">php.doc.no</link></entry>
       <entry><link xlink:href="&url.php.manual;no/">manual/no</link></entry>
      </row>
      <row>
       <entry>Polish translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/pl/">phpdoc-pl</link>
       </entry>
       <entry><link xlink:href="mailto:doc-pl&email.lists;">doc-pl</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.pl">php.doc.pl</link></entry>
       <entry><link xlink:href="&url.php.manual;pl/">manual/pl</link></entry>
      </row>
      <row>
       <entry>Portuguese translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/pt/">phpdoc-pt</link>
       </entry>
       <entry><link xlink:href="mailto:doc-pt&email.lists;">doc-pt</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.pt">php.doc.pt</link></entry>
       <entry><link xlink:href="&url.php.manual;pt/">manual/pt</link></entry>
      </row>
      <row>
       <entry>Brazilian Portuguese translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/pt_BR/">phpdoc-pt_BR</link>
       </entry>
       <entry><link xlink:href="mailto:doc-pt-br&email.lists;">doc-pt-br</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.pt-br">php.doc.pt-br</link></entry>
       <entry><link xlink:href="&url.php.manual;pt_BR/">manual/pt_BR</link></entry>
      </row>
      <row>
       <entry>Romanian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/ro/">phpdoc-ro</link>
       </entry>
       <entry><link xlink:href="mailto:doc-ro&email.lists;">doc-ro</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.ro">php.doc.ro</link></entry>
       <entry><link xlink:href="&url.php.manual;ro/">manual/ro</link></entry>
      </row>
      <row>
       <entry>Russian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/ru/">phpdoc-ru</link>
       </entry>
       <entry><link xlink:href="mailto:doc-ru&email.lists;">doc-ru</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.ru">php.doc.ru</link></entry>
       <entry><link xlink:href="&url.php.manual;ru/">manual/ru</link></entry>
      </row>
      <row>
       <entry>Slovak translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/sk/">phpdoc-sk</link>
       </entry>
       <entry><link xlink:href="mailto:doc-sk&email.lists;">doc-sk</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.sk">php.doc.sk</link></entry>
       <entry><link xlink:href="&url.php.manual;sk/">manual/sk</link></entry>
      </row>
      <row>
       <entry>Slovenian translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/sl/">phpdoc-sl</link>
       </entry>
       <entry><link xlink:href="mailto:doc-sl&email.lists;">doc-sl</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.sl">php.doc.sl</link></entry>
       <entry><link xlink:href="&url.php.manual;sl/">manual/sl</link></entry>
      </row>
      <row>
       <entry>Swedish translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/sv/">phpdoc-sv</link>
       </entry>
       <entry><link xlink:href="mailto:doc-sv&email.lists;">doc-sv</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.sv">php.doc.sv</link></entry>
       <entry><link xlink:href="&url.php.manual;sv/">manual/sv</link></entry>
      </row>
      <row>
       <entry>Turkish translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/tr/">phpdoc-tr</link>
       </entry>
       <entry><link xlink:href="mailto:doc-tr&email.lists;">doc-tr</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.tr">php.doc.tr</link></entry>
       <entry><link xlink:href="&url.php.manual;tr/">manual/tr</link></entry>
      </row>
      <row>
       <entry>Chinese (Traditional) translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/tw/">phpdoc-tw</link>
       </entry>
       <entry><link xlink:href="mailto:doc-tw&email.lists;">doc-tw</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.tw">php.doc.tw</link></entry>
       <entry><link xlink:href="&url.php.manual;tw/">manual/tw</link></entry>
      </row>
      <row>
       <entry>Chinese (Simplified) translation</entry>
       <entry>
        <link xlink:href="&url.php.svn;phpdoc/zh/">phpdoc-zh</link>
       </entry>
       <entry><link xlink:href="mailto:doc-zh&email.lists;">doc-zh</link></entry>
       <entry><link xlink:href="&url.newsserver;php.doc.zh">php.doc.zh</link></entry>
       <entry><link xlink:href="&url.php.manual;zh/">manual/zh</link></entry>
      </row>
    </tbody>
    </tgroup>
   </table>
  </para>
 </chapter>

 <chapter xml:id="chapter-user-notes" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>User Note Editing Guidelines</title>
  
  <para>
   These are some guidelines to follow when editing user notes in the manual.
  </para>
  <para>
   To begin editing user notes in the manual, you must have SVN commit access
   to the manual, and you must either:
   <itemizedlist>
    <listitem>
     <para>
      Subscribe to the <literal>php-notes</literal> mailing list or newsgroup
      as described at <xref linkend="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.
     </para>
    </listitem>
    <listitem>
     <para>
      Log on to the server at
      <link xlink:href='&url.notes.admin;'>&url.notes.admin;</link> 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.
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   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: <link xlink:href="&url.user-notes;">
   &url.user-notes;</link>.  You can also view the exact text of the rejection
   email there.
   <itemizedlist>
    <listitem>
     <simpara>
      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.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      If the note contains useful information appropriate for the manual proper,
      you may incorporate the information into the manual and then 'delete' the 
      note.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      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.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      If the note is in a language other than English, 'delete' the note.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      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.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   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.
  </para>
  <para>
   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.
  </para>
  <para>
   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).
  </para>
 </chapter>

 &howto.scripts;

 <chapter xml:id="chapter-misc" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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
-->