[boost] Improving PDF generation - a common look and feel?

From: John Maddock (john_at_[hidden])
Date: 2007-05-08 05:53:51

Folks,

I've been working on improving our ability to generate PDF's from 
Quickbook/Docbook source using a "torture-test" consisting of a subset of 
the Math lib docs.  I have some questions/feedback required, but first some 
observations:

FO Generators:
~~~~~~~~~~~~~~

I've tried three FO processors:

Apache FOP-0.23: lot's of flow control issues, and SVG rendering problems. 
Don't use unless you have to.

Apache FOP-0.93 (latest stable release): Some flow control issues, but 
hugely improved compared to 0.23.  Doesn't render symbol characters (Greek 
characters for example) correctly without manually editing the FO output.

XEP from RenderX (www.renderx.com): Everything I've tried just plain works 
first time.  It's command line compatible with FOP so it fit's into 
Boost.Build with just a trivial change to your user_config.jam.  Only 
downside is that it's a commercial product and the free personal edition 
puts a small logo at the bottom of each page.

Test outputs from each can be found in the vault: 
http://boost-consulting.com/vault/index.php?&direction=0&order=&directory=PDF%20Test

Improving Our Stylesheets
~~~~~~~~~~~~~~~~~~~~~~~~~

I've made some changes (not committed yet) to our fo.xsl stylesheet to:

* Syntax highlight C++ code.
* Put a box around code blocks and admonishments.
* Improve the appearance of tables.
* Added some keep-together instructions to improve flow-control around 
tables/code/admonishments.

I've tried to mimic our HTML stylesheets as far possible, and the effects 
can be seen in the test PDF's.

The Questions:
~~~~~~~~~~~~~~

1) How do folks feel about the look and feel of these: are these heading in 
the right direction?
2) Do we want a consistent look/feel across all Boost-PDF's?  If yes, is it 
OK to commit the stylesheet changes (diff's attached)?
3) Many of the page layout options (margins etc) I'm using are expressed as 
xsl-params in my Jamfile, should these be in the fo.xsl as well?  Currently 
I have:

# PDF Options:
# TOC Generation: this is needed for FOP-0.9 and later:
# <xsl:param>fop1.extensions=1
# TOC for XEP only:
<xsl:param>xep.extensions=1
# TOC generation: this is needed for FOP 0.2, but must not be set to zero 
for FOP-0.9 or XEP!
<xsl:param>fop.extensions=0
# No indent on body text:
<xsl:param>body.start.indent=0pt
# Margin size:
<xsl:param>page.margin.inner=0.5in
# Margin size:
<xsl:param>page.margin.outer=0.5in
# Yes, we want graphics for admonishments:
<xsl:param>admon.graphics=1
# Set this one for PDF generation *only*:
# default pnd graphics are awful in PDF form,
# better use SVG's instead:
<xsl:param>admon.graphics.extension=".svg"

4) Do we have a consistent location for PDF downloads: if not should we 
have?

Outstanding Issues:
~~~~~~~~~~~~~~~~~~~

The biggest one is that PDF generation is a lot harder than it should be 
with bjam: if we could get FO's and PDF's placed in a "pdf" subdirectory 
that would help enormously - currently they get generated in a directory of 
bjam's choosing under bin.v2 which results in all links to images breaking 
:-(  FO generation also fails if the FO file already exists.  So basically I 
need a Boost.Build expert to help with these: or at least explain how the 
existing rules work!

Anyway, thanks in advance for any feedback you may have,

John.