docbook · ndw · Sep 27, 2024 · Sep 27, 2024
diff --git a/src/guide/xml/ch03.xml b/src/guide/xml/ch03.xml
@@ -843,6 +843,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>
+<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">

diff --git a/src/main/xslt/modules/titles.xsl b/src/main/xslt/modules/titles.xsl
@@ -83,7 +83,7 @@
 
     <xsl:choose>
       <xsl:when test="$test">
-        <xsl:sequence select="."/>
+        <xsl:sequence select="fp:title-properties-override($test, .)"/>
         <xsl:break/>
       </xsl:when>
       <xsl:otherwise>
@@ -93,11 +93,45 @@
   </xsl:iterate>
 </xsl:function>
 
+<xsl:function name="fp:title-properties-override" as="element()" cache="yes">
+  <xsl:param name="context" as="element()"/>
+  <xsl:param name="properties" as="element()"/>
+
+  <xsl:variable name="numbered-pi"
+                select="($context/ancestor-or-self::* ! f:pi(., 'numbered'))[last()]"/>
+
+  <!--
+  <xsl:message select="node-name($context), $numbered-pi"/>
+  -->
+
+  <xsl:element name="{node-name($properties)}" namespace="{namespace-uri($properties)}">
+    <xsl:copy select="$properties/@* except $properties/@group"/>
+    <xsl:attribute name="group">
+      <xsl:choose>
+        <xsl:when test="empty($numbered-pi)">
+          <xsl:sequence select="$properties/@group"/>
+        </xsl:when>
+        <xsl:when test="$numbered-pi[1] = 'true'">
+          <xsl:sequence select="'title-numbered'"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:sequence select="'title-unnumbered'"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:attribute>
+  </xsl:element>
+</xsl:function>
+
+
 <xsl:template match="*" mode="mp:compute-headline-label" as="item()*">
   <xsl:param name="purpose" as="xs:string" required="yes"/>
 
   <xsl:variable name="prop" select="fp:title-properties(.)"/>
 
+  <!--
+  <xsl:message select="node-name(.), $purpose, $prop/@group/string()"/>
+  -->
+
   <xsl:variable name="template"
                 select="if ($purpose = 'lot')
                         then fp:localization-template(., 'list-of-titles')

diff --git a/src/test/resources/expected/book.020.html b/src/test/resources/expected/book.020.html
@@ -0,0 +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.020</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 class="book division"><header><h1>Unit Test: book.020</h1><div class="author"><h3><span class="first-last personname"><span class="firstname">Norman</span> <span class="surname">Walsh</span></span></h3></div></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#R_ch1"><span class="label">1</span><span class="sep">. </span>First Chapter</a><ul class="toc"><li><a href="#R_ch1_s1"><span class="label">1</span><span class="sep">. </span>First section</a><ul class="toc"><li><a href="#R_ch1_s1_s1"><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</a></li></ul></li></ul></li><li><a href="#R_ch2">Second Chapter</a><ul class="toc"><li><a href="#R_ch2_s1">First section</a><ul class="toc"><li><a href="#R_ch2_s1_s1">Second section</a></li></ul></li></ul></li><li><a href="#R_ch3"><span class="label">3</span><span class="sep">. </span>Third Chapter</a><ul class="toc"><li><a href="#R_ch3_s1">First section</a><ul class="toc"><li><a href="#R_ch3_s1_s1">Second section</a></li></ul></li></ul></li><li><a href="#R_ch4">Fourth Chapter</a><ul class="toc"><li><a href="#R_ch4_s1"><span class="label">1</span><span class="sep">. </span>First section</a><ul class="toc"><li><a href="#R_ch4_s1_s1"><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</a></li></ul></li></ul></li></ul></div></div><section id="R_ch1" class="chapter component"><header><h2>Chapter <span class="label">1</span><span class="sep">. </span>First Chapter</h2></header><p>This chapter is numbered, so are its sections.</p><section id="R_ch1_s1" class="section"><header><h2><span class="label">1</span><span class="sep">. </span>First section</h2></header><section id="R_ch1_s1_s1" class="section"><header><h3><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</h3></header><p>…</p></section></section></section><section id="R_ch2" class="chapter component"><header><h2>Second Chapter</h2></header><p>This chapter is not numbered, neither are its sections.</p><section id="R_ch2_s1" class="section"><header><h2>First section</h2></header><section id="R_ch2_s1_s1" class="section"><header><h3>Second section</h3></header></section></section></section><section id="R_ch3" class="chapter component"><header><h2>Chapter <span class="label">3</span><span class="sep">. </span>Third Chapter</h2></header><p>This chapter is numbered, its sections are not.</p><section id="R_ch3_s1" class="section"><header><h2>First section</h2></header><section id="R_ch3_s1_s1" class="section"><header><h3>Second section</h3></header><p>…</p></section></section></section><section id="R_ch4" class="chapter component"><header><h2>Fourth Chapter</h2></header><p>This chapter is not numbered, but its sections are.</p><section id="R_ch4_s1" class="section"><header><h2><span class="label">1</span><span class="sep">. </span>First section</h2></header><section id="R_ch4_s1_s1" class="section"><header><h3><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</h3></header></section></section></section></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/expected/book.021.html b/src/test/resources/expected/book.021.html
@@ -0,0 +1,10 @@
+<!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.021</title><link href="./css/pygments.css" rel="stylesheet"/><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"/><script src="./js/copy-verbatim.js" defer="defer"></script></head><body class="home"><nav class="top"></nav><main><article class="book division"><header><h1>Unit Test: book.021</h1><div class="author"><h3><span class="first-last personname"><span class="firstname">Norman</span> <span class="surname">Walsh</span></span></h3></div></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#R_p1">Preface</a></li><li><a href="#R_article1">First Article</a><ul class="toc"><li><a href="#R_article1_s1"><span class="label">1</span><span class="sep">. </span>First section</a><ul class="toc"><li><a href="#R_article1_s1_s1"><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</a></li></ul></li></ul></li><li><a href="#R_article2">Second Article</a><ul class="toc"><li><a href="#R_article2_s1">First section</a><ul class="toc"><li><a href="#R_article2_s1_s1">Second section</a></li></ul></li></ul></li><li><a href="#R_article3">Third Article</a><ul class="toc"><li><a href="#R_article3_s1">First section</a><ul class="toc"><li><a href="#R_article3_s1_s1">Second section</a></li></ul></li></ul></li><li><a href="#R_article4">Fourth Article</a><ul class="toc"><li><a href="#R_article4_s1"><span class="label">1</span><span class="sep">. </span>First section</a><ul class="toc"><li><a href="#R_article4_s1_s1"><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</a></li></ul></li></ul></li></ul></div></div><section id="R_p1" class="component preface"><header><h2>Preface</h2></header><p>This test demonstrates something a little bit confusing. Although we can
+toggle article numeration, it has no apparent effect. That’s because there’s also
+a localization component to numeration and in the (“en”) localization, numbered
+articles don’t have a label. This is either a bug or a design choice, I guess.
+But you can fix it changing the <code>self::db:article</code> template in the
+“title-numbered” part of the localization to:
+
+<div class="pre-wrap highlight" db-startinglinenumber="1" db-numberoflines="1"><pre class="language-xml numbered programlisting verbatim verblines"><span class="line" db-line="1"><span class="ln">  <span class="nsep">|</span></span><span class="ld"><code><span class="nt">&lt;template</span><span class="w"> </span><span class="na">match=</span><span class="s">"self::db:article"</span><span class="nt">&gt;</span>%l%.%c<span class="nt">&lt;/template&gt;</span></code></span></span>
+</pre></div>
+</p></section><section id="R_article1" class="article component"><header><h1>First Article</h1></header><p>This article is numbered, so are its sections.</p><section id="R_article1_s1" class="section"><header><h2><span class="label">1</span><span class="sep">. </span>First section</h2></header><section id="R_article1_s1_s1" class="section"><header><h3><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</h3></header><p>…</p></section></section></section><section id="R_article2" class="article component"><header><h1>Second Article</h1></header><p>This article is not numbered, neither are its sections.</p><section id="R_article2_s1" class="section"><header><h2>First section</h2></header><section id="R_article2_s1_s1" class="section"><header><h3>Second section</h3></header></section></section></section><section id="R_article3" class="article component"><header><h1>Third Article</h1></header><p>This article is numbered, its sections are not.</p><section id="R_article3_s1" class="section"><header><h2>First section</h2></header><section id="R_article3_s1_s1" class="section"><header><h3>Second section</h3></header><p>…</p></section></section></section><section id="R_article4" class="article component"><header><h1>Fourth Article</h1></header><p>This article is not numbered, but its sections are.</p><section id="R_article4_s1" class="section"><header><h2><span class="label">1</span><span class="sep">. </span>First section</h2></header><section id="R_article4_s1_s1" class="section"><header><h3><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</h3></header></section></section></section></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/xml/book.020.xml b/src/test/resources/xml/book.020.xml
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="utf-8"?>
+<book xmlns="http://docbook.org/ns/docbook" version="5.2">
+<info>
+  <title>Unit Test: book.020</title>
+  <author>
+    <personname>
+      <firstname>Norman</firstname>
+      <surname>Walsh</surname>
+    </personname>
+    <email>[email protected]</email>
+  </author>
+</info>
+
+<chapter>
+  <title>First Chapter</title>
+  <para>This chapter is numbered, so are its sections.</para>
+  <section>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+      <para>…</para>
+    </section>
+  </section>
+</chapter>
+
+<chapter>
+  <?db numbered="false"?>
+  <title>Second Chapter</title>
+  <para>This chapter is not numbered, neither are its sections.</para>
+  <section>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+    </section>
+  </section>
+</chapter>
+
+<chapter>
+  <title>Third Chapter</title>
+  <para>This chapter is numbered, its sections are not.</para>
+  <section>
+    <?db numbered="false"?>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+      <para>…</para>
+    </section>
+  </section>
+</chapter>
+
+<chapter>
+  <?db numbered="false"?>
+  <title>Fourth Chapter</title>
+  <para>This chapter is not numbered, but its sections are.</para>
+  <section>
+    <?db numbered="true"?>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+    </section>
+  </section>
+</chapter>
+
+</book>
diff --git a/src/test/resources/xml/book.021.xml b/src/test/resources/xml/book.021.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="utf-8"?>
+<book xmlns="http://docbook.org/ns/docbook" version="5.2">
+<info>
+  <title>Unit Test: book.021</title>
+  <author>
+    <personname>
+      <firstname>Norman</firstname>
+      <surname>Walsh</surname>
+    </personname>
+    <email>[email protected]</email>
+  </author>
+</info>
+
+<preface>
+<title>Preface</title>
+<para>This test demonstrates something a little bit confusing. Although we can
+toggle article numeration, it has no apparent effect. That’s because there’s also
+a localization component to numeration and in the (“en”) localization, numbered
+articles don’t have a label. This is either a bug or a design choice, I guess.
+But you can fix it changing the <code>self::db:article</code> template in the
+“title-numbered” part of the localization to:
+
+<programlisting language="xml"
+><![CDATA[<template match="self::db:article">%l%.%c</template>]]></programlisting>
+</para>
+</preface>
+
+<article>
+  <title>First Article</title>
+  <para>This article is numbered, so are its sections.</para>
+  <section>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+      <para>…</para>
+    </section>
+  </section>
+</article>
+
+<article>
+  <?db numbered="false"?>
+  <title>Second Article</title>
+  <para>This article is not numbered, neither are its sections.</para>
+  <section>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+    </section>
+  </section>
+</article>
+
+<article>
+  <title>Third Article</title>
+  <para>This article is numbered, its sections are not.</para>
+  <section>
+    <?db numbered="false"?>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+      <para>…</para>
+    </section>
+  </section>
+</article>
+
+<article>
+  <?db numbered="false"?>
+  <title>Fourth Article</title>
+  <para>This article is not numbered, but its sections are.</para>
+  <section>
+    <?db numbered="true"?>
+    <title>First section</title>
+    <section>
+      <title>Second section</title>
+    </section>
+  </section>
+</article>
+
+</book>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +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.020</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 class="book division"><header><h1>Unit Test: book.020</h1><div class="author"><h3><span class="first-last personname"><span class="firstname">Norman</span> <span class="surname">Walsh</span></span></h3></div></header><div class="list-of-titles"><div class="lot toc"><div class="title">Table of Contents</div><ul class="toc"><li><a href="#R_ch1"><span class="label">1</span><span class="sep">. </span>First Chapter</a><ul class="toc"><li><a href="#R_ch1_s1"><span class="label">1</span><span class="sep">. </span>First section</a><ul class="toc"><li><a href="#R_ch1_s1_s1"><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</a></li></ul></li></ul></li><li><a href="#R_ch2">Second Chapter</a><ul class="toc"><li><a href="#R_ch2_s1">First section</a><ul class="toc"><li><a href="#R_ch2_s1_s1">Second section</a></li></ul></li></ul></li><li><a href="#R_ch3"><span class="label">3</span><span class="sep">. </span>Third Chapter</a><ul class="toc"><li><a href="#R_ch3_s1">First section</a><ul class="toc"><li><a href="#R_ch3_s1_s1">Second section</a></li></ul></li></ul></li><li><a href="#R_ch4">Fourth Chapter</a><ul class="toc"><li><a href="#R_ch4_s1"><span class="label">1</span><span class="sep">. </span>First section</a><ul class="toc"><li><a href="#R_ch4_s1_s1"><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</a></li></ul></li></ul></li></ul></div></div><section id="R_ch1" class="chapter component"><header><h2>Chapter <span class="label">1</span><span class="sep">. </span>First Chapter</h2></header><p>This chapter is numbered, so are its sections.</p><section id="R_ch1_s1" class="section"><header><h2><span class="label">1</span><span class="sep">. </span>First section</h2></header><section id="R_ch1_s1_s1" class="section"><header><h3><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</h3></header><p>…</p></section></section></section><section id="R_ch2" class="chapter component"><header><h2>Second Chapter</h2></header><p>This chapter is not numbered, neither are its sections.</p><section id="R_ch2_s1" class="section"><header><h2>First section</h2></header><section id="R_ch2_s1_s1" class="section"><header><h3>Second section</h3></header></section></section></section><section id="R_ch3" class="chapter component"><header><h2>Chapter <span class="label">3</span><span class="sep">. </span>Third Chapter</h2></header><p>This chapter is numbered, its sections are not.</p><section id="R_ch3_s1" class="section"><header><h2>First section</h2></header><section id="R_ch3_s1_s1" class="section"><header><h3>Second section</h3></header><p>…</p></section></section></section><section id="R_ch4" class="chapter component"><header><h2>Fourth Chapter</h2></header><p>This chapter is not numbered, but its sections are.</p><section id="R_ch4_s1" class="section"><header><h2><span class="label">1</span><span class="sep">. </span>First section</h2></header><section id="R_ch4_s1_s1" class="section"><header><h3><span class="label">1<span class="sep">.</span>1</span><span class="sep">. </span>Second section</h3></header></section></section></section></article></main><nav class="bottom"></nav></body></html>