Boost logo

Boost :

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


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

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 ( 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:

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

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:
# TOC generation: this is needed for FOP 0.2, but must not be set to zero
for FOP-0.9 or XEP!
# No indent on body text:
# Margin size:
# Margin size:
# Yes, we want graphics for admonishments:
# Set this one for PDF generation *only*:
# default pnd graphics are awful in PDF form,
# better use SVG's instead:

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

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,


Boost list run by bdawes at, gregod at, cpdaniel at, john at