From 5721229b9f3e6aaa4432487bb66c53692fbb4b73 Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Tue, 5 Jul 2005 11:32:42 +0000
Subject: [PATCH] Added support for enabling users to control what appears and
 does not appear in the content of the .TH title-line header/footer. (Closes
 #1210492)

---
 xsl/manpages/other.xsl                  | 51 ++++++++++++++++++++++---
 xsl/manpages/param.ent                  |  7 +++-
 xsl/manpages/param.xweb                 | 17 ++++++++-
 xsl/params/man.th.extra1.suppress.xml   | 27 +++++++++++++
 xsl/params/man.th.extra2.max.length.xml | 37 ++++++++++++++++++
 xsl/params/man.th.extra2.suppress.xml   | 39 +++++++++++++++++++
 xsl/params/man.th.extra3.max.length.xml | 37 ++++++++++++++++++
 xsl/params/man.th.extra3.suppress.xml   | 29 ++++++++++++++
 xsl/params/man.th.title.max.length.xml  |  7 ++--
 9 files changed, 239 insertions(+), 12 deletions(-)
 create mode 100644 xsl/params/man.th.extra1.suppress.xml
 create mode 100644 xsl/params/man.th.extra2.max.length.xml
 create mode 100644 xsl/params/man.th.extra2.suppress.xml
 create mode 100644 xsl/params/man.th.extra3.max.length.xml
 create mode 100644 xsl/params/man.th.extra3.suppress.xml

diff --git a/xsl/manpages/other.xsl b/xsl/manpages/other.xsl
index 558f7df4c..20f090854 100644
--- a/xsl/manpages/other.xsl
+++ b/xsl/manpages/other.xsl
@@ -14,6 +14,12 @@
 
      ******************************************************************** -->
 
+<xsl:param name="man.th.extra1.suppress">0</xsl:param>
+<xsl:param name="man.th.extra2.suppress">0</xsl:param>
+<xsl:param name="man.th.extra3.suppress">0</xsl:param>
+<xsl:param name="man.th.extra2.max.length">30</xsl:param>
+<xsl:param name="man.th.extra3.max.length">40</xsl:param>
+
 <!-- * This file contains named templates that are related to things -->
 <!-- * other than just assembling the actual text of the main text flow -->
 <!-- * of each man page. This "other" stuff currently amounts to: -->
@@ -92,19 +98,52 @@
     <xsl:text>.TH "</xsl:text>
     <xsl:call-template name="string.upper">
       <xsl:with-param name="string">
-        <!-- * truncate title if it exceeds max. length (user-configurable) -->
-        <xsl:value-of
-            select="normalize-space(substring($title, 1, $man.th.title.max.length))"/>
+        <xsl:choose>
+          <xsl:when test="$man.th.title.max.length != ''">
+            <xsl:value-of
+                select="normalize-space(substring($title, 1, $man.th.title.max.length))"/>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:value-of select="normalize-space($title)"/>
+          </xsl:otherwise>
+        </xsl:choose>
       </xsl:with-param>
     </xsl:call-template>
     <xsl:text>" "</xsl:text>
     <xsl:value-of select="normalize-space($section)"/>
     <xsl:text>" "</xsl:text>
-    <xsl:value-of select="normalize-space($extra1)"/>
+    <xsl:if test="$man.th.extra1.suppress = 0">
+      <!-- * there is no max.length for the extra1 field; the reason -->
+      <!-- * is, it is almost always a date, and it is not possible -->
+      <!-- * to truncate dates without changing their meaning -->
+      <xsl:value-of select="normalize-space($extra1)"/>
+    </xsl:if>
     <xsl:text>" "</xsl:text>
-    <xsl:value-of select="normalize-space($extra2)"/>
+    <xsl:if test="$man.th.extra2.suppress = 0">
+      <xsl:choose>
+        <!-- * if max.length is non-empty, use value to truncate field -->
+        <xsl:when test="$man.th.extra2.max.length != ''">
+          <xsl:value-of
+              select="normalize-space(substring($extra2, 1, $man.th.extra2.max.length))"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="normalize-space($extra2)"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:if>
     <xsl:text>" "</xsl:text>
-    <xsl:value-of select="normalize-space($extra3)"/>
+    <xsl:if test="$man.th.extra3.suppress = 0">
+      <xsl:choose>
+        <!-- * if max.length is non-empty, use value to truncate field -->
+        <xsl:when test="$man.th.extra3.max.length != ''">
+          <xsl:value-of
+              select="normalize-space(substring($extra3, 1, $man.th.extra3.max.length))"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="normalize-space($extra3)"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:if>
     <xsl:text>"&#10;</xsl:text>
     <xsl:call-template name="mark.subheading"/>
   </xsl:template>
diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 577ec4458..27b259ff9 100644
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -10,7 +10,6 @@
 <!ENTITY man.charmap.subset.profile SYSTEM "../params/man.charmap.subset.profile.xml">
 <!ENTITY man.subheading.divider SYSTEM "../params/man.subheading.divider.xml">
 <!ENTITY man.subheading.divider.enabled SYSTEM "../params/man.subheading.divider.enabled.xml">
-<!ENTITY man.th.title.max.length SYSTEM "../params/man.th.title.max.length.xml">
 <!ENTITY refentry.date.profile.enabled SYSTEM "../params/refentry.date.profile.enabled.xml">
 <!ENTITY refentry.manual.profile.enabled SYSTEM "../params/refentry.manual.profile.enabled.xml">
 <!ENTITY refentry.source.name.profile.enabled SYSTEM "../params/refentry.source.name.profile.enabled.xml">
@@ -23,3 +22,9 @@
 <!ENTITY refentry.source.fallback.profile SYSTEM "../params/refentry.source.fallback.profile.xml">
 <!ENTITY refentry.source.name.profile SYSTEM "../params/refentry.source.name.profile.xml">
 <!ENTITY refentry.version.profile SYSTEM "../params/refentry.version.profile.xml">
+<!ENTITY man.th.title.max.length SYSTEM "../params/man.th.title.max.length.xml">
+<!ENTITY man.th.extra2.max.length SYSTEM "../params/man.th.extra2.max.length.xml">
+<!ENTITY man.th.extra3.max.length SYSTEM "../params/man.th.extra3.max.length.xml">
+<!ENTITY man.th.extra1.suppress SYSTEM "../params/man.th.extra1.suppress.xml">
+<!ENTITY man.th.extra2.suppress SYSTEM "../params/man.th.extra2.suppress.xml">
+<!ENTITY man.th.extra3.suppress SYSTEM "../params/man.th.extra3.suppress.xml">
diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index c90e75043..23990cd13 100644
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -38,7 +38,6 @@
 &man.string.subst.map;
 &man.subheading.divider.enabled;
 &man.subheading.divider;
-&man.th.title.max.length;
   </reference>
   <reference id="charmap">
   <title>Character map</title>
@@ -61,6 +60,15 @@
 &refentry.version.profile.enabled;
 &refentry.manual.fallback.profile;
 &refentry.source.fallback.profile;
+  </reference>
+  <reference id="charmap">
+  <title>Page header/footer</title>
+&man.th.extra1.suppress;
+&man.th.extra2.suppress;
+&man.th.extra3.suppress;
+&man.th.title.max.length;
+&man.th.extra2.max.length;
+&man.th.extra3.max.length;
   </reference>
   <appendix id="stylesheet">
     <title>The Stylesheet</title>
@@ -97,7 +105,6 @@
 <src:fragref linkend="man.charmap.subset.profile.frag"/>
 <src:fragref linkend="man.subheading.divider.frag"/>
 <src:fragref linkend="man.subheading.divider.enabled.frag"/>
-<src:fragref linkend="man.th.title.max.length.frag"/>
 <src:fragref linkend="refentry.date.profile.enabled.frag"/>
 <src:fragref linkend="refentry.manual.profile.enabled.frag"/>
 <src:fragref linkend="refentry.source.name.profile.enabled.frag"/>
@@ -110,6 +117,12 @@
 <src:fragref linkend="refentry.source.fallback.profile.frag"/>
 <src:fragref linkend="refentry.source.name.profile.frag"/>
 <src:fragref linkend="refentry.version.profile.frag"/>
+<src:fragref linkend="man.th.title.max.length.frag"/>
+<src:fragref linkend="man.th.extra2.max.length.frag"/>
+<src:fragref linkend="man.th.extra3.max.length.frag"/>
+<src:fragref linkend="man.th.extra1.suppress.frag"/>
+<src:fragref linkend="man.th.extra2.suppress.frag"/>
+<src:fragref linkend="man.th.extra3.suppress.frag"/>
 </xsl:stylesheet>
     </src:fragment>
 
diff --git a/xsl/params/man.th.extra1.suppress.xml b/xsl/params/man.th.extra1.suppress.xml
new file mode 100644
index 000000000..0dcca9fc1
--- /dev/null
+++ b/xsl/params/man.th.extra1.suppress.xml
@@ -0,0 +1,27 @@
+<refentry id="man.th.extra1.suppress">
+<refmeta>
+<refentrytitle>man.th.extra1.suppress</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.th.extra1.suppress</refname>
+<refpurpose>Suppress extra1 part of header/footer?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.th.extra1.suppress.frag'>
+<xsl:param name="man.th.extra1.suppress">0</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of <parameter>man.th.extra1.suppress</parameter> is
+non-zero, then the <literal>extra1</literal> part of the
+<literal>.TH</literal> title line header/footer is suppressed.</para>
+
+<para>The content of the <literal>extra1</literal> field is almost
+always displayed in the center footer of the page and is, universally,
+a date.</para>
+
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.th.extra2.max.length.xml b/xsl/params/man.th.extra2.max.length.xml
new file mode 100644
index 000000000..d8c079629
--- /dev/null
+++ b/xsl/params/man.th.extra2.max.length.xml
@@ -0,0 +1,37 @@
+<refentry id="man.th.extra2.max.length">
+<refmeta>
+<refentrytitle>man.th.extra2.max.length</refentrytitle>
+<refmiscinfo role="type">integer</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.th.extra2.max.length</refname>
+<refpurpose>Maximum length of extra2 in header/footer</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.th.extra2.max.length.frag'>
+<xsl:param name="man.th.extra2.max.length">40</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>Specifies the maximum permitted length of the
+<literal>extra2</literal> part of the man-page part of the
+<literal>.TH</literal> title line header/footer. If the
+<literal>extra2</literal> content exceeds the maxiumum specified, it
+is truncated down to the maximum permitted length.</para>
+
+<para>The content of the <literal>extra2</literal> field is usually
+displayed in the left footer of the page and is typically "source"
+data, often in the form
+<replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>;
+for example, "GTK+ 1.2" (from the <literal>gtk-options(7)</literal>
+man page).</para>
+
+<para>The default value for this parameter is reasonable (perhaps too
+liberal) but somewhat arbitrary. If you are processing pages with long
+"source" infromation, you may want to experiment with changing the
+value in order to achieve the correct aesthetic results.</para>
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.th.extra2.suppress.xml b/xsl/params/man.th.extra2.suppress.xml
new file mode 100644
index 000000000..8bc0a8228
--- /dev/null
+++ b/xsl/params/man.th.extra2.suppress.xml
@@ -0,0 +1,39 @@
+<refentry id="man.th.extra2.suppress">
+<refmeta>
+<refentrytitle>man.th.extra2.suppress</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.th.extra2.suppress</refname>
+<refpurpose>Suppress extra2 part of header/footer?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.th.extra2.suppress.frag'>
+<xsl:param name="man.th.extra2.suppress">0</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of <parameter>man.th.extra2.suppress</parameter> is
+non-zero, then the <literal>extra2</literal> part of the
+<literal>.TH</literal> title line header/footer is suppressed.</para>
+
+<para>The content of the <literal>extra2</literal> field is usually
+displayed in the left footer of the page and is typically "source"
+data, often in the form
+<replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>;
+for example, "GTK+ 1.2" (from the <literal>gtk-options(7)</literal>
+man page).</para>
+
+<note>
+  <para>You can use the
+  <parameter>refentry.source.name.suppress</parameter> and
+  <parameter>refentry.version.suppress</parameter> parameters to
+  independently suppress the <replaceable>Name</replaceable> and
+  <replaceable>Version</replaceable> parts of the
+  <literal>extra2</literal> field.</para>
+</note>
+
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.th.extra3.max.length.xml b/xsl/params/man.th.extra3.max.length.xml
new file mode 100644
index 000000000..5406da3fe
--- /dev/null
+++ b/xsl/params/man.th.extra3.max.length.xml
@@ -0,0 +1,37 @@
+<refentry id="man.th.extra3.max.length">
+<refmeta>
+<refentrytitle>man.th.extra3.max.length</refentrytitle>
+<refmiscinfo role="type">integer</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.th.extra3.max.length</refname>
+<refpurpose>Maximum length of extra3 in header/footer</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.th.extra3.max.length.frag'>
+<xsl:param name="man.th.extra3.max.length">30</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>Specifies the maximum permitted length of the
+<literal>extra3</literal> part of the man-page <literal>.TH</literal>
+title line header/footer. If the <literal>extra3</literal> content
+exceeds the maxiumum specified, it is truncated down to the maximum
+permitted length.</para>
+
+<para>The content of the <literal>extra3</literal> field is usually
+displayed in the middle header of the page and is typically a "manual
+name"; for example, "GTK+ User's Manual" (from the
+<literal>gtk-options(7)</literal> man page).</para>
+
+<para>The default value for this parameter is reasonable but somewhat
+arbitrary. If you are processing pages with long "manual names" -- or
+especially if you are processing pages that have both long "title"
+parts (command/function, etc. names) <emphasis>and</emphasis> long
+manual names -- you may want to experiment with changing the value in
+order to achieve the correct aesthetic results.</para>
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.th.extra3.suppress.xml b/xsl/params/man.th.extra3.suppress.xml
new file mode 100644
index 000000000..b7c51c1f1
--- /dev/null
+++ b/xsl/params/man.th.extra3.suppress.xml
@@ -0,0 +1,29 @@
+<refentry id="man.th.extra3.suppress">
+<refmeta>
+<refentrytitle>man.th.extra3.suppress</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.th.extra3.suppress</refname>
+<refpurpose>Suppress extra3 part of header/footer?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.th.extra3.suppress.frag'>
+<xsl:param name="man.th.extra3.suppress">0</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of <parameter>man.th.extra3.suppress</parameter> is
+non-zero, then the <literal>extra3</literal> part of the
+<literal>.TH</literal> title line header/footer is
+suppressed.</para>
+
+<para>The content of the <literal>extra3</literal> field is usually
+displayed in the middle header of the page and is typically a "manual
+name"; for example, "GTK+ User's Manual" (from the
+<literal>gtk-options(7)</literal> man page).</para>
+
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.th.title.max.length.xml b/xsl/params/man.th.title.max.length.xml
index 778c594e6..c07d20ab5 100644
--- a/xsl/params/man.th.title.max.length.xml
+++ b/xsl/params/man.th.title.max.length.xml
@@ -5,7 +5,7 @@
 </refmeta>
 <refnamediv>
 <refname>man.th.title.max.length</refname>
-<refpurpose>Maximum length of title in TH title line</refpurpose>
+<refpurpose>Maximum length of title in header/footer</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -17,8 +17,9 @@
 <refsect1><title>Description</title>
 
 <para>Specifies the maximum permitted length of the title part of the
-man-page TH title line. If the title exceeds the maxiumum specified,
-it is truncated down to the maximum permitted length.</para>
+man-page <literal>.TH</literal> title line header/footer. If the title
+exceeds the maxiumum specified, it is truncated down to the maximum
+permitted length.</para>
 
 <refsect2>
   <title>Details</title>
-- 
2.50.1