4.1.1.1. FOSI stylesheet

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 Example 4-1.

<e-i-c gi="para">
  <charlist>
    <textbrk startln="1" endln="1">
  </charlist>
</e-i-c>

<e-i-c gi="emphasis">
  <charlist inherit="1">
    <font posture="italic">
  </charlist>
</e-i-c>

<e-i-c gi="emphasis" context="emphasis">
  <charlist inherit="1">
    <font posture="upright">
  </charlist>
</e-i-c>

4.1.1.2. DSSSL stylesheet

DSSSL stylesheets are written in a Scheme-like language (see "Scheme" later in this chapter). It is the element function that controls the presentation of individual elements. See the example in Example 4-2.

(element para
  (make paragraph
    (process-children)))

(element emphasis
  (make sequence
    font-posture: 'italic
    (process-children)))

(element (emphasis emphasis)
  (make sequence
    font-posture: 'upright
    (process-children)))

4.1.1.3. CSS stylesheet

CSS stylesheets consist of selectors and formatting properties, as shown in Example 4-3.

para              { display: block }
emphasis          { display: inline;
                    font-style: italic; }
emphasis emphasis { display: inline;
                    font-style: upright; }

4.1.1.4. XSL stylesheet

XSL stylesheets are XML documents, as shown in Example 4-4. The element in the XSL stylesheet that controls the presentation of specific elements is the xsl:template element.

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format">

<xsl:template match="para">   
  <fo:block>
    <xsl:apply-templates/>  
  </fo:block>
</xsl:template>  

<xsl:template match="emphasis">
  <fo:sequence font-style="italic">
    <xsl:apply-templates/>  
  </fo:sequence>
</xsl:template>  

<xsl:template match="emphasis/emphasis">
  <fo:sequence font-style="upright">
    <xsl:apply-templates/>  
  </fo:sequence>
</xsl:template>  

</xsl:stylesheet>

4.3.6.1. Element expressions

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 Example 4-7. This rule says that a para element should be formatted by making a paragraph (see Section 4.3.6.2").

(element para
  (make paragraph
    space-before: 8pt
    (process-children)))

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.

4.3.6.2. Make expressions

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 ...)

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).

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))

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.

Some common flow objects in the print stylesheet are:

simple-page-sequence

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

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

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

A score flow object creates underlining, strike-throughs, or overlining.

table

A table flow object creates a table of rows and cells.

The HTML stylesheet uses the SGML backend, which has a different selection of flow objects.

element

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

Creates an empty element that may not have content. The expression:

(make empty-element gi: "BR"
     attributes: '(("CLEAR" "ALL")))

produces <BR CLEAR="ALL">.

sequence

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

Inserts an entity reference. The expression:

(make entity-ref name: "nbsp")

produces &nbsp;.

In both stylesheets, a completely empty flow object is constructed with (empty-sosofo).

4.3.6.3. Selecting data

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.

4.3.6.4. Selecting elements

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.

There are many other expressions for manipulating nodes and node lists.

4.3.6.5. Processing expressions

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.

4.3.6.6. Define expressions

You can declare your own functions and constants in DSSSL. The general form of a function declaration is:

(define (function args)
  function-body)

(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.

4.3.6.7. Conditionals

In DSSSL, the constant #t represents true and #f false. There are several ways to test conditions and take action in DSSSL.

if

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 evaulated when the condition is not met. If you want to produce nothing, use (empty-sosofo).

case

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

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.

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?).

4.3.6.8. Let expressions

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)

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.

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.

4.3.6.9. Loops

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))))

4.3.7.1. Processing chapters

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.

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.

4.3.7.2. Processing titles

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 Section 4.3.7.4".

4.3.7.3. Processing paragraphs

Para elements are simply formatted as paragraphs.

4.3.7.4. Processing emphasis

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.

4.3.7.5. Processing subscripts and superscripts

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

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

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.

4.4.2.1. Using the lang attribute

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.

Table 4-1 summarizes the language codes for the supported languages.[2] The following chapter uses text generated in French:

<chapter lang="fr"><title>Bêtises</title>
<para>Pierre qui roule n'amasse pas mousse.</para>
</chapter>

4.4.2.2. Changing the default language

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. Table 4-1 summarizes the language codes for the supported languages. The following driver makes German the default language:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

(define %default-language% "dege")

</style-specification-body>
</style-specification>
<external-specification id="docbook" document="dbstyle">
</style-sheet>

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%

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:

<book><title>A Test Book</title>
<preface>
<para>There are three chapters in this book: <xref linkend=c1>, 
<xref linkend=c2>, and <xref linkend=c3>.
</para>
</preface>
<chapter lang=usen><title>English</title> ... </chapter>
<chapter lang=fr><title>French</title> ... </chapter>
<chapter lang=dege><title>Deutsch</title> ... </chapter>
</book>

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.