From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Wed, 28 Sep 2005 09:36:46 +0000 (+0000)
Subject: Added two new parameters for handling of multi-term varlistentry
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ca852ca635307d67467719dc03e02fde066db670;p=docbook-dsssl

Added two new parameters for handling of multi-term varlistentry
elements:

variablelist.term.break.after:
  When the variablelist.term.break.after is non-zero, it will
  generate a line break after each term multi-term varlistentry.

variablelist.term.separator:
  When a varlistentry contains multiple term elements, the string
  specified in the value of the variablelist.term.separator
  parameter is placed after each term except the last. The default
  is ", " (a comma followed by a space). To suppress rendering of
  the separator, set the value of variablelist.term.separator to
  the empty string ("").

These parameters are primarily intended to be useful if you have
multi-term varlistentries that have long terms.

Closes #1306676. Thanks to Sam Steingold for providing an example
"lots of long terms" doc that demonstrated the value of having
these options.

Also, added normalize-space() call to processing of each term.

This change affects all output formats (HTML, PDF, manpages). The
default behavior should pretty much remain the same as before, but
it is possible (as always) that the change may introduce some new
bugginess.
---

diff --git a/xsl/fo/lists.xsl b/xsl/fo/lists.xsl
index 482a5cea1..421d9dc37 100644
--- a/xsl/fo/lists.xsl
+++ b/xsl/fo/lists.xsl
@@ -565,11 +565,22 @@
 </xsl:template>
 
 <xsl:template match="varlistentry/term">
-  <fo:inline><xsl:apply-templates/>, </fo:inline>
-</xsl:template>
-
-<xsl:template match="varlistentry/term[position()=last()]" priority="2">
-  <fo:inline><xsl:apply-templates/></fo:inline>
+  <xsl:variable name="content">
+    <xsl:apply-templates/>
+  </xsl:variable>
+  <fo:inline><xsl:value-of select="normalize-space($content)"/></fo:inline>
+  <xsl:choose>
+    <xsl:when test="position() = last()"/> <!-- do nothing -->
+    <xsl:otherwise>
+      <!-- * if we have multiple terms in the same varlistentry, generate -->
+      <!-- * a separator (", " by default) and/or an additional line -->
+      <!-- * break after each one except the last -->
+      <fo:inline><xsl:value-of select="$variablelist.term.separator"/></fo:inline>
+      <xsl:if test="not($variablelist.term.break.after = '0')">
+        <fo:block/>
+      </xsl:if>
+    </xsl:otherwise>
+  </xsl:choose>
 </xsl:template>
 
 <xsl:template match="varlistentry/listitem">
diff --git a/xsl/fo/param.ent b/xsl/fo/param.ent
index edcc6aa35..e2c979f77 100644
--- a/xsl/fo/param.ent
+++ b/xsl/fo/param.ent
@@ -193,6 +193,9 @@
 <!ENTITY use.role.for.mediaobject SYSTEM "../params/use.role.for.mediaobject.xml">
 <!ENTITY use.svg SYSTEM "../params/use.svg.xml">
 <!ENTITY variablelist.as.blocks SYSTEM "../params/variablelist.as.blocks.xml">
+<!ENTITY variablelist.max.termlength SYSTEM "../params/variablelist.max.termlength.xml">
+<!ENTITY variablelist.term.separator SYSTEM "../params/variablelist.term.separator.xml">
+<!ENTITY variablelist.term.break.after SYSTEM "../params/variablelist.term.break.after.xml">
 <!ENTITY verbatim.properties SYSTEM "../params/verbatim.properties.xml">
 <!ENTITY xep.extensions SYSTEM "../params/xep.extensions.xml">
 <!ENTITY xep.index.item.properties SYSTEM "../params/xep.index.item.properties.xml">
@@ -258,7 +261,6 @@
 <!ENTITY qanda.title.level4.properties SYSTEM "../params/qanda.title.level4.properties.xml">
 <!ENTITY qanda.title.level5.properties SYSTEM "../params/qanda.title.level5.properties.xml">
 <!ENTITY qanda.title.level6.properties SYSTEM "../params/qanda.title.level6.properties.xml">
-<!ENTITY variablelist.max.termlength SYSTEM "../params/variablelist.max.termlength.xml">
 <!ENTITY qanda.defaultlabel SYSTEM "../params/qanda.defaultlabel.xml">
 <!ENTITY xref.label-title.separator SYSTEM "../params/xref.label-title.separator.xml">
 <!ENTITY xref.label-page.separator SYSTEM "../params/xref.label-page.separator.xml">
diff --git a/xsl/fo/param.xweb b/xsl/fo/param.xweb
index a7267b1ef..6f05851b2 100644
--- a/xsl/fo/param.xweb
+++ b/xsl/fo/param.xweb
@@ -387,15 +387,17 @@ zero by default, so this is simply the page-master region-left.
 </reference>
 
 <reference><title>Lists</title>
-&list.block.spacing;
-&list.item.spacing;
 &compact.list.item.spacing;
-&variablelist.max.termlength;
-&list.block.properties;
 &itemizedlist.properties;
 &itemizedlist.label.properties;
+&list.block.properties;
+&list.block.spacing;
+&list.item.spacing;
 &orderedlist.properties;
 &orderedlist.label.properties;
+&variablelist.max.termlength;
+&variablelist.term.separator;
+&variablelist.term.break.after;
 </reference>
 
 <reference><title>Cross References</title>
@@ -808,6 +810,8 @@ around all these parameters.</para>
 <src:fragref linkend="use.svg.frag"/>
 <src:fragref linkend="variablelist.as.blocks.frag"/>
 <src:fragref linkend="variablelist.max.termlength.frag"/>
+<src:fragref linkend="variablelist.term.separator.frag"/>
+<src:fragref linkend="variablelist.term.break.after.frag"/>
 <src:fragref linkend="verbatim.properties.frag"/>
 <src:fragref linkend="xep.extensions.frag"/>
 <src:fragref linkend="xep.index.item.properties.frag"/>
diff --git a/xsl/html/lists.xsl b/xsl/html/lists.xsl
index 8b4de119b..5e516d109 100644
--- a/xsl/html/lists.xsl
+++ b/xsl/html/lists.xsl
@@ -442,15 +442,22 @@
 <xsl:template match="varlistentry/term">
   <span class="term">
     <xsl:call-template name="anchor"/>
-    <xsl:apply-templates/>
-    <xsl:text>, </xsl:text>
-  </span>
-</xsl:template>
-
-<xsl:template match="varlistentry/term[position()=last()]" priority="2">
-  <span class="term">
-    <xsl:call-template name="anchor"/>
-    <xsl:apply-templates/>
+    <xsl:variable name="content">
+      <xsl:apply-templates/>
+    </xsl:variable>
+    <xsl:value-of select="normalize-space($content)"/>
+    <xsl:choose>
+      <xsl:when test="position() = last()"/> <!-- do nothing -->
+      <xsl:otherwise>
+        <!-- * if we have multiple terms in the same varlistentry, generate -->
+        <!-- * a separator (", " by default) and/or an additional line -->
+        <!-- * break after each one except the last -->
+        <xsl:value-of select="$variablelist.term.separator"/>
+        <xsl:if test="not($variablelist.term.break.after = '0')">
+          <br/>
+        </xsl:if>
+      </xsl:otherwise>
+    </xsl:choose>
   </span>
 </xsl:template>
 
diff --git a/xsl/html/param.ent b/xsl/html/param.ent
index a1f867f14..0c388debb 100644
--- a/xsl/html/param.ent
+++ b/xsl/html/param.ent
@@ -228,6 +228,8 @@
 <!ENTITY use.role.for.mediaobject SYSTEM "../params/use.role.for.mediaobject.xml">
 <!ENTITY use.svg SYSTEM "../params/use.svg.xml">
 <!ENTITY variablelist.as.table SYSTEM "../params/variablelist.as.table.xml">
+<!ENTITY variablelist.term.separator SYSTEM "../params/variablelist.term.separator.xml">
+<!ENTITY variablelist.term.break.after SYSTEM "../params/variablelist.term.break.after.xml">
 <!ENTITY para.propagates.style SYSTEM "../params/para.propagates.style.xml">
 <!ENTITY html.cellpadding SYSTEM "../params/html.cellpadding.xml">
 <!ENTITY html.cellspacing SYSTEM "../params/html.cellspacing.xml">
diff --git a/xsl/html/param.xweb b/xsl/html/param.xweb
index 37bc78d9b..138008a31 100644
--- a/xsl/html/param.xweb
+++ b/xsl/html/param.xweb
@@ -223,6 +223,13 @@ stylesheet like this:</para>
 &olink.resolver;
 </reference>
 
+<reference id="lists"><title>Lists</title>
+&segmentedlist.as.table;
+&variablelist.as.table;
+&variablelist.term.separator;
+&variablelist.term.break.after;
+</reference>
+
 <reference><title>Bibliography</title>
 &biblioentry.item.separator;
 &bibliography.collection;
@@ -246,8 +253,6 @@ stylesheet like this:</para>
 &shade.verbatim;
 &shade.verbatim.style;
 &punct.honorific;
-&segmentedlist.as.table;
-&variablelist.as.table;
 &tex.math.in.alt;
 &tex.math.file;
 &tex.math.delims;
@@ -696,6 +701,8 @@ around all these parameters.</para>
 <src:fragref linkend="use.role.for.mediaobject.frag"/>
 <src:fragref linkend="use.svg.frag"/>
 <src:fragref linkend="variablelist.as.table.frag"/>
+<src:fragref linkend="variablelist.term.separator.frag"/>
+<src:fragref linkend="variablelist.term.break.after.frag"/>
 <src:fragref linkend="xref.with.number.and.title.frag"/>
 <src:fragref linkend="xref.label-title.separator.frag"/>
 <src:fragref linkend="xref.label-page.separator.frag"/>
diff --git a/xsl/manpages/lists.xsl b/xsl/manpages/lists.xsl
index 6322f8419..7a69456dc 100644
--- a/xsl/manpages/lists.xsl
+++ b/xsl/manpages/lists.xsl
@@ -38,26 +38,54 @@
 </xsl:template>
 
 <xsl:template match="varlistentry|glossentry">
-  <xsl:text>.TP&#10;</xsl:text> 
-  <!-- * read in contents of all terms or glossterms so that we can run -->
-  <!-- * normalize-space on them as a set before rendering -->
-  <xsl:variable name="content">
-    <!-- * check each term/glossterm to see if it is the last one in the set; -->
-    <!-- * if not last, render a comma and space after it so that multiple -->
-    <!-- * terms/glossterms are displayed as a comma-separated list -->
-    <xsl:for-each select="term|glossterm">
+  <xsl:choose>
+    <!-- * if we have multiple terms in the same varlistentry, we can't -->
+    <!-- * use the .TP macro; we need to use .PP instead, then manually -->
+    <!-- * indent the listitem using .RS and .RE (see further down)-->
+    <xsl:when test="count(term) > 1">
+      <xsl:text>.PP&#10;</xsl:text> 
+    </xsl:when>
+    <xsl:otherwise> <!-- * we only have one term, so use .TP -->
+      <xsl:text>.TP&#10;</xsl:text> 
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:for-each select="term|glossterm">
+    <xsl:variable name="content">
       <xsl:apply-templates/>
-      <xsl:choose>
-        <xsl:when test="position() = last()"/> <!-- do nothing -->
-        <xsl:otherwise>
-          <xsl:text>, </xsl:text>
-        </xsl:otherwise>
-      </xsl:choose>
-    </xsl:for-each>
-  </xsl:variable>
-  <xsl:value-of select="normalize-space($content)"/>
+    </xsl:variable>
+    <xsl:value-of select="normalize-space($content)"/>
+    <xsl:choose>
+      <xsl:when test="position() = last()"/> <!-- do nothing -->
+      <xsl:otherwise>
+        <!-- * if we have multiple terms in the same varlistentry, generate -->
+        <!-- * a separator (", " by default) and/or an additional line -->
+        <!-- * break after each one except the last -->
+        <!-- * -->
+        <!-- * note that it is not valid to have multiple glossterms -->
+        <!-- * within a glossentry, so this logic never gets exercised -->
+        <!-- * for glossterms (every glossterm is always the last in -->
+        <!-- * its parent glossentry) -->
+        <xsl:value-of select="$variablelist.term.separator"/>
+        <xsl:if test="not($variablelist.term.break.after = '0')">
+          <xsl:text>&#10;</xsl:text>
+          <xsl:text>.br&#10;</xsl:text>
+        </xsl:if>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:for-each>
   <xsl:text>&#10;</xsl:text>
-  <xsl:apply-templates/>
+  <xsl:choose>
+    <!-- * if we have multiple terms in the same varlistentry, we need to-->
+    <!-- *  manually indent the listitem using .RS and .RE -->
+    <xsl:when test="count(term) > 1">
+      <xsl:text>.RS&#10;</xsl:text>
+      <xsl:apply-templates/>
+      <xsl:text>.RE&#10;</xsl:text>
+    </xsl:when>
+    <xsl:otherwise> <!-- * we only have one term, so just apply-templates -->
+      <xsl:apply-templates/>
+    </xsl:otherwise>
+  </xsl:choose>
 </xsl:template>
 
 <xsl:template match="varlistentry/term"/>
diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index d201fc225..1ecb8f12d 100644
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -8,6 +8,8 @@
 <!ENTITY man.links.are.underlined SYSTEM "../params/man.links.are.underlined.xml">
 <!ENTITY man.links.list.enabled SYSTEM "../params/man.links.list.enabled.xml">
 <!ENTITY man.links.list.heading SYSTEM "../params/man.links.list.heading.xml">
+<!ENTITY variablelist.term.separator SYSTEM "../params/variablelist.term.separator.xml">
+<!ENTITY variablelist.term.break.after SYSTEM "../params/variablelist.term.break.after.xml">
 <!ENTITY man.string.subst.map SYSTEM "../params/man.string.subst.map.xml">
 <!ENTITY man.charmap.enabled SYSTEM "../params/man.charmap.enabled.xml">
 <!ENTITY man.charmap.use.subset SYSTEM "../params/man.charmap.use.subset.xml">
diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index bfe83a466..a81d69371 100644
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -43,6 +43,11 @@
 &man.links.are.underlined;
 &man.links.list.enabled;
 &man.links.list.heading;
+  </reference>
+  <reference id="lists">
+  <title>Lists</title>
+&variablelist.term.separator;
+&variablelist.term.break.after;
   </reference>
   <reference id="charmap">
   <title>Character/string substitution</title>
@@ -119,6 +124,8 @@
 <src:fragref linkend="man.links.are.underlined.frag"/>
 <src:fragref linkend="man.links.list.enabled.frag"/>
 <src:fragref linkend="man.links.list.heading.frag"/>
+<src:fragref linkend="variablelist.term.separator.frag"/>
+<src:fragref linkend="variablelist.term.break.after.frag"/>
 <src:fragref linkend="man.charmap.enabled.frag"/>
 <src:fragref linkend="man.charmap.uri.frag"/>
 <src:fragref linkend="man.charmap.use.subset.frag"/>
diff --git a/xsl/params/variablelist.term.break.after.xml b/xsl/params/variablelist.term.break.after.xml
new file mode 100644
index 000000000..b62af9fab
--- /dev/null
+++ b/xsl/params/variablelist.term.break.after.xml
@@ -0,0 +1,34 @@
+<refentry id="variablelist.term.break.after">
+<refmeta>
+<refentrytitle>variablelist.term.break.after</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>variablelist.term.break.after</refname>
+<refpurpose>Generate line break after each <tag>term</tag> within a
+multi-term <tag>varlistentry</tag>?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='variablelist.term.break.after.frag'>
+<xsl:param name="variablelist.term.break.after">, </xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>Set a non-zero value for the
+<parameter>variablelist.term.break.after</parameter> parameter to
+generate a line break between <tag>term</tag>s in a
+multi-term <tag>varlistentry</tag>.</para>
+
+<note>
+<para>If you set a non-zero value for
+<parameter>variablelist.term.break.after</parameter>, you may also
+want to set the value of the
+<parameter>variablelist.term.separator</parameter> parameter to an
+empty string (to suppress rendering of the default comma and space
+after each <tag>term</tag>).</para>
+</note>
+
+</refsect1>
+</refentry>
diff --git a/xsl/params/variablelist.term.separator.xml b/xsl/params/variablelist.term.separator.xml
new file mode 100644
index 000000000..74b28cd57
--- /dev/null
+++ b/xsl/params/variablelist.term.separator.xml
@@ -0,0 +1,35 @@
+<refentry id="variablelist.term.separator">
+<refmeta>
+<refentrytitle>variablelist.term.separator</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>variablelist.term.separator</refname>
+<refpurpose>Text to separate <tag>term</tag>s within a multi-term
+<tag>varlistentry</tag></refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='variablelist.term.separator.frag'>
+<xsl:param name="variablelist.term.separator">, </xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>When a <tag>varlistentry</tag> contains multiple <tag>term</tag>
+elements, the string specified in the value of the
+<parameter>variablelist.term.separator</parameter> parameter is placed
+after each <tag>term</tag> except the last.</para>
+
+<note>
+  <para>To generate a line break between multiple <tag>term</tag>s in
+  a <tag>varlistentry</tag>, set a non-zero value for the
+  <parameter>variablelist.term.break.after</parameter> parameter. If
+  you do so, you may also want to set the value of the
+  <parameter>variablelist.term.separator</parameter> parameter to an
+  empty string (to suppress rendering of the default comma and space
+  after each <tag>term</tag>).</para>
+</note>
+
+</refsect1>
+</refentry>