Chapter 2. Tools and Setup Instructions

Table of Contents
2.1. Tools on Linux
2.2. Tools on Windows
2.3. Tools on Mac OS X
2.4. 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 work on Windows. The very basic things you need to work:

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:

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

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 Jade / OpenJade 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 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.

If you have information about other good XML editors and/or tools not mentioned here, please send your suggestion to the phpdoc mailing list: [email protected].

2.1. Tools on Linux

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.

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. Read on for more information on tools and editors.

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

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

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

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

  • sgml-common-0.1-3.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 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.

You may also consider using OpenJade a well maintained and extended version of Jade (in fact, OpenJade is recommended).

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

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

If you choose the OpenJade route, download opensp and openjade. Compile and install opensp first, and then openjade.