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

 <chapter id="chapter-tools">
  <title>Tools and Setup Instructions</title>
   
  <para>
   What tools you need depends on the operating system you use.
   Linux or some sort of Unix is recommended, although many
   things in phpdoc work on Windows. The very basic things 
   you need to work:
   <itemizedlist>
    <listitem><simpara>CVS account</simpara></listitem>
    <listitem><simpara>Command line CVS client</simpara></listitem>
    <listitem><simpara>Text editor</simpara></listitem>
   </itemizedlist>
   The basic process is to check out (~download) a file
   using the CVS client, then edit it, and finally commit
   (~upload) it to the server. Of course you can find better
   tools to edit XML files than a simple text editor, it
   is just the absolute minimum. It is worth noting that 
   the different translation projects use different encodings,
   so to work with those projects, you need an editor, which
   supports these encodings. The English documentation mostly
   uses ISO-Latin-1 (ISO-8859-1), but some files are UTF-8
   encoded, so you are better equiped with an UTF-8 supporting
   editor. Some more useful tools:
   <itemizedlist>
    <listitem><simpara>Visual CVS client</simpara></listitem>
    <listitem><simpara>XML [capable] editor</simpara></listitem>
    <listitem><simpara>Tools to test your modifications</simpara></listitem>
   </itemizedlist>
   In the following paragraphs, you can find information about
   how to obtain these tools and how to make them work for you.
  </para>

  <para>
   Testing your modifications is the hardest to get working, as you
   need a copy of the English and your translation's language files.
   Also you need to set up the DocBook files, and several other tools.
   The viewable manual, and other formats such as PDF and RTF, are
   currently created using <ulink url="&url.jade;">Jade</ulink> /
   <ulink url="&url.openjade;">OpenJade</ulink> and
   <ulink url="&url.nwalsh;">Norman Walsh's Modular DocBook
   Stylesheets</ulink>. There are other tools used to produce some
   other formats and files. It is recommended to set up Jade to be
   able to test your contributions. Otherwise you can easily cause
   headaches to other team members, or stop the automatic generation
   of the manual files. You'll also need a command line PHP installed
   to work with the test system.
  </para>

  <para>
   <emphasis>
    If you have information about other good XML editors and/or tools
    not mentioned here, please send your suggestion to the phpdoc mailing
    list: <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>.
   </emphasis>
  </para>
  
  <sect1 id="tools-on-linux">
   <title>Tools on Linux</title>
  
   <para>
    Although many tools are preinstalled on the majority of
    Linux systems, we collected some useful information
    about how they can be obtained and installed, if your
    system misses them.
   </para>
   
   <para>
    You will need your favorite text editor and a working
    <link linkend="chapter-cvs">CVS</link> installation. Although
    it is possible to use a simple text editor such as vi 
    to write the XML files, it is recommended to use an
    XML/SGML editor that helps you along and makes sure your
    document is proper XML conforming to the used document type
    definition (DTD). A very good (and free) XML/SGML editor
    is Emacs+PSGML. Both Emacs and CVS are already part of just
    about every Linux distribution available. Read on for more
    information on tools and editors.
   </para>

   <para>
    You will also need <ulink url="&url.autoconf;">autoconf</ulink> to
    build the phpdoc GNU configure script. Many distributions come
    with autoconf already installed. The latest copy can be found at:
    <itemizedlist>
     <listitem>
      <simpara><ulink url="&url.autoconf.ftp;">&url.autoconf.ftp;</ulink></simpara>
     </listitem>
    </itemizedlist>
   </para>

   <sect2 id="tools-on-linux-obtaining">
    <title>Obtaining the Tools</title>

    <para>
     To simplify the installation process of the tools necessary to
     write PHP documentation, we have chosen to detail how to download
     and install the source RPMs from a sourceware mirror. You will
     need a working copy of <ulink url="&url.rpm;">RPM</ulink> installed
     on the machine you wish to install these tools on.
    </para>

    <para>
     These tools are all separate packages and can be downloaded and
     installed directly from the author's websites if you choose to do
     so. You do not have to use these source RPMs, but installing from
     the author's separate packages is out of the scope of this HOWTO.
    </para>

    <para>
     The RPMs with the necessary software can be downloaded from one of
     the following URLs:
    </para>

    <para>
     <itemizedlist>
      <listitem>
       <simpara>
        <ulink url="&url.docbookmirror1;">&url.docbookmirror1;</ulink>
       </simpara>
      </listitem>

      <listitem>
       <simpara>
        <ulink url="&url.docbookmirror2;">&url.docbookmirror2;</ulink>
       </simpara>
      </listitem>
     </itemizedlist>
    </para>

    <para>
     You will need to download the following files. Note, that you won't
     need jadetex if you are not going to generate PDF files, and there
     is no need to set up psgml if you are not using Emacs for editing.
     <itemizedlist>
      <listitem><simpara>jade-1.2.x-y.src.rpm</simpara></listitem>
      <listitem><simpara>jadetex-2.x-y.src.rpm</simpara></listitem>
      <listitem><simpara>psgml-1.2.x-y.src.rpm</simpara></listitem>
      <listitem><simpara>sgml-common-0.1-3.src.rpm</simpara></listitem>
     </itemizedlist>
    </para>

    <para>
     These packages are updated from time to time. Please make sure
     you download the latest version available from the above sites
     (the actual file names may change, so if you find newer files
     than mentioned above, please report, and we can update this list).
    </para>
    
    <note>
     <para>
      We currently use DocBook 4.1.2 for writing phpdoc files, which
      is not the very latest DocBook version, but seems to be sufficient
      for our need. The 4.1.2 DTD is available in the phpdoc folder, and
      style sheets needed for output generation are also there, so there
      is no need to set these up.
     </para>
    </note>
    
    <para>
     You may also consider using <ulink url="&url.openjade;">OpenJade</ulink>
     a well maintained and extended version of Jade (in fact, OpenJade is
     recommended).
    </para>
   </sect2>

   <sect2 id="tools-on-linux-installing">
    <title>Installing the Tools</title> 

    <para>
     Installing the tools is simple. If you downloaded all of the
     above files into a separate directory by themselves, simply issue
     the following command:
    </para>
   
    <para>
     <informalexample>
      <programlisting>
$ rpm -Uvh *.rpm
      </programlisting>
     </informalexample>
    </para>

    <para>
     Or, you can issue them one by one in the following order:
     <informalexample>
      <programlisting>
$ rpm -Uvh jade-1.2.x-4.src.rpm
$ rpm -Uvh jadetex-2.x-0.src.rpm
$ rpm -Uvh psgml-1.2.x-1.src.rpm
$ rpm -Uvh sgml-common-0.1-3.src.rpm
      </programlisting>
     </informalexample>
    </para>

    <para>
     That's it. You should now have necessary tools installed to edit
     and verify your PHP documentation contributions.
    </para>
    
    <para>
     If you choose the OpenJade route, download opensp and openjade.
     Compile and install opensp first, and then openjade.
    </para>

   </sect2>
  </sect1>

  <sect1 id="tools-on-windows">
   <title>Tools on Windows</title>
  
   <para>
    Although the phpdoc environment is based on many Unix
    tools and techniques, there are ways to accomplish the
    same tasks on Windows. It is not too hard to set up a
    Windows working environment with CVS and the DocBook
    tools, but put away your mouse as you will need the
    keyboard for the majority of the tasks! :)
   </para>
   
   <sect2 id="tools-on-windows-obtaining">
    <title>Obtaining the Tools</title>

    <para>
     You need the same tools as on Linux. The very basic
     thing is a command line CVS client, which is included in Cygwin.
     Although you can use GUI tools such as WinCVS or TortoiseCVS,
     we provided instructions only for command line clients in order
     to keep this HOWTO short and simple.
    </para>
    
    <para>
     You are encouraged not to use intelligent WYSIWYG XML editors, such
     as XML Spy, because the often friendly auto-indent, and optimize
     features can make the XML files so different from the one you started
     to work with, that the diff posted to our
     <link linkend="chapter-maillist">mailing lists</link> and used
     by translators will be useless. Emacs is also available for
     Windows if you would like to give it a try, but any basic text
     editor with Linux line ending support will suffice.
    </para>
   
    <para>
     If you want to produce something viewable, or just would
     like to test the modified file before committing (recommended!),
     you need some more tools. To get it running on Windows,
     you'll need these:

     <itemizedlist>
      <listitem>
       <simpara>
        <ulink url="&url.win.cygwin;">Cygwin (linux tools for windows; it's huge...)</ulink>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <ulink url="&url.jade;">Jade (the actual parser, take the windows binary dist)</ulink> or
        <ulink url="&url.openjade;">OpenJade</ulink>
       </simpara>
      </listitem>
     </itemizedlist>
     Note that if you use Cygwin, there is no need to download a
     CVS client, as Cygwin comes with a CVS client built in.
    </para>
   </sect2>

   <sect2 id="tools-on-windows-installing">
    <title>Installing the Tools</title> 

    <para>
     You need to download and install the Cygwin tools. 
     Just select the "Install now!" link and run the supplied
     <filename>setup.exe</filename>. It will guide you through
     the process of installation. These tools are ports of standard
     Unix tools like sed, awk, autoconf, make, perl, ...
     for Windows. 
    </para>
    
    <note>
     <para>
      Be aware, that Cygwin is grown to be a very huge project and
      it includes many programs (such as PostgreSQL and Apache) ported
      to Windows, which are not needed for phpdoc. To install the
      minimal set of required packages select
      <literal>devel/autoconf</literal>, <literal>devel/automake</literal>,
      <literal>devel/make</literal>, <literal>doc/libxml2</literal>,
      <literal>lib/crypt</literal> and <literal>text/openjade</literal>
      along with components, which are selected in setup by 
      default. You may also want to add <literal>devel/cvs</literal>
      to the installation list if you don't have a CVS client yet.
      Do not care about dependencies - they will be selected
      automatically.
     </para>
    </note>
    
    <para>
     Once installed, you will see a "Cygwin Bash Shell" command in
     the Programs menu. Running that, you get a command line which
     behaves same as bash on Unix boxes. If you never worked with
     bash or Unix before, note that there are slashes (/) instead
     of backslashes (\) in paths. If you want to access the
     <literal>foo</literal> directory on drive <literal>c:</literal>
     write it as <literal>c:/foo</literal> instead of
     <literal>c:\foo.</literal>
    </para>
    
    <warning>
     <simpara>
      Do NOT use symlinks with Cygwin, it's buggy.
     </simpara>
    </warning>
    
    <para>
     To build and test the manual, you also need a working command
     line copy of PHP, whose directory should be in the PATH, as it is
     explained in the PHP Manual.
    </para>

    <para>
     If you don't have your phpdoc checkout yet, grab it from CVS. More
     information about CVS can be found in the
     <link linkend="chapter-cvs">CVS section</link> of this document.
    </para>

    <para>
     Change to the dir where your phpdoc snapshot is (or where you 
     want to have it). Use, just like in Windows, the
     <literal>cd</literal> command. In Cygwin, the
     <literal>dir</literal> command is also supported.  Before doing
     this it's important that your Cygwin environment uses full
     paths.  A simple way to initialize this is to first type
     <literal>cd c:</literal> which should then put you in the
     <literal>/cygdrive/c</literal> (c: root) directory.  From here 
     use your commands as usual.
    </para>
    
    <para>
     Now as you are in the <literal>phpdoc</literal> directory, execute:
     <informalexample>
      <programlisting>
autoconf
./configure --with-lang=your_language_code
      </programlisting>
     </informalexample>
     Substitute <literal>your_language_code</literal> with
     a language code you checked out the files of, and would
     like to work on. The <literal>--with-lang</literal>
     parameter is optional. If you don't specify it, the
     default is <literal>en</literal> (English).
    </para>
    
    <para>
     If you didn't get any errors, you're ready to rock&amp;roll.
     Otherwise, you could check out the
     <ulink url="&url.docbook.appa;">installation appendix</ulink>
     of "DocBook: The Definitive Guide". If you think that the problem
     is in the build system, ask on the
     <link linkend="chapter-maillist">mailing list</link>.
    </para>

   </sect2>
  </sect1>

  <sect1 id="tools-on-macosx">
   <title>Tools on Mac OS X</title>

   <para>
    Users of Mac OS X can install the necessary tools using
    <ulink url="&url.macosx.fink;">Fink</ulink>. After Fink is 
    installed, the tools can be set up using the following commands:
    <informalexample>
     <programlisting>
apt-get install openjade
apt-get install libxml
apt-get install xsltproc
     </programlisting>
    </informalexample>
   </para>

  </sect1>
  
  <sect1 id="tools-for-xsl">
   <title>Tools for XSL Stylesheets</title>
  
   <para>
    In order to successfully use the XSL stylesheets
    you must have some XSLT processor. This is sufficient
    for generating HTML version of the documentation.
    If you also want to create a version suitable
    for printing, you will additionally need a
    FO processor.
   </para>
   
   <para>
    This is an operating system independent section,
    as most of the tools are either provided for several
    operating systems, are written in the Java
    language, or provide a version in Java. This means,
    you can run them on virtually any operating system,
    where a Java Virtual Machine is available. See the
    <ulink url="&url.sunjava;">Java homepage</ulink>
    for more information.
   </para>
   
   <note>
    <para>
     Using XSL stylesheets to generate different formats
     of the <literal>phpdoc</literal> XML files is
     <emphasis>optional</emphasis> currently. This method
     is not as well supported as DSSSL stylesheets,
     but is a promising technology. You do not need
     to setup any tools mentioned here if you would
     not like to play with XSL stylesheets. However
     we plan to use XSL in the future for documentation
     generation, and XSL is already in use in the 'new
     CHM edition' and with Livedocs.
    </para>
   </note>
   
   <para>
    The phpdoc <filename>Makefile</filename> has options to
    generate files using the XSL sheets, but these are currently
    experimental (and require xsltproc exclusively). After running
    <filename>./configure</filename> you can run
    <itemizedlist>
     <listitem>
      <simpara>
        <literal>make html_xsl</literal> to generate HTML files
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>make bightml_xsl</literal> to generate one big HTML file
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>make fo</literal> to generate a FO file (Formatting
       Objects file, which will be used by the FO processor to generate
       PDF files for example)
      </simpara>
     </listitem>
    </itemizedlist>
    using XSL sheets.
   </para>
  
   <para>
    The build system only supports <ulink url="&url.xsl.libxslt;">LibXSLT</ulink>
    (also known as xsltproc), available as Windows binaries too at:
    <ulink url="&url.xsl.libxslt.win;">&url.xsl.libxslt.win;</ulink>,
    and also included in current Cygwin setups, if selected for installation.
   </para>

   <note>
    <para>
     As we tested, other XSLT processors, like XT and MSXML cannot handle
     the DocBook XSL stylesheets, so these cannot be used for even
     the simplest HTML creation. <ulink url="&url.xsl.xalan;">Xalan</ulink>
     works with DocBook XSL stylesheets, but the sources of the PHP manual
     currently exceed the limit of max. opened files.
    </para>
   </note>
   
   <para>
    FO processors:
    <itemizedlist>
     <listitem>
      <simpara>
       PassiveTeX: <ulink url="&url.xsl.passivetex;">&url.xsl.passivetex;</ulink>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       FOP: <ulink url="&url.xsl.fop;">&url.xsl.fop;</ulink> (you need version
       0.20.5rc2 or higher)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       XEP: <ulink url="&url.xsl.xep;">&url.xsl.xep;</ulink>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  
  </sect1>
 </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
-->