From: Michael Smith Date: Thu, 6 Apr 2006 06:23:15 +0000 (+0000) Subject: Ripped out parts of the doc source that we are no longer building X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=1f3952e9d37e904da95118e62ea1c36187137243;p=docbook-dsssl Ripped out parts of the doc source that we are no longer building (because the info in those parts is out of date, no longer maintained, and now obviated by existence of Bob Stayton's book. --- diff --git a/xsl/docsrc/documentation.xml b/xsl/docsrc/documentation.xml deleted file mode 100644 index f8dc84d94..000000000 --- a/xsl/docsrc/documentation.xml +++ /dev/null @@ -1,70 +0,0 @@ - - - - - - -]> - - -DocBook XSL Stylesheet Documentation - - - -Walsh -Norman -Stayton -Bob -Kosek -Jiří - - - -1999200020012002 -Norman Walsh - - - -Preface - -This is the beginnings of documentation for the DocBook XSL -Stylesheets. - - - -&publishing.xml; -&extensions.xml; - - -Tools documentation - -There are several tools useful for usage with DocBook in -directory tools. - - - -Profiling - - - - - - -Reference Documentation - -Reference documentation is also available: - - - - - - - -&templates.xml; -&htmlhelp.xml; - - diff --git a/xsl/docsrc/extensions.xml b/xsl/docsrc/extensions.xml deleted file mode 100644 index 0b7717f86..000000000 --- a/xsl/docsrc/extensions.xml +++ /dev/null @@ -1,169 +0,0 @@ - -Extensions - - - The DocBook XSL Stylesheets distribution includes a set of - DocBook-specific XSLT extensions (currently implemented in Java) - for performing a variety of functions that would be impractical to - implement with standard XSLT only: - - - embed callouts in verbatim environments (program - listings, for example) - - - add line numbers to verbatim environments (program - listings, for example) - - - adjust the width of table columns in HTML output to - match specs in the CALS table source - - - directly include contents of a text file in rendered - output - - - determine the intrinsic size of an image - - - - - The line numbers and callouts in the following example are - made possible through the use of the DocBook XSLT extension - functions. - - A program listing with line numbering and callouts - - - - - - - - - - - -@rem = '--*-Perl-*-- -@echo off -perl.exe %_batchname %$ -goto endofperl -@rem '; - -# Compress mail... - -require 'n:/home/nwalsh/lib/cygnus.pl'; -require 'timelocal.pl'; -use Cwd; - -select (STDERR); $| = 1; -select (STDOUT); $| = 1; - -@DIRS = ("/home/nwalsh/Mail"); -while (@DIRS) { - $dir = shift @DIRS; - opendir (DIR, $dir); - while ($fname = readdir(DIR)) { - $file = "$dir/$fname"; - next if ! -d $file; - next if $fname =~ /^\.\.?$/; - - print "$file\n"; - push (@DIRS, $file); - &compress ($file); - } -} - -exit; - - -The prologue handles embedding a Perl script in a DOS batch file. - - -The goto statement, interpreted by the DOS batch -file interpreter, skips over the body of the Perl script. - - -The require statement sources in external program -fragments. - - -The use statement is similar, but has additional -utility. It is a Perl5 function. (Note that this callout area specifies -both a line and a column.) - - -This is a user subroutine call. - - - - - - -
-Using the Extensions - - The extensions are included in the DocBook XSL Stylesheets - distribution in the extensions directory. - - - To use the extensions, you need to: - - Determine which extension jar file (in the extensions directory) corresponds most - closely to the Java XSLT engine you use. - - - Include the name of that jar file in your Java - CLASSPATH. - - - Set the correct XSLT extension - parameters to enable the behavior you need. (For - compatibility with other processors, the extensions are - disabled by default.) - - - - - For example, if you're using Saxon 6.4.4, include the - extensions/saxon644.jar file in your Java - classpath. If you're using Xalan-Java 2, include the - extensions/xalan2.jar file in your - classpath. - - - The DocBook XSLT extensions are not supported for - Xalan-Java 1 or for versions of Saxon prior to 6.4.3. And - because the only current implementation of the extensions is - written in Java, you can't yet use them with xsltproc (which - is a written in C) or with Xalan-C++. - - - - At a minimum, you'll also need to set the value of the use.extensions - parameter to 1 (instead of the default - 0). - - Enabling the extensions from the command line - To enable the extensions from the command line, you need to - pass the use.extensions parameter - to your XSLT engine. Here's an example of how to do that with Saxon: - - java com.icl.saxon.StyleSheet filename.xml docbook/html/docbook.xsl \ - use.extensions=1 > output.html - - and here's an example of how to do it with Xalan: - - java org.apache.xalan.xslt.Process -IN filename.xml -XSL docbook/html/docbook.xsl \ - -PARAM use.extensions 1 -OUT output.html - - - -
- - - diff --git a/xsl/docsrc/htmlhelp.xml b/xsl/docsrc/htmlhelp.xml deleted file mode 100644 index 7a81437e4..000000000 --- a/xsl/docsrc/htmlhelp.xml +++ /dev/null @@ -1,158 +0,0 @@ - - - - - -Jirka -Kosek - - -2001-2003 -Jiří Kosek - -$Id$ - -Using the XSL stylesheets to generate HTML Help - - -HTML Help (HH) is a help format used in newer versions of Microsoft -Windows and applications written for that platform. The HTML Help format allows -you to pack several HTML files together with images, a table of contents, and -an index into a single file. Windows contains a browser for this file format -and full-text search is also supported on HH files. If you want to know -more about HH and its capabilities, visit the Microsoft HTML -Help Start Page. - -
-How to generate your first HTML Help file from DocBook sources - -Working with the HH stylesheets is the same as with other XSL DocBook -stylesheets. Simply run your favorite XSLT processor on your document -with the HH stylesheet: - -saxon yourfile /path/to/stylesheets/htmlhelp/htmlhelp.xsl - -The stylesheet imports the standard chunking stylesheet, so a set of -HTML files is created in the usual way. Other files are also created -– htmlhelp.hhp is the project file for the HTML -Help Compiler and toc.hhc holds the structure of your -document. - -The language identifier for the overall HH file is taken from the top-most -element with a lang attribute in -your DocBook source. This is perfectly legal for documents in only one -language. If a language is not specified in the document, US English is -used. There is one problem – MS language codes are country-sensitive, -and this information is not available in the DocBook source. If -the stylesheet selects a bad code for you, edit -langcodes.xml, and remove all entries which have -your language code, but are located in an inappropriate country. - -The title for the overall HH file is taken from the first title element in your -document. Full-text searching is automatically on. If your document -contains index terms, they are automatically converted to HH ActiveX -objects, which are recognized by the HTML Help compiler. - -The stylesheet creates couple other files which are then used as an -input for the HTML Help Compiler (HHC), which is part of HTML Help Workshop. If you have HHC in your path, you can -start conversion to the HH format by running this command: - -hhc htmlhelp.hhp - -If you cannot stand to work without using your mouse, there is alternative -way. Just double-click on the htmlhelp.hhp file. HH Workshop will be -launched automatically. Generation of the HH file can be started by selecting - -File Compile from the application's -menu. - -
- -
-Customizing generated files - -
-Enabling navigation links - -By default, the HTML Help stylesheet disables navigation links at -the start and the bottom of each page. If you want to enable the -links instead, start your XSLT processor with the parameter suppress.navigation set to 0. - -saxon yourfile /path/to/stylesheets/htmlhelp/htmlhelp.xsl "suppress.navigation=0" - -Another approach is to create a driver file, which overrides -the default parameter value. - - - - - - - - -]]> - -
- -
-Generating HTML Help for non-Western European languages - -If you are generating HTML Help for non-Western Europe -languages, you should change the output encoding of your files, because -the HTML Help compiler improperly handles UTF-8 and even character -entities in the TOC file and index entries. This can be easily done using a -driver file like this: - - - - - - - - - - -]]> - -Default encoding is ISO-8859-1 (aka ISO Latin 1). If you get -some strange message about characters from your XSLT processor and -your document is in some of Western European languages, try changing -encoding to windows-1252. This encoding is similar -to ISO-8859-1 but contains some additional characters like -typographical quotes and dashes. - -
- -
-More about customizing - -More info will come in a near future (I hope and -believe). Meanwhile look into reference for description of HTML Help -specific parameters. - -
- -
- -
-Feedback - -If you have any comments and suggestions about the HTML Help -stylesheet feel free to contact me at following address -jirka@kosek.cz. - -
- - \ No newline at end of file diff --git a/xsl/docsrc/publishing.xml b/xsl/docsrc/publishing.xml deleted file mode 100644 index 0f04b7ea6..000000000 --- a/xsl/docsrc/publishing.xml +++ /dev/null @@ -1,817 +0,0 @@ - - - - - $Id$ - -Stayton -Bob -2000Bob Stayton - - -DocBook XSL - -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 DocBook XSL: The Complete Guide available online at . - - -Using XSL tools to publish DocBook - documents -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: - - - Extensible Stylesheet Language (XSL) - - 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. - - - -XSL Transformation (XSLT) - -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. - - - -XML Path Language (XPath) - -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. - - - -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. - -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? -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, xsltproc (the command line - processor packaged with libxslt, the XSLT - C library for Gnome), and Michael Kay's Java-based - implementation, Saxon. - -XSLT engines not recommended for use with DocBook -The following engines are not currently recommended for - use with the DocBook XSL stylesheets: - - - 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. - - - -Xalan (both Java and C++ implementations) - -Bugs in current versions of Xalan prevent it - from being used reliably with 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 a non-Java application are using - xsltproc. 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 DocBook - page that, among other things, includes a shell - script you can use to automatically generate XML - catalogs for DocBook.) But one current limitation - xsltproc has is - that it doesn't yet support Norm Walsh's DocBook-specific - XSLT extension functions. -If you can use a Java-based implementation, choose Michael - Kay's Saxon. It - supports Norm Walsh's DocBook-specific XSLT extension - functions. -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 - xsltproc and - Saxon are - currently the only recommended XSLT engines for use with - DocBook). - - - xsltproc, written in C, from Daniel Veillard (http://xmlsoft.org/XSLT/) - - -Saxon, written in Java, from Michael Kay (http://saxon.sourceforge.net/) - - - -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: - - - current versions of Arbortext Epic - Editor include integrated support for - processing formatting object files - - -RenderX - XEP (written in Java) is a standalone tool - for processing formatting object files - - - - -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.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.icl.saxon.StyleSheet filename.xml docbook/fo/docbook.xsl > output.fo -java org.apache.fop.apps.CommandLine output.fo output.pdf - - -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 - 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. -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 - xsl: 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. -Here is an example of a simple XSL stylesheet applied - to a simple XML file to generate HTML output. - -Simple XML file -<?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> - - - -Simple XSL stylesheet -<?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> - - - - -HTML output -<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> - - - - - -XSL processing model -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 template. -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. -Take the -DocBook <para> paragraph element as -an example. To convert this to HTML, you want to wrap the -paragraph content with the HTML -tags <p> and </p>. -But a DocBook <para> 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 <para> can be quite -simple: -<xsl:template match="para"> - <p> - <xsl:apply-templates/> - </p> -</xsl:template> - -The <xsl:template> element -starts a new template, and -its match attribute indicates where to -apply the template, in this case to -any <para> elements. The template -says to output a literal <p> string -and then execute -the <xsl:apply-templates/> 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 <xsl:apply-templates/> instruction, -then all descendents will eventually be processed. When it -is through recursively applying templates to the paragraph -content, it outputs the </p> closing -tag. - -Context is important -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 match attribute -of <xsl:template> 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 <formalpara> element is -handled: -<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> - -There are three templates defined, one for -the <formalpara> element itself, - and one for each of its children elements. The match attribute -value formalpara/title in the second -template is an XPath expression indicating -a <title> element that is an -immediate child of -a <formalpara> element. This -distinguishes such titles from -other <title> elements used in -DocBook. XPath expressions are the key to controlling how -your templates are applied. -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 formalpara/para. By -including this template, the stylesheet processes a <para> within <formalpara> in -a special way, in this case by not outputting the HTML <p> 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 match="para" described -above, which would have output a second set of <p> tags. -You can also control template context with -XSL modes, which are used extensively -in the DocBook stylesheets. Modes let you process the same -input more than once in different ways. -A mode attribute in -an <xsl:template> definition adds a -specific mode name to that template. When the same mode -name is used -in <xsl:apply-templates/>, it acts -as a filter to narrow the selection of templates to only -those selected by -the match expression and 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 <listitem> elements: -<xsl:template match="listitem"> - <li><xsl:apply-templates/></li> -</xsl:template> - -<xsl:template match="listitem" mode="xref"> - <xsl:number format="1"/> -</xsl:template> - -The first template is for the normal list item -context where you want to output the -HTML <li> tags. The second template -is called with <xsl:apply-templates -select="$target" mode="xref"/> in the context -of processing <xref> elements. In -this case the select attribute locates -the ID of the specific list item and -the mode 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 <xref> elements, it is -convenient to define a mode name xref to -handle them all. Keep in mind that mode settings -do not automatically get passed down to -other templates -through <xsl:apply-templates/>. - - - - -Programming features -Although XSL is template-driven, it also has some -features of traditional programming languages. Here are -some examples from the DocBook stylesheets. -Assign a value to a variable: -<xsl:variable name="refelem" select="name($target)"/> - -If statement: -<xsl:if test="$show.comments"> - <i><xsl:call-template name="inline.charseq"/></i> -</xsl:if> - -Case statement: -<xsl:choose> - <xsl:when test="@columns"> - <xsl:value-of select="@columns"/> - </xsl:when> - <xsl:otherwise>1</xsl:otherwise> -</xsl:choose> - -Call a template by name like a subroutine, passing parameter values and accepting a return value: -<xsl:call-template name="xref.xreflabel"> - <xsl:with-param name="target" select="$target"/> -</xsl:call-template> - -However, you can't always use these constructs as you -do in other programming languages. Variables in particular -have very different behavior. - -Using variables and parameters -XSL provides two elements that let you assign a value -to a -name: <xsl:variable> and <xsl:param>. -These share the same name space and syntax for assigning -names and values. Both can be referred to using -the $name 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 <xsl:with-param> element as in the -last example above. -Here are two examples from DocBook: -<xsl:param name="cols">1</xsl:param> -<xsl:variable name="segnum" select="position()"/> - -In both elements, the name of the parameter or -variable is specified with -the name attribute. So the name of -the param here -is cols and the name of -the variable is segnum. -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 select attribute, and the element -itself has no content. -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. -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. -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 pi.xsl that illustrates different -scopes for two variables: - - 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> - - -The scope of the variable pi begins -on line 8 where it is defined in this template, and ends on -line 20 when its last sibling ends.Technically, the scope extends to the end tag of the parent of the <xsl:variable> element. That is effectively the last sibling. The scope of the variable rest begins on line 13 and ends on line 15. Fortunately, line -15 outputs an expression using the value before it goes out of -scope. -What happens when -an <xsl:apply-templates/> 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. -To pass a value to another template, you pass a -parameter using -the <xsl:with-param> element. This -parameter passing is usually done with calls to a specific -named template -using <xsl:call-template>, although -it works -with <xsl:apply-templates> too. -That's because the called template must be expecting the -parameter by defining it using -a <xsl:param> element with the same -parameter name. Any passed parameters whose names are not -defined in the called template are ignored. -Here is an example of parameter passing -from docbook.xsl: -<xsl:call-template name="head.content"> - <xsl:with-param name="node" select="$doc"/> -</xsl:call-template> - -Here a template -named head.content is being called and -passed a parameter named node whose -content is the value of the $doc variable -in the current context. The top of that template looks like -this: -<xsl:template name="head.content"> - <xsl:param name="node" select="."/> - -The template is expecting the parameter because it -has a <xsl:param> 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. - - - - - - - - -Generating HTML output. -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 docbook/html/docbook.xsl as your -stylesheet. That is the master stylesheet file that -uses <xsl:include> to pull in the -component files it needs to assemble a complete stylesheet -for producing HTML. -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 docbook.xsl: -<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> - -This template matches the root element of your input -document, and starts the process of recursively applying -templates. It first defines a variable -named doc and then outputs two literal -HTML elements <html> and <head>. -Then it calls a named -template head.content to process the -content of the HTML <head>, closes -the <head> and starts -the <body>. There it -uses <xsl:apply-templates/> to -recursively process the entire input document. Then it just -closes out the HTML file. -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 sections.xsl that shows how a -heading tag is generated using -the <xsl:element> and <xsl:attribute> elements: - - 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> - -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 $level passed as a parameter to -this template. Thus a single template can -generate <h1>, <h2>, -etc. depending on the context in which it is called. Line 2 -defines a class="title" attribute that is -added to this element. Lines 3 to 5 add -a style="clear all" attribute, but only -if the heading level is less than 3. Line 6 opens -an <a> anchor element. Although this -looks like a literal output string, it is actually modified -by lines 7 to 9 that insert -the name attribute into -the <a> 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 </a> 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. -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 docbook.xsl you will find -this template that handles any text not processed by any -other template: -<xsl:template match="text()"> - <xsl:value-of select="."/> -</xsl:template> - -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. - - - - - -Generating formatting objects. -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 docbook/fo/docbook.xsl as your -stylesheet. That is the master stylesheet file that -uses <xsl:include> 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. -The DocBook fo stylesheet works in a similar manner -to the HTML stylesheet. Instead of outputting HTML tags, it -outputs text marked up -with <fo:something> tags. -For example, to indicate that some text should be kept -in-line and typeset with a monospace font, it might look -like this: -<fo:inline-sequence font-family="monospace">/usr/man</fo:inline-sequence> -The templates -in docbook/fo/inline.xsl that produce -this output for a -DocBook <filename> element look -like this: -<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> - -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. - - - - - - diff --git a/xsl/docsrc/reference.xml b/xsl/docsrc/reference.xml index bb0ecc099..8fb6e4f7b 100644 --- a/xsl/docsrc/reference.xml +++ b/xsl/docsrc/reference.xml @@ -21,17 +21,31 @@ PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" Walsh Norman - 19992005 + 19992006 Norman Walsh - Preface + - <para>This is reference documentation for the DocBook XSL - stylesheets. It is divided into two sections: documentation for - users and documentation for developers.</para> + <para>This is generated reference documentation for the DocBook XSL + stylesheets, primarily documentation on the parameters you can + adjust to control the behavior of the stylesheets.</para> + + <note> + <para>This is purely reference documentation â€“not how-to + documentation. For a thorough step-by-step how-to guide to + publishing content using the DocBook XSL stylesheets, see Bob + Stayton’s <ulink + url="http://www.sagehill.net/book-description.html" >DocBook + XSL:The Complete Guide</ulink>, available online at <ulink + url="http://www.sagehill.net/docbookxsl/index.html" + >http://www.sagehill.net/docbookxsl/index.html</ulink></para> + </note> + + <para>This document is divided into two parts: the first provides + user documentation; the second, developer documentation.</para> <itemizedlist> <title>User documentation diff --git a/xsl/docsrc/template-example.xml b/xsl/docsrc/template-example.xml deleted file mode 100644 index abb3dbd1e..000000000 --- a/xsl/docsrc/template-example.xml +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - <author/> - <edition/> - </t:titlepage-content> -</t:titlepage> -</t:templates> diff --git a/xsl/docsrc/template-example.xsl b/xsl/docsrc/template-example.xsl deleted file mode 100644 index b4bd9d6e2..000000000 --- a/xsl/docsrc/template-example.xsl +++ /dev/null @@ -1,20 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> - -<!-- This stylesheet was created by titlepage.xsl; do not edit it by hand. --> - -<xsl:import href="/path/to/html/docbook.xsl"/> - -<xsl:template name="article.titlepage.recto"><xsl:apply-templates mode="article.titlepage.recto.mode" select="(articleinfo/title|artheader/title|title)[1]|articleinfo/author|artheader/author|articleinfo/edition|artheader/edition"/> -</xsl:template> - -<xsl:template name="article.titlepage"> - <div class="titlepage"> - <xsl:call-template name="article.titlepage.before.recto"/> - <xsl:call-template name="article.titlepage.recto"/> - <xsl:call-template name="article.titlepage.before.verso"/> - <xsl:call-template name="article.titlepage.verso"/> - <xsl:call-template name="article.titlepage.separator"/> - </div> -</xsl:template> - -</xsl:stylesheet> \ No newline at end of file diff --git a/xsl/docsrc/templates.xml b/xsl/docsrc/templates.xml deleted file mode 100644 index 4864ff470..000000000 --- a/xsl/docsrc/templates.xml +++ /dev/null @@ -1,108 +0,0 @@ -<chapter> -<chapterinfo> -<releaseinfo role="meta"> -$Id$ -</releaseinfo> -<author><surname>Walsh</surname> -<firstname>Norman</firstname></author> -<copyright><year>2000</year><holder>Norman Walsh</holder> -</copyright> -</chapterinfo> -<title>The Template System - -Some parts of the DocBook XSL Stylesheets are actually generated -using XSL Stylesheets. In particular, the formatting of title pages -is generated using a special template system. The same template system -will eventually allow you to easily customize bibliography entries and -perhaps other parts of the system as well. - -FIXME: there needs to be more introductory/explanatory text -here! - -
Changing the Article Title Page - -In order to demonstrate how this system works, let's consider -how we can use it to change the format of article title pages. - -By default, the stylesheets print the following elements on the -article title page, in this order: -title -subtitle -corpauthor -authorgroup -author -releaseinfo -copyright -legalnotice -pubdate -revision -revhistory -abstract -. Suppose we want to put only the -title, author, and -edition elements on the title page, in the order -that they appear in the articleinfo. - - -The hard (and wrong!) way to do it would be to -edit titlepage.templates.xsl and make the changes -by hand. - -The easy and right way is to construct a template document that -describes the order and sequence of elements that you want: - - - - - - - <author/> - <edition/> - </t:titlepage-content> -</t:titlepage> -</t:templates> -]]></screen> - -<para>Then process this document with the -<filename>template/titlepage.xsl</filename> stylesheet. This will -produce the following somewhat cryptic stylesheet:</para> - -<screen><![CDATA[ -<?xml version="1.0" encoding="utf-8"?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> - -<!-- This stylesheet was created by titlepage.xsl; do not edit it by hand. --> - -<xsl:template name="article.titlepage.recto"><xsl:apply-templates mode="article.titlepage.recto.mode" select="(articleinfo/title|artheader/title|title)[1]|articleinfo/author|artheader/author|articleinfo/edition|artheader/edition"/> -</xsl:template> - -<xsl:template name="article.titlepage"> - <div class="titlepage"> - <xsl:call-template name="article.titlepage.before.recto"/> - <xsl:call-template name="article.titlepage.recto"/> - <xsl:call-template name="article.titlepage.before.verso"/> - <xsl:call-template name="article.titlepage.verso"/> - <xsl:call-template name="article.titlepage.separator"/> - </div> -</xsl:template> - -</xsl:stylesheet> -]]></screen> - -<para>Despite its cryptic appearance, it has the desired result. -When you use <literal>xsl:include</literal> to include these -generated templates into the main stylesheet, then they are -used to format the title page elements. -The elements are selected and processed in the order you specified. -</para> -<para> -If you want to change <emphasis>how</emphasis> the titlepage elements -are formatted (as opposed to which ones are formatted), you have to -write your own customization layer that overrides the template for -the element in question in the <quote>titlepage.mode</quote> mode.</para> -</section> - -</chapter> diff --git a/xsl/docsrc/tools/Makefile b/xsl/docsrc/tools/Makefile deleted file mode 100644 index b54bc7beb..000000000 --- a/xsl/docsrc/tools/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -XSLT=../../../cvstools/saxon -XJPARSE=../../../cvstools/xjparse - -JSTYLE=../../docsrc/xsl2jref.xsl -VPATH=../../common - -XMLFILES = profiling.xml - -all: $(XMLFILES) - -clean: - -echo nop - -%.xml : %.xsl $(JSTYLE) ../../docsrc/legalnotice.xml - $(XSLT) $< $(JSTYLE) /dev/null output-file=$@ - $(XJPARSE) $@ diff --git a/xsl/docsrc/tools/profile-chain.png b/xsl/docsrc/tools/profile-chain.png deleted file mode 100644 index ad3a35765..000000000 Binary files a/xsl/docsrc/tools/profile-chain.png and /dev/null differ diff --git a/xsl/docsrc/tools/profiling.xml b/xsl/docsrc/tools/profiling.xml deleted file mode 100644 index fe5fee69d..000000000 --- a/xsl/docsrc/tools/profiling.xml +++ /dev/null @@ -1,330 +0,0 @@ -<?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 -An easy way to personalize your content for several target audiences - -Jirka -Kosek - -
E-mail: jirka@kosek.cz -Web: http://www.kosek.cz - -
- - - -2001 -Jiří Kosek - - -$Id$ - - - -
-Introduction - -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. -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. - -
- -
-$0 solution - -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 os, userlevel and arch. 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 role. -shows how document with profiling information might -look like. - - -Sample DocBook document with profiling information - - - -How to setup SGML catalogs - -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 SGML_CATALOG_FILES. - -On Unix systems you can set this variable by invoking -command export SGML_CATALOG_FILES=/usr/lib/catalog -on command line. If you want maintain value of the variable between -sessions, place this command into startup file, -e.g. .profile. - -In Windows NT/2000 you can set environment variable by -issuing command Start -Settings Control -Pannel -System. Then select -Advanced card in the dialog box and click on the -Environment Variables... button. Using the -New button you can add new environment variable -into your system. - -]]> - - -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. -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. -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. - -
-Profiling stream - - - - - -
- -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 -profiling/profile.xsl. -
- -
-Usage - -If you want to generate Unix specific guide from our sample -document () you can do it in the following -way. (We assume, that command saxon is able to run -XSLT processor on your machine. You can use your preffered XSLT -processor instead.) - -saxon unixsample.xml sample.xml profile.xsl "os=unix" - -We are processing source document -sample.xml with profiling stylesheet -profile.xsl. Result of transformation is stored -in file unixsample.xml. By setting parameter -os to value unix, 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: - - - - -How to setup SGML catalogs - -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 SGML_CATALOG_FILES. - -On Unix systems you can set this variable by invoking -command export SGML_CATALOG_FILES=/usr/lib/catalog -on command line. If you want maintain value of the variable between -sessions, place this command into startup file, -e.g. .profile. - -]]> - -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. - -Stylesheet support several attributes for specifying profiling -values. They are summarized in the following list. - - - -profile.os - -This parameter is used for specifying operating system (os attribute) for which you want get -profiled version of document. - - - -profile.userlevel - -This parameter is used for specifying user level (userlevel attribute) for which you want get -profiled version of document. - - - -profile.arch - -This parameter is used for specifying hardware architecture (arch attribute) for which you want get -profiled version of document. - - - -profile.condition -profile.conformance -profile.revision -profile.revisionflag -profile.security -profile.vendor -profile.role -profile.lang - -These parameters can be used to specify target profile for -corresponding attributes. - - - -profile.attribute - -Name of attribute on which profiling should be based. It can be -used if profiling information is stored in other attributes then -os, userlevel and arch. - - - -profile.value - -This parameter is used for specifying value for attribute -selected by attr parameter. -E.g. setting profile.attribute=os and -profile.value=unix is same as setting -os=unix. - - - -profile.separator - -Separator for multiple target audience identifiers. Default is -;. - - - - - -Current implementation is able to handle multiple profiling -targets in one attribute. In that case you must separate identifiers -by semicolon: - -...]]> - -It is possible to use different separator than semicolon by -setting sep parameter. There cann't be spaces -between separator and target names. - -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: - -saxon xsample.xml sample.xml profile.xsl "profile.os=win" "profile.userlevel=beginner" - -As you can see above described profiling process can be used to -substitute SGML marked sections mechanism which is missing in XML. - -
- -
-Single pass profiling - -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 profile- instead of -normal one (e.g. profile-docbook.xsl, -profile-chunk.xsl or -profile-htmlhelp.xsl). For example to get HTML -version of profiled document use: - -saxon sample.html sample.xml .../html/profile-docbook.xsl "profile.os=win" "profile.userlevel=beginner" - -No additional processing is necessary. If you want to use -profiling with your customized stylesheets import profiling-able -stylesheet instead of normal one. - -
- -
-Conclusion - -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. - -
- - -