Merge pull request docbook#462 from ndw/minor-fixes

Fix bugs related to automatic glossaries
ndw · Jan 30, 2024 · b0ceb13 · b0ceb13
2 parents f600ceb + a5e2197
commit b0ceb13
Show file tree

Hide file tree

Showing 16 changed files with 226 additions and 32 deletions.
diff --git a/src/guide/xml/ch03.xml b/src/guide/xml/ch03.xml
@@ -738,12 +738,9 @@ check whether a corresponding <code>glossentry</code> exists for a
 <code>glossterm</code> or <code>firstterm</code> while you are still
 writing. Corresponding Schematron schemas are not yet part of the
 xslTNG framework.</para>
-
-  <simplesect>
-    <title>Caveats</title>
-    <para>The use of <code>glossdiv</code> is not supported for automatic glossaries, all
-    of the entries will appear in a flat list.</para>
-  </simplesect>
+
+<para>Generating glossary divisions automatically is controlled by the
+<parameter>glossary-automatic-divisions</parameter> parameter.</para>
 </section>
 
 <section xml:id="different">

diff --git a/src/guide/xml/ref-params.xml b/src/guide/xml/ref-params.xml
@@ -2022,22 +2022,57 @@ the first term is used.</para>
   <refmeta>
     <fieldsynopsis>
       <varname>glossary-sort-entries</varname>
-      <initializer>true()</initializer>
+      <initializer>'true'</initializer>
     </fieldsynopsis>
   </refmeta>
   <refnamediv>
     <refpurpose>Sort glossaries?</refpurpose>
   </refnamediv>
 <refsection>
 <title>Description</title>
-<para>If <parameter>glossary-sort-entries</parameter> is true, the entries in a
+<para>If <parameter>glossary-sort-entries</parameter> <glossterm>is true</glossterm>, the entries in a
 <tag>glossary</tag> or <tag>glosslist</tag> will be sorted before transformation.
 This saves the author from the burden of maintaining the list in a strictly
 alphabetic order.
 </para>
 </refsection>
 </refentry>
 
+<refentry>
+  <refmeta>
+    <fieldsynopsis>
+      <varname>glossary-automatic-divisions</varname>
+      <initializer>'false'</initializer>
+    </fieldsynopsis>
+  </refmeta>
+  <refnamediv>
+    <refpurpose>Divide glossaries into sections?</refpurpose>
+  </refnamediv>
+<refsection>
+<title>Description</title>
+<para>If <parameter>glossary-automatic-divisions</parameter> <glossterm>is true</glossterm>,
+the entries in an automatically constructed glossary will be grouped. The actual grouping
+is performed by the <template>t:glossary-divisions</template> template. This parameter is
+false by default for backwards compatibility.
+</para>
+
+<para>Automatic divisions can be specified on a per-glossary basis with a
+<literal>db</literal> processing instruction
+<indexterm>
+<primary>db processing instruction</primary>
+</indexterm> using the <literal>glossary-divisions</literal><indexterm>
+<primary>db processing instruction</primary>
+<secondary>glossary-divisions pseudo-attribute</secondary>
+</indexterm>
+pseudo-attribute with a value of <code>true</code> or <code>false</code>.</para>
+
+<para>This parameter only applies if 
+<parameter>glossary-sort-entries</parameter> <glossterm>is true</glossterm> and the glossary
+is not already grouped with <tag>glossdiv</tag> elements by hand.
+</para>
+</refsection>
+</refentry>
+
 <refentry>
   <refmeta>
     <fieldsynopsis>

diff --git a/src/guide/xml/ref-templates.xml b/src/guide/xml/ref-templates.xml
@@ -665,4 +665,25 @@ element with an <att>xlink:href</att> attribute) and extended links.
 </refsection>
 </refentry>
 
+<refentry xml:id="t_glossary-divisions">
+<?db filename="t_glossary-divisions"?>
+<refmeta>
+<refentrytitle>t:glossary-divisions</refentrytitle>
+<refmiscinfo>{http://docbook.org/ns/docbook/templates}glossary-divisions</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>t:glossary-divisions</refname>
+<refpurpose>Groups entries in a glossary</refpurpose>
+<refclass>template</refclass>
+</refnamediv>
+<refsection>
+<title>Description</title>
+<para>If <parameter>glossary-automatic-divisions</parameter> <glossterm>is true</glossterm>,
+this template is used to construct the divisions. By default, it makes groups based on the
+(upper-case) first letter of the terms. It does not add a grouping wrapper if there’s only
+one group.
+</para>
+</refsection>
+</refentry>
+
 </reference>
diff --git a/src/guide/xsl/common.xsl b/src/guide/xsl/common.xsl
@@ -24,9 +24,12 @@
 <!-- Load the whole stylesheet; well, down to one level of nesting -->
 <xsl:variable name="main.xsl"
               select="resolve-uri('../../../build/xslt/docbook.xsl', static-base-uri())"/>
+<xsl:variable name="standalone.xsl"
+              select="resolve-uri('../../../build/xslt/standalone-functions.xsl', static-base-uri())"/>
 <xsl:variable name="param_xsl">
   <main xmlns="">
     <xsl:apply-templates select="doc($main.xsl)/*" mode="mg:collect-imports"/>
+    <xsl:apply-templates select="doc($standalone.xsl)/*" mode="mg:collect-imports"/>
   </main>
 </xsl:variable>
 

diff --git a/src/main/scss/media-all.scss b/src/main/scss/media-all.scss
@@ -1506,11 +1506,14 @@ li[db-mark='box'] {
 
 /* ============================================================ */
 
-
 .glossdiv {
     margin-top: 1em;
 }
 
+.glossdiv dl dt {
+    padding-left: 1em;
+}
+
 /* ============================================================ */
 
 .sidebar {

diff --git a/src/main/scss/media-screen.scss b/src/main/scss/media-screen.scss
@@ -211,7 +211,7 @@ nav.top {
     width: 100%;
     background-color: var(--nav-background-color);
     opacity: 1;
-    z-index: 2; /* make sure floating elements go under it! */
+    z-index: 100; /* make sure floating elements go under it! */
 }
 
 body.home nav.top {

diff --git a/src/main/xslt/modules/glossary.xsl b/src/main/xslt/modules/glossary.xsl
@@ -19,27 +19,76 @@
   <xsl:variable name="gi" select="if (parent::*)
                                   then 'div'
                                   else 'article'"/>
+
+  <xsl:variable name="make-divisions"
+                select="if (empty(f:pi(., 'glossary-divisions', ())))
+                        then f:is-true($glossary-automatic-divisions)
+                        else f:is-true(f:pi(., 'glossary-divisions', 'false'))"/>
+
   <xsl:element name="{$gi}" namespace="http://www.w3.org/1999/xhtml">
     <xsl:apply-templates select="." mode="m:attributes"/>
     <xsl:apply-templates select="." mode="m:generate-titlepage"/>
     <xsl:apply-templates select="* except (db:glossentry|db:bibliography)"/>
-    <dl class="{local-name(.)}">
-      <xsl:choose>
-        <xsl:when test="$glossary-sort-entries">
+    <xsl:choose>
+      <xsl:when test="self::db:glossary and db:glossentry
+                      and f:is-true($glossary-sort-entries) and $make-divisions">
+        <xsl:call-template name="t:glossary-divisions">
+          <xsl:with-param name="terms" as="element(db:glossentry)+">
+            <xsl:for-each select="db:glossentry">
+              <xsl:sort select="(@sortas, normalize-space(db:glossterm[1]))[1]"
+                        collation="{$sort-collation}"/>
+              <xsl:sequence select="."/>
+            </xsl:for-each>
+          </xsl:with-param>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:when test="db:glossentry and f:is-true($glossary-sort-entries)">
+        <dl class="{local-name(.)}">
           <xsl:apply-templates select="db:glossentry">
             <xsl:sort select="(@sortas, normalize-space(db:glossterm[1]))[1]"
                       collation="{$sort-collation}"/>
           </xsl:apply-templates>
-        </xsl:when>
-        <xsl:otherwise>
-          <xsl:apply-templates select="db:glossentry"/>
-        </xsl:otherwise>
-      </xsl:choose>
-    </dl>
+        </dl>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:apply-templates select="db:glossentry"/>
+      </xsl:otherwise>
+    </xsl:choose>
     <xsl:apply-templates select="db:bibliography"/>
   </xsl:element>
 </xsl:template>
 
+<xsl:template name="t:glossary-divisions">
+  <xsl:param name="terms" as="element(db:glossentry)+"/>
+
+  <xsl:variable name="gid" select="f:id(.)"/>
+
+  <xsl:for-each-group
+      select="$terms"
+      group-by="upper-case(substring((db:glossterm[1]/@baseform, string(db:glossterm[1]))[1], 1, 1))">
+    <xsl:choose>
+      <!-- Don't bother with the group in the unlikely event that there's only one. -->
+      <xsl:when test="last() gt 1">
+        <div id="{$gid}_{current-grouping-key()}" class="glossdiv">
+          <header>
+            <div class="title">
+              <xsl:sequence select="current-grouping-key()"/>
+            </div>
+          </header>
+          <dl>
+            <xsl:apply-templates select="current-group()"/>
+          </dl>
+        </div>
+      </xsl:when>
+      <xsl:otherwise>
+        <dl>
+          <xsl:apply-templates select="current-group()"/>
+        </dl>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:for-each-group>
+</xsl:template>
+
 <xsl:template match="db:glossentry">
   <dt>
     <xsl:apply-templates select="." mode="m:attributes"/>

diff --git a/src/main/xslt/modules/variable.xsl b/src/main/xslt/modules/variable.xsl
@@ -26,10 +26,6 @@
 <xsl:variable name="v:as-json" select="map {'method':'json','indent':true()}"/>
 <xsl:variable name="v:as-xml" select="map {'method':'xml','indent':true()}"/>
 
-<xsl:variable name="v:pi-db-attributes-are-uris" as="xs:string*"
-              select="('glossary-collection', 'bibliography-collection',
-                       'annotation-collection')"/>
-
 <xsl:variable name="v:custom-localizations" as="document-node()?"
               select="()"/>
 

diff --git a/src/main/xslt/standalone-functions.xsl b/src/main/xslt/standalone-functions.xsl
@@ -15,6 +15,10 @@
 |    Functions designed for use independent from the xsTNG Stylesheets 
 |    e. g. in Schematron rules  
 |=================================================================================== -->
+
+<xsl:variable name="v:pi-db-attributes-are-uris" as="xs:string*"
+              select="('glossary-collection', 'bibliography-collection',
+                       'annotation-collection')"/>
 
 <!-- ====================================================================================
 |    Functions for processing instructions and their pseudo attributes

diff --git a/src/main/xslt/transforms/50-normalize.xsl b/src/main/xslt/transforms/50-normalize.xsl
@@ -159,14 +159,14 @@
 </xsl:template>
 
 <xsl:template match="db:glossary">
-  <xsl:variable name="glossary">
+  <xsl:variable name="glossary" as="element(db:glossary)">
     <xsl:call-template name="tp:normalize-generated-title">
       <xsl:with-param name="title-key" select="local-name(.)"/>
     </xsl:call-template>
   </xsl:variable>
 
   <xsl:choose>
-    <xsl:when test="$glossary/db:glossary[@role = 'auto']">
+    <xsl:when test="$glossary[@role = 'auto']">
       <xsl:variable name="terms" as="element()*">
         <xsl:for-each-group select="//db:glossterm[not(ancestor::db:glossary)] union //db:firstterm"
                             group-by="(@baseform, normalize-space())[1]">
@@ -175,7 +175,7 @@
       </xsl:variable>
       <xsl:if test="exists($terms)">
         <glossary xmlns="http://docbook.org/ns/docbook">
-          <xsl:sequence select="$glossary/*/@*, $glossary/*/db:info"/>
+          <xsl:sequence select="$glossary/@*, $glossary/node() except $glossary/db:glossentry"/>
           <xsl:call-template name="t:glossary-content">
             <xsl:with-param name="terms" select="$terms"/>
           </xsl:call-template>

diff --git a/src/test/resources/expected/glossary.001.html b/src/test/resources/expected/glossary.001.html
@@ -42,4 +42,4 @@
           flowering vine in the family Piperaceae, cultivated for its fruit, which is usually
           dried and used as a spice and seasoning. Long pepper has a taste similar to, but sweeter
           and less pungent than, that of its close relative Piper nigrum – from which black, green
-          and white pepper are obtained. </p></dd></dl></div><dl class="glossary"></dl></div></article></main><nav class="bottom"></nav></body></html>
+          and white pepper are obtained. </p></dd></dl></div></div></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/expected/glossary.008.html b/src/test/resources/expected/glossary.008.html
@@ -14,21 +14,21 @@
             <em>Quince</em> or <em>Bloodroot</em> in the results document
         glossary, although there is an entry in the internal glossary of the input document, because
         there is no <em>glossterm</em> or <em>firstterm</em> that references
-        it.</p><div id="R_g1" class="auto component glossary"><header><h2>Glossary</h2></header><dl class="glossary"><dt id="R_g1_ge1" class="glossentry"><span class="glossterm">Apple</span></dt><dd class="glossdef"><p>In early autumn the apple orchards come alive with people and sounds. The
+        it.</p><div id="R_g1" class="auto component glossary"><header><h2>Glossary</h2></header><div id="R_g1_A" class="glossdiv"><header><div class="title">A</div></header><dl><dt id="R_g1_ge1" class="glossentry"><span class="glossterm">Apple</span></dt><dd class="glossdef"><p>In early autumn the apple orchards come alive with people and sounds. The
                     farmers are picking, peeling, and processing apples into everything from apple
                     pies to apple sauce. Families swarm the apple trees with their baskets looking
                     for the best Honeycrisp and Macintosh. The sound of children playing is blended
                     with the occasional barking dog, or the low rumble of the old Ferguson Orchard
-                    tractor pulling a wagon up and down the rows. </p></dd><dt id="R_g1_ge3" class="glossentry"><span class="glossterm">Cucumber</span></dt><dd class="glossdef"><p>The cucumber (Cucumis sativus) is a widely-cultivated creeping vine plant in the family
+                    tractor pulling a wagon up and down the rows. </p></dd></dl></div><div id="R_g1_C" class="glossdiv"><header><div class="title">C</div></header><dl><dt id="R_g1_ge3" class="glossentry"><span class="glossterm">Cucumber</span></dt><dd class="glossdef"><p>The cucumber (Cucumis sativus) is a widely-cultivated creeping vine plant in the family
         Cucurbitaceae that bears cylindrical to spherical fruits, which are used as culinary
         vegetables. Considered an annual plant, there are three main types of cucumber—slicing,
         pickling, and seedless—within which several cultivars have been created. The cucumber
         originates in Asia extending from India, Nepal, Bangladesh, China (Yunnan, Guizhou,
         Guangxi), and Northern Thailand, but now grows on most continents, and many different types
         of cucumber are grown commercially and traded on the global market. In North America, the
         term wild cucumber refers to plants in the genera Echinocystis and Marah, though the two are
-        not closely related.</p></dd><dt id="pear" class="glossentry"><span class="glossterm">Pear</span></dt><dd class="glossdef"><p>The pear tree and shrub are a species of genus
+        not closely related.</p></dd></dl></div><div id="R_g1_P" class="glossdiv"><header><div class="title">P</div></header><dl><dt id="pear" class="glossentry"><span class="glossterm">Pear</span></dt><dd class="glossdef"><p>The pear tree and shrub are a species of genus
     Pyrus, in the family Rosaceae, bearing the pomaceous
     fruit of the same name. Several species of pear are valued for
     their edible fruit and juices while others are cultivated as
-    trees.</p></dd></dl></div></article></main><nav class="bottom"></nav></body></html>
+    trees.</p></dd></dl></div></div></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/expected/glossary.010.html b/src/test/resources/expected/glossary.010.html
@@ -0,0 +1,18 @@
+<!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: glossary.010</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: glossary.010</h1><h2>Wikipedia fruits with pepper</h2><div class="editor"><h3><span class="editedby">Edited by </span><span class="first-last personname"><span class="firstname">Someone</span> <span class="surname">Random</span></span></h3></div><p class="releaseinfo"><span class="releaseinfo">Just some test data</span></p></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>Fruits and Peppers</a></li><li><a href="#glossary">Glossary</a></li></ul></div></div><section id="R_ch1" class="chapter component"><header><h2>Chapter <span class="label">1</span><span class="sep">. </span>Fruits and Peppers</h2></header><div class="admonition note"><div><div class="icon">ⓘ</div><div class="body"><header><div class="title">Note</div></header><div><p>The test harness is configured to run this test with the
+<code class="parameter">glossary-collection</code> parameter pointing to
+<code class="filename">src/test/resources/glosscollection.xml</code>.</p></div></div></div></div><p><span class="glossterm"><a href="#peach">Peaches</a></span>,
+<span class="glossterm"><a href="#pear">Pears</a></span>, and
+<span class="glossterm"><a href="#glossary_ge3">Peppers</a></span>.</p></section><div id="glossary" class="auto component glossary"><header><h2>Glossary</h2></header><dl><dt id="peach" class="glossentry"><span class="glossterm">Peach</span></dt><dd class="glossdef"><p>The peach (Prunus persica) is a deciduous tree native to the
+    region of Northwest China between the Tarim Basin and the north
+    slopes of the Kunlun Mountains, where it was first domesticated
+    and cultivated. It bears an edible juicy fruit called a peach
+    or a nectarine.</p></dd><dt id="pear" class="glossentry"><span class="glossterm">Pear</span></dt><dd class="glossdef"><p>The pear tree and shrub are a species of genus
+    Pyrus, in the family Rosaceae, bearing the pomaceous
+    fruit of the same name. Several species of pear are valued for
+    their edible fruit and juices while others are cultivated as
+    trees.</p></dd><dt id="glossary_ge3" class="glossentry"><span class="glossterm">Pepper</span></dt><dd class="glossdef"><p>Black pepper (Piper nigrum) is a flowering vine in the family Piperaceae, cultivated for
+            its fruit (the peppercorn), which is usually dried and used as a spice and seasoning.
+            Peppercorns and the ground pepper derived from them may be described simply as pepper,
+            or more precisely as <em>black pepper</em> (cooked and dried unripe fruit),
+              <em>green pepper</em> (dried unripe fruit), or <em>white pepper
+            </em>(ripe fruit seeds).</p></dd></dl></div></article></main><nav class="bottom"></nav></body></html>