Most problems with print output are in the FO processor,
not the DocBook XSL stylesheets. PassiveTeX is another FO
processor that formats verbatim elements properly, and it
runs on Windows as well as Linux. I've written a draft of
a short PassiveTeX Howto article that I've included below.
If you would be willing to try it out and give me feedback,
I'd appreciate it.
Getting started with PassiveTeX
_________________________________________________________________
This article describes how to install and run PassiveTeX.
Installing PassiveTeX
---------------------------
PassiveTeX is an extension of the TeX typesetting system that permits
conversion of XSLFO files to PDF. More accurately, it is an extension
of other extensions such as pdftex, pdflatex, and xmltex. For this
reason, trying to add the necessary packages to an existing TeX
installation can sometimes lead to mismatched components that don't
work together. Because of the large number of files involved in a
complete TeX installation, it can be difficult to sort out the
problems.
Currently the easiest way to get PassiveTeX working is to install a
new TeX system that supports it. Sebastian Rahtz, the author of
PassiveTeX, has assembled such a system and made it available as part
of the TeX Live CD distribution. Version 7 of TeX Live CD defines
several "schemes", which are selections of TeX packages designed for
particular purposes. One of those schemes is called "XML Typesetting".
That scheme includes the PassiveTeX pieces needed to process XSLFO
files generated by the DocBook XSL stylesheets.
The TeX Live CD has support for Windows, Linux, UNIX, and MacOSX
systems. It also permits you to run your TeX processing almost
entirely from the CD, installing just a minimum number of files. Since
the size of a TeX installation for DocBook is over 200 MB, that may be
a necessary option. But it does make the processing run more slowly
because it has to read many files from the CD each time.
To install PassiveTeX from the TeX Live 7 CD:
1. Obtain a TeX Live 7 CD
Instructions for obtaining a TeX Live 7 CD are available at:
http://www.tug.org/texlive.html
You can obtain the CD by joining the TeX User's Group (TUG), or
you can download the CD image and burn your own CD. It is a huge
download and requires a fast Internet connection.
2. Start the installation program
On Windows, the CD may automatically start when you put the CD in
the drive. If not, then run \bin\win32\TeXLive.exe to start it
manually. Then select Install->TeXLive. That will start the setup
wizard.
On Linux or UNIX, run sh install-cd.sh in the top directory of the
CD. The file itself is not executable, which is why you need to
precede it with sh. That command presents a text interface for
selecting installation options.
3. Select the XML Typesetting scheme
As you step through the installation interface, you can select
where TeX installs, what languages you want to support, and other
options. The important step for DocBook is to select the "XML
Typesetting" scheme. If you aren't offered a scheme selection as
part of the options, then your TeX Live CD is older than version 7.
4. Run the installation
After you have selected all the options and scheme, run the
Install and sit back until it completes.
5. Adjust some TeX settings
You need to increase the values of certain TeX parameters to
process DocBook files. The settings are located in the following
file:
Windows:
\Program Files\TeXLive\texmf-var\web2c\texmf.cnf
Linux or UNIX:
/usr/TeX/texmf-var/web2c/texmf.cnf
Make a backup copy of the original file, and then use a text
editor to locate and change the following values to be at least
these sizes:
main_memory = 2500000 (that's 2,500,000)
hash_extra = 50000
pool_size = 500000
save_size = 50000
Confirm that the following values are set:
param_size = 1500
stack_size = 1500
string_vacancies = 45000
pool_free = 47500
nest_size = 500
max_strings = 65000
buf_size = 200000
6. Set environment variables
To use a TeX system, it needs to know where the commands are
located (PATH) and where the TeX configuration files are installed
(TEXMFCNF). So you need to set these two environment variables. On
Windows they should be set automatically, but you should check
them anyway.
Windows:
PATH=C:\Program Files\TeXLive\bin\win32;etc.
TEXMFCNF=C:\Program Files\TeXLive\texmf-var\web2c
Linux and UNIX:
PATH=/usr/TeX/bin:$PATH check this path
TEXMFCNF=/usr/TeX/texmf-var/web2c
export PATH TEXMFCNF
You can test to see if your installation is working by typing at a
command prompt:
pdftex -ini "&pdflatex" pdfxmltex.ini
That will generate a lot of status messages, but should result in a
file named pdfxmltex.fmt.
Using PassiveTeX
---------------------
PassiveTeX will convert a .fo file created using one of the XSLT
processors into a .pdf file. Once the system is set up and working,
you should be able to execute the following command on your .fo files:
pdftex --interaction nonstopmode "&pdfxmltex" myfile.fo
pdftex --interaction nonstopmode "&pdfxmltex" myfile.fo
You want to run the same command twice in order to resolve page
numbers in the table of contents. You'll notice that it generates a
lot of status messages. If you don't end up with a myfile.pdf file,
then something went wrong. All the noise is recorded in a log file
named myfile.log, which you can scan for clues as to what went wrong.
Dissecting this command:
* The pdftex command runs the version of the TeX formatting engine
that generates PDF output instead of the original TeX DVI output.
* The --interaction nonstopmode option forces it to keep going even
if it comes across something questionable. Generally the questions
it asks can only be answered by a TeX expert.
* The "&pdfxmltex" argument tells the formatter to use the TeX
format file named pdfxmltex.fmt that was installed with the XML
Typesetting scheme. This is the PassiveTeX extension that parses
the XSLFO file and applies TeX formatting.
Note
Tables processed by PassiveTeX currently require width specifications
with units in colspec elements. Proportional width specifications do
not work.
--
Bob Stayton 400 Encinal Street
Publications Architect Santa Cruz, CA 95060
Technical Publications voice: (831) 427-7796
Caldera International, Inc. fax: (831) 429-1887
email: bobs@caldera.com