Chapter 2. Tools and Setup Instructions

Table of Contents
2.1. Tools on Linux
2.2. Tools on Windows
2.3. Tools for XSL Stylesheets

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:

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:

In the following paragraphs, you can find information about how to obtain these tools and how to make them work for you.

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 Jade and Norman Walsh's Modular DocBook Stylesheets. 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.

If you have information about other good XML editors and/or tools not mentioned here, please send it to the maintainer: phpdoc@lists.php.net.

2.1. Tools on Linux

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.

You will need your favorite text editor and a working CVS 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.

You will also need autoconf to build the phpdoc GNU configure script. Many distributions come with autoconf already installed. The latest copy can be found at:

2.1.1. Obtaining the Tools

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 RPM installed on the machine you wish to install these tools on.

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.

The RPMs with the necessary software can be downloaded from one of the following URLs:

You will need to download the following files:

  • docbook-3.x-5.src.rpm

  • jade-1.2.x-4.src.rpm

  • jadetex-2.x-0.src.rpm

  • psgml-1.2.x-1.src.rpm

  • sgml-common-0.1-3.src.rpm

  • stylesheets-0.10-2.src.rpm

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).

Note: 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.

2.1.2. Installing the Tools

Installing the tools is simple. If you downloaded all of the above files into a separate directory by themselves, simply issue the following command:

$ rpm -Uvh *.rpm

Or, you can issue them one by one in the following order:

$ 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

That's it. You should now have necessary tools installed to edit and verify your PHP documentation contributions.