I shortened up the documentation a little bit (like a good editor tries
to do :-) ).
To work around an issue with <programlisting> in docbook - we need to
put the first and last lines of the listing on the same line as the
<programlisting> tag - otherwise the formatting gets an extra space at
the top / bottom.
Also, it looks better in the output to start each line within a
<programlisting> in column 1 unless you intend to indent. (I removed
the extra 4 spaces in front of each line.)
I'm not sure it's better or not, but for <programlisting>s that are
introduced by a preceeding paragraph, I put the <programlisting> within
the <para> ... </para> tags. (Docbook allows this kind of nesting; you
can even nest <para>s ). It's possible that docbook formatting might
take advantage of this additional semantic info to better lay things out
(e.g. it could try and avoid page breaks).
When I ran the build process, I noticed a couple of FOP reported
formatting errors that look like:
[ERROR] Areas pending, text probably lost in line <followed by the
line text ....>
These result in actual loss of text - in one case the word "science" was
lost, in the other, the page number in a cross reference. I've posted a
question on docbook-apps mailing list to find out how to "work-around"
these errors, coming from FOP. FOP, by the way says in their news
9 January 2007 - Apache FOP 0.93 released
The Apache FOP team is proud to present to you the first production
grade release of the new FOP codebase. This release has the new API
first introduced in release 0.92 beta. It contains again many bug fixes
and new features.
So - at some point, we might try switching - but I'm guessing that would
be a big job...
-Marshall
