I'm coming into this feeling that I need to be convinced that we
actually have to change the base format for the main spec documents.
Its a significant time since I used docbook, but I did do all my
documentation sets in it for a few months (because it seemed to be a
better long term bet than LaTeX at the time). However I dropped it and
translated documents out of it after that period because:-
* I just don't enjoy pain that much
* The output quality was horrid (Philip mentions the typographical
quality)
* LaTeX hasn't died yet
I would be unhappy about moving the current format into a less rich
environment, and if we lose information about the content function (ie
by having to lose differentiation of options, flags, addresses etc in
the source) I would consider that to be a retrograde step. An
alternative I guess would be to have our own DTD with bells and whistles
as required - and a cvs (or other version system) which enforced
validation before checkin.
In terms of what we need to get out, we obviously need:-
* Printable format - with right (ie ISO) and wrong (US Letter)
format outputs. This pretty much means either PS or probably
better now PDF (ideally with indexing).
* On-line readable form - ie HTML or the various related things.
We should also be using id and class tagging on HTML so the
formatting can be made appropriate using CSS etc.
* ASCII.
I don't know how much texinfo is really needed - I think I asked for it
in the early days because it was a good intermediate format that I could
use to generate structured HTML from.
However I could well be convinced at present to stay with SGCAL format
and write stuff to spit out docbook/xml or some other good intermediate
format.
As for diagrams, SVG is good, although the tools I have used for them up
to now have not been as good as I would like, but they are improving
reasonably quick and its becoming a standard output format for several
other tools both free and otherwise.
It would also be worth considering having dot and the other graphviz
formats used for some classes of diagrams. See
http://www.graphviz.org/
I do not see wiki stuff as currently being a good place to put the main
documents. However I am hoping they can contribute to the document
development. Maybe the way here is to have a wiki output format which
we spit new releases into, and then monitor changes to those trees to
see how people are updating those documents. That would require some
work to make it work well. This is not unlike the postgresql
documentation which has all pages in a form where comments can be added
to the bottom.
Nigel.
--
[ Nigel Metheringham Nigel.Metheringham@??? ]
[ - Comments in this message are my own and not ITO opinion/policy - ]
