+++ /dev/null
-<?xml version="1.0" encoding="utf-8"?>
-<chapter>
-<chapterinfo>
-<releaseinfo role="meta">
- $Id$
- </releaseinfo>
-<author><surname>Stayton</surname>
-<firstname>Bob</firstname></author>
-<copyright><year>2000</year><holder>Bob Stayton</holder>
-</copyright>
-</chapterinfo>
-<title>DocBook XSL</title> <?dbhtml filename="publishing.html"?>
-<important>
-<para>The information about publishing tools in this chapter is outdated. A more complete and up-to-date description can be found in Bob Stayton's book <citetitle>DocBook XSL: The Complete Guide</citetitle> available online at <ulink url="http://www.sagehill.net/docbookxsl/index.html"></ulink>. </para>
-</important>
-<sect1>
-<title>Using XSL tools to publish DocBook
- documents</title>
-<para>There is a growing list of tools to process DocBook
- documents using XSL stylesheets. Each tool implements parts
- or all of the XSL standard, which actually has several
- components:
- <variablelist>
- <varlistentry>
- <term>Extensible Stylesheet Language (XSL)</term>
- <listitem>
- <para>A language for expressing stylesheets written
- in XML. It includes the formatting object language, but
- refers to separate documents for the transformation
- language and the path language.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>XSL Transformation (XSLT)</term>
-<listitem>
-<para>The part of XSL for transforming XML documents
- into other XML documents, HTML, or text. It can be used to
- rearrange the content and generate new content.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>XML Path Language (XPath)</term>
-<listitem>
-<para>A language for addressing parts of an XML
- document. It is used to find the parts of your document to
- apply different styles to. All XSL processors use this
- component.</para>
-</listitem>
-</varlistentry>
-</variablelist></para>
-<para>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 an FO engine to produce
- PostScript or PDF output.</para>
-<sect2>
-<title>XSLT engines</title>
-<para>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.</para>
-<sect3>
-<title>Which XSLT engine should I use?</title>
-<para>Currently, the only XSLT engines that are recommended and
- known to work well with the DocBook XSL stylesheets are
- Daniel Veillard's C-based implementation, <application class="software">xsltproc</application> (the command line
- processor packaged with <ulink url="http://xmlsoft.org/XSLT/">libxslt</ulink>, the XSLT
- C library for Gnome), and Michael Kay's Java-based
- implementation, <application class="software"><ulink url="http://saxon.sourceforge.net/">Saxon</ulink></application>.</para>
-<warning>
-<title>XSLT engines not recommended for use with DocBook</title>
-<para>The following engines are not currently recommended for
- use with the DocBook XSL stylesheets:
- <variablelist>
- <varlistentry>
- <term>James Clark's XT</term>
- <listitem>
- <para>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.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>Xalan (both Java and C++ implementations)</term>
-<listitem>
-<para>Bugs in current versions of Xalan prevent it
- from being used reliably with the stylesheets.</para>
-</listitem>
-</varlistentry>
-</variablelist> </para>
-</warning>
-<para>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 a non-Java application are using
- <application class="software">xsltproc</application>. 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. (And the
- libxslt site features a <ulink url="http://xmlsoft.org/XSLT/docbook.html">DocBook
- page</ulink> that, among other things, includes a shell
- script you can use to automatically generate <ulink url="http://xmlsoft.org/catalog.html">XML
- catalogs</ulink> for DocBook.) But one current limitation
- <application class="software">xsltproc</application> has is
- that it doesn't yet support Norm Walsh's DocBook-specific
- XSLT extension functions.</para>
-<para>If you can use a Java-based implementation, choose Michael
- Kay's <application class="software">Saxon</application>. It
- supports Norm Walsh's DocBook-specific XSLT extension
- functions.</para>
-<para>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 consider (though
- <application class="software">xsltproc</application> and
- <application class="software">Saxon</application> are
- currently the only recommended XSLT engines for use with
- DocBook).
- <itemizedlist>
- <listitem>
- <para>xsltproc, written in C, from Daniel Veillard (<ulink url="http://xmlsoft.org/XSLT/">http://xmlsoft.org/XSLT/</ulink>)</para>
-</listitem>
-<listitem>
-<para>Saxon, written in Java, from Michael Kay (<ulink url="http://saxon.sourceforge.net/">http://saxon.sourceforge.net/</ulink>)</para>
-</listitem>
-<!-- commented out because current Xalan versions don't work with DocBook
- <listitem>
- <para>Xalan, available in both C++ and Java
- implementations, from the Apache XML Project (<ulink
- url="http://xml.apache.org"
- >http://xml.apache.org</ulink>)</para>
- </listitem>
-<!-->
-<listitem>
-<para>4XSLT, written in Python, from FourThought LLC
- (<ulink url="http://www.fourthought.com">http://www.fourthought.com</ulink>)</para>
-</listitem>
-<listitem>
-<para>Sablotron, written in C++, from Ginger Alliance
- (<ulink url="http://www.gingerall.com">http://www.gingerall.com</ulink>)</para>
-</listitem>
-<listitem>
-<para>XML::XSLT,written in Perl, from Geert Josten and
- Egon Willighagen (<ulink url="http://www.cpan.org">http://www.cpan.org</ulink>)</para>
-</listitem>
-</itemizedlist> </para>
-<para>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:
- <itemizedlist>
- <listitem><para>PassiveTeX (TeX-based) from Sebastian
- Rahtz (<ulink url="http://www.hcu.ox.ac.uk/TEI/Software/passivetex/">http://www.hcu.ox.ac.uk/TEI/Software/passivetex/</ulink>)</para>
-</listitem>
-<listitem>
-<para>FOP (Java-based) from the Apache XML Project
- (<ulink url="http://xml.apache.org/fop/">http://xml.apache.org/fop/</ulink>)</para>
-</listitem>
-</itemizedlist> Of those, PassiveTeX currently seems to be the more
-mature, less buggy implementation. </para>
-<para>And there are two proprietary commercial products that
- both seem to be fairly mature, complete implementations of the
- FO part of the XSL specification:
- <itemizedlist>
- <listitem>
- <para>current versions of <ulink url="http://www.arbortext.com">Arbortext Epic
- Editor</ulink> include integrated support for
- processing formatting object files</para>
-</listitem>
-<listitem>
-<para><ulink url="http://www.renderx.com">RenderX
- XEP</ulink> (written in Java) is a standalone tool
- for processing formatting object files</para>
-</listitem>
-</itemizedlist> </para>
-</sect3>
-<sect3>
-<title>How do I use an XSLT engine?</title>
-<para>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.</para>
-<note>
-<para>You'll need to alter your
- <parameter>CLASSPATH</parameter> environment variable to
- include the path to where you put the
- <filename>saxon.jar</filename> file from the Saxon
- distribution. And you'll need to specify the correct path
- to the <filename>docbook.xsl</filename> HTML stylesheet
- file in your local environment.</para>
-</note>
-<example>
-<title>Using Saxon to generate HTML output</title>
-<screen>CLASSPATH=saxon.jar:$CLASSPATH
-export CLASSPATH
-java com.icl.saxon.StyleSheet <replaceable>filename.xml</replaceable> <replaceable>docbook/html/docbook.xsl</replaceable> > <replaceable>output.html</replaceable></screen>
-
-</example>
-<para>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 (<ulink url="http://xml.apache.org/fop/">http://xml.apache.org/fop/</ulink>).
- Here is an example of that two-stage process.</para>
-<example>
-<title>Using Saxon and FOP to generate PDF output</title>
-<screen>CLASSPATH=saxon.jar:fop.jar:$CLASSPATH
-export CLASSPATH
-java com.icl.saxon.StyleSheet <replaceable>filename.xml</replaceable> <replaceable>docbook/fo/docbook.xsl</replaceable> > <replaceable>output.fo</replaceable>
-java org.apache.fop.apps.CommandLine <replaceable>output.fo</replaceable> <replaceable>output.pdf</replaceable></screen>
-
-</example>
-<para>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.</para>
-<example>
-<title>Using xsltproc to generate HTML output</title>
-<screen>xsltproc <replaceable>docbook/html/docbook.xsl</replaceable> <replaceable>filename.xml</replaceable> > <replaceable>output.html</replaceable></screen>
-
-</example>
-<para>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).</para>
-</sect3>
-</sect2>
-</sect1>
-<sect1>
-<title>A brief introduction to XSL</title>
-<para>XSL is both a transformation language and a
- formatting language. The XSLT transformation part lets you
- scan through a document's structure and rearrange its
- content any way you like. You can write out the content
- using a different set of XML tags, and generate text as
- needed. For example, you can scan through a document to
- locate all headings and then insert a generated table of
- contents at the beginning of the document, at the same time
- writing out the content marked up as HTML. XSL is also a
- rich formatting language, letting you apply typesetting
- controls to all components of your output. With a good
- formatting backend, it is capable of producing high quality
- printed pages.</para>
-<para>An XSL stylesheet is written using XML syntax, and is
- itself a well-formed XML document. That makes the basic
- syntax familiar, and enables an XML processor to check for
- basic syntax errors. The stylesheet instructions use
- special element names, which typically begin with
- <literal>xsl:</literal> to distinguish them from any XML
- tags you want to appear in the output. The XSL namespace is
- identified at the top of the stylesheet file. As with other
- XML, any XSL elements that are not empty will require a
- closing tag. And some XSL elements have specific attributes
- that control their behavior. It helps to keep a good XSL
- reference book handy.</para>
-<para>Here is an example of a simple XSL stylesheet applied
- to a simple XML file to generate HTML output.</para>
-<example>
-<title>Simple XML file</title>
-<programlisting><?xml version="1.0"?>
-<document>
-<title>Using a mouse</title>
-<para>It's easy to use a mouse. Just roll it
-around and click the buttons.</para>
-</document></programlisting>
-
-</example>
-<example>
-<title>Simple XSL stylesheet</title>
-<programlisting><?xml version='1.0'?>
-<xsl:stylesheet
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
-<xsl:output method="html"/>
-
-<xsl:template match="document">
- <HTML><HEAD><TITLE>
- <xsl:value-of select="./title"/>
- </TITLE>
- </HEAD>
- <BODY>
- <xsl:apply-templates/>
- </BODY>
- </HTML>
-</xsl:template>
-
-<xsl:template match="title">
- <H1><xsl:apply-templates/></H1>
-</xsl:template>
-
-<xsl:template match="para">
- <P><xsl:apply-templates/></P>
-</xsl:template>
-
-</xsl:stylesheet>
-</programlisting>
-
-</example>
-<example>
-<title>HTML output</title>
-<programlisting><HTML>
-<HEAD>
-<TITLE>Using a mouse</TITLE>
-</HEAD>
-<BODY>
-<H1>Using a mouse</H1>
-<P>It's easy to use a mouse. Just roll it
-around and click the buttons.</P>
-</BODY>
-</HTML>
-</programlisting>
-
-</example>
-</sect1>
-<sect1>
-<title>XSL processing model</title>
-<para>XSL is a template language, not a procedural
-language. That means a stylesheet specifies a sample of the
-output, not a sequence of programming steps to generate it.
-A stylesheet consists of a mixture of output samples with
-instructions of what to put in each sample. Each bit of
-output sample and instructions is called
-a <emphasis>template</emphasis>.</para>
-<para>In general, you write a template for each element
-type in your document. That lets you concentrate on
-handling just one element at a time, and keeps a stylesheet
-modular. The power of XSL comes from processing the
-templates recursively. That is, each template handles the
-processing of its own element, and then calls other
-templates to process its children, and so on. Since an XML
-document is always a single root element at the top level
-that contains all of the nested descendent elements, the
-XSL templates also start at the top and work their way down
-through the hierarchy of elements.</para>
-<para>Take the
-DocBook <literal><para></literal> paragraph element as
-an example. To convert this to HTML, you want to wrap the
-paragraph content with the HTML
-tags <literal><p></literal> and <literal></p></literal>.
-But a DocBook <literal><para></literal> can contain
-any number of in-line DocBook elements marking up the text.
-Fortunately, you can let other templates take care of those
-elements, so your XSL template
-for <literal><para></literal> can be quite
-simple:</para>
-<programlisting><xsl:template match="para">
- <p>
- <xsl:apply-templates/>
- </p>
-</xsl:template>
-</programlisting>
-<para>The <literal><xsl:template></literal> element
-starts a new template, and
-its <literal>match</literal> attribute indicates where to
-apply the template, in this case to
-any <literal><para></literal> elements. The template
-says to output a literal <literal><p></literal> string
-and then execute
-the <literal><xsl:apply-templates/></literal> instruction.
-This tells the XSL processor to look among all the
-templates in the stylesheet for any that should be applied
-to the content of the paragraph. If each template in the
-stylesheet includes
-an <literal><xsl:apply-templates/></literal> instruction,
-then all descendents will eventually be processed. When it
-is through recursively applying templates to the paragraph
-content, it outputs the <literal></p></literal> closing
-tag.</para>
-<sect2>
-<title>Context is important</title>
-<para>Since you aren't writing a linear procedure to
-process your document, the context of where and how to
-apply each modular template is important.
-The <literal>match</literal> attribute
-of <literal><xsl:template></literal> provides that
-context for most templates. There is an entire expression
-language, XPath, for identifying what parts of your
-document should be handled by each template. The simplest
-context is just an element name, as in the example above.
-But you can also specify elements as children of other
-elements, elements with certain attribute values, the first
-or last elements in a sequence, and so on. Here is how the
-DocBook <literal><formalpara></literal> element is
-handled:</para>
-<programlisting><xsl:template match="formalpara">
- <p>
- <xsl:apply-templates/>
- </p>
-</xsl:template>
-
-<xsl:template match="formalpara/title">
- <b><xsl:apply-templates/></b>
- <xsl:text> </xsl:text>
-</xsl:template>
-
-<xsl:template match="formalpara/para">
- <xsl:apply-templates/>
-</xsl:template>
-</programlisting>
-<para>There are three templates defined, one for
-the <literal><formalpara></literal> element itself,
- and one for each of its children elements. The <literal>match</literal> attribute
-value <literal>formalpara/title</literal> in the second
-template is an XPath expression indicating
-a <literal><title></literal> element that is an
-immediate child of
-a <literal><formalpara></literal> element. This
-distinguishes such titles from
-other <literal><title></literal> elements used in
-DocBook. XPath expressions are the key to controlling how
-your templates are applied.</para>
-<para>In general, the XSL processor has internal rules that
-apply templates that are more specific before templates
-that are less specific. That lets you control the details,
-but also provides a fallback mechanism to a less specific
-template when you don't supply the full context for every
-combination of elements. This feature is illustrated by the
-third template, for <literal>formalpara/para</literal>. By
-including this template, the stylesheet processes a <literal><para></literal> within <literal><formalpara></literal> in
-a special way, in this case by not outputting the HTML <literal><p></literal> tags already output by its parent. If this template had not been included, then the processor would have fallen back to the template
-specified by <literal>match="para"</literal> described
-above, which would have output a second set of <literal><p></literal> tags.</para>
-<para>You can also control template context with
-XSL <emphasis>modes</emphasis>, which are used extensively
-in the DocBook stylesheets. Modes let you process the same
-input more than once in different ways.
-A <literal>mode</literal> attribute in
-an <literal><xsl:template></literal> definition adds a
-specific mode name to that template. When the same mode
-name is used
-in <literal><xsl:apply-templates/></literal>, it acts
-as a filter to narrow the selection of templates to only
-those selected by
-the <literal>match</literal> expression <emphasis>and</emphasis> that
-have that mode name. This lets you define two different
-templates for the same element match that are applied under
-different contexts. For example, there are two templates
-defined for
-DocBook <literal><listitem></literal> elements:</para>
-<programlisting><xsl:template match="listitem">
- <li><xsl:apply-templates/></li>
-</xsl:template>
-
-<xsl:template match="listitem" mode="xref">
- <xsl:number format="1"/>
-</xsl:template>
-</programlisting>
-<para>The first template is for the normal list item
-context where you want to output the
-HTML <literal><li></literal> tags. The second template
-is called with <literal><xsl:apply-templates
-select="$target" mode="xref"/></literal> in the context
-of processing <literal><xref></literal> elements. In
-this case the <literal>select</literal> attribute locates
-the ID of the specific list item and
-the <literal>mode</literal> attribute selects the second
-template, whose effect is to output its item number when it
-is in an ordered list. Because there are many such special
-needs when
-processing <literal><xref></literal> elements, it is
-convenient to define a mode name <literal>xref</literal> to
-handle them all. Keep in mind that mode settings
-do <emphasis>not</emphasis> automatically get passed down to
-other templates
-through <literal><xsl:apply-templates/></literal>.</para>
-
-
-</sect2>
-<sect2>
-<title>Programming features</title>
-<para>Although XSL is template-driven, it also has some
-features of traditional programming languages. Here are
-some examples from the DocBook stylesheets. </para>
-<programlisting><lineannotation>Assign a value to a variable:</lineannotation>
-<xsl:variable name="refelem" select="name($target)"/>
-
-<lineannotation>If statement:</lineannotation>
-<xsl:if test="$show.comments">
- <i><xsl:call-template name="inline.charseq"/></i>
-</xsl:if>
-
-<lineannotation>Case statement:</lineannotation>
-<xsl:choose>
- <xsl:when test="@columns">
- <xsl:value-of select="@columns"/>
- </xsl:when>
- <xsl:otherwise>1</xsl:otherwise>
-</xsl:choose>
-
-<lineannotation>Call a template by name like a subroutine, passing parameter values and accepting a return value:</lineannotation>
-<xsl:call-template name="xref.xreflabel">
- <xsl:with-param name="target" select="$target"/>
-</xsl:call-template>
-</programlisting>
-<para>However, you can't always use these constructs as you
-do in other programming languages. Variables in particular
-have very different behavior.</para>
-<sect3>
-<title>Using variables and parameters</title>
-<para>XSL provides two elements that let you assign a value
-to a
-name: <literal><xsl:variable></literal> and <literal><xsl:param></literal>.
-These share the same name space and syntax for assigning
-names and values. Both can be referred to using
-the <literal>$name</literal> syntax. The main difference
-between these two elements is that a param's value acts as
-a default value that can be overridden when a template is
-called using
-a <literal><xsl:with-param></literal> element as in the
-last example above.</para>
-<para>Here are two examples from DocBook:</para>
-<programlisting><xsl:param name="cols">1</xsl:param>
-<xsl:variable name="segnum" select="position()"/>
-</programlisting>
-<para>In both elements, the name of the parameter or
-variable is specified with
-the <literal>name</literal> attribute. So the name of
-the <literal>param</literal> here
-is <literal>cols</literal> and the name of
-the <literal>variable</literal> is <literal>segnum</literal>.
-The value of either can be supplied in two ways. The value
-of the first example is the text node "1" and is supplied
-as the content of the element. The value of the second
-example is supplied as the result of the expression in
-its <literal>select</literal> attribute, and the element
-itself has no content.</para>
-<para>The feature of XSL variables that is odd to new users
-is that once you assign a value to a variable, you cannot
-assign a new value within the same scope. Doing so will
-generate an error. So variables are not used as dynamic
-storage bins they way they are in other languages. They
-hold a fixed value within their scope of application, and
-then disappear when the scope is exited. This feature is a
-result of the design of XSL, which is template-driven and
-not procedural. This means there is no definite order of
-processing, so you can't rely on the values of changing
-variables. To use variables in XSL, you need to understand
-how their scope is defined.</para>
-<para>Variables defined outside of all templates are
-considered global variables, and they are readable within
-all templates. The value of a global variable is fixed, and
-its global value can't be altered from within any template.
-However, a template can create a local variable of the same
-name and give it a different value. That local value
-remains in effect only within the scope of the local
-variable.</para>
-<para>Variables defined within a template remain in effect
-only within their permitted scope, which is defined as all
-following siblings and their descendants. To understand
-such a scope, you have to remember that XSL instructions
-are true XML elements that are embedded in an XML family
-hierarchy of XSL elements, often referred to as parents,
-children, siblings, ancestors and descendants. Taking the
-family analogy a step further, think of a variable
-assignment as a piece of advice that you are allowed to
-give to certain family members. You can give your advice
-only to your younger siblings (those that follow you) and
-their descendents. Your older siblings won't listen,
-neither will your parents or any of your ancestors. To
-stretch the analogy a bit, it is an error to try to give
-different advice under the same name to the same group of
-listeners (in other words, to redefine the variable). Keep
-in mind that this family is not the elements of your
-document, but just the XSL instructions in your stylesheet.
-To help you keep track of such scopes in hand-written
-stylesheets, it helps to indent nested XSL elements. Here
-is an edited snippet from the DocBook stylesheet
-file <filename>pi.xsl</filename> that illustrates different
-scopes for two variables:</para>
-<programlisting>
- 1 <xsl:template name="dbhtml-attribute">
- 2 ...
- 3 <xsl:choose>
- 4 <xsl:when test="$count>count($pis)">
- 5 <!-- not found -->
- 6 </xsl:when>
- 7 <xsl:otherwise>
- 8 <xsl:variable name="pi">
- 9 <xsl:value-of select="$pis[$count]"/>
-10 </xsl:variable>
-11 <xsl:choose>
-12 <xsl:when test="contains($pi,concat($attribute, '='))">
-13 <xsl:variable name="rest" select="substring-after($pi,concat($attribute,'='))"/>
-14 <xsl:variable name="quote" select="substring($rest,1,1)"/>
-15 <xsl:value-of select="substring-before(substring($rest,2),$quote)"/>
-16 </xsl:when>
-17 <xsl:otherwise>
-18 ...
-19 </xsl:otherwise>
-20 </xsl:choose>
-21 </xsl:otherwise>
-22 </xsl:choose>
-23 </xsl:template>
-
-</programlisting>
-<para>The scope of the variable <literal>pi</literal> begins
-on line 8 where it is defined in this template, and ends on
-line 20 when its last sibling ends.<footnote><para>Technically, the scope extends to the end tag of the parent of the <literal><xsl:variable></literal> element. That is effectively the last sibling.</para></footnote> The scope of the variable <literal>rest</literal> begins on line 13 and ends on line 15. Fortunately, line
-15 outputs an expression using the value before it goes out of
-scope.</para>
-<para>What happens when
-an <literal><xsl:apply-templates/></literal> element
-is used within the scope of a local variable? Do the
-templates that are applied to the document children get the
-variable? The answer is no. The templates that are applied
-are not actually within the scope of the variable. They
-exist elsewhere in the stylesheet and are not following
-siblings or their descendants. </para>
-<para>To pass a value to another template, you pass a
-parameter using
-the <literal><xsl:with-param></literal> element. This
-parameter passing is usually done with calls to a specific
-named template
-using <literal><xsl:call-template></literal>, although
-it works
-with <literal><xsl:apply-templates></literal> too.
-That's because the called template must be expecting the
-parameter by defining it using
-a <literal><xsl:param></literal> element with the same
-parameter name. Any passed parameters whose names are not
-defined in the called template are ignored.</para>
-<para>Here is an example of parameter passing
-from <filename>docbook.xsl</filename>:</para>
-<programlisting><xsl:call-template name="head.content">
- <xsl:with-param name="node" select="$doc"/>
-</xsl:call-template>
-</programlisting>
-<para>Here a template
-named <literal>head.content</literal> is being called and
-passed a parameter named <literal>node</literal> whose
-content is the value of the <literal>$doc</literal> variable
-in the current context. The top of that template looks like
-this:</para>
-<programlisting><xsl:template name="head.content">
- <xsl:param name="node" select="."/>
-</programlisting>
-<para>The template is expecting the parameter because it
-has a <literal><xsl:param></literal> defined with the
-same name. The value in this definition is the default
-value. This would be the parameter value used in the
-template if the template was called without passing that
-parameter.</para>
-
-
-
-
-</sect3>
-
-</sect2>
-<sect2>
-<title>Generating HTML output.</title>
-<para>You generate HTML from your DocBook XML files by
-applying the HTML version of the stylesheets. This is done
-by using the HTML driver
-file <filename>docbook/html/docbook.xsl</filename> as your
-stylesheet. That is the master stylesheet file that
-uses <literal><xsl:include></literal> to pull in the
-component files it needs to assemble a complete stylesheet
-for producing HTML. </para>
-<para>The way the DocBook stylesheet generates HTML is to
-apply templates that output a mix of text content and HTML
-elements. Starting at the top level in the main
-file <filename>docbook.xsl</filename>:</para>
-<programlisting><xsl:template match="/">
- <xsl:variable name="doc" select="*[1]"/>
- <html>
- <head>
- <xsl:call-template name="head.content">
- <xsl:with-param name="node" select="$doc"/>
- </xsl:call-template>
- </head>
- <body>
- <xsl:apply-templates/>
- </body>
- </html>
-</xsl:template>
-</programlisting>
-<para>This template matches the root element of your input
-document, and starts the process of recursively applying
-templates. It first defines a variable
-named <literal>doc</literal> and then outputs two literal
-HTML elements <literal><html></literal> and <literal><head></literal>.
-Then it calls a named
-template <literal>head.content</literal> to process the
-content of the HTML <literal><head></literal>, closes
-the <literal><head></literal> and starts
-the <literal><body></literal>. There it
-uses <literal><xsl:apply-templates/></literal> to
-recursively process the entire input document. Then it just
-closes out the HTML file.</para>
-<para>Simple HTML elements can generated as literal
-elements as shown here. But if the HTML being output
-depends on the context, you need something more powerful to
-select the element name and possibly add attributes and
-their values. Here is a fragment
-from <filename>sections.xsl</filename> that shows how a
-heading tag is generated using
-the <literal><xsl:element></literal> and <literal><xsl:attribute></literal> elements:</para>
-<programlisting>
- 1 <xsl:element name="h{$level}">
- 2 <xsl:attribute name="class">title</xsl:attribute>
- 3 <xsl:if test="$level<3">
- 4 <xsl:attribute name="style">clear: all</xsl:attribute>
- 5 </xsl:if>
- 6 <a>
- 7 <xsl:attribute name="name">
- 8 <xsl:call-template name="object.id"/>
- 9 </xsl:attribute>
-10 <b><xsl:copy-of select="$title"/></b>
-11 </a>
-12 </xsl:element>
-</programlisting>
-<para>This whole example is generating a single HTML
-heading element. Line 1 begins the HTML element definition
-by identifying the name of the element. In this case, the
-name is an expression that includes the
-variable <literal>$level</literal> passed as a parameter to
-this template. Thus a single template can
-generate <literal><h1></literal>, <literal><h2></literal>,
-etc. depending on the context in which it is called. Line 2
-defines a <literal>class="title"</literal> attribute that is
-added to this element. Lines 3 to 5 add
-a <literal>style="clear all"</literal> attribute, but only
-if the heading level is less than 3. Line 6 opens
-an <literal><a></literal> anchor element. Although this
-looks like a literal output string, it is actually modified
-by lines 7 to 9 that insert
-the <literal>name</literal> attribute into
-the <literal><a></literal> element. This illustrates
-that XSL is managing output elements as active element
-nodes, not just text strings. Line 10 outputs the text of
-the heading title, also passed as a parameter to the
-template, enclosed in HTML boldface tags. Line 11 closes
-the anchor tag with the
-literal <literal></a></literal> syntax, while line 12
-closes the heading tag by closing the element definition.
-Since the actual element name is a variable, it couldn't
-use the literal syntax.</para>
-<para>As you follow the sequence of nested templates
-processing elements, you might be wondering how the
-ordinary text of your input document gets to the output. In
-the file <filename>docbook.xsl</filename> you will find
-this template that handles any text not processed by any
-other template:</para>
-<programlisting><xsl:template match="text()">
- <xsl:value-of select="."/>
-</xsl:template>
-</programlisting>
-<para>This template's body consists of the "value" of the text node,
-which is just its text. In general, all XSL processors have
-some built-in templates to handle any content for which
-your stylesheet doesn't supply a matching template. This
-template serves the same function but appears explicitly in
-the stylesheet.</para>
-
-
-
-</sect2>
-<sect2>
-<title>Generating formatting objects.</title>
-<para>You generate formatting objects from your DocBook XML
-files by applying the fo version of the stylesheets. This
-is done by using the fo driver
-file <filename>docbook/fo/docbook.xsl</filename> as your
-stylesheet. That is the master stylesheet file that
-uses <literal><xsl:include></literal> to pull in the
-component files it needs to assemble a complete stylesheet
-for producing formatting objects. Generating a formatting
-objects file is only half the process of producing typeset
-output. You also need a formatting object processor such as
-the Apache XML Project's FOP as described in an earlier
-section.</para>
-<para>The DocBook fo stylesheet works in a similar manner
-to the HTML stylesheet. Instead of outputting HTML tags, it
-outputs text marked up
-with <literal><fo:<replaceable>something</replaceable>></literal> tags.
-For example, to indicate that some text should be kept
-in-line and typeset with a monospace font, it might look
-like this:</para>
-<programlisting><fo:inline-sequence font-family="monospace">/usr/man</fo:inline-sequence></programlisting>
-<para>The templates
-in <filename>docbook/fo/inline.xsl</filename> that produce
-this output for a
-DocBook <literal><filename></literal> element look
-like this:</para>
-<programlisting><xsl:template match="filename">
- <xsl:call-template name="inline.monoseq"/>
-</xsl:template>
-
-<xsl:template name="inline.monoseq">
- <xsl:param name="content">
- <xsl:apply-templates/>
- </xsl:param>
- <fo:inline-sequence font-family="monospace">
- <xsl:copy-of select="$content"/>
- </fo:inline-sequence>
-</xsl:template>
-</programlisting>
-<para>There are dozens of fo tags and attributes specified
-in the XSL standard. It is beyond the scope of this
-document to cover how all of them are used in the DocBook
-stylesheets. Fortunately, this is only an intermediate
-format that you probably won't have to deal with very much
-directly unless you are writing your own
-stylesheets.</para>
-
-
-</sect2>
-
-</sect1>
-</chapter>
+++ /dev/null
-<?xml version='1.0' encoding='iso-8859-1'?>
-<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN' 'http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd'>
-<article>
-<articleinfo>
-<title>Profiling DocBook documents</title>
-<subtitle>An easy way to personalize your content for several target audiences</subtitle>
-<author>
-<firstname>Jirka</firstname>
-<surname>Kosek</surname>
-<affiliation>
-<address>E-mail: <email>jirka@kosek.cz</email>
-<otheraddr>Web: <ulink
-url="http://www.kosek.cz">http://www.kosek.cz</ulink>
-</otheraddr>
-</address>
-</affiliation>
-</author>
-<copyright>
-<year>2001</year>
-<holder>Jiří Kosek</holder>
-</copyright>
-<releaseinfo role="meta">
-$Id$
-</releaseinfo>
-</articleinfo>
-
-<section>
-<title>Introduction</title>
-
-<para>There are many situations when we need to generate several
-versions of document with slightly different content from the single
-source. User guide for program with both Windows and Linux port will
-differ only in several topics related to installation and
-configuration. It would be futile to create and maintain two different
-documents in sync. Another real world example – in addition to
-standard documentation we can have guide enriched with problem
-solutions from help-desk. It also may be better to store these
-information in one document in order to make them absolutely
-synchronized.</para>
-<para>Several high-end editing tools have built in support for
-profiling. User can easily add target audiences for any part of
-document in a simple to use dialog box. User can select desired target
-audience before printing or generation of other output formats.
-Software will automatically filter out excess parts of document and
-pass rest of it to rendering engine. However, if your budget is
-limited you can not use commercial solutions. In the following text I
-will show you simple but flexible profiling solution based on freely
-available technologies.</para>
-
-</section>
-
-<section>
-<title>$0 solution</title>
-
-<para>In the document we mark parts targeted for particular platform
-or user group. When generating final output version of document we
-must do profiling i.e. personalization for particular target audience.
-Only some parts of document are processed. DocBook has built in
-support for marking document parts – on almost every element you
-can use attributes like <sgmltag class="attribute">os</sgmltag>, <sgmltag
-class="attribute">userlevel</sgmltag> and <sgmltag
-class="attribute">arch</sgmltag>. We can store identifier of operating
-system, user group or hardware architecture here. You can also store
-profiling information into some general use attribute like <sgmltag
-class="attribute">role</sgmltag>. <xref linkend="ex.doc"/>
-shows how document with profiling information might
-look like.</para>
-
-<example id="ex.doc">
-<title>Sample DocBook document with profiling information</title>
-<programlisting><![CDATA[<?xml version='1.0' encoding='iso-8859-1'?>
-<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'
- 'http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd'>
-<chapter>
-<title>How to setup SGML catalogs</title>
-
-<para>Many existing SGML tools are able to map public identifiers to
-files on your local file system. Mapping is specified in so called
-catalog file. List of catalog files to use is stored in environment
-variable <envar>SGML_CATALOG_FILES</envar>.</para>
-
-<para os="unix">On Unix systems you can set this variable by invoking
-command <command>export SGML_CATALOG_FILES=/usr/lib/catalog</command>
-on command line. If you want maintain value of the variable between
-sessions, place this command into startup file,
-e.g. <filename>.profile</filename>.</para>
-
-<para os="win">In Windows NT/2000 you can set environment variable by
-issuing command <menuchoice><guimenu>Start</guimenu>
-<guisubmenu>Settings</guisubmenu> <guisubmenu>Control
-Pannel</guisubmenu>
-<guimenuitem>System</guimenuitem></menuchoice>. Then select
-<guilabel>Advanced</guilabel> card in the dialog box and click on the
-<guibutton>Environment Variables...</guibutton> button. Using the
-<guibutton>New</guibutton> button you can add new environment variable
-into your system.</para>
-
-</chapter>]]></programlisting>
-</example>
-
-<para>DocBook documents are often processed by freely available DSSSL
-and XSL stylesheets. Most DocBook users who want profiling starts with
-creation of customization layer which filters out some parts of
-document. This approach has several serious disadvantages. First, you
-must create profiling customization for all output formats as they are
-using different stylesheets. This mean that you must maintain same
-code on several places or do some dirty tricks with importing several
-stylesheets into one stylesheet.</para>
-<para>Second drawback is more serious. If you override templates to
-filter out documents, you can get almost correct output in a single
-run of stylesheet. If you will closely look on generated output, you
-will recognize that in the table of contents there are entries for
-items which should be completely removed by profiling. Similar
-problems are in several other places – e.g. skipped auto
-generated numbers for tables, pictures and so on. To correct this one
-should change all stylesheet code which generates ToC,
-cross-references and so on to ignore filtered content. This is very
-complicated task and will disallow you to easily upgrade to new
-versions of stylesheets.</para>
-<para>Thus we must use different approach. Profiling should be totally
-separate step which will filter out some parts of original document
-and will create new correct DocBook document. When processed with any
-DocBook tool or stylesheet you will get always correct output from the
-new standalone document now. Big advantage of this method is
-compatibility with all DocBook tools. Filtered document is normal
-DocBook document and it does not require any special processing. Of
-course, there is also one disadvantage – formating is now two
-stage process – first you must filter source document and in
-second step you could apply normal stylesheets on result of filtering.
-This may be little bit inconvenient for many users, but whole task can
-be very easily automated by set of shell scripts or batch files or
-whatever else. Starting from version 1.50 of XSL stylesheets you can
-do profiling in one step together with normal stylesheet
-processing.</para>
-
-<figure>
-<title>Profiling stream</title>
-<mediaobject>
-<imageobject>
-<imagedata fileref="profile-chain.png" format="PNG"/>
-</imageobject>
-</mediaobject>
-</figure>
-
-<para>When implementing filter, you can use many different approaches
-and tools. I decided to use XSLT stylesheet. Writing necessary filter
-is very easy in XSLT and many users have XSLT processor already
-installed. Profiling stylesheet is part of standard XSL stylesheets
-distribution and can be found in file
-<filename>profiling/profile.xsl</filename>.</para>
-</section>
-
-<section>
-<title>Usage</title>
-
-<para>If you want to generate Unix specific guide from our sample
-document (<xref linkend="ex.doc"/>) you can do it in the following
-way. (We assume, that command <command>saxon</command> is able to run
-XSLT processor on your machine. You can use your preffered XSLT
-processor instead.)</para>
-
-<screen><command>saxon</command> <option>-o</option> unixsample.xml sample.xml profile.xsl "os=unix"</screen>
-
-<para>We are processing source document
-<filename>sample.xml</filename> with profiling stylesheet
-<filename>profile.xsl</filename>. Result of transformation is stored
-in file <filename>unixsample.xml</filename>. By setting parameter
-<parameter>os</parameter> to value <literal>unix</literal>, we tell
-that only general and Unix specific parts of document should be copied
-to the result document. If you will look at generated result, you will
-notice that this is correct DocBook document:</para>
-
-<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE chapter
- PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
-<chapter>
-<title>How to setup SGML catalogs</title>
-
-<para>Many existing SGML tools are able to map public identifiers to
-files on your local file system. Mapping is specified in so called
-catalog file. List of catalog files to use is stored in environment
-variable <envar>SGML_CATALOG_FILES</envar>.</para>
-
-<para os="unix">On Unix systems you can set this variable by invoking
-command <command moreinfo="none">export SGML_CATALOG_FILES=/usr/lib/catalog</command>
-on command line. If you want maintain value of the variable between
-sessions, place this command into startup file,
-e.g. <filename moreinfo="none">.profile</filename>.</para>
-
-</chapter>]]></programlisting>
-
-<para>It is same as the input document, only Windows specific
-paragraph is missing. Same procedure can be used to get Windows
-specific version of document. The result generated by profiling
-stylesheet have correct document type declaration (DOCTYPE). Without
-it some tools would not be able to process them further. On the result
-of filtering you can run common tools – for example DSSSL or XSL
-stylesheets.</para>
-
-<para>Stylesheet support several attributes for specifying profiling
-values. They are summarized in the following list.</para>
-
-<variablelist>
-<varlistentry>
-<term><parameter>profile.os</parameter></term>
-<listitem>
-<para>This parameter is used for specifying operating system (<sgmltag
-class="attribute">os</sgmltag> attribute) for which you want get
-profiled version of document.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><parameter>profile.userlevel</parameter></term>
-<listitem>
-<para>This parameter is used for specifying user level (<sgmltag
-class="attribute">userlevel</sgmltag> attribute) for which you want get
-profiled version of document.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><parameter>profile.arch</parameter></term>
-<listitem>
-<para>This parameter is used for specifying hardware architecture (<sgmltag
-class="attribute">arch</sgmltag> attribute) for which you want get
-profiled version of document.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><parameter>profile.condition</parameter></term>
-<term><parameter>profile.conformance</parameter></term>
-<term><parameter>profile.revision</parameter></term>
-<term><parameter>profile.revisionflag</parameter></term>
-<term><parameter>profile.security</parameter></term>
-<term><parameter>profile.vendor</parameter></term>
-<term><parameter>profile.role</parameter></term>
-<term><parameter>profile.lang</parameter></term>
-<listitem>
-<para>These parameters can be used to specify target profile for
-corresponding attributes.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><parameter>profile.attribute</parameter></term>
-<listitem>
-<para>Name of attribute on which profiling should be based. It can be
-used if profiling information is stored in other attributes then
-<sgmltag class="attribute">os</sgmltag>, <sgmltag
-class="attribute">userlevel</sgmltag> and <sgmltag class="attribute">arch</sgmltag>.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><parameter>profile.value</parameter></term>
-<listitem>
-<para>This parameter is used for specifying value for attribute
-selected by <parameter>attr</parameter> parameter.</para>
-<para>E.g. setting <literal>profile.attribute=os</literal> and
-<literal>profile.value=unix</literal> is same as setting
-<literal>os=unix</literal>.</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><parameter>profile.separator</parameter></term>
-<listitem>
-<para>Separator for multiple target audience identifiers. Default is
-<literal>;</literal>.</para>
-</listitem>
-</varlistentry>
-
-</variablelist>
-
-<para>Current implementation is able to handle multiple profiling
-targets in one attribute. In that case you must separate identifiers
-by semicolon:</para>
-
-<programlisting><![CDATA[<para os="unix;mac;win">...</para>]]></programlisting>
-
-<para>It is possible to use different separator than semicolon by
-setting <parameter>sep</parameter> parameter. There cann't be spaces
-between separator and target names.</para>
-
-<para>You can also perform profiling based on several profiling
-attributes in a single step as stylesheet can handle all parameters
-simultaneously. For example to get hypothetical guide for Windows
-beginners, you can run profiling like this:</para>
-
-<screen><command>saxon</command> <option>-o</option> xsample.xml sample.xml profile.xsl "profile.os=win" "profile.userlevel=beginner"</screen>
-
-<para>As you can see above described profiling process can be used to
-substitute SGML marked sections mechanism which is missing in XML.</para>
-
-</section>
-
-<section>
-<title>Single pass profiling</title>
-
-<para>If you are using XSL stylesheets version 1.50 and later with
-EXSLT enabled XSLT processor (Saxon, xsltproc, Xalan) you can do
-profiling and transformation to HTML or FO in a single step. To do this
-use stylesheet with prefix <filename>profile-</filename> instead of
-normal one (e.g. <filename>profile-docbook.xsl</filename>,
-<filename>profile-chunk.xsl</filename> or
-<filename>profile-htmlhelp.xsl</filename>). For example to get HTML
-version of profiled document use:</para>
-
-<screen><command>saxon</command> <option>-o</option> sample.html sample.xml .../html/profile-docbook.xsl "profile.os=win" "profile.userlevel=beginner"</screen>
-
-<para>No additional processing is necessary. If you want to use
-profiling with your customized stylesheets import profiling-able
-stylesheet instead of normal one.</para>
-
-</section>
-
-<section>
-<title>Conclusion</title>
-
-<para>Profiling is necessary in many larger DocBook applications. It
-can be quite easily implemented by simple XSLT stylesheet which is
-presented here. This mechanism can also be used to simulate behavior
-of marked sections known from SGML.</para>
-
-</section>
-
-</article>
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: xml
-sgml-shorttag:t
-End:
--->
projects / docbook-dsssl / commitdiff
