Re: Book titles changed?

Thomas Lockhart writes:

> I notice that the book titles now include a PostgreSQL version number
> and do not have a date or edition information associated with them. Was
> this changed because DocBook was not handling it correctly, or for
> stylistic reasons? istm that the version number should not be in the
> title, but rather in edition info which is typical for other books.
> Comments?

I added the version number (before 7.1, I believe) to alleviate the
confusion at the time about which docs where the released and which the
under-development ones. It has the advantage (at least considered in the
context of why it was originally added) that the version number appears on
top of each HTML file.

There is other markup for including release and version information, but I
think this is mostly useful for books that are published on their own and
have very formal rules about this metadata. Since each new release of our
docs covers a different software, it seems okay to change the title to go
along. But is there some specific appearance you had in mind?

> I'm also not certain what I should be seeing for index information in
> the rtf output. The first time through, jade went into an infinite loop
> processing the tutorial. I did a "make clean" and tried again, and it
> goes to completion just fine. But the console output the second time
> through was slightly different, and omitted mention of some (presumably)
> intermediate files. And the index section for the tutorial was empty.

I haven't seen infinite loops in jade for a while, but processing the
index can take a very long time because it has to scan the entire document
to find the links.

The way the index is built is this: First you build the HTML docs. This
leaves a file HTML.index which contains the index information in some
internal format. This file is processed with collateindex.pl to produce
an index in SGML markup (named bookindex.sgml). This file is included in
the books via a system entity (like all the other things are included).
Then you can build whatever format you want. If you build without first
doing an HTML build (or if you do the first HTML build) then
collateindex.pl is called to create an empty index.

So basically you need to do:

make clean
make tutorial.html
make tutorial.rtf

The last step takes about 30 sec on my system.

As for how the index should look, it's basically like in a regular book,
two columns, big letters to head the sections, and small entries with page
numbers. It should be at the very end, after the bibliography.

> For the Developer's Guide, there was no index section generated. Is this
> expected?

The Developer's Guide and the Reference Manual don't have indexes
currently. The Developer's Guide hasn't been indexed because it seems a
lower priority to make it user-friendly. As for the Reference Manual, I'm
not sure if it's useful to index it, because by its nature the table of
contents and the See Also sections provide that functionality.

> btw, the hardcopy generation process is much smoother this time through,
> probably taking less than 20 minutes for the tutorial.

I plan to provide an experimental release of docs in PDF format generated
by pdfjadetex. With the latest stylesheets plus some patches the output
looks pretty good now, plus you get bookmarks and web links. The overly
pedantic TeX line-breaking algorithm is making trouble, but this can be
fixed by tweaking the .tex file. The bitmap images in the Programmer's
Guide look absolutely terrible in this output, though.

Btw., I think to get correct index output you need some patches for the
stylesheets, some of which may have made it into their CVS already. This
relates in particular to resolving the page numbers that the index entries
point to. Since the RTF backend pretty much doesn't handle page numbers
anyway you might not be affected by this, but if you are then I can send
you the required patches. (Building the stylesheets from CVS is a bear.
I haven't succeeded yet.)

--
Peter Eisentraut peter_e(at)gmx(dot)net