Re: Improve setup for documentation building with FOP

Peter Eisentraut wrote:
> In order to modernize our documentation tool chain, I have made a few
> tweaks to allow using FOP to build the PDF documentation. I'd like to
> get some testing on different operating systems and versions thereof in
> order to learn whether this solution is robust and easily accessible by
> users and developers, and also whether the resulting documents are
> correct and free of major rendering problems. I'll add it to the
> commitfest for that. Reviewers should ideally just have to install the
> "fop" package that is hopefully supplied by their operating systems and
> then run the make targets mentioned in the patch. I'm aware of a few
> potential pitfalls, but I'd rather not mention them yet in order to get
> unbiased reports.

The FOP-based build works fine for me. I gave the output a look. I
like that text formatted with fixed-width font wraps at the right
margin, instead of continuing beyond it; there are some strange
artifacts about it (such as addition of hyphens in some places, say in
the middle of a configure option); but I think it's nicer than the
output of the other toolchain nevertheless. This willingness to break
in the middle of <pre> formatted elements looks weird in some places;
for example table 17.2 SSL Server File Usage; old output puts the option
name on first line, file path on second line; new output puts option
name on top, file name is split in half.

In the US size PDF, look at page 386; below the "gmake install-world"
there's the bottom-of-page horizontal line, but the paragraph continues
below that. Bug?

Section 17.8 "Encryption Options" is formatted differently; previous
method used indentation for the paragraph after each item, new one uses
a table. I like the old method better. This is notoriously bad in the
"superuser_reserved_connections" entry in "18.3.1. Connection Settings",
and others. Also, the synopsis in PQconnectStartParams entry in 31.1
"Database Connection Control Functions" looks a lot worse. This
manifests in many places, and while it's an improvement in a minority of
them, I think it's a net loss overall.

I like that the new output has horizontal lines at top and bottom of the
text area of the page. In the old method, the page heading (above that
line) contains the chapter number and title, while in FOP it only has
title (no number). I find that number useful. Also, limiting the space
for the title and wrapping if the title is too long seems pointless; see
example of this in chapter "High Availability, Load Balancing and
Replication", where even the word Bal-ancing has been hyphenated.

Formatting of <note>, <tip> and such seems a lot better in FOP. For
<warning>, the old method used a surrounding box; the new one just has a
"Warning" title and indented paragraph, just like for <note> et al.
Doesn't look like a problem to me. It'd be nice to have pretty icons
for these areas.

Formatting of ref links is nicer: for instance, you get something like
which can make those operations much faster (see
Section 14.4.7, “Disable WAL Archival and Streaming Replica-
tion”).
instead of
which can make those operations much faster (see Section 14.4.7).
Not sure if there are cases in which this can be a problem.

[aside: I really wish we didn't paste verbatim psql output in SGML docs ]

<sidebar> renders as grey-background box in FOP, white-background in old
tool. Not sure about this; it looks like the only place with grey
background in the whole manual. We only have one <sidebar> in the
entire SGML source.

Example 19.1 "Example pg_hba.conf Entries" is completely broken (no page
break); renders normally in old method. There are other cases of this,
including libpq sample programs and ECPG.

<url> renders differently: it used to produce a footnote. FOP instead
puts the link text inline. Not really sure about this.

The table 25.1 "High Availability, Load Balancing, and Replication
Feature Matrix" contains a lot of "[bull]", which look odd. Presumably
an image of a bull head would be better?

Tables 27-13 and 27-14 are misformatted in both implementations. Surely
we can do better than overlaying the contents of cells ...

The START_REPLICATION stuff in the Frontend/Backend Protocol chapter is
completely broken. Maybe wrong markup? Also in StartupMessage.

Seems <author> resulted in nothing in the old toolchain, but now it does
print the name of the author. There are only two authors mentioned, in
NLS and GEQO, though. In the GEQO case it's a bit funny because the
author is now mentioned twice.

Speaking of GEQO: the links in its "53.4 Further Reading" section don't
look well in the FOP. And the bibliography looks completely
different.

Oh, the index at the end is not output.

--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services