Appendix A. Changes in version 2.x
A.1. Change 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.1. Changes 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.
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.2. Changes in version 2.1.9
Links added with
m:head-additions
were not being made relative to the chunk base URI. Reworkedm:html-body-script
slightly so that links there can also be made relative appropriately.
A.1.3. Changes in version 2.1.8
Added
m:head-additions
mode for customizers. This allows a customization layer to add information to the HTMLhead
.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 containedbook
s.)When formatting a
part
with apartintro
and a list of titles, move thepartintro
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
set
s.
A.1.4. Changes 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.5. Changes 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.6. Changes 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
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.
A.1.7. Changes 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 thetemplates-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
anddefault-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.8. Changes 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
andcitetitle
are formatted in bibliographies.Added support for the
translate
attribute in HTMLvia the$translate-suppress-elements
parameter and thef: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.9. Changes in version 2.1.2
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.
A.1.10. Changes 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.11. Changes 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.2. Introduction 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
andm:mediaobject-end
.Fixed the bug where attributes on image, video, audio, and text objects in
mediaobject
andinlinemediaobject
were not being preserved in the output. In particular, this meant thatrole
attributes on those objects were not reflected in the HTMLclass
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 ofdiv
elements) for sections inside ofrefentry
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 emptytoc
element (ordb-toc
processing instruction).Added support for creating ToCs by hand. (Former handling for
tocdiv
andtocentry
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 aformalgroup
, 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
andt: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 aftermain
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 thebody
element, they’re placed in thehead
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 akeycombo
.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, butdb-footnote
isn’t used that way.Fixed bug where
authorgroup
wasn’t being processed inbiblioentry
.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”.