Appendix AChanges in version 2.x

A.1Change Log

This section documents the changes made in each release. This does not necessarily include every minor change, only those likely to be of interest to users of the stylesheets. See the commits and pull requests on the repository for finer detail.

A.1.1Changes in version 2.2.0

  • Support $titleabbrev-passthrough, fixed #469.

  • Integrated support for automatic glossaries contributed by Frank Steimke. Fixed #453 and #445. Extended to support automatic glossary divisions, fixed #460.

  • Added support for automatic bibliographies analogous to automatic glossaries.

  • Integrated documentation improvements contributed by Frank Steimke, fixed #452.

  • Attempted to work around a scrolling issue in the persistent ToC, fixed #451.

  • Corrected the image intrinsic functions so that non-integer dimensions are supported in SVG; added support for dimensions with units, fixed #413, #432, and #443.

  • Allow pre- and post-processing transforms to be specified as command line parameters, fixed #440 and #441

  • Merged a fix to the German localization contributed by Tom Schraitle, fixed #428.

  • Make sure $v:debug is declared in print.xsl, fixed #420.

  • Ensure that subtitle appears on a book titlepage, fixed #415.

  • Integrated improved support for improved cross reference styles contributed by Frank Steimke, fixed #414.

  • Merged a patch, contributed by Frank Steimke, to avoid a warning when a table width is exactly the same as the nominal page width, fixed #411.

  • Corrected an error where column widths computed from CALS tables did not correctly specify units, fixed #410.

A.1.2Changes in version 2.1.9

  • Links added with m:head-additions were not being made relative to the chunk base URI. Reworked m:html-body-script slightly so that links there can also be made relative appropriately.

A.1.3Changes in version 2.1.8

  • Added m:head-additions mode for customizers. This allows a customization layer to add information to the HTML head.

  • Added tunnel parameters to the list of titles templates. This allows a customization to determine the parent element of the list of titles. (For example, to format the table of contents for a set differently than for the contained books.)

  • When formatting a part with a partintro and a list of titles, move the partintro before the list of titles. (This is technically backwards incompatible, but it seems so obviously superior to the current behavior that I’m calling the current behavior a bug.)

  • Removed incorrect use of v: prefix in the documentation; fixed #406.

  • Added a $inline-xlink-href parameter to control whether or not XLink href attributes are printed after the link in the paged media stylesheets; fixed #404. Previously, this was handled in two different ways: for simple links, the links where always printed; for extended links, the text were actually added by CSS. Now they’re both controlled by the parameter and CSS is no longer involved.

  • Hacked PrismJS a bit; added support for ABNF and my own attempt at an Invisible XML highlighter.

  • Added CSS for lists of titles in sets.

A.1.4Changes in version 2.1.7

  • Tweaks to presentation.js to make sure revealed elements are in view.

  • Tweaks to the bundled PrismJS to support (not especially well) syntax highlighting Invisible XML.

  • CSS improvements for footnote rendering in paged media.

  • First attempt to support Vivliostyle for rendering paged media.

A.1.5Changes in version 2.1.6

  • Fixed the bug where disabling division, component, or section numbers didn’t change their presentation in Tables of Contents. It’s not especially elegant, the stylesheets simply check if “unnumbered” occurs in the localization group name for the title. If it does, then the unnumbered table of contents template is also selected.

  • Fixed the bug where chunk navigation wasn’t localized.

A.1.6Changes in version 2.1.5

  • Introduced “presentation mode” as a replacement for earlier “slides” and “speaker notes” customizations. Simplified the normal “chunk navigation” processing.

  • Improved copyright handling on title pages. Removed most CSS page-break-inside: avoid rules. (They cause overflow if the space isn’t big enough.)

  • Added the ability to put arbitrary CSS properties on elements with attributes in the namespace.

  • Added css to the set of verbatim environment languages that are syntax highlighted by default.

  • The $output-media is now set to “epub” when formatting EPUBs.

  • Paged media improvements: removed body margins (they’re provided by the page setup); enabled hyphenation.

  • Add documentation for the properties in

  • Yet even more fussing with the building the distribution on Windows.

A.1.7Changes in version 2.1.4

  • Fixed a bug where the Index by module index in the PDF guide ran off the bottom of the page.

  • Improved the left and right page headers in PDF output.

  • Fixed (another) bug in $unwrap-paragraphs support.

  • Fixed a bug where the link for the persistent ToC was not visible. (This started in 2.1.3 when a z-index was added to the page header.)

  • Added a m:back-cover mode for producing a back cover. By default, this mode produces no output, but it can be changed an a customization layer to produce a cover.

  • Fixed a few places where the $debug parameter was not being tested correctly. Documented the templates-matches debug flag.

  • Reworked how the change log is produced; it’s now an appendix rather than attempting to put it between the front cover and the table of contents.

  • Fixed some navigation issues associated with annotations when JavaScript is being used to display the annotations.

  • For convenience, the SASS SCSS stylesheets are now in the distribution ZIP archive. These aren’t used at runtime, but if you have plans to make extensive changes to the CSS, deriving those changes from the SASS sources may prove easier than updating the derived CSS directly.

  • Added CSS variables: default-font-size and default-line-height to simplify customization.

  • Reworked the title page for articles in books. Previously, they only rendered the title. An article in a book now renders the “full” titlepage that’s consistent with stand-alone articles.

  • A bunch of build fixes: matrix builds work again, attempting to get the release information uses an authenticated request if it can, an old Xerces implementation pulled in by a transitive dependency is explicitly excluded (it has problems with UTF-16 encoded files, for example on Windows).

A.1.8Changes in version 2.1.3

  • Fixed a bug in the handling of the $unwrap-paragraphs parameter. The list of “block” elements understood to be “unwrapped” was incomplete.

  • Fixed the way title and citetitle are formatted in bibliographies.

  • Added support for the translate attribute in HTMLvia the $translate-suppress-elements parameter and the f:translate-attribute() function. Note that these attributes are in the HTML output, so they won’t directly help with translations of the source XML. Apparently, some production toolchains involve translating the published HTML.

  • Attempt to address problems caused by Oxygen change markup in CALS tables. Deleted cells are now identified in the output (to keep the dimensions of the table valid) rather than removing them.

  • Fixed the rendering of table footnotes in PDF.

  • Added support for PDF bookmarks for H1 and H2 headings.

  • Removed the page-break-inside: avoid property from program listings. The property was causing some program listings to be rendered beyond the bottom of the page in PDF.

  • CSS has been adjusted in an attempt to avoid extra space below a calloutlist.

  • Added z-index to avoid problems in fixed navigation headers.

  • Extended the documentation about Docker and Docker alternatives; improved the Dockerfile, especially with respect to Linux.

  • There are now two files in the GitHub distribution, the “normal” one and one labeled “nosaxon”. The “nosaxon” ZIP file is the same release, but without a copy of Saxon-HE. This release should be easier to integrate into environments, like <oXygen/>, where a version of Saxon is already provided. (Having two different versions of Saxon can cause problems.)

  • A fallback version of the “Pygments” CSS file is included in repository. This allows the correct formatting to be achieved even if Pygments (and especially pygmentize) isn’t available locally.

  • Lots (and lots) of build changes to support building the release on Windows. It’s now at the “works on my machine” stage, but not yet working generally. Specific suggestions welcome.

  • A few other build improvements. A wholly unsuccessful attempt to use the matrix build in CI.

  • A variety of typos have been fixed in the guide.

A.1.9Changes in version 2.1.2

A.1.10Changes in version 2.1.1

  • Added a $copy-verbatim-js parameter. This feature creates a dynamic “copy” button on verbatim listings that will copy the text of the listing (without callouts, line annotations, etc.) to the clipboard.

  • Fixed a minor issue where some spurious namespace declarations were being copied into the HTML output.

A.1.11Changes in version 2.1.0

This is the first official release of the “2.x” versions of the stylesheets. Version 2.1.0 introduces a number of new features and corrects major issues with localization and media object rendering, but is not entirely backwards compatible with the 1.x versions. The incompatibilities should mostly effect customization layers, not formatted documents, though the HTML output will be a little different in most cases. For a summary of the changes, see Section A.2, “Introduction to xslTNG 2.x”.

A.2Introduction to xslTNG 2.x

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.5, “Testing tasks”.