Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Conversion of Phing's documentation to Docbook
PHP JavaScript Other
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
build
website
xml
.gitignore
readme.markdown

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.