[izpack-devel] Documentation migration plan

[Julien Ponge]

Hi everyone,

I have started the transition of the documentation to reStructured
text. You will find in src/doc-reST the first chapters that have been
extracted.

The migration phases will be the following ones.

1. Extract the text from the old documentation and put into
reStructured document files, one per chapter. There should be no
modification, the goal here is not to have a perfect extraction but
have a decent base to get started.

2. Create 2 'main' reStructured text documents: one which is tailored
for HTML ouput and one which is tailored for LaTeX/PDF output. The
reason here is that HTML is better read when split through several
files rather than when put into a single document. By contrast,
generating the LaTeX/PDF version needs the output to be done in a
single file.

3. Provide the automated scripted build support. Provide an anchor in
the Ant build to call the documentation building chain.

4. Enhance the markup, fix typos, rewrite unclear paragraphs,

I won't have time to work on this for a few days, so volunteers are
welcome for performing the extraction of the other chapters. I will
handle the rest of the 2, 3 and 4 phases of course :-)

If you need help on reStructured Text, then please go to:
* http://docutils.sourceforge.net/docs/user/rst/quickref.html
* http://docutils.sourceforge.net/docs/ref/rst/directives.html

Cheers