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

 <chapter id="chapter-makefile">
  <title>The Makefile</title>

  <para>
   An important part of making contributions to the PHP documentation
   is being able to validate your changes and to be able to see what
   they will look like in their various forms, whether that is in
   HTML, Adobe PDF, RTF or other formats.
  </para>

  <para>
   The <filename>Makefile</filename> controls serveral aspects
   of how the documentation is validated and created. To generate a
   <filename>Makefile</filename> from a fresh checkout,
   <command>cd</command> to the <filename>phpdoc</filename>
   directory and issue the following commands:
   <informalexample>
    <programlisting>
$ autoconf

$ ./configure
    </programlisting>
   </informalexample>
   This will generate a current <filename>Makefile</filename> for
   your copy of the <emphasis>phpdoc</emphasis> tree.
  </para>
  
  <note>
   <para>
    If you are using Windows, these commands
    only work in the Cygwin bash shell.
   </para>
  </note>
  
  <para>
   Configure has two important options you may use. One is
   <literal>--with-dsssl</literal>. Using this option, you
   can specify the path to the DSSSL stylesheets. There are
   many (more than 15) directories searched for DSSSL style
   sheets, so you may not worry about this option. You
   can specify the used manual language with the
   <literal>--with-lang</literal> option. The default
   is "en". An example on using this option:
   <informalexample>
    <programlisting>
$ ./configure --with-lang=nl
    </programlisting>
   </informalexample>
   There are some more options. The most important are
   the <literal>--with-xsl</literal> option to specify
   the XSL style sheets path, and the
   <literal>--with-zendapi</literal> to specify the
   path to the Zend API documentation.
  </para>
  
 </chapter>

 <chapter id="chapter-validating">
  <title>Validating Changes</title>

  <para>
   Now that you have a Makefile, you can validate the
   documentation changes you have previously made:
  </para>
  <para>
   <informalexample>
    <programlisting>
$ cd phpdoc
$ make test
    </programlisting>
   </informalexample>
  </para>

  <para>
   Which will generate output similar to this:
  </para>
  <para>
   <screen>
touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
   </screen>
  </para>

  <para>
   If you made a mistake such as forgetting to close a tag or using
   an invalid tag name, <command>make test</command> will report the
   error and give you the line number it found the error at.
  </para>
  <para>
    <screen>
touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
nsgmls:en/chpaters/intro.xml:54:13:E: end tag for "para" omitted, but OMITTAG NO was specified
make: *** [test] Error 1
   </screen>
  </para>
  <para>
   In the above example output, the parser expected to see an end tag
   for &lt;para&gt; at line 54 in the file
   <filename>en/chapters/intro.xml</filename>.
   Using this information, you can go back to the file and correct
   the mistake before committing your changes.
  </para>

  <para>
   In order to check the validity of your XML you may use 
   <literal>make test_xml</literal> as this executes a
   <command>xmllint</command> check on the entire phpdoc tree.  This
   will find problems <command>make test</command> ignores, problems like a
   missing ; or &amp; for an entity.  <command>xmllint</command> is much
   slower than the SGML check and will take roughly 4 times longer to execute
   (and will consume much more memory).
  </para>
  <para>
   <informalexample>
    <programlisting>
$ cd phpdoc
$ make test_xml
    </programlisting>
   </informalexample>
  </para>
  <para>
   Or to simply check the XML validity of one file you may use the
   <filename>xml-check.php</filename> script found in the phpdoc
   <filename>scripts/</filename> directory. This is much faster than
   <command>make test</command> or <command>make test_xml</command> if you
   have only modified one file.  Use it like so:
   <informalexample>
    <programlisting>
$ scripts/xml-check.php en/reference/mysql/functions/mysql-connect.xml
    </programlisting>
   </informalexample>
  </para>
  <para>
   It is important to do a test before committing, because if you
   commit files with errors, this single file will cause the automatic
   build process to halt, and the manual files and downloads
   will not be updated online. This can make phpdoc people angry.
  </para>

  <note>
   <title>When adding a new file</title>
   <para>
    If you're adding a new file be sure to run
    <command>./configure</command> again before <command>make test</command>
    so that your new file will also be checked for validity.
  </para>
 </note>
 
 </chapter>

 <chapter id="chapter-viewing">
  <title>Viewing Your Changes</title>

  <para>
   There are several stylesheets available for generating viewable
   documentation, the most useful will probably be:
   <itemizedlist>
    <listitem>
     <para>
      <literal>html</literal>, the plain html manual found at <ulink
      url="&url.php.manual.plain;">&url.php.manual.plain;</ulink>
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>bightml</literal>, one big HTML file, only available for download at <ulink
      url="&url.php.docdownload;">&url.php.docdownload;</ulink>
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>phpweb</literal>, the main PHP online manual found at <ulink
      url="&url.php.manual;">&url.php.manual;</ulink>
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>install-win.txt</literal>, the text version of the Windows 
      install instructions that goes into the PHP source (as 
      <filename>php-src/win32/install.txt</filename>). It's based off HTML 
      (via lynx) using <filename>install-win.xml</filename>. Before commit, 
      be sure Unix style (\n) line endings are used as the Windows packaging 
      script later converts them to Windows format (\r\n). Both 
      <filename>install-win.txt</filename> and 
      <filename>install-win.html</filename> are generated.
     </para>
     <para>
      Be sure the &amp;install.windows.building; entity is removed from
      <filename>en/install/windows/index.xml</filename> before building
      this file.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>install-unix.txt</literal>, the text version of the Unix 
      install instructions that goes into the PHP source (as 
      <filename>php-src/INSTALL</filename>). It's based off HTML (via lynx) 
      using <filename>install-unix.xml</filename>. Before commit, be sure 
      Unix style (\n) line endings are used. Both 
      <filename>install-unix.txt</filename> and 
      <filename>install-unix.html</filename> are generated.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>pdf</literal>, a PDF version of the manual, currently not
      available online
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>rtf</literal>, a RTF (Rich Text Format) version of the manual,
      currently not available online
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>howto</literal>, this HOWTO document in a simple HTML format:
      <ulink url="&url.php.howto;">&url.php.howto;</ulink>
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   There are also XSL stylesheets available, that are equivalents to the above
   DSSSL sheets. The list includes: <literal>html_xsl</literal>,
   <literal>bightml_xsl</literal>, <literal>phpweb_xsl</literal>,
   <literal>howto_xsl</literal>, <literal>chm_xsl</literal> and
   <literal>fo</literal> (produces a FO file, that can be later transformed to
   PDF using a FO processor, like Apache FOP)
  </para>

  <para>
   To generate a viewable copy of the documentation,
   <command>cd</command> to the <filename>phpdoc</filename> directory
   and issue one of the following commands:
   <informalexample>
    <programlisting>
$ make html
$ make bightml
$ make phpweb
    </programlisting>
   </informalexample>
   To make an actual copy of this HOWTO:
   <informalexample>
    <programlisting>
$ make howto
 -or-
$ make howto_xsl
    </programlisting>
   </informalexample>
   The plain text version of the PHP documentation is made
   by filtering the <literal>bightml</literal> output through lynx.
  </para>

  <note>
   <para>
    Generating viewable documentation is CPU intensive and can take a
    little while to complete. E.g. generating the simple HTML 
    manual takes about 1 hour on a normal computer.
   </para>
  </note>

  <para>
   Where the output files are placed depends on the format you
   built. HTML manuals generate in the <filename>html</filename>
   subdirectory of <literal>phpdoc</literal>, similarly the
   <literal>make phpweb</literal> command will place the files
   in the <filename>php</filename> directory. The place for
   the HOWTO HTML files is <filename>howto/html</filename>.
  </para>
  
  <para>
   If all goes well, you should have your own copy of the
   documentation, including any changes you've made.
  </para>

  <tip>
   <para>
    Instead of generating the whole manual (which takes too much time), you
    can generate just a single section, by issuing the following command:
    <command>xsltproc --stringparam rootid "&lt;ID&gt;" xsl/html.xsl
    manual.xml</command> (replacing <literal>&lt;ID&gt;</literal> by the ID of
    the file/section you want to build.
   </para>
  </tip>

 </chapter>

 <chapter id="chapter-online-generation">
  <title>The Online Generation System</title>

  <para>
   The online generation system is working at <literal>rsync.php.net</literal>.
  </para>
  <para>
   This system generates manuals for all languages
   with a <filename>language-defs.ent</filename> file
   in the translation directory. However the listing of
   languages at <ulink url="&url.php.docs;">&url.php.docs;</ulink>
   and <ulink url="&url.php.docdownload;">&url.php.docdownload;</ulink>
   are static, so only manually added languages show up in
   those listings.
  </para>
  <para>
   This generator system only builds a new online manual,
   and new downloadable files from one language, if
   it is modified in a one day period. The build process
   takes hours for only one language, so not all languages
   can be built in one day. During the generation, a
   <filename>build.log.gz</filename> is saved with build
   information. See the <link linkend="translation-practical">section
   for translators</link> about the <filename>build.log.gz</filename>
   file. If there were some errors in the build process,
   you can find the errors loged in this file.
  </para>
  <para>
   The automatic build process updates the online manual,
   and all downloadable ones, excluding the CHM versions.
   The CHM versions are also built daily, but on a separate
   Windows machine, as the compiler is only available for
   Microsoft Windows.
  </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
-->