Глава 14. Writing documentationThis chapter provides a detailed description how to write documentation using one of the supported formats. It is aimed at both PEAR developers that are already maintaining packages in PEAR and at people who are planning to contribute a new package. The DocBook XML formatDocBook is an XML dialect that is used by a wide range of projects to maintain their documentation. Examples for DocBook usage in OpenSource projects are the documentations of KDE and PHP. PEAR has opted for using DocBook, because we believe that it provides a solid foundation for the technical documentation for PEAR packages. The trade-off for using DocBook is that it is relatively hard to use. Testing documentation requires a number of tools to be installed and one needs to learn a (not very complicated) XML dialect. Once one is familiar with how DocBook works, they will enjoy writing documentation with it though. The book [DocBook: The Definitive Guide], written by Norman Walsh and Leonard Muellner and published by O'Reilly & Associates, Inc., is available online and it makes up a great resource for people interested in learning DocBook. Definitely check out the book's "DocBook Element Reference" section. This portion provides detailed information about each element, including which elements can (and must) be used as parents and children. Required softwareEven if DocBook XML can (like any other XML file) be written using a normal text editor, it is optimal for users to install some software on their machine in order to test the validity of the documenting efforts. A list of the required software and a installation instruction can be found in the PHP Documentation HOWTO. Apart from providing information about the software, this HOWTO also provides a ton of other useful information that goes far beyond this chapter. One is encouraged to completely read it. (Chapter II can be skipped, because it only contains information that is very PHP specific.) Unfortunately, installing that software can be difficult under some circumstances. If you are unable to get it working, don't use that as an excuse for not writing documentation. There are two test servers that every two hours automatically download peardoc from CVS and build the manual. Any parsing errors your changes cause will show up in the logs the next time the build happens:
Once the necessary software is in place, one has to get the latest version of the XML sources from PEAR's CVS repository:
If you do not own an account for cvs.php.net, please choose cvsread as the username. When asked for the password, type phpfi. After that the directory ./peardoc will contain a local copy ("sandbox") of the latest sources. If you are not yet familiar with CVS, then the online book "Open Source Development with CVS" will provide you with all the necessary information. Directory structureThis chapter will not describe all the details about the directory structure, because one can find out the essentials about it by browsing the previously created directory peardoc. As a starting point for package documentors peardoc/en/package/ fits well. If one has further questions concerning the directory structure, they can ask on the documentation mailinglist. Writing documentationInstead of a long and boring description for writing documentation using DocBook, we would like to point you to a bunch of "reference documents", from which you should be able to learn quickly:
In addition to the examples above, you will find much more documenation examples by browsing the peardoc directory, which contains your local version of the CVS tree. Especially the directory peardoc/en/packages/ should be of interest for you. You can also browse the CVS module using the web interface, including the raw XML for the file you are presently reading. Translating documentationTranslating documentation is another important task. Not only does new documentation need to be translated into the existing languages, additional languages are welcome. Also, existing translations need to be brought up to date because the English versions have been changed. Help on how to perform the translation process is in the Revision Tracking section of the manual. Questions?We are well aware that we cannot cover all questions about writing DocBook documentation in this chapter. If you have more questions or problems, do not hesitate to get in touch with the documentation team at pear-doc@lists.php.net. To join the pear-doc list send an email to pear-doc-subscribe@lists.php.net.
|
HIVE: All information for read only. Please respect copyright! |