Appendix A. Changes in version 2.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.

ⓘ
Note

This chapter is still being revised. This is (mostly) a placeholder.

  • Implemented an on-page table of contents feature.

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

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

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

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

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

  • Support creation of ToCs generated by hand. (Former handling for tocdiv and tocentry was just broken.)

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

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

  • 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 mediaobject-test group of tasks. (Run ./gradlew tasks in the source repository.)

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

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

  • Removed ↑ from $chunk-nav.

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

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

  • Reworked the way the persistent ToC is generated.

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

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

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

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

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

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