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:
CVS account
CVS client
Text editor
XML [capable] editor
Tools to test the edited file
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. 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 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 it to the maintainer: phpdoc@lists.php.net.
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.
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:
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:
ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/SRPMS/
ftp://sourceware.cygnus.com/pub/docbook-tools/docware/SRPMS/
You will need to download the following files:
docbook-4.x.src.rpm [see note below]
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
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 enables us to document OO based stuff (currently not used), and we use many new structural elements. So 3.x docbook files are not acceptable. The 4.1.2 DTD is available in the phpdoc directory, and style sheets needed for output generation are also there.
You may also consider using OpenJade a well maintained and extended version of Jade.
Installing the tools is simple. If you downloaded all of the above files into a separate directory by themselves, simply issue the following command:
Or, you can issue them one by one in the following order:
$ rpm -Uvh docbook-4.x.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 |
That's it. You should now have necessary tools installed to edit and verify your PHP documentation contributions.