From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Sun, 9 Mar 2008 13:33:45 +0000 (+0000)
Subject: removed man.links.are.underlined and added man.font.links. Also,
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=0f37917b1ef24ff9188248534f4c9ba39bb661a4;p=docbook-dsssl

removed man.links.are.underlined and added man.font.links. Also,
changed the default font formatting for links to bold.
---

diff --git a/xsl/manpages/endnotes.xsl b/xsl/manpages/endnotes.xsl
index c78f95885..4e11450dd 100644
--- a/xsl/manpages/endnotes.xsl
+++ b/xsl/manpages/endnotes.xsl
@@ -175,9 +175,10 @@
 <!-- ==================================================================== -->
 
 <xsl:template match="*[@xlink:href]|ulink
-                     |imagedata|audiodata|videodata
-                     |footnote[not(ancestor::table)]
-                     |annotation|alt">
+  |imagedata|audiodata|videodata
+  |footnote[not(ancestor::table)]
+  |annotation|alt">
+  <xsl:variable name="refname" select="ancestor::refentry/refnamediv[1]/refname[1]"/>
   <xsl:variable name="all.earmark.indexes.in.current.document.rtf">
     <xsl:call-template name="get.all.earmark.indexes.in.current.document"/>
   </xsl:variable>
@@ -265,7 +266,6 @@
             <!-- * block-level child content of an endnote properly unless -->
             <!-- * it's wrapped in a para that has some "prefatory" text -->
             <xsl:variable name="parent-name" select="local-name(..)"/>
-            <xsl:variable name="refname" select="ancestor::refentry/refnamediv[1]/refname[1]"/>
             <xsl:variable name="endnote-number">
               <xsl:call-template name="pad-string">
                 <!-- * endnote number may be 2 digits, so pad it with a space -->
@@ -343,21 +343,48 @@
   </xsl:variable>
 
   <xsl:if test="self::ulink or self::*[@xlink:href]">
-    <!-- * This is a hyperlink, so we need to decide how to format -->
-    <!-- * the inline contents of the link (to underline or not). -->
+    <xsl:variable name="link.wrapper">
+      <xsl:value-of select="$notesource.contents"/>
+    </xsl:variable>
+    <!-- * This is a hyperlink, so we need to determine if the user wants -->
+    <!-- * font formatting applied to it, and if so, what font -->
     <xsl:choose>
-      <!-- * if user wants links underlined, underline (ital) it -->
-      <xsl:when test="$man.links.are.underlined != 0">
-        <xsl:variable name="link.wrapper">
-          <xsl:value-of select="$notesource.contents"/>
-        </xsl:variable>
+      <xsl:when test="$man.font.links = 'B'">
+        <xsl:call-template name="bold">
+          <xsl:with-param name="node" select="exsl:node-set($link.wrapper)"/>
+          <xsl:with-param name="context" select="."/>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:when test="$man.font.links = 'I'">
         <xsl:call-template name="italic">
           <xsl:with-param name="node" select="exsl:node-set($link.wrapper)"/>
           <xsl:with-param name="context" select="."/>
         </xsl:call-template>
       </xsl:when>
+      <xsl:when test="$man.font.links = ''">
+        <!-- * if man.font.links is empty, user doesn't want links -->
+        <!-- * underlined, so just display content -->
+        <xsl:value-of select="$notesource.contents"/>
+      </xsl:when>
       <xsl:otherwise>
-        <!-- * user doesn't want links underlined, so just display content -->
+        <!-- * otherwise the user has specified an unsupported value for -->
+        <!-- * man.font.links, so emit a warning and don't apply any font -->
+        <!-- * formatting -->
+        <xsl:message>
+          <xsl:call-template name="log.message">
+            <xsl:with-param name="level">Warn</xsl:with-param>
+            <xsl:with-param name="source" select="$refname"/>
+            <xsl:with-param name="context-desc">
+              <xsl:text>link font</xsl:text>
+            </xsl:with-param>
+            <xsl:with-param name="message">
+              <xsl:text>invalid $man.font.links value: </xsl:text>
+              <xsl:text>'</xsl:text>
+              <xsl:value-of select="$man.font.links"/>
+              <xsl:text>'</xsl:text>
+            </xsl:with-param>
+          </xsl:call-template>
+        </xsl:message>
         <xsl:value-of select="$notesource.contents"/>
       </xsl:otherwise>
     </xsl:choose>
diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 034b3ca2d..2d41f8c0e 100644
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -12,6 +12,7 @@
 <!ENTITY man.endnotes.list.heading SYSTEM "../params/man.endnotes.list.heading.xml">
 <!ENTITY man.font.funcprototype SYSTEM "../params/man.font.funcprototype.xml">
 <!ENTITY man.font.funcsynopsisinfo SYSTEM "../params/man.font.funcsynopsisinfo.xml">
+<!ENTITY man.font.links SYSTEM "../params/man.font.links.xml">
 <!ENTITY man.font.table.headings SYSTEM "../params/man.font.table.headings.xml">
 <!ENTITY man.font.table.title SYSTEM "../params/man.font.table.title.xml">
 <!ENTITY man.funcsynopsis.style SYSTEM "../params/man.funcsynopsis.style.xml">
@@ -25,7 +26,6 @@
 <!ENTITY man.indent.verbatims SYSTEM "../params/man.indent.verbatims.xml">
 <!ENTITY man.indent.width SYSTEM "../params/man.indent.width.xml">
 <!ENTITY man.justify SYSTEM "../params/man.justify.xml">
-<!ENTITY man.links.are.underlined SYSTEM "../params/man.links.are.underlined.xml">
 <!ENTITY man.output.base.dir SYSTEM "../params/man.output.base.dir.xml">
 <!ENTITY man.output.encoding SYSTEM "../params/man.output.encoding.xml">
 <!ENTITY man.output.in.separate.dir SYSTEM "../params/man.output.in.separate.dir.xml">
diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index b2b8f51fe..450a0125a 100644
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -51,6 +51,7 @@
   <title>Fonts</title>
 &man.font.funcprototype;
 &man.font.funcsynopsisinfo;
+&man.font.links;
 &man.font.table.headings;
 &man.font.table.title;
   </reference>
@@ -69,7 +70,6 @@
 &man.endnotes.list.heading;
 &man.endnotes.are.numbered;
 &man.base.url.for.relative.links;
-&man.links.are.underlined;
   </reference>
   <reference xml:id="lists">
   <title>Lists</title>
@@ -165,6 +165,7 @@
 <src:fragref linkend="man.endnotes.list.heading.frag"/>
 <src:fragref linkend="man.font.funcprototype.frag"/>
 <src:fragref linkend="man.font.funcsynopsisinfo.frag"/>
+<src:fragref linkend="man.font.links.frag"/>
 <src:fragref linkend="man.font.table.headings.frag"/>
 <src:fragref linkend="man.font.table.title.frag"/>
 <src:fragref linkend="man.funcsynopsis.style.frag"/>
@@ -178,7 +179,6 @@
 <src:fragref linkend="man.indent.verbatims.frag"/>
 <src:fragref linkend="man.indent.width.frag"/>
 <src:fragref linkend="man.justify.frag"/>
-<src:fragref linkend="man.links.are.underlined.frag"/>
 <src:fragref linkend="man.output.base.dir.frag"/>
 <src:fragref linkend="man.output.encoding.frag"/>
 <src:fragref linkend="man.output.in.separate.dir.frag"/>
diff --git a/xsl/params/man.endnotes.are.numbered.xml b/xsl/params/man.endnotes.are.numbered.xml
index 396cbded4..b069ec3ed 100644
--- a/xsl/params/man.endnotes.are.numbered.xml
+++ b/xsl/params/man.endnotes.are.numbered.xml
@@ -43,13 +43,13 @@ an “empty” notesource is on that looks like this:<literallayout class="monos
 </itemizedlist>
 The default heading for the list of endnotes is
 <literal>NOTES</literal>. To output a different heading, set a value
-for the <parameter>man.links.section.heading</parameter>
+for the <parameter>man.endnotes.section.heading</parameter>
 parameter.</para>
 
 <note>
   <para>The endnotes list is also displayed (but without
     numbers) if the value of
-    <parameter>man.links.list.enabled</parameter> is
+    <parameter>man.endnotes.list.enabled</parameter> is
     non-zero.</para>
 </note>
 
@@ -95,7 +95,12 @@ parameter. Empty links are handled simply by displaying their URLs
 inline. Empty links are never auto-numbered.</para>
 
 <para>If you disable endnotes numbering, you should probably also set
-<parameter>man.links.are.underlined</parameter> to zero (to disable
-link underlining).</para>
+<parameter>man.font.links</parameter> to an empty value (to
+disable font formatting for links.</para>
+</refsection>
+
+<refsection><info><title>Related Parameters</title></info>
+  <para><parameter>man.endnotes.list.enabled</parameter>,
+    <parameter>man.font.links</parameter></para>
 </refsection>
 </refentry>
diff --git a/xsl/params/man.endnotes.list.enabled.xml b/xsl/params/man.endnotes.list.enabled.xml
index 8c302f253..89d81888f 100644
--- a/xsl/params/man.endnotes.list.enabled.xml
+++ b/xsl/params/man.endnotes.list.enabled.xml
@@ -58,7 +58,7 @@ if a (numbered) list of endnotes is also generated.</para>
     browser.</para>
   <para>Also, note that various “man to html” tools, such as the
     widely used <command><link xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)
-  application, automatically mark up URLs with into a@href markup
+    application, automatically mark up URLs with <literal>a@href</literal> markup
   during conversion — resulting in “real” hyperlinks in HTML
   output from those tools.</para>
 </note>
diff --git a/xsl/params/man.font.links.xml b/xsl/params/man.font.links.xml
new file mode 100644
index 000000000..0f8a1e0f7
--- /dev/null
+++ b/xsl/params/man.font.links.xml
@@ -0,0 +1,64 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+          version="5.0" xml:id="man.font.links">
+<refmeta>
+<refentrytitle>man.font.links</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.font.links</refname>
+<refpurpose>Specifies font for links</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.font.links.frag">
+<xsl:param name="man.font.links">B</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>The <parameter>man.font.links</parameter> parameter
+specifies the font for output of links (<tag>ulink</tag> instances
+and any instances of any element with an <tag
+  class="attribute">xlink:href</tag> attribute).</para>
+
+<para>The value of <parameter>man.font.links</parameter> must be
+  either <literal>B</literal> or <literal>I</literal>, or empty. If
+the value is empty, no font formatting is applied to links.</para>
+
+<para>If you set <parameter>man.endnotes.are.numbered</parameter> and/or
+<parameter>man.endnotes.list.enabled</parameter> to zero (disabled), then
+you should probably also set an empty value for
+<parameter>man.font.links</parameter>. But if
+<parameter>man.endnotes.are.numbered</parameter> is non-zero (enabled),
+you should probably keep
+<parameter>man.font.links</parameter> set to
+<literal>B</literal> or <literal>I</literal><footnote><para>The
+    main purpose of applying a font format to links in most output
+formats it to indicate that the formatted text is
+“clickable”; given that links rendered in man pages are
+not “real” hyperlinks that users can click on, it might
+seem like there is never a good reason to have font formatting for
+link contents in man output.</para>
+<para>In fact, if you suppress the
+display of inline link references (by setting
+<parameter>man.endnotes.are.numbered</parameter> to zero), there is no
+good reason to apply font formatting to links. However, if
+<parameter>man.endnotes.are.numbered</parameter> is non-zero, having
+font formatting for links (arguably) serves a purpose: It provides
+“context” information about exactly what part of the text
+is being “annotated” by the link. Depending on how you
+mark up your content, that context information may or may not
+have value.</para></footnote>.</para>
+</refsection>
+
+<refsection><info><title>Related Parameters</title></info>
+  <para><parameter>man.endnotes.list.enabled</parameter>,
+    <parameter>man.endnotes.are.numbered</parameter></para>
+</refsection>
+
+</refentry>
diff --git a/xsl/params/man.links.are.underlined.xml b/xsl/params/man.links.are.underlined.xml
deleted file mode 100644
index bf9635bfa..000000000
--- a/xsl/params/man.links.are.underlined.xml
+++ /dev/null
@@ -1,58 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
-          xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
-          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-          version="5.0" xml:id="man.links.are.underlined">
-<refmeta>
-<refentrytitle>man.links.are.underlined</refentrytitle>
-<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
-</refmeta>
-<refnamediv>
-<refname>man.links.are.underlined</refname>
-<refpurpose>Underline links?</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<src:fragment xml:id="man.links.are.underlined.frag">
-<xsl:param name="man.links.are.underlined">1</xsl:param>
-</src:fragment>
-</refsynopsisdiv>
-
-<refsection><info><title>Description</title></info>
-
-<para>If the value of <parameter>man.links.are.underlined</parameter>
-is non-zero (the default), then the contents of links are rendered
-with an underline.</para>
-
-<para>If the value of <parameter>man.links.are.underlined</parameter>
-is zero, links are displayed without any underlining.</para>
-
-<note>
-  <para>Currently, this parameter only affects output for
-  <tag>ulink</tag>s.</para>
-</note>
-
-<para>If you set <parameter>man.links.are.numbered</parameter> and/or
-<parameter>man.links.list.enabled</parameter> to zero (disabled), then
-you should probably also set
-<parameter>man.links.are.underlined</parameter> to zero. But if
-<parameter>man.links.are.numbered</parameter> is non-zero (enabled),
-you should probably set a non-zero value for
-<parameter>man.links.are.underlined</parameter> also<footnote><para>If the main purpose of underlining of links in most output
-formats it to indicate that the underlined text is
-“clickable”, given that links rendered in man pages are
-not “real” hyperlinks that users can click on, it might
-seem like there is never a good reason to have link contents
-underlined in man output.</para> <para>In fact, if you suppress the
-display of inline link references (by setting
-<parameter>man.links.are.numbered</parameter> to zero), there is no
-good reason to have links underlined. However, if
-<parameter>man.links.are.numbered</parameter> is non-zero, having
-links underlined may (arguably) serve a purpose: It provides
-“context” information about exactly what part of the text
-is being “annotated” by the link. Depending on how you
-mark up your content, that context information may or may not
-have value.</para></footnote>.</para>
-</refsection>
-</refentry>