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 482a5cea1324255c8248a8da4877af54abc42672..421d9dc37048917828a904bea3b601f02808fdbe 100644 (file)
--- 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 edcc6aa350ed66a72dfdef32851fb8cb48bf85f7..e2c979f7754eb711cff818b9ec5b48851ddc6f1f 100644 (file)
--- 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 a7267b1ef4883ef0bfcec96bbcc869216ab8434e..6f05851b2d5d612ce348ac08b92412afc2801136 100644 (file)
--- 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 8b4de119bda26187d049e16f9d1d2227eb4a24b8..5e516d109484234af4ebd08ce7c7074cb84482c2 100644 (file)
--- 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 a1f867f1453a4690cdab83783c2ec5e46e9d04ce..0c388debbdd5b264877d282c98768246e7773181 100644 (file)
--- 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 37bc78d9b60855882592c60e28ece0cab5a3c7d1..138008a31891a8dab6d04cfc483036e635d3f95b 100644 (file)
--- 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 6322f8419392da592f387110160d04954ad09a2b..7a69456dc15ff157b244444b93144949cc9f636c 100644 (file)
--- 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 d201fc2253083f9d1b5ec09e346aaf2e64c7d2cb..1ecb8f12d89fd077c1243a9f2c8ae88b9a3517e5 100644 (file)
--- 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 bfe83a4669c40bd0a1e66776e3b6a965814feaf5..a81d69371fee899135d44749a62ba094e55948b7 100644 (file)
--- 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 (file)
index 0000000..b62af9f
--- /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 (file)
index 0000000..74b28cd
--- /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>