Appendix A. Changes in version 2.x

• Rewrote verbatim handling; fixed #556.

  There are a lot of changes to verbatim handling. The code has been refactored and cleaned up significantly. There are a number of backwards-incompatible changes as a result. (Though the goal is that most documents should look substantially the same.)

  1. A bug where db-line in the output didn’t take the starting line number into consideration has been fixed.

  2. Verbatim environments that aren’t numbered no longer have “invisible” line number markup.

  3. The verbatim features are provided using highlight.js and prism as much as is practical.

  4. There are new top-level parameters, $verbatim-embellishments and $verbatim-embellish-linenumbers. These can control embellishments overall and line numbering specifically at a global level. (Apparently, the XSLT 1.0 stylesheets didn’t number verbatim environments by default but when I wrote the xslTNG stylesheets, I did. I’m reluctant to make that backwards-incompatible change, so I’ve added a parameter to get that effect easily.)

  5. The verbatim style and syntax highlighter can be set on per-document basis with a processing instruction.

  6. The f:verbatim-highlight and f:highlight-verbatim functions have been removed. The highlighter, and highligting, are determined by the combination of options. See Section 2.11, “Verbatim environments”.

• Added $use-id-as-filename parameter. If true, the xml:id value of a chunk will be used as the chunk filename.

• Support xrefstyle on link; fixed #561.

• A recent fix for bottom-of-page navigation links broke the persistent ToC navigation link. This release fixes both of those problems simultaneously; fixed #543.

• Reworked the main.xsl module to resolve import precedence issues; fixed #536. This change has two visible consequences:

  1. The formatting of command in cmdsynopsis uses span instead of code. This was always the intent; a cmdsynopsis is already monospaced.

  2. The formatting of task elements no longer suppresses the title. I don’t imagine that was intentional, but if you use task elements with titles, make sure you’re getting the results you expect!

  It’s also possible that this will have consequences in customization layers, but I don’t think that’s the case.

• Added a wrapper around cmdsynopsis; fixed #538. This makes customization of command synopses more practical in CSS.

• In the DocBook Python script, pass the Saxon return code back to the shell; fixed #535. Thanks, Frank!

• Fixed the CI build issue that was preventing the link to the most recent version of the guide from updating correctly; fixed #534.

• The principle new feature in version 2.3.0 is support for landscape (and portrait) rotation in paged media, fixing #476. This entails a lage number of changes to the paged media stylesheets and some markup changes in the HTML output.

  The most significant markup change is that elements that appear before the first section of component (before the first section of a chapter, for example) are now wrapped in a div element with the class “db-bfs”. This true in both browser and paged media presentations, though it’s currently unused in the browser presentation.

  Another change is that rotated elements will have “landscape” or “portrait” in their class attribute. At present, this has no effect in the browser presentation.

• Added support for titleabbrev in bibliography entries; fixed #487. Thanks, Frank!

• Added a vendor-weasyprint.css stylesheet for use with the $vendor-css parameter; fixed #497.

• Reworked Java initialization; fixed #504. This change is a consequence of how Saxon initializes the XML Resolver.

• Support linking on db:arg and db:group elements; fixed #528.

• Provided additional class attributes on various flavors of synopsis to enable more precise CSS styling.

• Add missing zh-cn localization for “Danger”; fixed #510.

• Added Section 3.4, “Customizing title pages”, describing how to customize title pages; fixed #507.

• Added support for a numbered DocBook processing instruction pseudo-attribute to control numbering of divisions, components, and sections on a per-element basis; fixed #506. See Section 3.6.1, “Numeration overrides”.

• Added $variablelist-panelset to support a “panel set” presentation of variable lists.

• Simplified and corrected the selection of bibliography entry abbreviations; fixed #479. Thanks, Frank!

• Improved docbook.py script. Thanks, Rafal!

• Added support for caption elements in CALS tables; fixed #472.

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

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

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

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

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

• 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 https://xsltng.docbook.org/ns/css 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 gradle.properties.

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

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

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

• Added a $verbatim-trim-leading-blank-lines parameter. This is analagous to the $verbatim-trim-trailing-blank-lines parameter except for leading blank lines instead of trailing ones. It is false by default, for backwards compatibility, but note that some syntax highlighters may trim leading (and trailing) blank links anyway.

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

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