Merge pull request #272 from ndw/guide-update

Guide and documentation updates (plus a bug fix)

properties.gradle

@@ -2,8 +2,8 @@
 ext {
   xslTNGtitle = 'DocBook xslTNG'
   xslTNGbaseName = 'docbook-xslTNG'
-  xslTNGversion = '2.0.11'
-  guideVersion = '2.0.11'
+  xslTNGversion = '2.0.12'
+  guideVersion = '2.0.12'
   guidePrerelease = true
 
   docbookVersion = '5.2CR5'

src/guide/xml/changelog.xml

@@ -2,6 +2,56 @@
             xmlns:xlink="http://www.w3.org/1999/xlink">
 <?db revhistory-style="list"?>
 
+<revision xml:id="r212">
+<revnumber>2.0.12</revnumber>
+<date>2023-03-12</date>
+<revdescription>
+<para>This is still a pre-release; see <link linkend="r208">2.0.10</link>.
+(Note that version 2.0.11 was not adequately documented in the change log.)</para>
+<itemizedlist>
+<listitem>
+<para>Fixed <link xlink:href="https://github.com/docbook/xslTNG/issues/271">a bug</link>
+where chapter and appendix numbering was wrong.
+</para>
+</listitem>
+<listitem>
+<para>Implemented an
+<link linkend="onpage-toc">on-page table of contents</link> feature.
+</para>
+</listitem>
+<listitem>
+<para>Switched to
+<tag namespace="http://www.w3.org/1999/xhtml">section</tag> elements for
+sections inside a <tag>refentry</tag> instead of
+<tag namespace="http://www.w3.org/1999/xhtml">div</tag> elements.
+This supports the new 
+<link linkend="onpage-toc">on-page table of contents</link> feature and
+should have been done when the rest of the sectioning elements
+were converted.
+</para>
+</listitem>
+<listitem>
+<para>Moved the 
+<tag namespace="http://www.w3.org/1999/xhtml">footer</tag> element from
+just after
+<tag namespace="http://www.w3.org/1999/xhtml">main</tag> to just inside it.
+This simplifies and improves CSS rendering and is arguably more correct.
+</para>
+</listitem>
+<listitem>
+<para>Made including the <filename>docbook-print.css</filename> 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.</para>
+</listitem>
+<listitem>
+<para>Fixed a bug where the <filename>catalog.xml</filename> file in the
+jar file was not at a location where the XML Resolver would find it.</para>
+</listitem>
+</itemizedlist>
+</revdescription>
+</revision>
+
 <revision xml:id="r210">
 <revnumber>2.0.10</revnumber>
 <date>2023-02-21</date>

src/guide/xml/guide.xml

@@ -55,6 +55,12 @@ contained herein.</para>
 <xi:include href="ch03b.xml"/> <!-- gentext -->
 <xi:include href="ch04.xml"/> <!-- implementation -->
 <xi:include href="ch05.xml"/> <!-- building  -->
+<xi:include href="ver2.xml"/>
+<xi:include href="glossary.xml"/>
+<xi:include href="references.xml"/>
+<xi:include href="ackno.xml"/>
+<xi:include href="index.xml"/>
+<xi:include href="mindex.xml"/>
 </part>
 <part>
 <title>Reference</title>
@@ -73,9 +79,4 @@ contained herein.</para>
 <xi:include href="ref-pi.xml"/>
 </part>
 <xi:include href="gfdl.xml"/>
-<xi:include href="glossary.xml"/>
-<xi:include href="references.xml"/>
-<xi:include href="ackno.xml"/>
-<xi:include href="index.xml"/>
-<xi:include href="mindex.xml"/>
 </book>

src/guide/xml/ver2.xml

@@ -0,0 +1,172 @@
+<appendix xmlns="http://docbook.org/ns/docbook"
+          version="5.0" xml:id="version2">
+<info>
+  <?db filename="version2"?>
+  <title>Changes in version 2.0</title>
+</info>
+
+<para>Version 2.x of the <citetitle>DocBook xslTNG
+Stylesheets</citetitle> 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.</para>
+
+<para>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
+<citetitle>xslTNG</citetitle> 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 <emphasis>even more complicated</emphasis> than
+what had worked before, so the model has largely been reverted to what
+it was before.</para>
+
+<para>The format of the localization data and the way that it’s used
+are the subject of <xref linkend="gentext"/>. 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.</para>
+
+<note>
+<para>This chapter is still being revised. This is (mostly) a placeholder.</para>
+</note>
+
+<itemizedlist>
+<listitem>
+<para>Implemented an
+<link linkend="onpage-toc">on-page table of contents</link> feature.
+</para>
+</listitem>
+<listitem>
+<para>Switched to
+<tag namespace="http://www.w3.org/1999/xhtml">section</tag> elements for
+sections inside a <tag>refentry</tag> instead of
+<tag namespace="http://www.w3.org/1999/xhtml">div</tag> elements.
+This supports the new 
+<link linkend="onpage-toc">on-page table of contents</link> feature and
+should have been done when the rest of the sectioning elements
+were converted.
+</para>
+</listitem>
+<listitem>
+<para>Moved the 
+<tag namespace="http://www.w3.org/1999/xhtml">footer</tag> element from
+just after
+<tag namespace="http://www.w3.org/1999/xhtml">main</tag> to just inside it.
+This simplifies and improves CSS rendering and is arguably more correct.
+</para>
+</listitem>
+<listitem>
+<para>Made including the <filename>docbook-print.css</filename> 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.</para>
+</listitem>
+<listitem>
+<para>Fixed a bug where the <filename>catalog.xml</filename> file in the
+jar file was not at a location where the XML Resolver would find it.</para>
+</listitem>
+<listitem>
+<para>Reworked ToC handling. Added <parameter>auto-toc</parameter> parameter.
+The placement of generated lists-of-titles can now be controlled with an
+empty <tag>toc</tag> element (or <tag class="pi">db-toc</tag> processing
+instruction).</para>
+</listitem>
+<listitem>
+<para>Support creation of ToCs generated by hand. (Former handling for
+<tag>tocdiv</tag> and <tag>tocentry</tag> was just broken.)
+</para>
+</listitem>
+<listitem>
+<para>Deprecated the <mode>m:html-body-script</mode> mode.
+Changed the way the standard scripts are included; instead of putting them
+at the end of the 
+<tag namespace="http://www.w3.org/1999/xhtml">body</tag> element, they’re
+placed in the 
+<tag namespace="http://www.w3.org/1999/xhtml">head</tag> but explicitly marked
+deferred.
+</para>
+</listitem> 
+<listitem>
+<para>Fixed incorrect URIs for SVG draft overlay in print CSS.</para>
+</listitem> 
+<listitem>
+<para>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 <code>mediaobject-test</code> group of tasks. (Run
+<command>./gradlew tasks</command> in the source repository.)</para>
+</listitem>
+<listitem>
+<para>Fixed the bug where attributes on image, video, audio, and text objects
+in <tag>mediaobject</tag> and <tag>inlinemediaobject</tag> were not being preserved
+in the output. In particular, this meant that <tag class="attribute">role</tag>
+attributes on those objects were not reflected in the HTML
+<tag class="attribute">class</tag> attribute.</para>
+</listitem>
+<listitem>
+<para>Changed <code>ext:cwd()</code> so that it always returns an absolute URI.
+This fixes a bug in chunk output base URI handling. Tidied up some code.</para>
+</listitem>
+<listitem>
+<para>Removed <keycap>↑</keycap> from <parameter>chunk-nav</parameter>.</para>
+</listitem>
+<listitem>
+<para>Support media objects that have no media (e.g., a media object that contains
+only inline text objects).</para>
+</listitem>
+<listitem>
+<para>Process unexected elements in titlepage templates in the normal way; removed
+the warning message associated with them. Add it back by putting
+<code>templates</code> in <parameter>debug</parameter>.</para>
+</listitem>
+<listitem>
+<para>Improved presentation of multiple <tag>keycap</tag> elements in a 
+<tag>keycombo</tag>.</para>
+</listitem>
+<listitem>
+<para>Added table-of-contents to the linear flow of EPUBs. This fixes an
+<application>epubcheck</application> 3.3 error. Fixed the CSS for the ToC.</para>
+</listitem>
+<listitem>
+<para>Reworked the way the <link linkend="persistent-toc">persistent ToC</link>
+is generated.</para>
+</listitem>
+<listitem>
+<para>Added support for ISO 690 bibliographies via a
+<parameter>bibliography-style</parameter> parameter.
+</para>
+</listitem>
+<listitem>
+<para>Fixed bug where <tag>authorgroup</tag> wasn’t being processed in
+<tag>biblioentry</tag>.
+</para>
+</listitem>
+<listitem>
+<para>The parameters for the <template>t:top-nav</template> and
+<template>t:bottom-nav</template> templates have changed. They are now always
+called, even when chunking is not being performed. The new
+<code>$chunk</code> parameter indicates whether or not a chunk is being formatted.
+</para>
+</listitem>
+<listitem>
+<para>Fixed a bug where <tag>orderedlist</tag> numeration was not handled
+correctly in cross-references to list items.</para>
+</listitem>
+<listitem>
+<para>Labels for formal objects may be different, but I think the previous
+formatting was actually in error.
+</para>
+</listitem>
+<listitem>
+<para>In some contexts, for example callouts, labels are now used for the
+links instead of titles.</para>
+</listitem>
+</itemizedlist>
+
+</appendix>

src/main/xslt/modules/titles.xsl

@@ -456,6 +456,21 @@
   </xsl:choose>
 </xsl:template>
 
+<xsl:template match="db:chapter|db:appendix" mode="mp:label-number" as="xs:integer">
+  <xsl:choose>
+    <xsl:when test="ancestor::db:book and self::db:chapter">
+      <xsl:number from="db:book" count="db:chapter" level="any"/>
+    </xsl:when>
+    <xsl:when test="ancestor::db:book and self::db:appendix">
+      <xsl:number from="db:book" count="db:appendix" level="any"/>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:sequence select="count(preceding::*
+                                  [node-name(.)=node-name(current())]) + 1"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
 <xsl:template match="*" mode="mp:label-number" as="xs:integer">
   <xsl:sequence select="count(preceding-sibling::*
                               [node-name(.)=node-name(current())]) + 1"/>

src/test/resources/expected/book.005.html

@@ -1 +1 @@
-<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" class="no-js"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><script>(function(H){H.className=H.className.replace(/\bno-js\b/,'js')})(document.documentElement)</script><title>Unit Test: book.005</title><meta name="viewport" content="width=device-width, initial-scale=1.0"/><link href="https://purl.org/dc/elements/1.1/" rel="schema.dc"/><meta content="2011-04-22T17:02:00-06:00" name="dc.modified"/><meta content="DocBook xslTNG" name="generator"/><link href="./css/docbook.css" rel="stylesheet" media="screen"/></head><body class="home"><nav class="top"></nav><main><article id="book" class="book division"><header><h1>Unit Test: book.005</h1></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#book_ded1">Dedication</a></li><li><a href="#book_p1">Preface</a></li><li><a href="#book_part1">Part <span class="label">I</span><span class="sep">. </span>First Part</a><ul class="toc"><li><a href="#book_part1_ch1"><span class="label">1</span><span class="sep">. </span>First Chapter</a></li><li><a href="#book_part1_ch2"><span class="label">2</span><span class="sep">. </span>Second Chapter</a></li></ul></li><li><a href="#book_part2">Part <span class="label">II</span><span class="sep">. </span>Second Part</a><ul class="toc"><li><a href="#book_part2_ch1"><span class="label">1</span><span class="sep">. </span>Third Chapter</a></li><li><a href="#book_part2_ch2"><span class="label">2</span><span class="sep">. </span>Fourth Chapter</a></li></ul></li><li><a href="#book_ap1"><span class="label">A</span><span class="sep">. </span>Appendix</a></li></ul></div></div><div id="book_ded1" class="component dedication"><header><h2>Dedication</h2></header><p>Some Dedication</p></div><div id="book_p1" class="component preface"><header><h2>Preface</h2></header><p>Some Preface</p></div><article id="book_part1" class="division part"><header><h1>Part <span class="label">I</span><span class="sep">. </span>First Part</h1></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#book_part1_ch1"><span class="label">1</span><span class="sep">. </span>First Chapter</a></li><li><a href="#book_part1_ch2"><span class="label">2</span><span class="sep">. </span>Second Chapter</a></li></ul></div></div><article id="book_part1_partintro1" class="component partintro"><p>Some Part Intro</p></article><div id="book_part1_ch1" class="chapter component"><header><h1>Chapter <span class="label">1</span><span class="sep">. </span>First Chapter</h1></header><p>Some Chapter</p></div><div id="book_part1_ch2" class="chapter component"><header><h1>Chapter <span class="label">2</span><span class="sep">. </span>Second Chapter</h1></header><p>Some Chapter</p></div></article><article id="book_part2" class="division part"><header><h1>Part <span class="label">II</span><span class="sep">. </span>Second Part</h1></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#book_part2_ch1"><span class="label">1</span><span class="sep">. </span>Third Chapter</a></li><li><a href="#book_part2_ch2"><span class="label">2</span><span class="sep">. </span>Fourth Chapter</a></li></ul></div></div><article id="book_part2_partintro1" class="component partintro"><p>Some Part Intro</p></article><div id="book_part2_ch1" class="chapter component"><header><h1>Chapter <span class="label">1</span><span class="sep">. </span>Third Chapter</h1></header><p>Some Chapter</p></div><div id="book_part2_ch2" class="chapter component"><header><h1>Chapter <span class="label">2</span><span class="sep">. </span>Fourth Chapter</h1></header><p>Some Chapter</p></div></article><div id="book_ap1" class="appendix component"><header><h2>Appendix <span class="label">A</span><span class="sep">. </span>Appendix</h2></header><p>Some Appendix</p></div></article></main><nav class="bottom"></nav></body></html>
+<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" class="no-js"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><script>(function(H){H.className=H.className.replace(/\bno-js\b/,'js')})(document.documentElement)</script><title>Unit Test: book.005</title><meta name="viewport" content="width=device-width, initial-scale=1.0"/><link href="https://purl.org/dc/elements/1.1/" rel="schema.dc"/><meta content="2011-04-22T17:02:00-06:00" name="dc.modified"/><meta content="DocBook xslTNG" name="generator"/><link href="./css/docbook.css" rel="stylesheet" media="screen"/></head><body class="home"><nav class="top"></nav><main><article id="book" class="book division"><header><h1>Unit Test: book.005</h1></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#book_ded1">Dedication</a></li><li><a href="#book_p1">Preface</a></li><li><a href="#book_part1">Part <span class="label">I</span><span class="sep">. </span>First Part</a><ul class="toc"><li><a href="#book_part1_ch1"><span class="label">1</span><span class="sep">. </span>First Chapter</a></li><li><a href="#book_part1_ch2"><span class="label">2</span><span class="sep">. </span>Second Chapter</a></li></ul></li><li><a href="#book_part2">Part <span class="label">II</span><span class="sep">. </span>Second Part</a><ul class="toc"><li><a href="#book_part2_ch1"><span class="label">3</span><span class="sep">. </span>Third Chapter</a></li><li><a href="#book_part2_ch2"><span class="label">4</span><span class="sep">. </span>Fourth Chapter</a></li></ul></li><li><a href="#book_ap1"><span class="label">A</span><span class="sep">. </span>Appendix</a></li></ul></div></div><div id="book_ded1" class="component dedication"><header><h2>Dedication</h2></header><p>Some Dedication</p></div><div id="book_p1" class="component preface"><header><h2>Preface</h2></header><p>Some Preface</p></div><article id="book_part1" class="division part"><header><h1>Part <span class="label">I</span><span class="sep">. </span>First Part</h1></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#book_part1_ch1"><span class="label">1</span><span class="sep">. </span>First Chapter</a></li><li><a href="#book_part1_ch2"><span class="label">2</span><span class="sep">. </span>Second Chapter</a></li></ul></div></div><article id="book_part1_partintro1" class="component partintro"><p>Some Part Intro</p></article><div id="book_part1_ch1" class="chapter component"><header><h1>Chapter <span class="label">1</span><span class="sep">. </span>First Chapter</h1></header><p>Some Chapter</p></div><div id="book_part1_ch2" class="chapter component"><header><h1>Chapter <span class="label">2</span><span class="sep">. </span>Second Chapter</h1></header><p>Some Chapter</p></div></article><article id="book_part2" class="division part"><header><h1>Part <span class="label">II</span><span class="sep">. </span>Second Part</h1></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#book_part2_ch1"><span class="label">3</span><span class="sep">. </span>Third Chapter</a></li><li><a href="#book_part2_ch2"><span class="label">4</span><span class="sep">. </span>Fourth Chapter</a></li></ul></div></div><article id="book_part2_partintro1" class="component partintro"><p>Some Part Intro</p></article><div id="book_part2_ch1" class="chapter component"><header><h1>Chapter <span class="label">3</span><span class="sep">. </span>Third Chapter</h1></header><p>Some Chapter</p></div><div id="book_part2_ch2" class="chapter component"><header><h1>Chapter <span class="label">4</span><span class="sep">. </span>Fourth Chapter</h1></header><p>Some Chapter</p></div></article><div id="book_ap1" class="appendix component"><header><h2>Appendix <span class="label">A</span><span class="sep">. </span>Appendix</h2></header><p>Some Appendix</p></div></article></main><nav class="bottom"></nav></body></html>