Re: No printable 7.1 docs? - Mailing list pgsql-hackers

> My feedback at this time is mostly the desire to know a bit better
> what prevents the hardcopy docs from being built automatically.  I am
> currently having some trouble compiling jadetex, so I can't take a
> look at the generated PDF yet, but I assume there's something wrong
> with it.  That seems like a big deficiency in the doc tools, which
> suprises me, given that they're rather large projects that have been
> used by other large projects for quite a while.

Hmm. Actually, afaik we were the first large open source project to
successfully use the jade toolset for docs. Others have used our project
as an example to help get them going, since as you have already found
out getting the tool chain completely set up is not trivial.

There are at least a few reasons why automatically generating hardcopy
without a final adjustment step is not currently feasible:

1) Table column alignment is not ideal. Many tables are generated with
same-width columns and some end up with large indents on each column.
They just don't fit on the page without adjustments. That is for RTF;
table support in jadetex has always been problematic.

2) Reference pages have a problem. It has *always* been the case that
our reference pages do not format correctly. afaict it is is a problem
with jade->RTF (since the problem shows up in both Applixware and
M$Word) but I do not have much insight into RTF conventions so have not
tracked it down. Very time-consuming hand-editing is required :(

3) Page breaks are not always ideal. Some hand adjustments are desirable
to get a better flow to the docs, especially wrt examples and lists; you
don't want them breaking between pages if you can avoid it, especially
with short examples.

4) Table of contents page numbers are not correct in the RTF output, so
a new ToC must be generated in Applixware or Word.

> My interest is partly to be able to compile the docs on my own, and
> partly research - I'm involved in the development of an application
> that has some hefty documentation requirements, and I was hoping that
> SGML + free software would come to the rescue.  If it's just a matter
> of time and effort, this may be an big enough area of overlap with
> work that I can spend Official Time and/or Official Money on it.

SGML+freeSW will do what you need. You can generate hardcopy
automatically, but I'm not sure it is realistic to expect a toolset to
do this for a complicated document without *any* hand adjustments. The
time-saving leverage is still tremendous though, and using these tools
is a net win imho.

Good luck!
                        - Thomas