DocBook

All Phing reference documentation is written using the DocBook5 XML markup (see DocBook Project). The main advantage with DocBook is that it is a single source but multiple outputs. These document sources can be rendered into many possible output formats such as (X)HTML, PDF, EPub, Webhelp, RTF, Text and many more. Another advantage, inherit with the text based XML format, is that the document sources are all completely text based written using UTF-8 encoding. Only a plain text editor is required to extend or edit this documentation.

However, XML tends to be quite verbose and even if a plain text editor technically is all that is needed the actual entering of text will be made much easier with custom XML editor. These editors can be used to hide the XML tags and do auto-completion and on-the-fly validation to make sure that what is written is a valid DocBook5 document.

To work with the documentation we recommend to use one of the free XML/DocBook aware editors available. For example

The sources for the documentation are included under the docs/docbook5 directory. The DocBook sources are split into several files in order to make it more maintainable using the XML standard XInclude (see XML Inclusions (XInclude) Version 1.0).

For the writing of the book only a subset of all available DocBook elements are used as shown in the section called “DocBook v5 elements used in the manual and their meaning”

As of this writing the build process has been validated using version 1.78.1 of the DocBook5 stylesheets.

Important

Make sure all documentation is written using UTF-8 text encoding.