<?xml version="1.0" encoding="UTF-8"?>

 <chapter xml:id="chapter-configure" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>The Configure process</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>
   Configure (<filename>configure.php</filename>) has several options
   that are used to help validate XML changes before commit, and also 
   setup the build environment. A few examples. 
   <example>
    <title><filename>configure.php</filename> examples</title>
    <programlisting>
<![CDATA[
# List the configure usage options
$ php configure.php --help

# Choose a language (like Japanese), the default is English
# Note: This assumes you checked out ja either as phpdoc-ja or phpdoc-all
$ php configure.php --with-lang=ja

# If a validation error occurred that requires additional debugging info then
# this (--enable-xml-details) memory intensive option may help
$ php configure.php --enable-xml-details

# Force a save even when the XML document is invalid
$ php configure.php --force-dom-save

# To configure one specific book, with APC as an example. This will create
# .manual.book.apc.xml instead of .manual.xml and although slightly faster
# it's not preferred. Consider creating .manual.xml and use PhD to choose ids
# as later described in this HOWTO
$ php configure.php --partial=book.apc
]]>
    </programlisting>
   </example>  
  </para>
  
  <note>
   <title>The future of <filename>configure.php</filename></title>
   <para>
    The <filename>configure.php</filename> script (which replaced autoconf/configure/make) 
    will be replaced by "PhD Setup" in the future. However, feel free to report
    bugs and problems as they occur.
   </para>
  </note>
  
 </chapter>

 <chapter xml:id="chapter-validating" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Validating Changes</title>

  <para>
   The use of <filename>configure.php</filename> will let you know if the XML
   is valid or not. Use it before any commit.
  </para>

  <para>
   It is important to test before committing changes because committing errors
   will cause other contributors tests to fail. This also means the 
   automatic build process will halt, so the manuals files and downloads
   will not be updated online.
  </para>
  <para>
   Before a commit is made, the diff should be reviewed to ensure the 
   patch only contains intentional modifications. For example, whitespace 
   changes are rarely necessary so should be eliminated before commit. For 
   example:
   <example>
    <title>Creating a unified diff / patch</title>
    <programlisting>
<![CDATA[
# Creates a unified diff, and saves it as a file named diff.patch
# Next, open this file in a text editor (like vim) and be certain 
# it looks correct
$ svn diff en/reference/foo/bar.xml > diff.patch
$ vim diff.patch
]]>
    </programlisting>
   </example>
  </para>
  <para>
   If command-line tools are unavailable, consider using a <acronym>GUI</acronym>
   based <acronym>SVN</acronym> tool to create and check the diffs.
  </para>

  <note>
   <title>When adding a new file</title>
   <para>
    Be certain to run <command>php configure.php</command> after adding a new file
    as otherwise the new file will not be validated or built.
  </para>
 </note>
 
 </chapter>

 <chapter xml:id="chapter-viewing" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Viewing Your Changes</title>

  <para>
   After being certain the diff looks commit worthy, and the XML validates, it
   may be worthwhile to see how the change will look after the manual is built.
   We use <link xlink:href="&url.phd;">PhD</link> to build the manual with several 
   themes and formats available to create viewable documentation, including:
   <itemizedlist>
    <listitem>
     <para>
      <literal>html</literal>, the plain html manual found at <link
      xlink:href="&url.php.manual.plain;">&url.php.manual.plain;</link>
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>bightml</literal>, one big HTML file, only available for download at <link
      xlink:href="&url.php.docdownload;">&url.php.docdownload;</link>
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>php</literal>, the main PHP online manual found at <link
      xlink:href="&url.php.manual;">&url.php.manual;</link>. You'll need to
      setup a <link xlink:href="&url.php.mirroring;">phpweb mirror</link> 
      to view these locally.
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   By default, all of the above themes are built together. Use the
   <literal>--theme</literal> option to alter this behaviour.
  </para>

  <note>
   <title>More information about PhD</title>
   <para>
    The PHP Manual uses the
    <link xlink:href="&url.phd;">PhD build system</link> which
    must be installed separately to build the manual.
   </para>
  </note>

  <para>
   Example usage for using PhD to build the manual:
   <example>
    <title>Example using PhD to build the PHP Manual</title>
    <programlisting>
<![CDATA[
# See all the phd options
$ phd -h

# Working in the phpdoc is optional, as it may also be passed to phd
$ cd /path/to/phpdoc/dir

# First, run configure
$ php configure.php

# Using phd to build the entire manual
$ phd -d .manual.xml

# Or build just one part, with book.apc as an example id
# And also we'll just create the bightml file here
$ phd -d .manual.xml -p book.apc -t bightml
]]>
    </programlisting>
   </example>
  </para>
  <para>
   The built files are placed in the current working directory
   within <filename>php/</filename>, <filename>html/</filename>, 
   and as <filename>bightml.html</filename> respectively. 
  </para>
  
  <para>
   If all goes well, you should have your own copy of the
   documentation, including any changes you've made.
  </para>

 </chapter>

 <chapter xml:id="chapter-online-generation" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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 <link xlink:href="&url.php.docs;">&url.php.docs;</link>
   and <link xlink:href="&url.php.docdownload;">&url.php.docdownload;</link>
   are static, so only manually added languages show up in
   those listings.
  </para>
  <para>
   The build process updates the online manual,
   and all downloadable ones, excluding the CHM versions.
   The CHM versions are built 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
-->