<?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 format.
  </para>

  <para>
   The <filename>Makefile</filename> controls serveral aspects
   of how 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:
   <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 it 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/functions/strings.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/functions/strings.xml</filename>.
   Using this information, you can go back to the file and correct
   the mistake before committing your changes.
  </para>
  
  <para>
   It is important to do a test before commiting, because if you
   commit files with errors, this single file will cause the automatic
   build process to halt, and the manual files and downloads
   wont be updated online. This can make phpdoc people angry.
  </para>
 </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>pdf</literal>, a PDF version of the manual found at <ulink
      url="&url.php.manual.pdf;">&url.php.manual.pdf;</ulink>
     </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>
   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
$ make pdf
$ make rtf
    </programlisting>
   </informalexample>
   To make an actual copy of this HOWTO:
   <informalexample>
    <programlisting>
$ make howto
    </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 7m 30s on a 700MHz box.
   </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>

 </chapter>

 <chapter id="chapter-using-xsl">
  <title>Using XSL Stylesheets</title>

  <para>
   Currently using XSL stylesheets to generate output
   of XML files is not as well supported as using DSSSL
   style sheets. This is because XSL stylesheets are not
   as customized as DSSSL ones, and XSL tools are not as
   widely used, and standardized.
  </para>
  
  <para>
   At this time there are no XSL specific targets in
   <filename>Makefile</filename>. This is because there
   are not standardized ways to invoke XSLT processors.
   To use XSL stylesheets you must run the
   <filename>configure</filename> script and tell it,
   where your copy of XSL DocBook Stylesheets is placed.
   The majority of XSLT processors require an URL instead
   of a filename, so be sure to prepend
   the <literal>file:///</literal> schema before path:
   <informalexample>
    <programlisting>
$ autoconf
$ ./configure --with-xsl=file:///path/to/docbook/xsl/styles
    </programlisting>
   </informalexample>
  </para>
  
  <para>
   Configure will create four files:
   <filename>html.xsl</filename>,
   <filename>bightml.xsl</filename>,
   <filename>htmlhelp.xsl</filename>,
   <filename>print.xsl</filename> among others. These files
   can be used to generate the desired output.
   <filename>html.xsl</filename> generates a set of small
   HTML files, <filename>bightml.xsl</filename> generates
   one large HTML file, <filename>htmlhelp.xsl</filename>
   generates source files processable by HTML Help Workshop
   and <filename>print.xsl</filename> generates a file
   with FO objects suitable for further processing with
   some FO processor.
  </para>
  
  <para>
   Invocation of XSLT processor is processor dependent,
   for now suppose that you have a shell script called
   <filename>saxon</filename> which is able to invoke the
   Saxon processor. Some examples:
   <informalexample>
    <programlisting>
$ mkdir html
$ saxon manual.xml html.xsl
$ saxon manual.xml htmlhelp.xsl
$ saxon -o bigmanual.html manual.xml bightml.xsl
$ saxon -o manual.fo manual.xml print.xsl
    </programlisting>
   </informalexample>
   Use the appropriate command from the examples above
   to generate the desired output as described above.
   If you would like to generate HTML Help output, you
   must run the Microsoft HTML Help Compiler after
   processing. To get a PDF from the FO file, you must
   run some FO processor on the
   <filename>manual.fo</filename> file.
  </para>
  
  <note>
   <para>
    Generating <filename>bigmanual.html</filename> with Saxon
    (using JDK 1.3) takes about two minutes on a Celeron 400
    computer. Generating FO files takes about two times more
    + plus time required to run the FO processor. Generating
    chunked version or HTML Help version of manual takes about
    60 minutes.
   </para>
  </note>
  
  <note>
   <para>
    Not all customization from DSSSL are backported to XSL,
    so some things are not as pretty as in DSSSL output
    <emphasis>currently</emphasis>.
   </para>
  </note>
 </chapter>

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

  <para>
   The online generation system is working
   at <ulink url="&url.php.rsync;">&url.php.rsync;</ulink>.
  </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</filename> is saved with build
   information. See the <link linkend="translation-practical">section
   for translators</link> about the <filename>build.log</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
-->