Re: Improve setup for documentation building with FOP - Mailing list pgsql-hackers

On 9/16/13 12:19 PM, Alvaro Herrera wrote:
> 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.

The wrapping and hyphenation is a complex issue.  I think we agree that
it's generally better to do suboptimal wrapping than to have the content
run off the page.  Everything between that is, AFAICT, a matter of
fine-tuning various parameters and attributes.

> 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?

Yeah, no idea how that can happen.

> 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.

Yep.  Fixed by setting an option that turns it back to the old way.

> 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.

Made a note that fix that later.

> 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.

Could be fine-tuned later.

> <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.

Hmm, maybe it's there to keep the printers honest. ;-)  It would be easy
to change this if desired.

> 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.

I can't reproduce that.  What version of FOP are you using?  I have 1.1.

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

Changed back to footnote.

> 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?

This is an artifact of the SGML to XML conversion.  Already fixed in
separate commit.

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

This also needs to be addressed by adjusting the wrapping and
hyphenation rules.  Or we could manually tweak it by adding some "zero
width space" characters.  It would need to be checked how that would
affect other output formats, however.

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

Same issue as with "Encryption Options" etc. above.

> 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.

I propose to remove those two author sections.  In the GEQO chapter, the
information is already present, and in the NLS case, well, I don't care.

> 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.

I see.  That is customizable, but maybe not the way it looks in the old
output.  We might need to reassess the entire bibliography at some point
anyway.  It's not really well-maintained.

> Oh, the index at the end is not output.

Fixed in separate commit.

Updated patch attached.


>From 0cfc14672eb14ffddda62f6bf0c572fd1fade592 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Wed, 11 Sep 2013 10:20:27 -0400
Subject: [PATCH v2] doc: Improve setup for documentation building with FOP

Add a makefile rule for building PDFs with FOP.  Two new build targets
in doc/src/sgml are postgres-A4-fop.pdf and postgres-US-fop.pdf.

Run .fo output through xmllint for reformatting, so that errors are
easier to find.  (The default output has hardly any line breaks, so you
might be looking for an error in column 20000.)

Set some XSLT parameters to optimize for building with FOP.
---
 doc/src/sgml/Makefile          | 18 +++++++++++++++---
 doc/src/sgml/geqo.sgml         | 24 ------------------------
 doc/src/sgml/nls.sgml          |  7 -------
 doc/src/sgml/stylesheet-fo.xsl | 11 +++++++++++
 4 files changed, 26 insertions(+), 34 deletions(-)

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 0ca6f58..063feea 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -268,12 +268,24 @@ xslthtml-stamp: stylesheet.xsl postgres.xml
 htmlhelp: stylesheet-hh.xsl postgres.xml
     $(XSLTPROC) $(XSLTPROCFLAGS) $^

-%-A4.fo: stylesheet-fo.xsl %.xml
+%-A4.fo.tmp: stylesheet-fo.xsl %.xml
     $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^

-%-US.fo: stylesheet-fo.xsl %.xml
+%-US.fo.tmp: stylesheet-fo.xsl %.xml
     $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^

+FOP = fop
+XMLLINT = xmllint
+
+# reformat FO output so that locations of errors are easier to find
+%.fo: %.fo.tmp
+    $(XMLLINT) --format --output $@ $^
+
+.SECONDARY: postgres-A4.fo postgres-US.fo
+
+%-fop.pdf: %.fo
+    $(FOP) -fo $< -pdf $@
+
 epub: postgres.epub
 postgres.epub: postgres.xml
     $(DBTOEPUB) $<
@@ -391,7 +403,7 @@ clean:
 # index
     rm -f HTML.index $(GENERATED_SGML)
 # XSLT
-    rm -f postgres.xml postgres.xmltmp htmlhelp.hhp toc.hhc index.hhk *.fo
+    rm -f postgres.xml postgres.xmltmp htmlhelp.hhp toc.hhc index.hhk *.fo *.fo.tmp
 # EPUB
     rm -f postgres.epub
 # Texinfo
diff --git a/doc/src/sgml/geqo.sgml b/doc/src/sgml/geqo.sgml
index 92276fc..e0f8adc 100644
--- a/doc/src/sgml/geqo.sgml
+++ b/doc/src/sgml/geqo.sgml
@@ -1,30 +1,6 @@
 <!-- doc/src/sgml/geqo.sgml -->

  <chapter id="geqo">
-  <chapterinfo>
-   <author>
-    <firstname>Martin</firstname>
-    <surname>Utesch</surname>
-    <affiliation>
-     <orgname>
-      University of Mining and Technology
-     </orgname>
-     <orgdiv>
-      Institute of Automatic Control
-     </orgdiv>
-     <address>
-      <city>
-       Freiberg
-      </city>
-      <country>
-       Germany
-      </country>
-     </address>
-    </affiliation>
-   </author>
-   <date>1997-10-02</date>
-  </chapterinfo>
-
   <title>Genetic Query Optimizer</title>

   <para>
diff --git a/doc/src/sgml/nls.sgml b/doc/src/sgml/nls.sgml
index 5bac66e..5f52fd4 100644
--- a/doc/src/sgml/nls.sgml
+++ b/doc/src/sgml/nls.sgml
@@ -1,13 +1,6 @@
 <!-- doc/src/sgml/nls.sgml -->

 <chapter id="nls">
- <chapterinfo>
-  <author>
-   <firstname>Peter</firstname>
-   <surname>Eisentraut</surname>
-  </author>
- </chapterinfo>
-
  <title>Native Language Support</title>

  <sect1 id="nls-translator">
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index aafc946..abaff0e 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -6,6 +6,17 @@
 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
 <xsl:include href="stylesheet-common.xsl" />

+<xsl:param name="fop1.extensions" select="1"></xsl:param>
+<xsl:param name="tablecolumns.extension" select="0"></xsl:param>
+<xsl:param name="ulink.footnotes" select="1"></xsl:param>
+<xsl:param name="use.extensions" select="1"></xsl:param>
+<xsl:param name="variablelist.as.blocks" select="1"></xsl:param>
+
+<xsl:attribute-set name="monospace.verbatim.properties"
+                   use-attribute-sets="verbatim.properties monospace.properties">
+  <xsl:attribute name="wrap-option">wrap</xsl:attribute>
+</xsl:attribute-set>
+
 <!-- Change display of some elements -->

 <xsl:template match="command">
--
1.8.4.rc3