Merge branch 'main' into main

build.gradle

@@ -37,8 +37,10 @@ plugins {
   id "de.undercouch.download" version "4.0.4"
 }
 
-sourceCompatibility=1.8
-targetCompatibility=1.8
+java {
+  sourceCompatibility = JavaVersion.VERSION_1_8
+  targetCompatibility = JavaVersion.VERSION_1_8
+}
 
 sourceSets {
   main {
@@ -1429,12 +1431,12 @@ jar {
 }
 
 task javadocJar(type: Jar, dependsOn: javadoc) {
-  classifier = 'javadoc'
+  archiveClassifier = 'javadoc'
   from javadoc.destinationDir
 }
 
 task sourcesJar(type: Jar) {
-  classifier = 'sources'
+  archiveClassifier = 'sources'
   from sourceSets.main.allSource
 }
 

buildSrc/build.gradle

@@ -2,8 +2,10 @@ plugins {
   id "java"
 }
 
-sourceCompatibility=1.8
-targetCompatibility=1.8
+java {
+  sourceCompatibility = JavaVersion.VERSION_1_8
+  targetCompatibility = JavaVersion.VERSION_1_8
+}
 
 repositories {
   mavenLocal()

buildSrc/src/main/groovy/org/docbook/xsltng/gradle/TestCase.groovy

@@ -137,6 +137,7 @@ class TestCase {
       doFirst {
         println("Processing ${testname}.html with ${config.name}")
         println(config.parameters)
+        println(dbxsl)
       }
        */
 

buildSrc/src/main/groovy/org/docbook/xsltng/gradle/TestGenerator.groovy

@@ -118,6 +118,10 @@ class TestGenerator {
     testConfigurations.create('default')
       .withEnvironments(['default'])
 
+    testConfigurations.create('book-014')
+      .withEnvironments(['default'])
+      .withStylesheet("${uBuildDir}/../src/test/resources/book.014.xsl")
+
     testConfigurations.create('callouts')
       .withEnvironments(['verbatim', 'callouts'])
 
@@ -156,6 +160,7 @@ class TestGenerator {
      'presentation\\.': 'presentations',
      'glossary\\.00[1,2,3,4,5,6]': 'glossary-collection', // Not 7, 8, or 9!
      'glossary\\.01': 'glossary-collection',
+     'book\\.014': 'book-014',
     ].each { entry ->
       Pattern pat = ~"^.*${entry.key}.*\$"
       regexList.add(new Tuple(pat, testConfigurations.find(entry.value)))

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

properties.gradle

@@ -2,21 +2,21 @@
 ext {
   xslTNGtitle = 'DocBook xslTNG'
   xslTNGbaseName = 'docbook-xslTNG'
-  xslTNGversion = '2.2.0'
-  guideVersion = '2.2.0'
+  xslTNGversion = '2.2.1'
+  guideVersion = '2.2.1'
   guidePrerelease = false
 
-  docbookVersion = '5.2CR5'
-  publishersVersion = '5.2CR5'
+  docbookVersion = '5.2'
+  publishersVersion = '5.2'
 
-  saxonVersion = '12.4'
+  saxonVersion = '12.5'
   saxonGroup = 'net.sf.saxon'
   saxonEdition = 'Saxon-HE'
   //saxonGroup = 'com.saxonica'
   //saxonEdition = 'Saxon-EE'
 
   metadataExtractorVersion = '2.18.0'
   jingVersion = '20220510'
-  xmlresolverVersion = '5.2.3'
+  xmlresolverVersion = '6.0.9'
   sincludeVersion = '5.2.4'
 }

src/bin/docbook.py

@@ -15,6 +15,7 @@
 
 class JavaClassRunnerException(Exception):
     """Subclass of Exception for errors raised by the runner."""
+    pass
 
 
 class JavaClassRunner:
@@ -64,10 +65,12 @@ def __init__(self, args):
         self._cp = {}
         self._seen = {}
 
-        # This script assumes it's in /path/to/somewhere/docbook/bin/python
+        # This script assumes it's in /path/to/somewhere/docbook/bin
         # where "docbook" is the root of the distribution. If you move
         # this script into /usr/local/bin or something, it won't work.
-        self.root = os.path.abspath(__file__)
+        # Instead, create a symbolic link with:
+        # ln -s /path/to/somewhere/docbook/bin/docbook /usr/local/bin/docbook
+        self.root = os.path.realpath(__file__)
         self.root = self.root[0:self.root.rfind(os.sep)]  # strip /docbook
         self.root = self.root[0:self.root.rfind(os.sep)]  # strip /bin
 

src/guide/xml/ch03.xml

@@ -226,6 +226,176 @@ a customization layer.</para>
 </orderedlist>
 </section>
 
+<section xml:id="titlepages">
+<title>Customizing title pages</title>
+
+<para>All of the titled elements (books, chapters, sections, etc.) have “title pages”. That is,
+they have a
+<tag namespace="http://www.w3.org/1999/xhtml">header</tag> element that contains the
+elements from the <tag>info</tag> that should be presented in the title header.
+In practice, <tag>info</tag> is a wrapper for general metadata about the element and
+often contains many elements that shouldn’t be presented.</para>
+
+<para>There’s <emphasis>so</emphasis> much variation both in what goes in the
+<tag>info</tag> elements and in what users need to have in the title header, that
+there’s no practical way to control it simply with stylesheet parameters.</para>
+
+<para>Instead the stylesheets offer two customization mechanisms: first, each header is formed
+from a header template. You can change the titlepage template in your
+<link linkend="layer">customization layer</link>.</para>
+
+<para>For example, the default titlepage template for chapter headers is:</para>
+
+<programlisting language="xml"><![CDATA[<header>
+  <tmp:apply-templates select="db:title">
+    <h2><tmp:content/></h2>
+  </tmp:apply-templates>
+  <tmp:apply-templates select="db:subtitle">
+    <h3><tmp:content/></h3>
+  </tmp:apply-templates>
+</header>]]></programlisting>
+
+<para>The <code>tmp:apply-templates</code> elements aren’t as sophisticated as
+XSLT templates, but they let you select parts of the document. If nothing is
+selected, the content is ignored. When the title page template is evaluated, the context
+item is the <tag>info</tag> element.</para>
+
+<para>Inside the <code>tmp:apply-templates</code>, you can decide what HTML markup should
+appear. The
+<code>tmp:content</code> element will be replaced by the result of processing
+the element or elements you selected.</para>
+
+<para>As a consequence of that template, a chapter title page contains the
+chapter title in an <tag namespace="http://www.w3.org/1999/xhtml">h2</tag> and
+the subtitle in an <tag namespace="http://www.w3.org/1999/xhtml">h3</tag>. No
+other elements in the <tag>info</tag> are presented.</para>
+
+<para>Suppose you are writing a book where each chapter has a different author.
+You can add the authors to the chapter title page by updating the template in
+your customization layer. The stylesheets contain a
+<varname>v:templates</varname> variable for this purpose. Any templates that you
+put inside it will be used before the default templates.</para>
+
+<programlisting language="xml"><![CDATA[<xsl:variable name="v:templates" as="document-node()"
+              xmlns:v="http://docbook.org/ns/docbook/variables">
+  <xsl:document xmlns:tmp="http://docbook.org/ns/docbook/templates"
+                xmlns:db="http://docbook.org/ns/docbook"
+                xmlns="http://www.w3.org/1999/xhtml">
+    <db:chapter context="parent::db:book">
+      <header>
+        <tmp:apply-templates select="db:title">
+          <h2><tmp:content/></h2>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:subtitle">
+          <h3><tmp:content/></h3>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:author">
+          <h3 class="author">
+            <tmp:content/>
+          </h3>
+        </tmp:apply-templates>
+      </header>
+    </db:chapter>
+  </xsl:document>
+</xsl:variable>]]></programlisting>
+
+<para>With that customization, a chapter title page contains the
+chapter title in an <tag namespace="http://www.w3.org/1999/xhtml">h2</tag>
+and the subtitle and authors in 
+<tag namespace="http://www.w3.org/1999/xhtml">h3</tag> elements, in that order.
+If you change the order of the <code>tmp:apply-template</code> elements, the
+order of the elements in the header will change.</para>
+
+<para>Another common requirement is to put a graphic on the title page of a
+book. Here’s how you might do that. (This example appears in the test suite
+as test <filename>book.014.xml</filename>.) Add the <tag>cover</tag> to your
+<tag>info</tag> element:</para>
+
+<programlisting language="xml"><![CDATA[<book xmlns="http://docbook.org/ns/docbook" version="5.2">
+<info>
+  <title>Unit Test: book.014</title>
+  <cover>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="../media/yoyodyne.png"/>
+      </imageobject>
+    </mediaobject>
+  </cover>
+  <editor>
+    <personname>
+      <firstname>Norman</firstname>
+      <surname>Walsh</surname>
+    </personname>
+    <email>[email protected]</email>
+  </editor>
+</info>
+…
+</book>]]></programlisting>
+
+<para>Then decide how you want that graphic in the header with a new book template:</para>
+
+<programlisting language="xml"><![CDATA[<xsl:variable name="v:templates" as="document-node()"
+              xmlns:v="http://docbook.org/ns/docbook/variables">
+  <xsl:document xmlns:tmp="http://docbook.org/ns/docbook/templates"
+                xmlns:db="http://docbook.org/ns/docbook"
+                xmlns="http://www.w3.org/1999/xhtml">
+    <db:book>
+      <header>
+        <tmp:apply-templates select="db:cover/db:mediaobject">
+          <div class="cover">
+            <tmp:content/>
+          </div>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:title">
+          <h1><tmp:content/></h1>
+        </tmp:apply-templates>
+        <tmp:apply-templates select="db:editor">
+          <div class="editor">
+            <h3><tmp:content/></h3>
+          </div>
+        </tmp:apply-templates>
+      </header>
+    </db:book>
+  </xsl:document>
+</xsl:variable>]]></programlisting>
+
+<para>This template will output the cover image, then the title, then the editor.
+If you want to update multiple templates, put them all in the same 
+<varname>v:templates</varname> element as siblings.</para>
+
+<para>Once you’ve output the elements in the header, you can use CSS to
+customize their appearance further.</para>
+
+<para>You can get a long way just by updating the title page templates, but not
+always far enough. If you can’t achieve what you need by changing a template,
+you can take full control.</para>
+
+<para>Each element generates its title page with the <mode>m:generate-titlepage</mode>
+mode. If you add a template in that mode to your customization layer, it has
+complete freedom to generate a custom title page.</para>
+
+<para>Here, for example, is a book title page template:</para>
+
+<programlisting language="xml"><![CDATA[<xsl:template match="db:book" mode="m:generate-titlepage">
+  <header>
+    <h1>
+      <xsl:apply-templates select="db:info/db:title" mode="m:titlepage"/>
+    </h1>
+    <p>Hello, world</p>
+  </header>
+</xsl:template>]]></programlisting>
+
+<para>With this XSLT template in your customization layer, the book title page
+will consist of the title in an 
+<tag namespace="http://www.w3.org/1999/xhtml">h1</tag>
+and the phrase “Hello, world” in a paragraph.
+In this case, the context item for the XSLT template is the main element, not
+its <tag>info</tag> child. But it will <emphasis>always</emphasis> have an
+<tag>info</tag> child, even if your original document didn’t have a wrapper
+around the titlepage metadata.</para>
+
+</section>
+
 <section xml:id="media">
 <title>Managing media</title>
 
@@ -705,6 +875,34 @@ first figure in chapter 2 will be labeled “2.1” and the first figure
 in the first section in chapter 2 will be labeled “2.1.1”, etc.
 This most closely reproduces the numbering from the 1.x stylesheets.</para>
 
+<section xml:id="numeration-overrides">
+<title>Numeration overrides</title>
+
+<para>Although the numeration parameters give you complete control over
+numeration, they aren’t simple to use. A few common cases can be handled with
+simpler settings: <parameter>division-numbers</parameter>,
+<parameter>component-numbers</parameter>, and
+<parameter>section-numbers</parameter>. Each of these parameters is “true” by
+default and numeration of divisions, components, and sections is handled as
+described above. If these parameters are set to “false”, divisions, components,
+and sections, respectively, will not be numbered.</para>
+
+<para>Numbering can also be controlled on a per-element basis with the
+<link linkend="pi_db">db processing instruction</link>.
+<indexterm>
+<primary>db processing instruction</primary>
+</indexterm>
+If the <literal>numbered</literal>
+<indexterm>
+<primary>db processing instruction</primary>
+<secondary>numbered pseudo-attribute</secondary>
+</indexterm>
+pseudo-attribute is “true”, the division, component, or section in which that 
+processing instruction occurs, and all of its descendants, will be numbered.
+If it’s “false”, the element and its descendants will not be numbered.</para>
+<para>In this way, it would be possible to have a single chapter or article with
+numbered sections even in a book where sections are not normally numbered.</para>
+</section>
 </section>
 
 <section xml:id="using-glossaries">

src/guide/xml/changelog.xml

@@ -10,6 +10,47 @@ be of interest to users of the stylesheets. See the commits and pull requests on
 <link xlink:href="https://github.com/docbook/xslTNG/">the repository</link> for
 finer detail.</para>
 
+<section xml:id="r221">
+<info>
+  <title>Changes in version 2.2.1</title>
+  <productnumber>2.2.1</productnumber>
+  <date>2024-09-27</date>
+</info>
+<itemizedlist>
+<listitem>
+  <para>Add missing zh-cn localization for “Danger”;
+  fixed <link xlink:href="https://github.com/docbook/xslTNG/issues/510">#510</link>.
+  </para>
+</listitem>
+<listitem>
+  <para>Added <xref linkend="titlepages"/>, describing how to customize title pages;
+  fixed <link xlink:href="https://github.com/docbook/xslTNG/issues/507">#507</link>.</para>
+</listitem>
+<listitem>
+  <para>Added support for a <code>numbered</code> DocBook processing instruction pseudo-attribute
+  to control numbering of divisions, components, and sections on a per-element basis;
+  fixed <link xlink:href="https://github.com/docbook/xslTNG/issues/506">#506</link>.
+  See <xref linkend="numeration-overrides"/>.</para>
+</listitem>
+<listitem>
+  <para>Added <parameter>variablelist-panelset</parameter> to 
+  support a “panel set” presentation of variable lists.</para>
+</listitem>
+<listitem>
+  <para>Simplified and corrected the selection of bibliography entry abbreviations;
+  fixed <link xlink:href="https://github.com/docbook/xslTNG/issues/479">#479</link>.
+  Thanks, Frank!</para>
+</listitem>
+<listitem>
+  <para>Improved <filename>docbook.py</filename> script. Thanks, Rafal!</para>
+</listitem>
+<listitem>
+  <para>Added support for <tag>caption</tag> elements in CALS tables;
+  fixed <link xlink:href="https://github.com/docbook/xslTNG/issues/472">#472</link>.</para>
+</listitem>
+</itemizedlist>
+</section>
+
 <section xml:id="r220">
 <info>
   <title>Changes in version 2.2.0</title>

src/guide/xml/guide.xml

@@ -14,7 +14,7 @@
 <pubdate/>
 <legalnotice>
 <literallayout><citetitle>DocBook xslTNG</citetitle>
-Copyright © 2020–2023 Norman Walsh.
+Copyright © 2020–2024 Norman Walsh.
 All Rights Reserved.</literallayout>
 
 <para>Permission is granted to copy, distribute and/or modify this