Fix refentry-generate-{name,title}

ndw · ndw · commit fb2dc1011dbb · 2025-06-21T08:50:46.000+01:00
Fix #568 Close #569 This PR takes a slightly different approach than the one proposed in #569, mostly in order to avoid introduce a backwards incompatible change by removing a parameter.
diff --git a/buildSrc/src/main/groovy/org/docbook/xsltng/gradle/TestGenerator.groovy b/buildSrc/src/main/groovy/org/docbook/xsltng/gradle/TestGenerator.groovy
@@ -141,13 +141,31 @@ class TestGenerator {
       .withParameters([
           'glossary-collection': "${fProjectDir}/src/test/resources/glosscollection.xml"])
 
+    testEnvironments.create('refentry-name')
+      .withParameters([
+          'refentry-generate-name': true,
+          'refentry-generate-title': false])
+
+    testEnvironments.create('refentry-title')
+      .withParameters([
+          'refentry-generate-name': false,
+          'refentry-generate-title': true])
+
+    testEnvironments.create('refentry-neither')
+      .withParameters([
+          'refentry-generate-name': false,
+          'refentry-generate-title': false])
+
     testConfigurations.create('unwrapped').withEnvironments(['unwrap'])
     testConfigurations.create('transclude').withEnvironments(['transclude'])
     testConfigurations.create('local').withEnvironments(['local'])
     testConfigurations.create('colors').withEnvironments(['colors'])
     testConfigurations.create('ptoc').withEnvironments(['ptoc'])
     testConfigurations.create('a11y').withEnvironments(['a11y'])
     testConfigurations.create('glossary-collection').withEnvironments(['glossary-collection'])
+    testConfigurations.create('refentry-name').withEnvironments(['refentry-name'])
+    testConfigurations.create('refentry-title').withEnvironments(['refentry-title'])
+    testConfigurations.create('refentry-neither').withEnvironments(['refentry-neither'])
 
     def regexList = []
     ['fit\\.': 'fit',
@@ -161,6 +179,9 @@ class TestGenerator {
      'glossary\\.00[1,2,3,4,5,6]': 'glossary-collection', // Not 7, 8, or 9!
      'glossary\\.01': 'glossary-collection',
      'book\\.014': 'book-014',
+     'refentry-name\\.': 'refentry-name',
+     'refentry-title\\.': 'refentry-title',
+     'refentry-neither\\.': 'refentry-neither'
     ].each { entry ->
       Pattern pat = ~"^.*${entry.key}.*\$"
       regexList.add(new Tuple(pat, testConfigurations.find(entry.value)))
diff --git a/src/guide/xml/ref-params.xml b/src/guide/xml/ref-params.xml
@@ -3553,8 +3553,9 @@ the provided grammar.
 <refsection>
 <title>Description</title>
 <para>If <parameter>refentry-generate-name</parameter> is true, the
-title of the refentry page will be the word “Name”. Otherwise it will
-be the title of the subject of the reference page. Generally, exactly one
+title of the refentry page will be the word “Name”. Otherwise its value
+depends on the setting of <parameter>refentry-generate-title</parameter>.
+Generally, exactly one
 of <parameter>refentry-generate-name</parameter> or
 <parameter>refentry-generate-title</parameter> should
 <glossterm baseform="is true">be true</glossterm>.
@@ -3566,7 +3567,7 @@ of <parameter>refentry-generate-name</parameter> or
   <refmeta>
     <fieldsynopsis>
       <varname>refentry-generate-title</varname>
-      <initializer>true()</initializer>
+      <initializer>false()</initializer>
     </fieldsynopsis>
   </refmeta>
   <refnamediv>
diff --git a/src/main/xslt/modules/refentry.xsl b/src/main/xslt/modules/refentry.xsl
@@ -31,7 +31,7 @@
     <xsl:apply-templates select="." mode="m:attributes"/>
 
     <xsl:choose>
-      <xsl:when test="$refentry-generate-name">
+      <xsl:when test="f:is-true($refentry-generate-name)">
         <header>
           <h2>
             <xsl:apply-templates select="." mode="m:gentext">
@@ -42,7 +42,7 @@
         </header>
       </xsl:when>
 
-      <xsl:when test="$refentry-generate-title">
+      <xsl:when test="f:is-true($refentry-generate-title)">
         <header>
           <h2>
             <xsl:choose>
@@ -59,6 +59,10 @@
           </h2>
         </header>
       </xsl:when>
+
+      <xsl:otherwise>
+        <!-- You don't get a title at all -->
+      </xsl:otherwise>
     </xsl:choose>
 
     <p>
diff --git a/src/test/resources/expected/refentry-name.001.html b/src/test/resources/expected/refentry-name.001.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>Article wrapper</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="article component"><header><h1>Article wrapper</h1></header><section id="minimal" class="component refentry"><div id="minimal_refnamediv1" class="refnamediv"><header><h2>Name</h2></header><p><span class="refname">Minimal</span><span class="refpurpose"><span class="refpurpose-sep"> — </span><span class="refpurpose-text">Test of a minimal RefEntry</span><span class="refpurpose-punc">.</span></span></p></div><section id="minimal_rs1_1" class="refsect1"><header><h2>Description</h2></header><p>This is a minimal RefEntry.</p></section></section></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/expected/refentry-neither.001.html b/src/test/resources/expected/refentry-neither.001.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>Article wrapper</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="article component"><header><h1>Article wrapper</h1></header><section id="minimal" class="component refentry"><div id="minimal_refnamediv1" class="refnamediv"><p><span class="refname">Minimal</span><span class="refpurpose"><span class="refpurpose-sep"> — </span><span class="refpurpose-text">Test of a minimal RefEntry</span><span class="refpurpose-punc">.</span></span></p></div><section id="minimal_rs1_1" class="refsect1"><header><h2>Description</h2></header><p>This is a minimal RefEntry.</p></section></section></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/expected/refentry-title.001.html b/src/test/resources/expected/refentry-title.001.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>Article wrapper</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="article component"><header><h1>Article wrapper</h1></header><section id="minimal" class="component refentry"><div id="minimal_refnamediv1" class="refnamediv"><header><h2><span class="refentrytitle">Minimal Title</span></h2></header><p><span class="refname">Minimal</span><span class="refpurpose"><span class="refpurpose-sep"> — </span><span class="refpurpose-text">Test of a minimal RefEntry</span><span class="refpurpose-punc">.</span></span></p></div><section id="minimal_rs1_1" class="refsect1"><header><h2>Description</h2></header><p>This is a minimal RefEntry.</p></section></section></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/expected/refentry.013.html b/src/test/resources/expected/refentry.013.html
@@ -1,4 +1,4 @@
-<!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: refentry.011</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"/><script src="./js/copy-verbatim.js" defer="defer"></script></head><body class="home"><nav class="top"></nav><main><article class="article component"><header><h1>Unit Test: refentry.011</h1></header><p>This <code class="tag tag-element">refentry</code> has no title but does have
+<!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: refentry.013</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"/><script src="./js/copy-verbatim.js" defer="defer"></script></head><body class="home"><nav class="top"></nav><main><article class="article component"><header><h1>Unit Test: refentry.013</h1></header><p>This <code class="tag tag-element">refentry</code> has no title but does have
 <code class="tag tag-element">refdescriptor</code>.</p><section id="printf" class="component refentry"><div id="printf_refnamediv1" class="refnamediv"><header><h2>Name</h2></header><p><span class="refdescriptor">print*</span><span class="refpurpose"><span class="refpurpose-sep"> — </span><span class="refpurpose-text">print formatted output</span><span class="refpurpose-punc">.</span></span></p></div><section id="printf_refsynopsisdiv1" class="refsynopsisdiv"><header><h2>Synopsis</h2></header><div class="funcsynopsis"><div class="pre-wrap funcsynopsisinfo-wrap"><pre class="funcsynopsisinfo verbatim"><code>#include &lt;stdio.h&gt;</code></pre></div><div class="funcprototype"><div><span class="funcdef">int <span class="function">printf</span></span><span class="arglist">(<span><span class="parameter">format</span><span>, </span></span><span></span>);</span></div><div class="paramdef">const char *<span class="parameter">format</span>;</div><div class="paramdef">...;</div></div><div class="funcprototype"><table class="prototype"><tbody><tr><td><span class="funcdef">int <span class="function">fprintf</span></span>(</td><td class="paramdef"><span class="parameter">strm</span>,</td></tr><tr><td rowspan="2"></td><td class="paramdef"><span class="parameter">format</span>,</td></tr><tr><td class="paramdef">);</td></tr></tbody></table><table class="params"><tbody><tr class="paramdef"><td>FILE *</td><td><span class="parameter">strm</span></td></tr><tr class="paramdef"><td>const char *</td><td><span class="parameter">format</span></td></tr><tr class="paramdef"><td></td><td></td></tr></tbody></table></div><div class="funcprototype"><div><span class="funcdef">int <span class="function">sprintf</span></span><span class="arglist">(<span><span class="parameter">s</span><span>, </span></span><span><span class="parameter">format</span><span>, </span></span><span></span>);</span></div><div class="paramdef">char *<span class="parameter">s</span>;</div><div class="paramdef">const char *<span class="parameter">format</span>;</div><div class="paramdef">...;</div></div></div></section><section id="printf_rs1_1" class="refsect1"><header><h2>Description</h2></header><p><code class="function">printf</code> places output on the standard
   output stream stdout.
   </p><p>…</p></section></section></article></main><nav class="bottom"></nav></body></html>
diff --git a/src/test/resources/xml/refentry-name.001.xml b/src/test/resources/xml/refentry-name.001.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0">
+   <title>Article wrapper</title>
+   <refentry xml:id="minimal">
+     <refmeta>
+       <refentrytitle>Minimal Title</refentrytitle>
+     </refmeta>
+     <refnamediv>
+       <refname>Minimal</refname>
+       <refpurpose>Test of a minimal RefEntry</refpurpose>
+     </refnamediv>
+     <refsect1>
+       <title>Description</title>
+       <para>This is a minimal RefEntry.</para>
+     </refsect1>
+   </refentry>
+</article>
diff --git a/src/test/resources/xml/refentry-neither.001.xml b/src/test/resources/xml/refentry-neither.001.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0">
+   <title>Article wrapper</title>
+   <refentry xml:id="minimal">
+     <refmeta>
+       <refentrytitle>Minimal Title</refentrytitle>
+     </refmeta>
+     <refnamediv>
+       <refname>Minimal</refname>
+       <refpurpose>Test of a minimal RefEntry</refpurpose>
+     </refnamediv>
+     <refsect1>
+       <title>Description</title>
+       <para>This is a minimal RefEntry.</para>
+     </refsect1>
+   </refentry>
+</article>
diff --git a/src/test/resources/xml/refentry-title.001.xml b/src/test/resources/xml/refentry-title.001.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0">
+   <title>Article wrapper</title>
+   <refentry xml:id="minimal">
+     <refmeta>
+       <refentrytitle>Minimal Title</refentrytitle>
+     </refmeta>
+     <refnamediv>
+       <refname>Minimal</refname>
+       <refpurpose>Test of a minimal RefEntry</refpurpose>
+     </refnamediv>
+     <refsect1>
+       <title>Description</title>
+       <para>This is a minimal RefEntry.</para>
+     </refsect1>
+   </refentry>
+</article>
diff --git a/src/test/resources/xml/refentry.013.xml b/src/test/resources/xml/refentry.013.xml
@@ -1,7 +1,7 @@
 <article xmlns="http://docbook.org/ns/docbook" version="5.0">
 <info>
   <?db toc='yes'?>
-  <title>Unit Test: refentry.011</title>
+  <title>Unit Test: refentry.013</title>
 </info>
 
 <para>This <tag>refentry</tag> has no title but does have

Original file line number	Diff line number	Diff line change
`@@ -0,0 +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>Article wrapper</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="article component"><header><h1>Article wrapper</h1></header><section id="minimal" class="component refentry"><div id="minimal_refnamediv1" class="refnamediv"><header><h2>Name</h2></header><p><span class="refname">Minimal</span><span class="refpurpose"><span class="refpurpose-sep"> — </span><span class="refpurpose-text">Test of a minimal RefEntry</span><span class="refpurpose-punc">.</span></span></p></div><section id="minimal_rs1_1" class="refsect1"><header><h2>Description</h2></header><p>This is a minimal RefEntry.</p></section></section></article></main><nav class="bottom"></nav></body></html>