From 3029e53e8a8425a2af682c077f7df775b2c18c74 Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Wed, 27 Mar 2002 16:32:59 +0000 Subject: [PATCH] Added admon: Don't use XT; XT examples -> Saxon; added info on xsltproc --- xsl/docsrc/publishing.xml | 238 +++++++++++++++++++++++++++++--------- 1 file changed, 184 insertions(+), 54 deletions(-) diff --git a/xsl/docsrc/publishing.xml b/xsl/docsrc/publishing.xml index 977db4565..7510bd4e8 100644 --- a/xsl/docsrc/publishing.xml +++ b/xsl/docsrc/publishing.xml @@ -48,65 +48,195 @@ $Id$ To publish HTML from your XML documents, you just need an XSLT engine. To get to print, you need an XSLT engine to produce formatting objects (FO), which then must - be processed with a formatting object processor to produce + be processed with an FO engine to produce PostScript or PDF output. -James Clark's XT was the first useful XSLT engine, - and it is still in wide use. It is written in Java, so it - runs on many platforms, and it is free ( - http://www.jclark.com). - XT comes with James Clark's nonvalidating parser XP, but - you can substitute a different Java parser. Here is a - simple example of using XT from the Unix command line to - produce HTML: You'll need to alter your - CLASSPATH environment variable to - include the path to where you put the - .jar files from the XT - distribution. -CLASSPATH=xt.jar:xp.jar:sax.jar + + XSLT engines + + This section provides a discussion about which XSLT + engines you might want to use to generate HTML and FO output + from your DocBook XML documents, along with a few short + examples of how to actually use some specific XSLT engines to + generate that output. Before using any particular XSLT engine, + you should consult its reference documentation for more + detailed information. + + + Which XSLT engine should I use? + + Before reading anything else in this section, please take + a few seconds to read the following warning. + + + One engine you should definitely + not use is James Clark's XT. XT is an + incomplete implementation of the XSLT 1.0 specification. One + of the important things that's missing from it is support for + XSLT "keys", which the DocBook XSLT stylesheets rely on for + generating indexes, among other things. So you can't use XT + reliably with current versions of the stylesheets. + + + + Your choice of an XSLT engine may depend a lot on the + environment you'll be running the engine in. Many DocBook + users who need or want to use a non-Java application are using + Daniel Veillard's C-based implementation, xsltproc (the + command line processor packaged with libxslt, the XSLT C + library for Gnome, http://xmlsoft.org/XSLT/). It's very fast, and also a + good choice because Veillard monitors the DocBook mailing + lists to field usage and troubleshooting questions and + responds very quickly to bug reports. But one current + limitation it has is that it doesn't yet support Norm Walsh's + DocBook-specific XSLT extension functions. + + The current Java-based XSLT engine of choice for many + DocBook users seems to be Michael Kay's Saxon (http://saxon.sourceforge.net/). It supports Norm + Walsh's DocBook-specific XSLT extension functions, and among the + Java-based engines, seems to generate the fewest bug reports to + the DocBook mailing lists. + + A variety of XSLT engines are available. Not all of them + are used much in the DocBook community, but here's a list of + some free/open-source ones you might want to try (including + the two previously mentioned). + + + xsltproc, written in C, from Daniel Veillard (http://xmlsoft.org/XSLT/) + + + Saxon, written in Java, from Michael Kay (http://saxon.sourceforge.net/) + + + Xalan, written in Java, from the Apache XML + Project (http://xml.apache.org) + + + 4XSLT, written in Python, from FourThought LLC + (http://www.fourthought.com) + + + Sablotron, written in C++, from Ginger Alliance + (http://www.gingerall.com) + + + XML::XSLT,written in Perl, from Geert Josten and + Egon Willighagen (http://www.cpan.org) + + + + + For generating print/PDF output from FO files, there are + two free/open-source FO engines that, while they aren't + complete bug-free implementations of the FO part of the XSL + specification, are still very useful: + + PassiveTeX (TeX-based) from Sebastian + Rahtz (http://www.hcu.ox.ac.uk/TEI/Software/passivetex/) + + + FOP (Java-based) from the Apache XML Project + (http://xml.apache.org/fop/) + + + Of those, PassiveTeX currently seems to be the more mature, + less buggy implementation. + + And there are two proprietary commercial products that + both seem to be fairly mature, complete implementations of the + FO part of the XSL specification: + + + Epic Editor 4.2 (includes support for processing + formatting object files) from Arbortext () + + + XEP (written in Java) from RenderX (http://www.renderx.com). + + + + + + + How do I use an XSLT engine? + + Before using any XSLT engine, you should consult the + reference documentation that comes with it for details about + its command syntax and so on. But there are some common + steps to follow when using the Java-based engines, so here's + an example of using Saxon from the UNIX command line that + might help give you general idea of how to use the Java-based + engines. + + + You'll need to alter your + CLASSPATH environment variable to + include the path to where you put the + saxon.jar file from the Saxon + distribution. And you'll need to specify the correct path + to the docbook.xsl HTML stylesheet + file in your local environment. + + + + Using Saxon to generate HTML output +CLASSPATH=saxon.jar:$CLASSPATH export CLASSPATH -java com.jclark.xsl.sax.Driver filename.xml docbook/html/docbook.xsl > output.html -If you replace the HTML stylesheet with a - formatting object stylesheet, XT will produce a formatting - object file. Then you can convert that to PDF using FOP, a - formatting object processor available for free from the - Apache XML Project ( - http://xml.apache.org). - Here is an example of that two stage processing: -CLASSPATH=xt.jar:xp.jar:sax.jar:fop.jar +java com.icl.saxon.StyleSheet filename.xml docbook/html/docbook.xsl > output.html + + If you replace the path to the HTML stylesheet with the + path to the FO stylesheet, Saxon will produce a formatting + object file. Then you can convert that to PDF using a FO + engine such such as FOP, the free/open-source FO engine + available from the Apache XML Project (http://xml.apache.org/fop/). + Here is an example of that two-stage process. + + Using Saxon and FOP to generate PDF output +CLASSPATH=saxon.jar:fop.jar:$CLASSPATH export CLASSPATH -java com.jclark.xsl.sax.Driver filename.xml docbook/fo/docbook.xsl > output.fo +java com.icl.saxon.StyleSheet filename.xml docbook/fo/docbook.xsl > output.fo java org.apache.fop.apps.CommandLine output.fo output.pdf -As of this writing, some other XSLT processors to - choose from include: - - - 4XSLT, written in Python, from FourThought LLC ( - http://www.fourthought.com) - - -Sablotron, written in C++, from Ginger Alliance ( + - http://www.gingerall.com) - - -Saxon, written in Java, from Michael Kay ( - http://users.iclway.co.uk/mhkay/saxon) - - -Xalan, written in Java, from the Apache XML - Project ( - http://xml.apache.org) - - -XML::XSLT,written in Perl, from Geert Josten and - Egon Willighagen ( - http://www.cpan.org) - - -For print output, these additional tools are available for processing formatting objects: -XEP (written in Java) from - RenderX ( - http://www.renderx.com).PassiveTeX from Sebastian Rahtz (http://users.ox.ac.uk/~rahtz/passivetex/). + Using a C-based XSLT engine such as xsltproc is a little + easier, since it doesn't require setting any environment + variables or remembering Java package names. Here's an example + of using xsltproc to generate HTML output. + + + Using xsltproc to generate HTML output + xsltproc docbook/html/docbook.xsl filename.xml > output.html + + + Note that when using xsltproc, the pathname to the + stylesheet file precedes the name of your XML source file on + the command line (it's the other way around with Saxon and + with most other Java-based XSLT engines). + + + + + + A brief introduction to XSL XSL is both a transformation language and a -- 2.40.0