The current User Guide for Phing doesn't feel OK :
- There is are several tasks documented on each manual page,
- The documentation only exists in HTML,
- The source of the documentation is that HTML: it's not made of any structured-format
- There is only an english version, and no translation seems to be planned.
So, this is my attempt to :
- Re-write the documentation in docbook
- Have it available in more than one format: at least HTML and PDF
- Plan for some translations
If you want to see the generated outputs, here are some links for the english version :
(the documentation published there is not necessarily up-to-date!)
Note: those will not always be valid; you should not consider those as the real documentation, and you should not link to those pages/documents!
In order to build the documentation, you will need :
- Phing ; latest stable version is OK
- Apache FOP -- Ubuntu, you can get it with a simple
apt-get install fop
- Microsoft HTML Help Workshop, to build .chm documentation
Other things which are (for now) commited inside the project, but should not be :
build/files/docbook.dtd: the docbook DTD
- You should get it from docbook.org
build/files/geshi: GeSHi v18.104.22.168, to syntax-highlight code
- You should get it from its official website
- And, as a result, you should have
build/files/docbook-csl-1.76.1(or any other version) : the XSL stylesheets, required to generate the HTML, FO, ... outputs
- You should get the
docbook-xslpackage from sourceforge.net
- You should get the
And you will have to copy
build/build.properties; and set the correct values, if needed.
If using FOP >= 0.95 on Debian/Ubuntu, see
build/reade.markdown for some additional informations.
For Microsoft HTML Help Workshop on Linux, see Microsoft HTML Help Workshop with Wine How-to
How to build the documentation
After installing the pre-requisites, and configuring build/build.properties, building the documentation is just a matter of launching one Phing target :
cd build phing
This will generate the documentation in
build/dist en/ fr/
In order to delete all generated files, you just have to launch
Disclaimer: I've only tried to build this documentation on Linux (Ubuntu, latest version); but, in, theory, you should be able to build it from Windows.
Many of the ideas (and some portions of code) I've used here come from what's been done for ZFSTDE -- and there are probably still a few things that need to be configured (like changing the colors in the CSS file, for example).