Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Conversion of Phing's documentation to Docbook

branch: master
readme.markdown

Introduction

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.

Ticket #408 and r421 are a first step to re-writing the documentation in docbook; but those are quite old (december 2009), and have not been really active...

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!

Pre-requisites

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
  • build/files/geshi : GeSHi v1.0.8.10, to syntax-highlight code
    • You should get it from its official website
    • And, as a result, you should have build/files/geshi/geshi.php, build/files/geshi/geshi/php.php, build/files/geshi/geshi/xml.php, ...
  • build/files/docbook-csl-1.76.1 (or any other version) : the XSL stylesheets, required to generate the HTML, FO, ... outputs

And you will have to copy build/build.properties.dist to 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

phing clean

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.

Thanks

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).

Something went wrong with that request. Please try again.