Re: Docmentation/FAQs

["Chris Travers" <..hidden..>]

First, on the documentation--

I think the main content needs to be stored in a presentation-neutral
format.  On further consideration, Docbook or even XHTML is probably
less subject to abuse than LaTeX for the simple reason that a greater
separation is enforced between content and presentation.

However-- the main consideration we need to consider is how to ensure
that we have sufficient semantic richness to be able to leverage the
features of renders,  This means that if there are things that LaTeX
handles better than Docbook, then we need to look at ways of encoding
the necessary context information via Docbook standards.  I don;t
really see an obstacle to doing this except that I am not sure that
the current tools will handle things properly, so I am willing to
accept Docbook as long as we understand we *may* have to tweak the
tools if we find issues.

Although I don't have much experience in Docbook yet, the one area in
the documentation that concerns me is index management,  Index entries
should be stored inline in the content and then pulled out by the
renderer.  This probably means using an anchor tag and building index
entries through a preprocessing run of the program.  I don't know how
the tools handle this and I can't find good information on it.  Again,
this is likely to be a tools issue (which ought to be easily solvable)
rather than a format issue (which would be a bigger problem).  Maybe
someone with expertise in the tools can comment?  If not, I will
assume that it is solvable but some work may need to be done.

Now for the templates:

If we can come up with a generic mechanism with links to external
scripts, I see no reason why supporting a variety of mechanisms would
be difficult.  I think we ought to be able to generate XML (for XSLT),
direct LaTeX templates, and the like pretty easily as long as we work
from the premise that we are going to do generic preprocessing.
Indeed any text-based format ought to be supportable pretty easily,
thought the current implementation sucks.

In short, there are two aspects to this issue:
1)  Generation of the invoice and
2)  Preprocessing of a template document (which could be any
text-based format including XML).

I don't understand yet why such a generic process would require
dropping support for formats, though it does need to be greatly
improved so that it can play well with everything.


Best Wishes,
Chris Travers