$Date: 2005/03/25 21:54:04 $ $Revision: 1.1 $ Publishing DocBook Documents DocBook DTD publishing documents publishing DocBook documents stylesheets publishing SGML/XML documents HTML translating SGML/XML documents Creating and editing &SGML;/&XML; documents is usually only half the battle. After you've composed your document, you'll want to publish it. Publishing, for our purposes, means either print or web publishing. For &SGML; and &XML; documents, this is usually accomplished with some kind of stylesheet. In some environments, it is now possible to publish an &XML; document on the Web simply by putting it online with a stylesheet. Jade Modular DocBook Stylesheets Modular DocBook Stylesheets Linux Documentation Project There are many ways, using both free and commercial tools, to publish &SGML; documents. In this chapter, we're going to survey a number of possibilities, and then look at just one solution in detail: Jade and the Modular DocBook Stylesheets. We used jade to produce this book and to produce the online versions on the CD-ROM; it is also being deployed in other projects such as <SGML>&tools;, which originated with the Linux Documentation Project. For a brief survey of other tools, see .
The MIME Type for DocBook When published on the web, documents must be identified with a MIME type. The MIME type for SGML DocBook documents published directly on the web is “application/sgml”. The most appropriate MIME type for XML DocBook documents published directly on the web is currently “application/xml”, however the DocBook Technical Committee may choose to register a more specific MIME type in the future.
A Survey of Stylesheet Languages stylesheets languages languages stylesheets Over the years, a number of attempts have been made to produce a standard stylesheet language and, failing that, a large number of proprietary languages have been developed. FOSIs FOSI stylesheets Formatting Output Specification InstanceFOSI stylesheets U.S. Department of Defense stylesheet standard First, the U.S. Department of Defense, in an attempt to standardize stylesheets across military branches, created the Output Specification, which is defined in MIL-PRF-28001C, Markup Requirements and Generic Style Specification for Electronic Printed Output and Exchange of Text. See Formally Published CALS Standards for more information. ADEPT Publisher (Arbortext), FOSIs support Arbortext ADEPT Publisher, FOSIs support Commonly called FOSIs (for Formatting Output Specification Instances), they are supported by a few products including ADEPT Publisher by Arbortext and DL Composer by Datalogics. DSSSL DSSSL Document Style Semantics and Specification LanguageDSSSL ISO standards DSSSL International Organization for StandardizationISO Entity Sets; ISO standards Next, the International Organization for Standardization (ISO) created DSSSL, the Document Style Semantics and Specification Language. Subsets of DSSSL are supported by Jade and a few other tools, but it never achieved widespread support. CSS CSS HTML CSS XML CSS The W3C CSS Working Group created CSS as a style attachment language for &HTML;, and, more recently, &XML;. XSL XSL XML XSL Extensible Style LanguageXSL Most recently, the &XML; effort has identified a standard Extensible Style Language (XSL) as a requirement. The W3C XSL Working Group is currently pursuing that effort.
Stylesheet Examples stylesheets examples By way of comparison, here's an example of each of the standard style languages. In each case, the stylesheet fragment shown contains the rules that reasonably formatted the following paragraph: This is an example paragraph. It should be presented in a reasonable body font. Emphasized words should be printed in italics. A single level of Nested emphasis should also be supported. ]]>
<acronym>FOSI</acronym> stylesheet FOSI stylesheets example SGML FOSIs e-i-c element element in context (e-i-c) FOSIs are &SGML; documents. The element in the FOSI that controls the presentation of specific elements is the e-i-c (element in context) element. A sample FOSI fragment is shown in . A Fragment of a <acronym>FOSI</acronym> Stylesheet
<acronym>DSSSL</acronym> stylesheet DSSSL stylesheets example Scheme language DSSSL stylesheets DSSSL stylesheets are written in a Scheme-like language (see later in this chapter). It is the element function that controls the presentation of individual elements. See the example in . A Fragment of a <acronym>DSSSL</acronym> Stylesheet
<acronym>CSS</acronym> stylesheet CSS stylesheets example CSS stylesheets consist of selectors and formatting properties, as shown in . A Fragment of a <acronym>CSS</acronym> Stylesheet
<acronym>XSL</acronym> stylesheet XSL stylesheets example XSL stylesheets are &XML; documents, as shown in . The element in the XSL stylesheet that controls the presentation of specific elements is the xsl:template element. A Fragment of an <acronym>XSL</acronym> Stylesheet
Using Jade and <acronym>DSSSL</acronym> to Publish DocBook Documents Jade DSSSL, using (DocBook document) SGML DSSSL stylesheets XML DSSSL stylesheets DSSSL stylesheets print and HTML output (DocBook) HTML DSSSL stylesheets Jade is a free tool that applies DSSSL stylesheets to &SGML; and &XML; documents. As distributed, Jade can output RTF, &TeX;, MIF, and &SGML;. The &SGML; backend can be used for &SGML; to &SGML; transformations (for example, DocBook to &HTML;). A complete set of DSSSL stylesheets for creating print and &HTML; output from DocBook is included on the CD-ROM. More information about obtaining and installing Jade appears in .
A Brief Introduction to <acronym>DSSSL</acronym> DSSSL is a stylesheet language for both print and online rendering. The acronym stands for Document Style Semantics and Specification Language. It is defined by ISO/IEC 10179:1996. For more general information about DSSSL, see the DSSSL Page.
Scheme Scheme language syntax LISP language, syntax syntax LISP language The DSSSL expression language is Scheme, a variant of Lisp. Lisp is a functional programming language with a remarkably regular syntax. Every expression looks like this: (operator arg1 arg2 ... argn ) syntax Scheme language This is called prefix syntax because the operator comes before its arguments. In Scheme, the expression that subtracts 2 from 3, is (- 3 2). And (+ (- 3 2) (* 2 4)) is 9. While the prefix syntax and the parentheses may take a bit of getting used to, Scheme is not hard to learn, in part because there are no exceptions to the syntax.
<acronym>DSSSL</acronym> Stylesheets DSSSL stylesheets formatting DSSSL stylesheets, elements A complete DSSSL stylesheet is shown in . After only a brief examination of the stylesheet, you'll probably begin to have a feel for how it works. For each element in the document, there is an element rule that describes how you should format that element. The goal of the rest of this chapter is to make it possible for you to read, understand, and even write stylesheets at this level of complexity. A Complete <acronym>DSSSL</acronym> Stylesheet DocBook DTD documents DSSSL stylesheets This stylesheet is capable of formatting simple DocBook documents like the one shown in . A Simple DocBook Document The result of formatting a simple document with this stylesheet can be seen in .
The formatted simple document
We'll take a closer look at this stylesheet after you've learned a little more DSSSL.
<acronym>DSSSL</acronym> Stylesheets Are &SGML; Documents SGML DSSSL stylesheets entities DSSSL stylesheets marked sections DSSSL stylesheets One of the first things that may strike you about DSSSL stylesheets (aside from all the parentheses), is the fact that the stylesheet itself is an &SGML; document! This means that you have all the power of &SGML; documents at your disposal in DSSSL stylesheets. In particular, you can use entities and marked sections to build a modular stylesheet. architecture DSSSL DTDs DSSSL stylesheets, changing In fact, DSSSL stylesheets are defined so that they correspond to a particular architecture. This means that you can change the &DTD; used by stylesheets within the bounds of the architecture. A complete discussion of document architectures is beyond the scope of this book, but we'll show you one way to take advantage of them in your DSSSL stylesheets in later in the chapter.
<acronym>DSSSL</acronym> Processing Model processing model (DSSSL) trees (DSSSL) nodes (DSSSL) A DSSSL processor builds a tree out of the source document. Each element in the source document becomes a node in the tree (processing instructions and other constructs become nodes as well). Processing the source tree begins with the root rule and continues until there are no more nodes to process.
Global Variables and Side Effects variables (DSSSL) global side effects (DSSSL) There aren't any global variables or side effects. It can be difficult to come to grips with this, especially if you're just starting out. functions DSSSL constants (DSSSL) It is possible to define constants and functions and to create local variables with let expressions, but you can't create any global variables or change anything after you've defined it.
<acronym>DSSSL</acronym> Expressions expressions (DSSSL) DSSSL has a rich vocabulary of expressions for dealing with all of the intricacies of formatting. Many, but by no means all of them, are supported by Jade. In this introduction, we'll cover only a few of the most common.
Element expressions DSSSL stylesheets element expressions elements element expressions (DSSSL) paragraphs DSSSL stylesheets, formattting Element expressions, which define the rules for formatting particular elements, make up the bulk of most DSSSL stylesheets. A simple element rule can be seen in . This rule says that a para element should be formatted by making a paragraph (see ). A Simple <acronym>DSSSL</acronym> Rule (element para (make paragraph space-before: 8pt (process-children))) ancestors (elements), DSSSL An element expression can be made more specific by specifying an element and its ancestors instead of just specifying an element. The rule (element title ...) applies to all Title elements, but a rule that begins (element (figure title) ...) applies only to Title elements that are immediate children of Figure elements. If several rules apply, the most specific rule is used. When a rule is used, the node in the source tree that was matched becomes the current node while that element expression is being processed.
Make expressions flow objects (DSSSL) content flow objects (DSSSL) A make expression specifies the characteristics of a flow object. Flow objects are abstract representations of content (paragraphs, rules, tables, and so on). The expression: (make paragraph font-size: 12pt line-spacing: 14pt ...) specifies that the content that goes here is to be placed into a paragraph flow object with a font-size of 12pt and a line-spacing of 14pt (all of the unspecified characteristics of the flow object are defaulted in the appropriate way). They're called flow objects because DSSSL, in its full generality, allows you to specify the characteristics of a sequence of flow objects and a set of areas on the physical page where you can place content. The content of the flow objects is then poured on to (or flows in to) the areas on the page(s). sosofo (DSSSL) make expressions (DSSSL) In most cases, it's sufficient to think of the make expressions as constructing the flow objects, but they really only specify the characteristics of the flow objects. This detail is apparent in one of the most common and initially confusing pieces of DSSSL jargon: the sosofo. Sosofo stands for a specification of a sequence of flow objects. All this means is that processing a document may result in a nested set of make expressions (in other words, the paragraph may contain a table that contains rows that contain cells that contain paragraphs, and so on). The general form of a make expression is: (make flow-object-name keyword1: value1 keyword2: value2 ... keywordn: valuen (content-expression)) keywords flow objects (DSSSL), defining Keyword arguments specify the characteristics of the flow object. The specific characteristics you use depends on the flow object. The content-expression can vary; it is usually another make expression or one of the processing expressions. flow objects (DSSSL) Some common flow objects in the print stylesheet are: simple-page-sequence simple-page-sequence (DSSSL) flow object Contains a sequence of pages. The keyword arguments of this flow object let you specify margins, headers and footers, and other page-related characteristics. Print stylesheets should always produce one or more simple-page-sequence flow objects. Nesting simple-page-sequence does not work. Characteristics on the inner sequences are ignored. paragraph paragraphs DSSSL flow objects nesting paragraphs (DSSSL) A paragraph is used for any block of text. This may include not only paragraphs in the source document, but also titles, the terms in a definition list, glossary entries, and so on. Paragraphs in DSSSL can be nested. sequence sequences DSSSL flow objects A sequence is a wrapper. It is most frequently used to change inherited characteristics (like font style) of a set of flow objects without introducing other semantics (such as line breaks). score score (DSSSL flow object) A score flow object creates underlining, strike-throughs, or overlining. table tables DSSSL flow objects A table flow object creates a table of rows and cells. HTML DSSSL flow objects The &HTML; stylesheet uses the &SGML; backend, which has a different selection of flow objects. element make expressions (DSSSL) elements creating Creates an element. The content of this make expression will appear between the start and end tags. The expression: (make element gi: "H1" (literal "Title")) produces <H1>Title</H1>. empty-element empty elements creating Creates an empty element that may not have content. The expression: (make empty-element gi: "BR" attributes: '(("CLEAR" "ALL"))) produces <BR CLEAR="ALL">. sequence wrappers sequences (DSSSL) Produces no output in of itself as a wrapper, but is still required in DSSSL contexts in which you want to output several flow objects but only one object top-level object may be returned. entity-ref entities entity-ref (DSSSL) references entities (DSSSL) entity-ref (DSSSL flow objects) Inserts an entity reference. The expression: (make entity-ref name: "nbsp") produces &nbsp;. DSSSL stylesheets flow objects, empty empty flow objects (DSSSL) flow objects (DSSSL) empty In both stylesheets, a completely empty flow object is constructed with (empty-sosofo).
Selecting data data, selecting (DSSSL) selecting data (DSSSL) Extracting parts of the source document can be accomplished with these functions: (data nd) Returns all of the character data from nd as a string. (attribute-string "attr" nd) Returns the value of the attr attribute of nd. (inherited-attribute-string "attr" nd) Returns the value of the attr attribute of nd. If that attribute is not specified on nd, it searches up the hierarchy for the first ancestor element that does set the attribute, and returns its value.
Selecting elements elements selecting selecting elements (DSSSL) content reordering, DSSSL functions DSSSL elements, selecting nodes (DSSSL) A common requirement of formatting is the ability to reorder content. In order to do this, you must be able to select other elements in the tree for processing. DSSSL provides a number of functions that select other elements. These functions all return a list of nodes. (current-node) Returns the current node. (children nd) Returns the children of nd. (descendants nd) Returns the descendants of nd (the children of nd and all their children's children, and so on). (parent nd) Returns the parent of nd. (ancestor "name" nd) Returns the first ancestor of nd named name. (element-with-id "id") Returns the element in the document with the ID id, if such an element exists. (select-elements node-list "name") Returns all of the elements of the node-list that have the name name. For example, (select-elements (descendants (current-node)) "para") returns a list of all the paragraphs that are descendants of the current node. (empty-node-list) Returns a node list that contains no nodes. Other functions allow you to manipulate node lists. (node-list-empty? nl) Returns true if (and only if) nl is an empty node list. (node-list-length nl) Returns the number of nodes in nl. (node-list-first nl) Returns a node list that consists of the single node that is the first node in nl. (node-list-rest nl) Returns a node list that contains all of the nodes in nl except the first node. expressions (DSSSL) nodes and node lists, manipulating elements element expressions (DSSSL) lists nodes, manipulating There are many other expressions for manipulating nodes and node lists.
Processing expressions processing expressions (DSSSL) Processing expressions control which elements in the document will be processed and in what order. Processing an element is performed by finding a matching element rule and using that rule. (process-children) Processes all of the children of the current node. In most cases, if no process expression is given, processing the children is the default behavior. (process-node-list nl) Processes each of the elements in nl.
Define expressions functions declaring your own (DSSSL) constants (DSSSL) declarations functions and constants (DSSSL) You can declare your own functions and constants in DSSSL. The general form of a function declaration is: (define (function args) function-body) A constant declaration is: (define constant constant-function-body) The distinction between constants and functions is that the body of a constant is evaluated when the definition occurs, while functions are evaluated when they are used.
Conditionals conditionals (DSSSL) false, testing for (DSSSL) true, testing for (DSSSL) expressions (DSSSL) conditionals In DSSSL, the constant #t represents true and #f false. There are several ways to test conditions and take action in DSSSL. if if expressions (DSSSL) The form of an if expression is: (if condition true-expression false-expression) If the condition is true, the true-expression is evaluated, otherwise the false-expression is evaluated. You must always provide an expression to be evaluated when the condition is not met. If you want to produce nothing, use (empty-sosofo). case case expression (DSSSL) case selects from among several alternatives: (case expression ((constant1) (expression1) ((constant2) (expression2) ((constant3) (expression3) (else else-expression)) The value of the expression is compared against each of the constants in turn and the expression associated with the first matching constant is evaulated. cond conditionals (DSSSL) cond also selects from among several alternatives, but the selection is performed by evaluating each expression: (cond ((condition1) (expression1) ((condition2) (expression2) ((condition3) (expression3) (else else-expression)) The value of each conditional is calculated in turn. The expression associated with the first condition that is true is evaluated. empty sets (DSSSL) Any expression that returns #f is false; all other expressions are true. This can be somewhat counterintuitive. In many programming languages, it's common to assume that empty things are false (0 is false, a null pointer is false, an empty set is false, for example.) In DSSSL, this isn't the case; note, for example, that an empty node list is not #f and is therefore true. To avoid these difficulties, always use functions that return true or false in conditionals. To test for an empty node list, use (node-list-empty?).
Let expressions let expressions (DSSSL) The way to create local variables in DSSSL is with (let). The general form of a let expression is: (let ((var1 expression1) (var2 expression2) ... (varn expressionn)) let-body) variables (DSSSL) let expressions In a let; expression, all of the variables are defined simultaneously. The expression that defines var2 cannot contain any references to any other variables defined in the same let expression. A let* expression allows variables to refer to each other, but runs slightly slower. define expresssions (DSSSL) Variables are available only within the let-body. A common use of let is within a define expression: (define (cals-rule-default nd) (let* ((table (ancestor "table" nd)) (frame (if (attribute-string "frame" table) (attribute-string "frame" table) "all"))) (equal? frame "all"))) This function creates two local variables table and frame. let returns the value of the last expression in the body, so this function returns true if the frame attribute on the table is all or if no frame attribute is present.
Loops for loop, DSSSL and loops, implementing (DSSSL) tail recursion (DSSSL) DSSSL doesn't have any construct that resembles the for loop that occurs in most imperative languages like C and Java. Instead, DSSSL employs a common trick in functional languages for implementing a loop: tail recursion. Loops in DSSSL use a special form of let. This loop counts from 1 to 10: (let loopvar ((count 1)) (if (> count 10) #t (loopvar (+ count 1)))) This variable controls the loop. It is declared without an initial value, immediately after the let operand. variables (DSSSL) local, defining after loop variable Any number of additional local variables can be defined after the loop variable, just as they can in any other let expression. If you ever want the loop to end, you have to put some sort of a test in it. This is the value that will be returned. Note that you iterate the loop by using the loop variable as if it was a function name. The arguments to this function are the values that you want the local variables declared in to have in the next iteration.
A Closer Look at <xref linkend="dsssl.stylesheet"/> DSSSL stylesheets style specifications is a style sheet that contains a style specification. Stylesheets may consist of multiple specifications, as we'll see in . The actual DSSSL code goes in the style specification body, within the style specification. Each construction rule processes different elements from the source document.
Processing chapters chapters, processing (DSSSL) simple-page-sequence (DSSSL) chapters, constructing printing stylesheets Chapters are processed by the chapter construction rule. Each Chapter is formatted as a simple-page-sequence. Every print stylesheet should format a document as one or more simple page sequences. Characteristics on the simple page sequence can specify headers and footers as well as margins and other page parameters. nesting simple page sequences (DSSSL), not allowed One important note about simple page sequences: they cannot nest. This means that you cannot blindly process divisions (Parts, Reference) and the elements they contain (Chapters, RefEntrys) as simple page sequences. This sometimes involves a little creativity.
Processing titles titles processing, DSSSL The make expression in the title element rule ensures that Titles are formatted in large, bold print. This construction rule applies equally to Chapter titles, Figure titles, and Book titles. It's unlikely that you'd want all of these titles to be presented in the same way, so a more robust stylesheet would have to arrange the processing of titles with more context. This might be achieved in the way that nested Emphasis elements are handled in .
Processing paragraphs Para elements are simply formatted as paragraphs. Para element DSSSL, processing
Processing emphasis Emphasis element DSSSL, processing nesting emphasis elements, DSSSL processing Processing Emphasis elements is made a little more interesting because we want to consider an attribute value and the possibility that Emphasis elements can be nested. In the simple case, in which we're processing an Emphasis element that is not nested, we begin by testing the value of the role attribute. If the content of that attribute is the string strong, it is formatted in bold; otherwise, it is formatted in italic. The nested case is handled by the (emphasis emphasis) rule. This rule simply formats the content using an upright (nonitalic) font. This rule, like the rule for Titles, is not robust. Emphasis nested inside strong Emphasis won't be distinguished, for example, and nestings more than two elements deep will be handled just as nestings that are two deep.
Processing subscripts and superscripts Subscript element DSSSL, processing Superscript element DSSSL, processing Processing Subscript and Superscript elements is really handled by the super-sub-script function. There are several interesting things about this function: The plus-or-minus argument Scheme language function, passing as argument functions Scheme, passing as argument You might ordinarily think of passing a keyword or boolean argument to the super-sub-script function to indicate whether subscripts or superscripts are desired. But with Scheme, it's possible to pass the actual function as an argument! Note that in the element construction rules for Superscript and Subscript, we pass the actual functions + and -. In the body of super-sub-script, we use the plus-or-minus argument as a function name (it appears immediately after an open parenthesis). The optional argument optional arguments (DSSSL functions) optional arguments are indicated by #!optional in the function declaration. Any number of optional arguments may be given, but each must specify a default value. This is accomplished by listing each argument and default value (an expression) as a pair. In super-sub-script, the optional argument sosofo is initialized to process-children. This means that at the point where the function is called, process-children is evaluated and the resulting sosofo is passed to the function. Use of inherited characteristics inherited characteristics, calculating new values with It is possible to use the current value of an inherited characteristic to calculate a new value. Using this technique, superscripts and subscripts will be presented at 80 percent of the current font size.
Customizing the Stylesheets DSSSL stylesheets customizing customizing DSSSL stylesheets driver files DSSSL stylsheets, customizing The best way to customize the stylesheets is to write your own driver file; this is a stylesheet that contains your local modifications and then includes the appropriate stylesheet from the standard distribution by reference. This allows you to make local changes and extensions without modifying the distributed files, which makes upgrading to the next release much simpler.
Writing Your Own Driver A basic driver file looks like this: ]> ;; your changes go here... ]]> public identifiers Modular DocBook Stylesheets Modular DocBook Stylesheets public identifiers There are two public identifiers associated with the Modular DocBook Stylesheets: -//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN -//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN printing stylesheets HTML stylesheets selecting catalog files Open (SGML) The former selects the print stylesheet and the latter selects the &HTML; stylesheet. There is an &SGML; Open catalog file in the distribution that maps these public identifiers to the stylesheet files. You can add your own definitions, or redefinitions, of stylesheet rules and parameters so that ;; your changes go here... occurs in the previous example. driver files example For a concrete example of a driver file, see plain.dsl in the docbook/print directory in the stylesheet distribution (or on the CD-ROM). This is a customization of the print stylesheet, which turns off title page and TOC generation.
Changing the Localization DocBook DTD stylesheets languages languages DocBook stylesheets As distributed, the stylesheets use English for all generated text, but other localization files are also provided. The languages supported at the time of this writing are summarized in . (If you can write a localization for another language, please contribute it.) Lang attribute customizing DSSSL stylesheets language, changing There are two ways to switch languages: by specifying a lang attribute, or by changing the default language in a customization.
Using the <sgmltag class="attribute">lang</sgmltag> attribute DocBook DTD Lang attribute languages codes One of the DocBook common attributes is lang. If you specify a language, the DocBook stylesheets will use that language (and all its descendants, if no other language is specified) for generated text within that element. summarizes the language codes for the supported languages. Language codes should conform to IETF RFC 3066. French language chapter, example The following chapter uses text generated in French: B]]>ê<![CDATA[tises Pierre qui roule n'amasse pas de mousse. ]]> DocBook Stylesheet Language Codes Language Code Language af Afrikaans ca Catalan cs Czech da Danish de German el Greek en English es Spanish et Estonian eu Basque fi Finnish fr French he Hebrew hu Hungarian id Indonesian it Italian ja Japanese ko Korean nl Dutch nn Nyorsk no Norwegian pl Polish pt Portuguese pt-br Portuguese (Brazil) ro Romanian ru Russian sk Slovak sl Slovenian sv Swedish th Thai tr Turkish uk Ukranian xh Xhosa zh-cn Chinese (Continental) zh-tw Chinese (Traditional)
Changing the default language languages default, changing driver files language, changing default If no lang attribute is specified, the default language is used. You can change the default language with a driver. In the driver, define the default language. summarizes the language codes for the supported languages. The following driver makes German the default language: ]> (define %default-language% "dege") ]]> %gentext-language% There are two other settings that can be changed only in a driver. Both of these settings are turned off in the distributed stylesheet: %gentext-language% If a language code is specified in %gentext-language%, then that language will be used for all generated text, regardless of any lang attribute settings in the document. %gentext-use-xref-language% %gentext-use-xref-language% cross references languages, changing (stylesheets) If turned on (defined as #t), then the stylesheets will generate the text associated with a cross reference using the language of the target, not the current language. Consider the following book: A Test Book There are three chapters in this book: , , and . English ... French ... Deutsch ... ]]> The standard stylesheets render the Preface as something like this:
There are three chapters in this book: Chapter 1, Chapter 2, and Chapter 3.
With %gentext-use-xref-language% turned on, it would render like this:
There are are three chapters in this book: Chapter 1, Chapitre 2, and Kapitel 3.
A Single Stylesheet for Both Print and &HTML; stylesheets HTML and print, using single printing stylesheets HTML stylesheets A DSSSL stylesheet consists of one or more style specifications. Using more than one style specification allows you to build a single stylesheet file that can format with either the print or &SGML; backends. shows a stylesheet with two style specifications. DSSSL stylesheets style specifications, multiple <filename>both.dsl</filename>: A Stylesheet with Two Style Specifications Jade style specifications, indicating selected Once you have stylesheets with more than one style specification, you have to be able to indicate which style specification you want to use. In Jade, you indicate this by providing the ID of the style specification after the stylesheet filename, separated with a hash mark: #. Using the code from , you can format a document using the print stylesheet by running: jade -t rtf -d both.dsl#print file.sgm and using the &HTML; stylesheet by running: jade -t sgml -d both.dsl#html file.sgm
Dealing with Multiple Declarations declarations multiple, using The DocBook &SGML; &DTD; and the DocBook DSSSL Stylesheets happen to use the same &SGML; declaration. This makes it very easy to run Jade with DocBook. However, you may sometimes wish to use Jade with other document types, for example the DocBook &XML; &DTD;, which has a different declaration. There are a couple of ways to do this.
Pass the Declaration Explicitly If your stylesheets parse fine with the default declaration, but you want to use an alternate declaration with a particular document, just pass the declaration on the command line: jade options the-declaration the-document Note that there's no option required before the declaration; it simply occurs before the first filename. Jade concatenates all of the files that you give it together, and parses them as if they were one document.
Use the Catalogs The other way to fix this is with a little catalog trickery. catalog files multiple declarations, using First, note that Jade always looks in the file called catalog in the same directory as the document that it is loading, and uses settings in that file in preference to settings in other catalogs. With this fact, we can employ the following trick: Put a catalog file in the directory that contains your stylesheets, which contain an SGMLDECL directive. Jade understands the directive, which points to the &SGML; declaration that you should use when parsing the stylesheets. For the DocBook stylesheets, the DocBook declaration works fine. In the directory that contains the document you want to process, create a catalog file that contains an SGMLDECL directive that points to the &SGML; declaration that should be used when parsing the document. There's no easy way to have both the stylesheet and the document in the same directory if they must be processed with different declarations. But this is usually not too inconvenient.
The <acronym>DSSSL</acronym> Architecture architecture DSSSL DSSSL architecture attributes DSSSL architecture elements DSSSL architecture and The concept of an architecture was promoted by HyTime. In some ways, it takes the standard &SGML;/&XML; notions of the role of elements and attributes and inverts them. Instead of relying on the name of an element to assign its primary semantics, it uses the values of a small set of fixed attributes. While this may be counterintuitive initially, it has an interesting benefit. An architecture-aware processor can work transparently with many different &DTD;s. A small example will help illustrate this point. The following example demonstrates the concept behind architectures, but for the sake of simplicity, it does not properly implement an architecture as defined in HyTime. Imagine that you wrote an application that can read an &SGML;/&XML; document containing a letter (conforming to some letter &DTD;), and automatically print an envelope for the letter. It's easy to envision how this works. The application reads the content of the letter, extracts the address and return address elements from the source, and uses them to generate an envelope: ]> &myaddress;
Leonard Muellner O'Reilly & Associates 90 Sherman Street CambridgeMA02140
Hi Lenny ... ]]> The processor extracts the Returnaddress and Address elements and their children and prints the envelope accordingly. Now suppose that a colleague from payroll comes by and asks you to adapt the application to print envelopes for mailing checks, using the information in the payroll database, which has a different &DTD;. And a week later, someone from sales comes by and asks if you can modify the application to use the contact information &DTD;. After a while, you would have 11 versions of this program to maintain. fixed attributes Suppose that instead of using the actual element names to locate the addresses in the documents, you asked each person to add a few attributes to their &DTD;. By forcing the attributes to have fixed values, they'd automatically be present in each document, but authors would never have to worry about them. For example, the address part of the letter &DTD; might look like this: Effectively, each address in a letter would look like this: In practice, the author would not include the ADDRESS attributes; they are automatically provided by the &DTD; because they are #FIXED. The use of uppercase names here is intentional. These are not attributes that an author is ever expected to type. In &XML;, which is case-sensitive, using uppercase for things like this reduces the likelihood of collision with real attribute names in the &DTD;. Now the address portion of the payroll &DTD; might look like this: The employee records will look like this: Your application no longer cares about the actual element names. It simply looks for the elements with the correct attributes and uses them. This is the power of an architecture: it provides a level of abstraction that processing applications can use to their advantage. In practice, architectural forms are a bit more complex to set up because they have facilities for dealing with attribute name conflicts, among other things. Why have we told you all this? Because DSSSL is an architecture. This means you can modify the stylesheet &DTD; and still run your stylesheets through Jade. Consider the case presented earlier in . In order to use this stylesheet, you must specify three things: the backend you want to use, the stylesheet you want to use, and the style specification you want to use. If you mismatch any of the parameters, you'll get the wrong results. In practice, the problem is compounded further: Some stylesheets support several backends (RTF, &TeX;, and &SGML;). backends, stylesheet support stylesheets backends, supporting Some stylesheets support only some backends (RTF and &SGML;, but not &TeX; or MIF). Some stylesheets support multiple outputs using the same backend (several kinds of &HTML; output, for example, using the &SGML; backend: &HTML;, &HTML;Help, JavaHelp, and so on). If you have complex stylesheets, some backends may require additional options to define parameter entities or stylesheet options. None of this complexity is really necessary, after all, the options don't change—you just have to use the correct combinations. The mental model is really something like this: I want a certain kind of output, &TeX; say, so I have to use this combination of parameters. You can summarize this information in a table to help keep track of it: Desired Output Backend Style specification Options Supported? rtf rtf print -V rtf-backend yes tex tex print -V tex-backend -i tex yes html sgml htmlweb -i html yes javahelp sgml help -i help yes htmlhelp no Putting this information in a table will help you keep track of it, but it's not the best solution. The ideal solution is to keep this information on your system, and let the software figure it all out. You'd like to be able to run a command, tell it what output you want from what stylesheet, what file you want to process, and then let it figure everything else out. For example: format html mybook.dsl mydoc.sgm stylesheets configuration data, storing within configuration data, storing in stylesheet One way to do this is to put the configuration data in a separate file, and have the format command load it out of this other file. The disadvantage of this solution is that it introduces another file that you have to maintain and it's independent from the stylesheet so it isn't easy to keep it up-to-date. In the DSSSL case, a better alternative is to modify the stylesheet &DTD; so you can store the configuration data in the stylesheet. Using this alternate &DTD;, your mybook.dsl stylesheets might look like this: In this example, the stylesheet has been annotated with a title, a list of the public IDs to which it is applicable, and a table that provides information about the output formats that it supports. Using this information, the format command can get all the information it needs to construct the appropriate call to Jade. To make HTML from myfile.sgm, format would run the following: jade -t sgml -d mybook.dsl#htmlweb -i html myfile.sgm The additional information, titles and public IDs, can be used as part of a GUI interface to simplify the selection of stylesheets for an author. The complete annotated stylesheet &DTD;, and an example of the format command script, are provided on the CD-ROM.
Stayton Bob 2000Bob Stayton A Brief Introduction to XSL
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 a formatting object processor to produce PostScript or PDF output. James Clark's XT was the first useful XSLT engine, and it is still in wide use. It is written in Java, so it runs on many platforms, and it is free ( http://www.jclark.com). XT comes with James Clark's nonvalidating parser XP, but you can substitute a different Java parser. Here is a simple example of using XT from the Unix command line to produce HTML: You'll need to alter your CLASSPATH environment variable to include the path to where you put the .jar files from the XT distribution. CLASSPATH=xt.jar:xp.jar:sax.jar export CLASSPATH java com.jclark.xsl.sax.Driver filename.xml docbook/html/docbook.xsl > output.html If you replace the HTML stylesheet with a formatting object stylesheet, XT will produce a formatting object file. Then you can convert that to PDF using FOP, a formatting object processor available for free from the Apache &XML; Project ( http://xml.apache.org). Here is an example of that two stage processing: CLASSPATH=xt.jar:xp.jar:sax.jar:fop.jar export CLASSPATH java com.jclark.xsl.sax.Driver filename.xml docbook/fo/docbook.xsl > output.fo java org.apache.fop.apps.CommandLine output.fo output.pdf As of this writing, some other XSLT processors to choose from include: 4XSLT, written in Python, from FourThought LLC ( http://www.fourthought.com) Sablotron, written in C++, from Ginger Alliance ( http://www.gingerall.com) Saxon, written in Java, from Michael Kay ( http://users.iclway.co.uk/mhkay/saxon) Xalan, written in Java, from the Apache &XML; Project ( http://xml.apache.org) XML::XSLT,written in Perl, from Geert Josten and Egon Willighagen ( http://www.cpan.org) For print output, these additional tools are available for processing formatting objects: XEP (written in Java) from RenderX ( http://www.renderx.com).PassiveTeX from Sebastian Rahtz (http://users.ox.ac.uk/~rahtz/passivetex/).
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 Using a mouse It's easy to use a mouse. Just roll it around and click the buttons. ]]> Simple XSL stylesheet <xsl:value-of select="./title"/>

]]> HTML output Using a mouse

Using a mouse

It's easy to use a mouse. Just roll it around and click the buttons.

]]>
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:

]]> 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:

]]> 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:
    • ]]>     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: ]]> If statement: ]]> Case statement: 1 ]]> Call a template by name like a subroutine, passing parameter values and accepting a return value: ]]> 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: 1 ]]> 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: 2 ... 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 ... 19 20 21 22 23 ]]> 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: ]]> 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: ]]> 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: ]]> 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: 2 title 3 4 clear: all 5 6 7 8 9 10 11 12 ]]> 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: ]]> 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: /usr/man]]> The templates in docbook/fo/inline.xsl that produce this output for a DocBook <filename> element look like this: ]]> 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.
    Customizing DocBook XSL stylesheets The DocBook XSL stylesheets are written in a modular fashion. Each of the HTML and FO stylesheets starts with a driver file that assembles a collection of component files into a complete stylesheet. This modular design puts similar things together into smaller files that are easier to write and maintain than one big stylesheet. The modular stylesheet files are distributed among four directories: common/ contains code common to both stylesheets, including localization data fo/ a stylesheet that produces XSL FO result trees html/ a stylesheet that produces HTML/XHTML result trees lib/ contains schema-independent functions The driver files for each of HTML and FO stylesheets are html/docbook.xsl and fo/docbook.xsl, respectively. A driver file consists mostly of a bunch of <xsl:include> instructions to pull in the component templates, and then defines some top-level templates. For example: ... ]]> The first four modules are shared with the FO stylesheet and are referenced using relative pathnames to the common directories. Then the long list of component stylesheets starts. Pathnames in include statements are always taken to be relative to the including file. Each included file must be a valid XSL stylesheet, which means its root element must be <xsl:stylesheet>.
    Stylesheet inclusion vs. importing XSL actually provides two inclusion mechanisms: <xsl:include> and <xsl:import>. Of the two, <xsl:include> is the simpler. It treats the included content as if it were actually typed into the file at that point, and doesn't give it any more or less precedence relative to the surrounding text. It is best used when assembling dissimilar templates that don't overlap what they match. The DocBook driver files use this instruction to assemble a set of modules into a stylesheet. In contrast, <xsl:import> lets you manage the precedence of templates and variables. It is the preferred mode of customizing another stylesheet because it lets you override definitions in the distributed stylesheet with your own, without altering the distribution files at all. You simply import the whole stylesheet and add whatever changes you want. The precedence rules for import are detailed and rigorously defined in the XSL standard. The basic rule is that any templates and variables in the importing stylesheet have precedence over equivalent templates and variables in the imported stylesheet. Think of the imported stylesheet elements as a fallback collection, to be used only if a match is not found in the current stylesheet. You can customize the templates you want to change in your stylesheet file, and let the imported stylesheet handle the rest. Customizing a DocBook XSL stylesheet is the opposite of customizing a DocBook DTD. When you customize a DocBook DTD, the rules of &XML; and &SGML; dictate that the first of any duplicate declarations wins. Any subsequent declarations of the same element or entity are ignored. The architecture of the DTD provides slots for inserting your own custom declarations early enough in the DTD for them to override the standard declarations. In contrast, customizing an XSL stylesheet is simpler because your definitions have precedence over imported ones. You can carry modularization to deeper levels because module files can also include or import other modules. You'll need to be careful to maintain the precedence that you want as the modules get rolled up into a complete stylesheet.
    Customizing with <sgmltag class="element"><xsl:import></sgmltag> There is currently one example of customizing with <xsl:import> in the HTML version of the DocBook stylesheets. The xtchunk.xsl stylesheet modifies the HTML processing to output many smaller HTML files rather than a single large file per input document. It uses XSL extensions defined only in the XSL processor XT. In the driver file xtchunk.xsl, the first instruction is <xsl:import href="docbook.xsl"/>. That instruction imports the original driver file, which in turn uses many <xsl:include> instructions to include all the modules. That single import instruction gives the new stylesheet the complete set of DocBook templates to start with. After the import, xtchunk.xsl redefines some of the templates and adds some new ones. Here is one example of a redefined template: Original template in autotoc.xsl # ]]> New template in xtchunk.xsl # ]]> The new template handles the more complex processing of HREFs when the output is split into many HTML files. Where the old template could simply output #object.id, the new one outputs filename#object.id.
    Setting stylesheet variables You may not have to define any new templates, however. The DocBook stylesheets are parameterized using XSL variables rather than hard-coded values for many of the formatting features. Since the <xsl:import> mechanism also lets you redefine global variables, this gives you an easy way to customize many features of the DocBook stylesheets. Over time, more features will be parameterized to permit customization. If you find hardcoded values in the stylesheets that would be useful to customize, please let the maintainer know. Near the end of the list of includes in the main DocBook driver file is the instruction <xsl:include href="param.xsl"/>. The param.xsl file is the most important module for customizing a DocBook XSL stylesheet. This module contains no templates, only definitions of stylesheet variables. Since these variables are defined outside of any template, they are global variables and apply to the entire stylesheet. By redefining these variables in an importing stylesheet, you can change the behavior of the stylesheet. To create a customized DocBook stylesheet, you simply create a new stylesheet file such as mystyle.xsl that imports the standard stylesheet and adds your own new variable definitions. Here is an example of a complete custom stylesheet that changes the depth of sections listed in the table of contents from two to three: 3 ]]> Following the opening stylesheet element are the import instruction and one variable definition. The variable toc.section.depth was defined in param.xsl with value "2", and here it is defined as "3". Since the importing stylesheet takes precedence, this new value is used. Thus documents processed with mystyle.xsl instead of docbook.xsl will have three levels of sections in the tables of contents, and all other processing will be the same. Use the list of variables in param.xsl as your guide for creating a custom stylesheet. If the changes you want are controlled by a variable there, then customizing is easy.
    Writing your own templates If the changes you want are more extensive than what is supported by variables, you can write new templates. You can put your new templates directly in your importing stylesheet, or you can modularize your importing stylesheet as well. You can write your own stylesheet module containing a collection of templates for processing lists, for example, and put them in a file named mylists.xsl. Then your importing stylesheet can pull in your list templates with a <xsl:include href="mylists.xsl"/> instruction. Since your included template definitions appear after the main import instruction, your templates will take precedence. You'll need to make sure your new templates are compatible with the remaining modules, which means: Any named templates should use the same name so calling templates in other modules can find them. Your template set should process the same elements matched by templates in the original module, to ensure complete coverage. Include the same set of <xsl:param> elements in each template to interface properly with any calling templates, although you can set different values for your parameters. Any templates that are used like subroutines to return a value should return the same data type.
    Writing your own driver Another approach to customizing the stylesheets is to write your own driver file. Instead of using <xsl:import href="docbook.xsl"/>, you copy that file to a new name and rewrite any of the <xsl:include/> instructions to assemble a custom collection of stylesheet modules. One reason to do this is to speed up processing by reducing the size of the stylesheet. If you are using a customized DocBook DTD that omits many elements you never use, you might be able to omit those modules of the stylesheet.
    Localization The DocBook stylesheets include features for localizing generated text, that is, printing any generated text in a language other than the default English. In general, the stylesheets will switch to the language identified by a lang attribute when processing elements in your documents. If your documents use the lang attribute, then you don't need to customize the stylesheets at all for localization. As far as the stylesheets go, a lang attribute is inherited by the descendents of a document element. The stylesheet searches for a lang attribute using this XPath expression: ]]> This locates the attribute on the current element or its most recent ancestor. Thus a lang attribute is in effect for an element and all of its descendents, unless it is reset in one of those descendents. If you define it in only your document root element, then it applies to the whole document: ... ]]> When text is being generated, the stylesheet checks the most recent lang attribute and looks up the generated text strings for that language in a localization &XML; file. These are located in the common directory of the stylesheets, one file per language. Here is the top of the file fr.xml: ... ]]> The stylesheet templates use the gentext key names, and then the stylesheet looks up the associated text value when the document is processed with that lang setting. The file l10n.xml (note the .xml suffix) lists the filenames of all the supported languages. You can also create a custom stylesheet that sets the language. That might be useful if your documents don't make appropriate use of the lang attribute. The module l10n.xsl defines two global variables that can be overridden with an importing stylesheet as described above. Here are their default definitions: en ]]> The first one sets the language for all elements, regardless of an element's lang attribute value. The second just sets a default language for any elements that haven't got a lang setting of their own (or their ancestors).