<?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 works on Windows. The very basic things 
   you need to work:
   <itemizedlist>
    <listitem><simpara>CVS account</simpara></listitem>
    <listitem><simpara>CVS client</simpara></listitem>
    <listitem><simpara>Text editor</simpara></listitem>
   </itemizedlist>
   The basic process is to check out (~download) the 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. Some more useful tools:
   <itemizedlist>
    <listitem><simpara>XML [capable] editor</simpara></listitem>
    <listitem><simpara>Tools to test the edited file</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>
   The last item in the above list (test the edited file) is
   the hardest to get working, as you need a copy of the English
   and your translations language files from the phpdoc tree. 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
   created using <ulink url="&url.jade;">Jade</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 the style
   sheets and Jade to be able to test your contributions. Otherwise
   you can easily cause headaches to other team members.
  </para>

  <para>
   <emphasis>
    If you have information about other good XML editors and/or tools
    not mentioned here, please send it to the maintainer:
    <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
    the 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.
   </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:
     <itemizedlist>
      <listitem><simpara>docbook-3.x-5.src.rpm</simpara></listitem>
      <listitem><simpara>jade-1.2.x-4.src.rpm</simpara></listitem>
      <listitem><simpara>jadetex-2.x-0.src.rpm</simpara></listitem>
      <listitem><simpara>psgml-1.2.x-1.src.rpm</simpara></listitem>
      <listitem><simpara>sgml-common-0.1-3.src.rpm</simpara></listitem>
      <listitem><simpara>stylesheets-0.10-2.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 3.1.7 (not the latest version) for
      writing phpdoc files. This is because there are
      incompatibilities between DocBook 3.x and 4.x currently not
      corrected in the documentation. Probably we will update
      the XML files, and move to DocBook 4.1.2 soon.
     </para>
    </note>

   </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 docbook-3.x-5.src.rpm
$ 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
$ rpm -Uvh stylesheets-0.10-2.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>

   </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 CVS client. You can find one simple command
     line client here at the <ulink url="&url.cvs-win;">CVSHome.org</ulink>
     Win32 download pool. We do not recommend GUI tools such
     as WinCVS, because they can easily screw up the repository
     with files not intended to be there (eg. files with
     uppercased names). The best is to use one command line
     client, as this way you are in control.
    </para>
    
    <para>
     About XML editors, you are encouraged not to use 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 the work with, that the diff posted to our
     <link linkend="chapter-maillist">mailing list</link> and used
     by translators will be useless. Emacs is also available for
     Windows if you would like to give it a try ;)
    </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 tools:

     <itemizedlist>
      <listitem>
       <simpara>
        <ulink url="&url.win.cygwin;">Cygwin (bash for windows; it's huge...)</ulink>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <ulink url="&url.jade;">Jade (the actual parser, take the windows binary dist)</ulink>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <ulink url="&url.nwalsh;">Norman Walsh's modular DocBook stylesheets</ulink>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <ulink url="&url.iso.entities;">Some ISO-entity declarations</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
     process of installation. These tools are port of standard
     Unix tools like sed, awk, autoconf, make, perl, ...
     for Windows.
    </para>
    
    <para>
     Run "Cygwin Bash Shell" command from the Programs menu
     (it will be added here by the previous step). Now 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. (Jade doesn't
       like them, and the shell doesn't handle them very well either)
     </simpara>
    </warning>
    
    <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.
    </para>

    <para>
     If you don't have your snapshot yet, execute CVS (packaged with
     Cygwin). More information about CVS can be found in the
     <link linkend="chapter-cvs">CVS section</link> of this document.
    </para>
    
    <note>
     <simpara>
      If you decide to use another directory in one of the next
      steps, you'll probably need to modify
      <filename>phpdoc/configure.in</filename> manually.
      We do not give any support if you are self-opinionated :)
      In this situation you can specify the DSSSL location
      manually by using the
      <literal>--with-dsssl=C:/path/to/dsssl</literal>
      option with configure.
     </simpara>
    </note>
    
    <para>
     Make sure that you are in the directory where the
     <literal>phpdoc</literal> dir is located. (if you type
     <literal>ls</literal>, you should see
     <literal>phpdoc</literal> listed).
    </para>
    
    <para>
     Type <literal>mkdir phpdoc-tools</literal>, and then unzip:

     <itemizedlist>
      <listitem><simpara>Jade to <literal>phpdoc-tools/jade</literal></simpara></listitem>
      <listitem><simpara>Norman Walsh's DSSSL files to <literal>phpdoc-tools/dsssl/docbook</literal></simpara></listitem>
      <listitem><simpara>the ISO-entities to <literal>phpdoc-tools/iso-entities</literal></simpara></listitem>
     </itemizedlist>

     XSL stylesheets are <emphasis>not necessary</emphasis>
     to generate the html versions of the manual, the DSSSL style
     sheets are used by default. If you think you would like
     to test XSL ones, than unzip Norman Walsh's
     XSL files to <literal>phpdoc-tools/xsl/docbook</literal>. See
     <ulink url="&url.nwalsh.xsl;">&url.nwalsh.xsl;</ulink>
     for more information and downloadable files.
    </para>

    <para>
     Verify that your directory structure looks like this:
     <informalexample>
      <programlisting>
+--phpdoc
|  |
|  +--CVS
|  |
|  +--en
|  |
|  +--...
|
+--phpdoc-tools
   |
   +--dsssl
   |  |
   |  +--docbook (with docbook.dcl etc)
   |
   +--iso-entities (with ISOamsa etc)
   |
   +--jade (with jade.exe etc)
   |
   +--xsl (OPTIONAL!)
      |
      +--docbook (etc)
      </programlisting>
     </informalexample>
    </para>
    
    <para>
     Now go to the <literal>phpdoc</literal> directory, and 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".
    </para>

   </sect2>
  </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 and the XSL
    DocBook Stylesheets. 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 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 XSLT in the future for HTML
     generation, and possibly PDF generation, if we
     can manage to work out how to do it correctly.
    </para>
   </note>
  
   <para>
    XSLT processors:
    <itemizedlist>
     <listitem>
      <simpara>
       Saxon: <ulink url="&url.xsl.saxon;">&url.xsl.saxon;</ulink>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Xalan: <ulink url="&url.xsl.xalan;">&url.xsl.xalan;</ulink>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Gnome LibXSLT: <ulink url="&url.xsl.libxslt;">&url.xsl.libxslt;</ulink>,
       also available as Windows binary:
       <ulink url="&url.xsl.libxslt.win;">&url.xsl.libxslt.win;</ulink>,
      </simpara>
     </listitem>
    </itemizedlist>
   </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.
    </para>
   </note>
   
   <para>
    XSL DocBook Stylesheets: <ulink url="&url.xsl.style;">&url.xsl.style;</ulink>
   </para>
	
   <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>
      </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
-->