Put quotes around section in .TH title line & normalize space in

title and section in .TH title line (as we do with all other
fields in it).

Also, added and refined comments, in part based on reading of
man(7) man page.

diff --git a/xsl/manpages/other.xsl b/xsl/manpages/other.xsl
index a6d19cd260d3bf4119031aeed67c18f7809ee75e..43a4cc0532e56df145aa35045f1ee0a4dfcd4b5e 100644 (file)
--- a/xsl/manpages/other.xsl
+++ b/xsl/manpages/other.xsl
@@ -45,27 +45,29 @@
     <!-- * versions. Below is a description of how Linux systems with -->
     <!-- * a modern groff seem to render .TH contents. -->
     <!-- * -->
-    <!-- *   title(section)      extra3      title(section)  <- page header -->
+    <!-- *   title(section)  extra3  title(section)  <- page header -->
+    <!-- *   extra2          extra1  title(section)  <- page footer-->
     <!-- * -->
-    <!-- *   extra2              extra1      title(section)  <- page footer-->
+    <!-- * Or, using the names with which the man(7) man page refers -->
+    <!-- * to the various fields: -->
     <!-- * -->
-    <!-- * Note the while extra1, extra2, and extra3 are all optional, almost all -->
-    <!-- * pages include an "extra1", which is almost always a date, -->
-    <!-- * and it is almost always rendered in the same place (the -->
-    <!-- * middle column of the footer), across all OSes and roff versions. -->
+    <!-- *   title(section)  manual  title(section)  <- page header -->
+    <!-- *   source          date    title(section)  <- page footer-->
     <!-- * -->
-    <!-- * Here are a couple of examples of real-world man pages that have -->
-    <!-- * useful page headers/footers: -->
+    <!-- * Note that while extra1, extra2, and extra3 are all (nominally) -->
+    <!-- * optional, in practice almost all pages include an "extra1" -->
+    <!-- * field, which is, universally, a date (in some form), and it is -->
+    <!-- * always rendered in the same place (the middle footer position) -->
     <!-- * -->
-    <!-- *   GIMP(1)           GIMP Manual Pages           GIMP(1) -->
-    <!-- *   Version 2.2.6     March 23 2004               GIMP(1) -->
+    <!-- * Here are a couple of examples of real-world man pages that -->
+    <!-- * have somewhat useful page headers/footers: -->
     <!-- * -->
-    <!-- *   QT2KDOC(1)        KDOC Documentation System   QT2KDOC(1) -->
-    <!-- *   2.0a54            2002-03-18                  QT2KDOC(1) -->
+    <!-- *   gtk-options(7)    GTK+ User's Manual   gtk-options(7) -->
+    <!-- *   GTK+ 1.2              2003-10-20       gtk-options(7) -->
+    <!-- * -->
+    <!-- *   svgalib(7)       Svgalib User Manual       svgalib(7) -->
+    <!-- *   Svgalib 1.4.1      16 December 1999        svgalib(7) -->
     <!-- * -->
-    <!-- * In those examples, extra2 has version data, while extra3 has "context" -->
-    <!-- * data about some larger system the documented item belongs to -->
-
     <xsl:param name="title"/>
     <xsl:param name="section"/>
     <xsl:param name="extra1"/>
@@ -73,16 +75,23 @@
     <xsl:param name="extra3"/>
 
     <xsl:call-template name="mark.subheading"/>
+    <!-- * Note that we generate quotes around _every_ field in the -->
+    <!-- * .TH title line, including the "title" and "section" -->
+    <!-- * fields. That is because we use the contents of those "as -->
+    <!-- * is", unchanged from the DocBook source; and DTD-based -->
+    <!-- * validation does not provide a way to constrain them to be -->
+    <!-- * "space free" -->
     <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="substring($title, 1, $man.th.title.max.length)"/>
+        <xsl:value-of
+            select="normalize-space(substring($title, 1, $man.th.title.max.length))"/>
       </xsl:with-param>
     </xsl:call-template>
-    <xsl:text>" </xsl:text>
-    <xsl:value-of select="$section"/>
-    <xsl:text> "</xsl:text>
+    <xsl:text>" "</xsl:text>
+    <xsl:value-of select="normalize-space($section)"/>
+    <xsl:text>" "</xsl:text>
     <xsl:value-of select="normalize-space($extra1)"/>
     <xsl:text>" "</xsl:text>
     <xsl:value-of select="normalize-space($extra2)"/>
@@ -134,7 +143,6 @@
   <!-- * -->
   <!-- * If a refentry has multiple refnames, we generate a "stub" page for -->
   <!-- * each additional refname found. -->
-
   <xsl:template name="write.stubs">
     <xsl:param name="metadata"/>
     <xsl:for-each select="refnamediv/refname">

diff --git a/xsl/manpages/refentry.xsl b/xsl/manpages/refentry.xsl
index 257cd05ea5f9fc3b24b51485d1615fe225f9c668..0348e61971737936e0dc75c31f328827d0b72c49 100644 (file)
--- a/xsl/manpages/refentry.xsl
+++ b/xsl/manpages/refentry.xsl
@@ -17,11 +17,13 @@
   <xsl:template match="refnamediv">
     <xsl:choose>
       <xsl:when test="preceding-sibling::refnamediv">
-        <!-- no title on secondary refnamedivs! -->
+        <!-- * no title on secondary refnamedivs! -->
       </xsl:when>
       <xsl:otherwise>
         <xsl:call-template name="mark.subheading"/>
         <xsl:text>.SH "</xsl:text>
+        <!-- * Use gentext to generate tiel for Refnamediv section, and -->
+        <!-- * make it uppercase -->
         <xsl:call-template name="string.upper">
           <xsl:with-param name="string">
             <xsl:call-template name="gentext">
@@ -34,12 +36,17 @@
     </xsl:choose>
     <xsl:text>&#10;</xsl:text>
     <xsl:call-template name="mark.subheading"/>
+    <!-- * if we have multiple Refname instances, separate the names -->
+    <!-- * with commas -->
     <xsl:for-each select="refname">
       <xsl:if test="position()>1">
         <xsl:text>, </xsl:text>
       </xsl:if>
       <xsl:value-of select="."/>
     </xsl:for-each>
+    <!-- * We don't precede the hyphen with a backslash here because -->
+    <!-- * the backslash gets added later, by the apply-string-subst-map -->
+    <!-- * template, before we generate final output -->
     <xsl:text> - </xsl:text>
     <xsl:value-of select="normalize-space (refpurpose)"/>
     <xsl:text>&#10;</xsl:text>
@@ -48,6 +55,8 @@
   <xsl:template match="refsynopsisdiv">
     <xsl:call-template name="mark.subheading"/>
     <xsl:text>.SH "</xsl:text>
+    <!-- * 'match="refsynopsisdiv" mode="title.markup' template does -->
+    <!-- * uppercasing for this -->
     <xsl:apply-templates select="." mode="title.markup"/>
     <xsl:text>"&#10;</xsl:text>
     <xsl:call-template name="mark.subheading"/>