Five Interesting Things Norman Tovey-Walsh ndw@nwalsh.com 2020-07-18 This book highlights five interesting things about the DocBook xslTNG Stylesheets. 1.1.0 2020-07-18 ndw Renamed chapter 1 and chapter 5 on the advice of a reviewer. 1.0.1 2020-06-29 ndw Small changes motivated by improvements in the CSS for paged media. 1.0.0 2020-06-28 ndw First publication. 0.0.1 2020-06-20 ndw Initial draft. 2020 Norman Tovey-Walsh Clean Look and Feel The output from the DocBook xslTNG Stylesheets is designed to be clean, semantic with accessibility features wherever possible. The online presentation is driven by modern, widely-available CSS and JavaScript APIs.
Look and Feel in Firefox Screenshot of this chapter as rendered in Firefox on the Mac 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.
The header is fixed to the top of the page so navigation links are always available. Accessibility features include long descriptions of images and tables, alt-text for images, and headers for table rows and columns. Where JavaScript is used, reasonable non-JavaScript fallbacks are provided. On short pages, the footer always floats to the bottom of the page. The “persistent ToC” feature puts the whole document’s Table of Contents within easy reach on every page. The design is generally cleaner. There are different and slightly larger fonts, the column width never exceeds a practical reading width, and media queries make the design responsive to the narrower displays on phones and tablets. The focus on clean, semantic markup means that you can create new (and better!) styles with CSS. You can also write stylesheet extensions to customize the markup, to add additional details to the header and footer, for example. Persistent Table of Contents Persistent ToC The Persistent Table of Contents brings the document’s Table of Contents navigation hierarchy to every page. Clicking on the [toc] link in the upper right corner slides out the Table of Contents window from the right hand edge of the screen.
Persistent Table of Contents in Firefox Screenshot of this chapter with the persistent ToC as rendered in Firefox on the Mac Screenshot showing the persistent table of contents rendered as a popup on the right hand side of the page.
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 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. Highlights the click library Constant: √5 is my current favorite library for parsing command line arguments in Python. This constant is the 5. I’m also taking advantage of the ability to use (and ) to break the listing into manageable fragments for documentation. The listing above, and the one below, are lines from the same file. Click takes care of type checking the arguments Closed-form calculation of n’th Fibonacci number Stackoverflow answer to the question “how do I make an ordinal number in Python”? If this is a main program, run it! One of the real strengths of using a tool like Click to wrangle arguments is that you get type and range checking pretty much for free. This is the closed-form solution to finding the “nth” Fibonacci number: 1 5 1 + 5 2 n -1 -5 2 n If you use , the stylesheets automatically include the libraries (or the MathML rendering libraries of your choosing). This allows you to display complex equations, of course, but it can also improve the appearance of even simple expressions, such as √5. (This is an annotation, more about them in the next chapter.) The closed-form solution amuses me because I used calculating Fibonacci numbers (recursively) as an argument for greater expressive power in XSLT 1.0. “What if I wanted to number a list with the Fibonacci numbers?” Stackoverflow showed me how to print the number as an ordinal. Finally, if this is a main program, compute the answer. If you hover over the callout numbers in the listing, alt-text will be displayed. Annotations Annotations, as the name implies, 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. The same annotation can be used more than once. 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. This one is pointless, but it is used twice. Annotation, noun According to Merriam-Webster, an annotation is a note added by way of comment or explanation. They give as an example quotation:
The bibliography was provided with helpful annotations.
Annotations can point to the elements the annotate. Alternatively, elements can point to their annotations. Extended Links 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: DocBook ]]> With JavaScript enabled, this link to DocBook 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. Simplifying link markup It’s worth noting that although the XLink vocabulary is defined purely in terms of attributes so that it can more easily be embedded in other vocabularies, there’s no reason a DocBook customization couldn’t use simplified markup to identify links: DocBook ]]> In this example, I’ve adopted the convention that an extended-link element identifies an extended link with the semantic that target element(s) identify the link target and any other element identifies the source. This is equivalent to the attribute form and could easily be translated into it. Paged media support The DocBook xslTNG Stylesheets anticipate that “print” output, that is, paged media, will be provided with a CSS formatter such as or . The stylesheet intended for paged media output produces slightly different HTML than the online stylesheet. This print customization assures that JavaScript features are disabled and changes the markup used for some elements. The resulting “.pdf.html” file is then processed by the formatter. In as much as the different CSS formatters behave differently and have different extensions for features that are needed in print but not yet standardized, additional customization may be necessary. References AntennaHouseAH Formatter. Version 7.0.3. CanIUseCan I use… Support tables for HTML5, CSS3, etc. 20 June 2020. ClickClick. Version 7.2. CSSCSS Specifications. World Wide Web Consortium. 2020. HTMLHTML: Living Standard. 18 June 2020. MathJaxMathJax. MathMLMathematical Markup Language (MathML) Version 3.0. World Wide Web Consortium. 2014. metadata-extractormetadata-extractor. Version 2.14.0. PrincePrince. Version 13.5. RFC 5147URI Fragment Identifiers for the text/plain Media Type. E. Wilde and M. Duerst, editors. Internet Engineering Task Force. 2008. XIncludeXML Inclusions (XInclude) Version 1.0 (Second Edition). World Wide Web Consortium. 2006. XLinkXML Linking Language (XLink) Version 1.1 World Wide Web Consortium. 2010. Colophon This book was authored in DocBook 5.1 with Emacs. It was formatted for presentation with the DocBook xslTNG Stylesheets version using . This book was authored in DocBook 5.1 with Emacs. It was formatted for presentation with the DocBook xslTNG Stylesheets.