PassiveTeX

Summary

• PassiveTeX is a library of TeX macros which can be used to process an XML document which results from an XSL transformation to formatting objects.
• PassiveTeX provides a rapid development environment for experimenting with XSL FO, using a reliable pre-existing formatter
• Running PassiveTeX with the pdfTeX variant of TeX generates high-quality PDF files in a single operation.
• PassiveTeX shows how TeX can remain the formatter of choice for XML, while hiding the details of its operation from the user.

How does it work?

PassiveTeX relies heavily on work by David Carlisle (his namespace-aware XML parser written in TeX, xmltex), and was developed from my JadeTeX macros for processing DSSSL via Jade.

Taking the XML version of the TEI Lite guidelines (teiu5.xml, with DTD teixlite.dtd), we apply an XSL stylesheet (see my page of TEI style sheets), and run it through Mike Kay's Saxon XSL processor:

  java com.icl.saxon.StyleSheet -o teiu5.fo teiu5.xml tei.xsl 

(assuming you have saxon.jar and sax.jar on your CLASSPATH). This creates the new XML file teiu5.fo. We now run XMLTeX on this

 pdfxmltex teiu5.fo

which creates teiu5.pdf. Voila! Actually, we need to do

 pdfxmltex teiu5.fo

again, to resolve page-number references in the table of contents. For a comparison with an HTML rendering of the same document (using XSL again), see teiu5.html on the TEI pages.

Installation

The PassiveTeX macros should be downloaded (as a ZIP file, passivetex.zip), unpacked, and installed in a TeX system (eg in texmf/tex/latex/passivetex) in the normal place where you put macros. Consult your local documentation or local expert if you do not know how to install a new package; on a web2c-based system, don't forget to run mktexlsr when you have the files in place, to update the file lookup table.

What about that pdfxmltex command we saw in the last section? You don't have it on your system? You need to download xmltex from CTAN and install it in the your TeX system. It too is just a set of TeX macro packages. IMPORTANT NOTE. You need a copy of xmltex.tex latex than 2001/11/30.

Now you can use xmltex on a file called (eg) teiu5.fo in one of two ways:

1. Build an xmltex format file for pdfTeX with

   pdftex -ini "&pdflatex" pdfxmltex.ini
   

   and process your file with

   pdflatex "&pdfxmltex" teiu5.fo
   

   The command pdfxmltex used above is just a script which does

   tex -fmt=pdfxmltex -progname=pdfxmltex
   

   Or,
2. Make a wrapper file called (eg) teiu5.tex looking like this:

   \def\xmlfile{teiu5.fo}
   \input xmltex
   

   and run pdfTeX on it as normal with

   pdflatex teiu5.tex
   

Do not worry, xmltex knows how to find the PassiveTeX macros as it needs them. You will likely need to increase TeX memory values (in the file texmf.cnf if you use a Web2c-based TeX); I use:

main_memory = 2500000
param_size = 1500
stack_size = 1500
hash_extra = 50000
string_vacancies = 45000
pool_free = 47500
nest_size = 500
save_size = 10000
pool_size = 500000
max_strings = 55000

For reference, the PassiveTeX package consists of the following files:

• The core xmltex `style' files for XSL FO XML:

   fotex.xmt
   fotex.sty
  

• Support for direct formatting of TEI XML with xmltex

   tei.xmt        
   teixml.sty
  

• Some support files, shared with JadeTeX:

   unicode.sty
   ucharacters.sty
   mlnames.sty 
   dummyels.sty
   nomulticol.sty
  

NOTE: TeX has a limit on the length of line it can read, and some .fo files you generate may cause TeX to die with an message about increasing buf_size. If you get that, edit your texmf.cnf file, increase the size of buf_size (mine is 200000), and remake any format files.

LICENSE

Copyright 2003 Sebastian Rahtz/Oxford University (sebastian.rahtz@oucs.ox.ac.uk)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and any associated documentation files (the ``Software''), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Extensions

PassiveTeX interprets MathML natively (elements must use the MathML namespace). I also support a bookmark element in the fotex namespace, used to make PDF bookmarks. Usage is like this:

<xsl:template match="div2">
     <xsl:apply-templates select="head"/>
     <fotex:bookmark  
	xmlns:fotex="http://www.tug.org/fotex" 
	fotex-bookmark-level="2"
	fotex-bookmark-label="{@id}">
        <xsl:value-of select="head"/>
     </fotex:bookmark>
  </fo:block>
</xsl:template>

Notes on conformance to the XSL specification

The following general limitations apply to most of the PassiveTeX implementation of XSL FO:

1. The `px' unit is not recognised
2. Absolute dimensions always work, but proportional ones are often not recognized
3. The functions allowed in attribute values are usually not recognized
4. There is no error checking at all, and all properies are recognized; do not assume that they do anything...

Most of the formatting objects are implemented more or less; the following are not implemented at all:

1. fo:bidi-override
2. fo:color-profile
3. fo:declarations
4. fo:initial-property-set
5. fo:instream-foreign-object
6. fo:multi-case
7. fo:multi-properties
8. fo:multi-property-set
9. fo:multi-switch
10. fo:multi-toggle
11. fo:region-end
12. fo:region-start
13. fo:table-footer

Sample files

• The TEI Lite description (teiu5.xml) converted PDF as teiu5.pdf
• A TEI test file (exercise.xml) converted to PDF as exercise.pdf
• A physics paper (teimath.xml) containing a fair amount of MathML markup, originally translated from LaTeX into XML. It is used extensively as an example in the LaTeX Web Companion. Here we see it converted to teimath.pdf using test/teimath.xsl
• James Tauber prepared a simple XSL spec (darkness.xsl) for Joseph Conrad's Heart of Darkness, which I ran to PDF as darkness.pdf

Concerns and problems

Some points to bear in mind

1. This is an experimental system to check whether the idea works. Expect something more polished eventually.
2. You need a modern TeX setup (like teTeX or TeX Live) to get to grips with it.
3. Quite a few flow objects and characteristics are not dealt with yet. I will add support for more things as needed or requested.
4. I do not have any objective check that what I think XSL FOs are supposed to do is actually right :-}
5. I have only worked so far with the TEI Lite (XML version) and Docbook DTDs, and probably misinterpreted half of what they say.

Things for LaTeX users to remember

• No use is made of LaTeX high-level constructs. No sections, no lists, no cross-refs, no bibliographies; on the other hand, some extensions in the fotex: namespace are supported (eg to get Acrobat bookmarks)
• XSL FO's underlying character set is Unicode; by default, entities are mapped to their Unicode position;
• All vertical and horizontal space is explicit in the specification
• Page and line breaking is left to TeX: the rest is up to you.

Future directions

• Complete the MathML handling
• Handle more variety in property values (eg colors, fonts)
• Deal with more complex tables
• Support SVG. How?
  • By direct intepretation and mapping to raw PDF
  • By translation to MetaPost, and spawning a MetaPost process
  • By pre-processing to existing TeX graphics languages
  In any case, SVG fragments need to be recognized directly to perform in-line graphical functions (setting text at an angle?)
• Use Unicode-based TeX variant (Omega) to handle non-Latin material more naturally

I will be very glad to discuss details with anyone. Contact me (Sebastian Rahtz) as sebastian.rahtz@oucs.ox.ac.uk