Appendix A. Changes in version 2.1.0

Version 2.x of the DocBook xslTNG Stylesheets include some substantial changes from version 1.x. If you use the stylesheets “out of the box” without any customization, you should have no trouble updating from version 1.x to version 2.1.0 (or later), but there will be differences in the HTML produced. If you have customization layers for 1.x, you may need to change them in order to get the results you expect from 2.x.

The most significant rewrite, and the change that actually motivated the decision to adopt some backwards incompatible changes, is in the area of localization. Version 1.x of the xslTNG stylesheets attempted to simplify (from the preceding XSLT 2.0 stylesheets) how generated text was constructed. The model adopted simply didn’t work for some languages. Trying to adapt the model to support these languages was going to result in something even more complicated than what had worked before, so the model has largely been reverted to what it was before.

The format of the localization data and the way that it’s used are the subject of Chapter 4, Localization. In broad terms, the new system should produce “the same results” as the old system for an equivalent localization, but there may be small changes in the way lists of titles and cross references are formatted.

The major changes are:

  • Completely reworked how localization is handled. See Chapter 4, Localization. The localization file format has changed. Localization files are no longer simply transformed from the XSLT 1.0 stylesheet format.

  • Completely reworked how numbering of elements is performed. See Section 3.5, “Controlling numeration”. It’s a bit more complicated now, but it’s also more flexible and better tested. The default numeration should be the same as before, although a few small changes may appear in places where (I think) the previous numeration was wrong.

  • Completely refactored the way that media objects are located during the transformation and how the URIs for them are generated in the output. It is now possible to store the media objects in a location independent of the source files. Four separate source arrangements are represented in the test suite and each can be processed to produce several different outputs; see the all_mo_tests build target and its dependencies.

  • Refactored the templates for processing media objects to improve support for accessibility metadata and formatting copyright statements, legal notices, etc. See m:mediaobject-start and m:mediaobject-end.

  • Fixed the bug where attributes on image, video, audio, and text objects in mediaobject and inlinemediaobject were not being preserved in the output. In particular, this meant that role attributes on those objects were not reflected in the HTML class attribute.

  • Reworked audio and video fallback. Placing an HTML prose description in the video tag is not the correct approach in modern browsers. That prose is only rendered by browsers that don’t understand the video tag at all. Apparently, it has to be handled by JavaScript. There’s now a $fallback-js parameter.

  • Support media objects that have no media (e.g., a media object that contains only inline text objects).

  • Implemented an on-page table of contents feature.

  • Switched to section elements (instead of div elements) for sections inside of refentry and a number of other places. This supports the new on-page table of contents feature and should have been done when the rest of the sectioning elements were converted.

  • Reworked ToC handling. Added $auto-toc parameter. The placement of generated lists-of-titles can now be controlled with an empty toc element (or db-toc processing instruction).

  • Added support for creating ToCs by hand. (Former handling for tocdiv and tocentry was just broken.)

  • Placement of table titles, before or after the table, is now set with $formal-object-title-placement. For backwards compatibility, it defaults to ‘before’ for tables. Within a formalgroup, title placement is controlled by $formalgroup-nested-object-title-placement. In a related way, the placement of media object details can be set with $mediaobject-details-placement.

  • Labels for formal objects may be different, but I think the previous formatting was actually in error.

  • Changed $mediaobject-accessibility and $table-accessibility parameters into space-separated lists of strings.

  • The parameters for the t:top-nav and t:bottom-nav templates have changed. They are now always called, even when chunking is not being performed. The new $chunk parameter indicates whether or not a chunk is being formatted.

  • Moved the footer element from just after main to just inside it. This simplifies and improves CSS rendering and is arguably more correct.

  • Added an $unwrap-paragraphs parameter. If this parameter is true, a single DocBook paragraph that contains block elements (for example, tables or figures) will be rendered as several HTML paragraphs with blocks between them. HTML doesn’t allow blocks inside paragraphs.

  • Made including the docbook-print.css file conditional on producing print output. Modern browsers attempt to parse the file, even when the link specifies that it’s for print media, and produce a large number of spurious error messages.

  • Deprecated the m:html-body-script mode. Changed the way the standard scripts are included; instead of putting them at the end of the body element, they’re placed in the head but explicitly marked deferred.

  • In some contexts, for example callouts, labels are now used for the links instead of titles.

  • Removed up-arrow from the keys that $chunk-nav responds to. The up-arrow key is used by browser to move up the page and chunk navigation was interfering with that behavior. The U key will still go “up” in chunk navigation.

  • Reworked the persistent ToC. It can now store the ToC in a separate file. Improved the error messages when the persistent ToC is unavailable.

  • Changed ext:cwd() so that it always returns an absolute URI. This fixes a bug in chunk output base URI handling. Tidied up some code.

  • Process unexected elements in titlepage templates in the normal way; removed the warning message associated with them. Add it back by putting templates in $debug.

  • Improved presentation of multiple keycap elements in a keycombo.

  • Added table-of-contents to the linear flow of EPUBs. This fixes an epubcheck 3.3 error. Fixed the CSS for the ToC.

  • Added support for ISO 690 bibliographies via a $bibliography-style parameter.

  • Added a $message-level parameter to support suppressing some informational messages.

  • Removed db-footnote attributes from the output. Technically, attribute names that contain a hyphen are HTML5 extension attributes, but sometimes they make validation more difficult. Some extension attributes remain, because they’re used by JavaScript in the presentation for example, but db-footnote isn’t used that way.

  • Fixed bug where authorgroup wasn’t being processed in biblioentry.

  • Fixed a bug where orderedlist numeration was not handled correctly in cross-references to list items.

  • Fixed incorrect URIs for SVG draft overlay in print CSS.

  • Fixed a bug where the catalog.xml file in the jar file was not at a location where the XML Resolver would find it.

  • Updated the build system to use Pygments version 2.14.0. This effects the markup produced in some syntax highlighted listings. (You’re free to use any version of Pygments that’s convenient; this is just about conformance with the expected test results.)

  • The way unit tests are managed has been completely rewritten. See Section 6.4, “Testing tasks”.