Five Interesting Things

The output from the DocBook xslTNG Stylesheets is designed to be clean, semantic HTML with accessibility features wherever possible. The online presentation is driven by modern, widely-available CSS and JavaScript APIs.

Screenshot of the new look and feel as rendered in Firefox. There’s a header across the top with Home, Up, Next, and Previous links. There’s a footer across the bottom with similar navigation features divided into a three column table: Previous on the left, Up and Home in the center, and Next on the right. The titles of preceding and next pages are shown in the footer.

Figure 1.1. Look and Feel in Firefox

The Persistent Table of Contents brings the document’s Table of Contents navigation hierarchy to every page. Clicking on the link in the upper right corner slides out the Table of Contents window from the right hand edge of the screen.

Screenshot showing the persistent table of contents rendered as a popup on the right hand side of the page.

Figure 2.1. Persistent Table of Contents in Firefox

Links in the persistent ToC navigate to the pages they identify. For large documents with long ToCs, the window scrolls and attempts to place the current page at the top of the ToC view.

Callouts are a mechanism for decorating the verbatim content of programlisting elements with marks that can be cross-referenced in documentation. They have the real advantage that they can be used to decorate the actual code or other listing. Importing the actual listing assures that the documented listing and the actual listing will be the same.

A system where you have to import the code or add the markup inline introduces the risk that the listing being documented will not be updated when the underlying resource is updated.

The program below computes the “nth” Fibonacci number.

1 |#!/bin/env python
  | 
  |"""Computes the n'th Fibonacci number."""
  | 
5 |import sys
  |import math
  |import click  ①
  | 
  |SQRT5 = math.sqrt(5)  ②

I’m also taking advantage of the ability to use XInclude (and RFC 5147) to break the listing into manageable fragments for documentation. The listing above, and the one below, are lines from the same file.

11 |@click.command()
   |@click.argument("number", nargs=1,
   |               ③ type=click.IntRange(1, None))
   |def fibonacci(number):
15 |    """Calculate the 'number'th Fibonacci number."""
   |    prefix = f"The {make_ordinal(number)} Fibonacci number is "
   |    try:
   |        value = (((1 + SQRT5) / 2) ** number -
   |                 ((1 - SQRT5) / 2) ** number) / SQRT5      ④
20 |        print(f"{prefix}{math.floor(value):,}.")
   |    except OverflowError:
   |        print(f"{prefix}too large to calculate.")
   |        sys.exit(1)
   | 
25 | 
   |def make_ordinal(n):
   |    """Create an ordinal from a number."""
   |    # https://stackoverflow.com/questions/9647202          ⑤
   |    suffix = ["th", "st", "nd", "rd", "th"][min(n % 10, 4)]
30 |    if 11 <= (n % 100) <= 13:
   |        suffix = "th"
   |    return str(n) + suffix
   | 
   | 
35 |if __name__ == "__main__":
   |    fibonacci()  ⑥

If you hover over the callout numbers in the listing, alt-text will be displayed.

Annotations, as the name implies^⌖3, allow you to associate annotations with content in your document. Annotations are non-local (they’re associated by ID/IDREF not containment) and the linking markup is bi-directional^⌖4. The same annotation can^⌖2 be used more than once^⌖2.

Annotations can be rendered with or without JavaScript support. With JavaScript, the annotations are popups. Without JavaScript, they’re presented at the bottom of the page, similar to footnotes, but styled somewhat differently. In paged media, annotations are rendered as footnotes and their titles are ignored.

XLink extended links, like annotations, can be non-local. The more interesting feature is that unlike HTML anchors, they can also have multiple endpoints. Consider the following link: ^⌖5

 1 |<phrase xmlns:xlink="http://www.w3.org/1999/xlink"
   |        xlink:type="extended">
   |  <link xlink:title="DocBook.org"
   |        xlink:label="target"
 5 |        xlink:href="http://docbook.org/"
   |        xlink:type="locator"/>
   |  <link xlink:title="DocBook on Wikipedia"
   |        xlink:label="target"
   |        xlink:href="http://en.wikipedia.org/wiki/DocBook"
10 |        xlink:type="locator"/>
   |  <citetitle xlink:label="source" xlink:type="resource"
   |  >DocBook</citetitle>
   |  <link xlink:to="target" xlink:from="source" xlink:type="arc"/>
   |</phrase>

With JavaScript enabled, this link to DocBook [DocBook.org, DocBook on Wikipedia] has a popup menu to select the link target. Rendered without JavaScript, the link choices are presented as alternatives after the link. In print media, the link URIs are also shown in parenthesis.