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:
CVS account
Command line CVS client
Text editor
Visual CVS client
XML [capable] editor
Tools to test your modifications
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].
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:
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).
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 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.