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.