Added option for turning off bold formatting in Funcsynopsis.

Boldface formatting in function synopsis is mandated in the man(7)
man page and is used almost universally in existing man pages.
Despite that, it really does look like crap to have an entire
Funcsynopsis output in bold, so I added params for turning off the
bold formatting and/or replacing it with a different roff special
font (e.g., "RI" for alternating roman/italic instead of the
default "BI" for alternating bold/italic). The new params are
"man.funcprototype.font" and "man.funcsynopsisinfo.font". To be
documented later.

Closes #1452247. Thanks to Joe Orton for the feature request.

diff --git a/xsl/manpages/block.xsl b/xsl/manpages/block.xsl
index d8420f29507bfeb1ca3efcf01e41d9d51d5a254c..d8729a69f6c5dd781d530e05dba2bd73bdc5b879 100644 (file)
--- a/xsl/manpages/block.xsl
+++ b/xsl/manpages/block.xsl
@@ -74,24 +74,30 @@
   </xsl:choose>
   <xsl:choose>
     <xsl:when test="self::funcsynopsisinfo">
-      <!-- * All funcsynopsisinfo content must be rendered in bold -->
-      <!-- * The man(7) man page says this: -->
+      <!-- * All Funcsynopsisinfo content is by default rendered in bold, -->
+      <!-- * because the man(7) man page says this: -->
       <!-- * -->
       <!-- *   For functions, the arguments are always specified using -->
       <!-- *   italics, even in the SYNOPSIS section, where the rest of -->
-      <!-- *   the function is specified in bold. -->
+      <!-- *   the function is specified in bold -->
       <!-- * -->
-      <!-- * If you take a look through the contents of the man/man2 -->
-      <!-- * directory on your system, you'll see that most existing pages -->
-      <!-- * do follow that "bold everything in function synopsis " rule. -->
+      <!-- * Look through the contents of the man/man2 and man3 directories -->
+      <!-- * on your system, and you'll see that most existing pages do follow -->
+      <!-- * this "bold everything in function synopsis" rule. -->
       <!-- * -->
-      <xsl:text>.\" bold on&#10;</xsl:text>
-      <xsl:text>.ft B&#10;</xsl:text>
+      <!-- * Users who don't want the bold output can choose to adjust the -->
+      <!-- * man.funcsynopsisinfo.font parameter on their own. So even if you -->
+      <!-- * don't personally like the way it looks, please don't change the -->
+      <!-- * default to be non-bold - because it's a convention that's -->
+      <!-- * followed is the vast majority of existing man pages that document -->
+      <!-- * functions, and we need to follow it by default, like it or no. -->
+      <xsl:text>.ft </xsl:text>
+      <xsl:value-of select="$man.funcsynopsisinfo.font"/>
+      <xsl:text>&#10;</xsl:text>
       <xsl:text>.nf&#10;</xsl:text>
       <xsl:apply-templates/>
       <xsl:text>&#10;</xsl:text>
       <xsl:text>.fi&#10;</xsl:text>
-      <xsl:text>.\" bold off&#10;</xsl:text>
       <xsl:text>.ft&#10;</xsl:text>
     </xsl:when>
     <xsl:otherwise>

diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl
index da8889bc6ca874ac796e8979266d6e30628137b5..984324f3c5cf5f219963adefa98f2b467ab7063b 100644 (file)
--- a/xsl/manpages/docbook.xsl
+++ b/xsl/manpages/docbook.xsl
@@ -42,6 +42,8 @@
   <xsl:param name="man.segtitle.suppress">0</xsl:param>
   <xsl:param name="man.indentation.default.adjust">1</xsl:param>
   <xsl:param name="man.indentation.default.value">3n</xsl:param>
+  <xsl:param name="man.funcprototype.font">BI</xsl:param>
+  <xsl:param name="man.funcsynopsisinfo.font">B</xsl:param>
 
 <!-- ==================================================================== -->
 

diff --git a/xsl/manpages/inline.xsl b/xsl/manpages/inline.xsl
index 67328c83de3dbb82489dc5ef646e28762346f501..078a07392923d5f9b0c5beb8ee82e9bf1759e465 100644 (file)
--- a/xsl/manpages/inline.xsl
+++ b/xsl/manpages/inline.xsl
@@ -22,7 +22,7 @@
   <xsl:apply-templates mode="italic" select="."/>
 </xsl:template>
 
-<xsl:template match="option|userinput|envar|errorcode|constant|type">
+<xsl:template match="option|userinput|envar|errorcode|constant">
   <xsl:if test="$man.hyphenate.computer.inlines = 0">
     <xsl:call-template name="suppress.hyphenation"/>
   </xsl:if>
@@ -43,6 +43,14 @@
   <xsl:apply-templates mode="bold" select="."/>
 </xsl:template>
 
+<xsl:template match="type[not(ancestor::cmdsynopsis) and
+                     not(ancestor::funcsynopsis)]">
+  <xsl:if test="$man.hyphenate.computer.inlines = 0">
+    <xsl:call-template name="suppress.hyphenation"/>
+  </xsl:if>
+  <xsl:apply-templates mode="bold" select="."/>
+</xsl:template>
+
 <xsl:template match="function[not(ancestor::cmdsynopsis) and
                      not(ancestor::funcsynopsis)]">
   <xsl:if test="$man.hyphenate.computer.inlines = 0">

diff --git a/xsl/manpages/synop.xsl b/xsl/manpages/synop.xsl
index e6a74219ac704bab2b8f93027e4b532885518d7b..20fac62a00950580e143a15694bc19b6b0d75294 100644 (file)
--- a/xsl/manpages/synop.xsl
+++ b/xsl/manpages/synop.xsl
@@ -208,29 +208,23 @@
   </xsl:if>
 </xsl:template>
 
-<!-- * NOTE TO DEVELOPERS: Below you will find many "bold" calls. -->
-<!-- * -->
-<!-- * The reason is that we need to bold each bit of Funcsynopsis -->
-<!-- * separately, to get around the limitations of not being able -->
-<!-- * to do \fBfoo \fBbar\fI baz\fR and have "baz" get bolded. -->
-<!-- * -->
-<!-- * And the reason we need to bold so much stuff is that the -->
-<!-- * man(7) man page says this: -->
+<!-- * All Funcprototype content is by default rendered in bold, -->
+<!-- * because the man(7) man page says this: -->
 <!-- * -->
 <!-- *   For functions, the arguments are always specified using -->
 <!-- *   italics, even in the SYNOPSIS section, where the rest of -->
-<!-- *   the function is specified in bold: -->
+<!-- *   the function is specified in bold -->
 <!-- * -->
-<!-- * And if you take a look through the contents of the man/man2 -->
-<!-- * directory on your system, you'll see that most existing pages -->
-<!-- * do follow this "bold everything in function synopsis " rule. -->
+<!-- * Look through the contents of the man/man2 and man3 directories -->
+<!-- * on your system, and you'll see that most existing pages do follow -->
+<!-- * this "bold everything in function synopsis" rule. -->
 <!-- * -->
-<!-- * So even if you don't personally like the way it looks, please -->
-<!-- * don't change it to be non-bold - because it is a convention -->
-<!-- * that is followed is the vast majority of existing man pages -->
-<!-- * that document functions, and there's no good reason for us to -->
-<!-- * be following it. -->
-
+<!-- * Users who don't want the bold output can choose to adjust the -->
+<!-- * man.funcprototype.font parameter on their own. So even if you -->
+<!-- * don't personally like the way it looks, please don't change the -->
+<!-- * default to be non-bold - because it's a convention that's -->
+<!-- * followed is the vast majority of existing man pages that document -->
+<!-- * functions, and we need to follow it by default, like it or no. -->
 <xsl:template match="funcprototype">
   <xsl:variable name="funcprototype.string.value">
     <xsl:value-of select="funcdef"/>
@@ -243,78 +237,69 @@
   <!-- * (because funcdef is always followed by one open paren char) -->
   <xsl:value-of select="string-length (normalize-space ($funcprototype.string.value)) + 1"/>
   <xsl:text>&#10;</xsl:text>
-  <xsl:value-of select="normalize-space ($funcprototype)"/>
-  <xsl:variable name="funcdef.suffix">
-    <Funcdef.Suffix>(</Funcdef.Suffix>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($funcdef.suffix)"/>
+  <xsl:text>.</xsl:text>
+  <xsl:value-of select="$man.funcprototype.font"/>
+  <xsl:text> </xsl:text>
+  <!-- * The following quotation mark (and the one further below) are -->
+  <!-- * needed to properly delimit the parts of the Funcprototype that -->
+  <!-- * should be rendered in the prevailing font (either Bold or Roman) -->
+  <!-- * from Parameter output that needs to be alternately rendered in -->
+  <!-- * italic. -->
+  <xsl:text>"</xsl:text>
+  <xsl:value-of select="normalize-space($funcprototype)"/>
+  <xsl:text>(</xsl:text>
   <xsl:apply-templates select="*[local-name() != 'funcdef']"/>
+  <xsl:text>"</xsl:text>
   <xsl:text>&#10;</xsl:text>
 </xsl:template>
 
 <xsl:template match="funcdef">
-  <xsl:variable name="funcdef">
-    <Funcdef>
-      <xsl:apply-templates select="." mode="prevent.line.breaking"/>
-    </Funcdef>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($funcdef)"/>
+  <xsl:apply-templates mode="prevent.line.breaking"/>
 </xsl:template>
 
 <xsl:template match="funcdef/function">
-  <xsl:apply-templates mode="bold" select="."/>
+  <xsl:apply-templates/>
 </xsl:template>
 
 <xsl:template match="void">
-  <xsl:variable name="void">
-    <Void>void);</Void>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($void)"/>
+  <xsl:text>void);</xsl:text>
 </xsl:template>
 
 <xsl:template match="varargs">
-  <xsl:variable name="varargs">
-    <Varargs>...);</Varargs>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($varargs)"/>
+  <xsl:text>...);</xsl:text>
 </xsl:template>
 
 <xsl:template match="paramdef">
-  <xsl:variable name="paramdef">
-    <Paramdef>
-      <xsl:apply-templates mode="bold" select="." />
-    </Paramdef>
-  </xsl:variable>
-  <xsl:apply-templates mode="prevent.line.breaking" select="exsl:node-set($paramdef)"/>
-  <xsl:variable name="paramdef.suffix">
-    <Paramdef.Suffix>
-      <xsl:choose>
-        <xsl:when test="following-sibling::*">
-          <xsl:text>, </xsl:text>
-        </xsl:when>
-        <xsl:otherwise>
-          <xsl:text>);</xsl:text>
-        </xsl:otherwise>
-      </xsl:choose>
-    </Paramdef.Suffix>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($paramdef.suffix)"/>
+  <xsl:apply-templates mode="prevent.line.breaking" select="."/>
+  <xsl:choose>
+    <xsl:when test="following-sibling::*">
+      <xsl:text>, </xsl:text>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:text>);</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
 </xsl:template>
 
 <xsl:template match="paramdef/parameter">
-  <xsl:apply-templates mode="italic" select="."/>
+  <!-- * x2008 is a "punctuation space"; we use it here because if we -->
+  <!-- * were to just use a normal space, it would get replaced with a -->
+  <!-- * non-breaking space when we run the whole Paramdef through the -->
+  <!-- * prevent.line.breaking template. And as far as why we're -->
+  <!-- * inserting the space an quotation marks around each Parameter to -->
+  <!-- * begin with, the reason is that we need to because we are -->
+  <!-- * outputting Funcsynopsis in either the "BI" or "RI" font, and -->
+  <!-- * the space and quotation marks delimit the text as the -->
+  <!-- * "alternate" or "I" text that needs to be rendered in italic. -->
+  <xsl:text>"&#x2008;"</xsl:text>
+  <xsl:apply-templates/>
+  <xsl:text>"&#x2008;"</xsl:text>
 </xsl:template>
 
 <xsl:template match="funcparams">
-  <xsl:variable name="funcparams.prefix">
-    <Funcparams.Prefix>(</Funcparams.Prefix>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($funcparams.prefix)"/>
-  <xsl:apply-templates mode="bold" select="."/>
-  <xsl:variable name="funcparams.suffix">
-    <Funcparams.Suffix>)</Funcparams.Suffix>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($funcparams.suffix)"/>
+  <text>(</text>
+  <xsl:apply-templates/>
+  <text>)</text>
 </xsl:template>
 
 </xsl:stylesheet>

diff --git a/xsl/params/man.string.subst.map.xml b/xsl/params/man.string.subst.map.xml
index 406793a5d2afad60e37b6577ee358d50cdfb69d3..878e2ef29195bdfaf3f1782bf08b0c9b2022c16d 100644 (file)
--- a/xsl/params/man.string.subst.map.xml
+++ b/xsl/params/man.string.subst.map.xml
@@ -71,6 +71,14 @@
   <!-- * lines that only have words separated by "\~" spaces, so it's -->
   <!-- * safer just to stick with the "\ " space -->
   <substitution oldstring="&#x00a0;" newstring="\ "/>
+  <!-- * x2008 is a "punctuation space"; we must replace it here because, -->
+  <!-- * for certain reasons, the stylesheets add it before and after -->
+  <!-- * every Parameter in Funcprototype output -->
+  <substitution oldstring="&#x2008;" newstring=" "/>
+  <!-- * -->
+  <!-- * Now deal with some other characters that are added by the -->
+  <!-- * stylesheets during processing. -->
+  <!-- * -->
   <!-- * bullet -->
   <substitution oldstring="&#x2022;" newstring="\(bu"/>
   <!-- * left double quote -->
@@ -85,12 +93,12 @@
   <substitution oldstring="&#x00a9;" newstring="\(co"/>
   <!-- * registered sign -->
   <substitution oldstring="&#x00ae;" newstring="\(rg"/>
-  <!-- * servicemark -->
-  <!-- * there is no groff equivalent for it -->
+  <!-- * servicemark... -->
+  <!-- * There is no groff equivalent for it. -->
   <substitution oldstring="&#x2120;" newstring="(SM)"/>
-  <!-- * trademark -->
-  <!-- * we don't do "\(tm" because for console output -->
-  <!-- * because groff just renders that as "tm"; that is: -->
+  <!-- * trademark... -->
+  <!-- * We don't do "\(tm" because for console output, -->
+  <!-- * groff just renders that as "tm"; that is: -->
   <!-- * -->
   <!-- *   Product&#x2122; -> Producttm -->
   <!-- * -->