Chapter 5. Implementation details

Chunking is controlled by the $chunk-include and $chunk-exclude parameters. These parameters are both strings that must contain an XPath expression.

For each node in the document, the $chunk-include parameter is evaluated. If it does not return an empty sequence, the element is considered a chunking candidate. In this case, the $chunk-exclude parameter is evaluated. If the exclude expression does return an empty sequence, then the element identified becomes a chunk. (If the exclude expression returns a non-empty value, the element will not become a chunk.)

Lengths appear in the context of images (width and height) and tables (column widths). Several different units of length are possible: absolute lengths (e.g., 3in), relative lengths (e.g., 3*), and percentages (e.g., 25%). In some contexts, these can be combined: a column width of “3*+0.5in” should have a width equal to 3 times the relative width plus ½ inch.

In practice, some of the more complicated forms in TR 9502:1995 have no direct mapping to the units available in HTML and CSS. The stylesheets attempt to specify a mapping that’s close. Broadly, they take the nominal width of the table ($nominal-page-width), subtract out the fixed widths, divide up the remaining widths proportionally among the relative widths, and compute final widths. The final widths can be expressed either in absolute terms or as percentages.

In handling the width and height of images, the intrinsic width and height of the image in pixels are converted into lengths by dividing by $pixels-per-inch. Nominal widths are taken into consideration if necessary.

The list of recognized units (in, cm, etc.) are taken from $v:unit-scale.

There are four verbatim styles: lines, table, plain, and raw.

lines

In the lines style, each line of the verbatim environment is marked up individually. In this style, lines can be numbered and callouts can be inserted.

table

In the table style, each line of the verbatim environment is marked up individually, very much like the lines style. In this style, lines can be numbered and callouts can be inserted. It differs from the lines style in that the whole thing is wrapped in a table.

The table has one row and two columns. The line numbers appear in the first column, the lines in the second. This format was added in order to improve the display in user agents that don’t support CSS. Ironically, in the course of adding this style, a number of changes were made to the way line numbers are formatted in the lines style making it largely, perhaps entirely, unnecessary.

plain

In the plain style, callouts can be inserted, but additional markup is not added (except for the callouts). Consequently, it isn’t possible to do line numbering or syntax highlighting. (It may be possible to provide these features with JavaScript libraries in the browser, however.)

raw

In the raw style, no changes are made to the verbatim content. It’s output as it appears. Inline markup that it contains, emphasis or other elements, will be processed, but you cannot add line numbers, callouts, or syntax highlighting.

Consult I. Parameter reference for a variety of parameters that control aspects of verbatim processing.

  |<span class="line">
  |  <span class="ln">5</span>
  |  <span class="ld">The line of text</span>
  |</span>

  |<span class="line">
  |  <span class="ln"> 5 <span class="nsep">|</span></span>
  |  <span class="ld">The line of text</span>
  |</span>

Starting in version 1.11.0, the way media objects are processed has been refactored. This is designed to support fallback at both the object level (imageobject, audioaobject, videoobject, textobject, and imageobjectco) and at the data level (imagedata, audiodata, videodata, and textdata within the objects).

Each data element and object element is processed in the m:mediaobject-info mode. This returns a map for each object that contains an array of maps, one for each data element:

Each data map has the following structure:

The uri and href properties are computed by processing the data elements in the m:mediaobject-uris mode.

Armed with information about the objects and the data associated with them, the stylesheets proceed to choose an object and then process it. Each object is considered in turn, if any of the data elements it contains were excluded, then it is rejected. The first object where all of the elements are acceptable is selected.

Consider this example:

 1 |<mediaobject>
   |<imageobject>
   |  <imagedata fileref="image.svg"/>
   |  <imagedata fileref="image.eps"/>
 5 |  <imagedata fileref="image.png" width="4in"/>
   |</imageobject>
   |<imageobject>
   |  <imagedata fileref="image.svg"/>
   |  <imagedata fileref="image.png" width="40em"/>
10 |</imageobject>
   |</mediaobject>

If this is being processed for online presentation, the default value of $mediaobject-exclude-extensions will exclude the EPS file. Because one of it’s data elements was excluded, the processor will choose the object containing only the SVG and PNG images for online presentation.

Once an object is selected, an appropriate wrapper is created and all of the alternatives are placed within it. So the example above will result in picture element containing a source for the SVG image and an img for the fallback PNG.

It’s difficult to make title pages for documents easy to customize. There is a lot of variation between documents and the styles can have very precise design constraints. At the end of the day, if you need complete control, you can define a template that matches the element in the m:generate-titlepage mode and generate all of the markup you wish.

The default title page handling attempts to make some declarative customization possible by using templates. A typical header template looks like this:

 1 |<db:section>
   |  <header>
   |    <tmp:apply-templates select="db:title">
   |      <h2><tmp:content/></h2>
 5 |    </tmp:apply-templates>
   |    <tmp:apply-templates select="db:subtitle">
   |      <h3><tmp:content/></h3>
   |    </tmp:apply-templates>
   |  </header>
10 |</db:section>

Any HTML element in the template will be copied to the output. The semantics of a “template apply templates” element (tmp:apply-templates) is that it runs the ordinary xsl:apply-templates instruction on the elements that match its select expression. If they result is the empty sequence (e.g, if there is no subtitle), nothing is output. If there is a result, the content of the tmp:apply-templates element is processed. Anywhere that tmp:content appears, the result of applying templates will be output.

In this example, if the title is “H₂O” and there is no subtitle, the resulting HTML title page will be:

  |<header>
  |  <h2>H<sub>2</sub>O</h2>
  |</header>

The stylesheets fully support annotations, including a number of presentation styles enabled by JavaScript in the browser. They also support an extension of the documented semantics of annotation.

Annotations are applied to elements with links. Either the element must point to its annotations (with an annotations attribute) or the annotations must point to the elements they annotate (with an annotates attribute). These are documented as ID/IDREF links but they are not IDREFS attributes because annotations may be stored separately.

Starting in version 1.5.1, the DocBook xslTNG Stylesheets^⌖1 support a non-standard extension: if you place the string xpath: in the annotates attribute of an annotation, then the rest of the attribute is assumed to contain an XPath expression that points to the element(s) to which the annotation applies. (If you want to put IDREF values before the xpath: token, that’s fine, but you can’t put them after; the expression continues to the end of the attribute value.)

Suppose, for example, that you wanted to annotate the stylesheet title in the previous paragraph. The standard mechanisms would require that you either put an xml:id attribute on the element or point to the annotation from the element. With the XPath extension, you can do this:

1 |<annotation
  |   annotates="xpath:preceding-sibling::db:para/db:citetitle"
  |   xmlns:db="http://docbook.org/ns/docbook">
  |<para>This annotation applies to the stylesheet title.
5 |For a discussion of this annotation, see the
  |following paragraphs.</para>
  |</annotation>

When the XPath expression is evaluated, the annotation element is the context item. Often, this means that you’ll want to start the expression with id() or /.

The namespace context for the expression is also the annotation element, that’s why I’ve added the DocBook namespace binding for the db prefix. In practice, if you’re doing this on several annotations, you can just put all the namespace bindings on a common ancestor. All of the bindings in scope on the annotation element are available in the expression.

Caveats:

1. There’s no way to have multiple XPath expressions. You can’t put “xpath:” in there twice. If you want an annotation to apply to multiple elements, you’ll have to construct a single expression that selects all the elements, or duplicate the annotation, or use ID/IDREF links.

   If this turns out to be a serious limitation in practice, additional syntax could be added to support multiple expressions, but it doesn’t seem necessary.

2. You can only select elements. There’s no way to select the third word in a particular paragraph, for example, unless it already has some markup around it. There’s also no way to select a comment or a processing instruction.

The placement of the annotation marker (“⌖” by default) can also be controlled globally and on individual annotations. The $annotation-placement parameter provides global control. To specify the position for an individual annotation, put the token “before” or “after” in the role attribute on the annotation.

Processing a DocBook document is a multi-stage process. The original document is transformed several times before converting it to HTML. The standard transformations are:

1. Adjust the logical structure. Adds an XML base attribute to the root of the document and converts media object entityref attributes into fileref attributes.

2. Perform XInclude processing. Only occurs if the appropriate extension function is available and if the document contains XInclude element.

3. Convert DocBook 4.x to DocBook 5.x. Only occurs if the root element is not in a namespace.

4. Peform transclusion.

5. Perform profiling.

6. Normalize the content. This removes a lot of variation that’s allowed for authoring. For example, authors aren’t required to use an info element if a formal object has only a title. This process adds the info element if it’s missing.

7. Resolve annotations.

8. Process XLink link bases.

9. Validate. Only occurs if the appropriate extension function is available and the stylesheet specifies a $relax-ng-grammar.

10. Process Oxygen change markup. Only occurs if $oxy-markup is true and the document contains Oxygen change markup processing instructions.

A customization can introduce transformations to the original document using three parameters:

$transform-original

This transform runs before step 1 in the standard transformations. If this transformation is used, it must take special care to preserve the base URI of the original document by adding an xml:base attribute to the root element (if it doesn’t already have one).

Only the first transformation in the list has access to the original base URI. If it isn’t preserved, relative references to other documents will be resolved against the static base URI of the stylesheet and not the URI of the original document. That’s unlikely to be correct.

$transform-before

This transformation runs after step 10. Its input is the DocBook document that will be transformed into HTML.

$transform-after

This transformation runs after the DocBook document has been transformed into HTML. The resulting HTML document is not valid HTML, but contains islands of valid HTML that will be separated out into chunks by subsequent processing.

(If you need to insert a transformation in the middle of the standard transformations, you’ll have to update the $v:standard-transforms variable in your customization.)

Each of the transformation variables holds a list of transforms that will be applied in the order specified. Each member of the list can be a map or a string. If a string is provided, it’s the equivalent of providing this map:

  |map {
  |  'stylesheet-location': $the-string
  |}

The map can have several keys: