From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Mon, 11 Jul 2005 10:29:58 +0000 (+0000)
Subject: Implemented out-of-line handling of URLs for links (Ulinks).
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3e2d2508272d8ed90d71aeee9a9ac38cea62602c;p=docbook-dsssl

Implemented out-of-line handling of URLs for links (Ulinks).
(Closes #1234711 and #1233909)

For display of links, this implementation gives users three choices:

  1. Number & list links. Each link is numbered and a numbered
     list of all links is added to the end of the document.

     or

  2. Only list links. Links are not numbered, but an (unnumbered)
     list of links is added to the end of the document.

     or

  3. Suppress links. Don't number links and don't add any list of
     links to the end of the document

Users can also choose whether links should be underlined.

Default is "the works" -- list, number, and underline links. The
man.links.* parameters can be used to change the defaults.

The default heading for the link list is REFERENCES. That can be
changed using the man.links.list.heading param.

There is a performance hit for listing and numbering links. But it
is not an unreasonable one.

The code currently only checks for Ulinks. It can be updated later
(possibly) to deal with DocBook NG linking. But come to think of
it, DocBook NG links get converted by the strip-ns template. So
DocBook NG users will just need to run that first. Or, if I can
ever manage to get the single-pass conversion process to work with
manpages, it will get done automatically.
---

diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl
index ae9986362..d0563679d 100644
--- a/xsl/manpages/docbook.xsl
+++ b/xsl/manpages/docbook.xsl
@@ -32,6 +32,7 @@
   <xsl:include href="inline.xsl"/>
   <xsl:include href="synop.xsl"/>
   <xsl:include href="lists.xsl"/>
+  <xsl:include href="links.xsl"/>
 
 <!-- ==================================================================== -->
 
@@ -141,12 +142,13 @@
         <xsl:with-param name="parentinfo" select="$parentinfo"/>
       </xsl:call-template>
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
-      <!-- * LINKS list (only generate if user wants links numbered) -->
+      <!-- * LINKS list (only if user wants links numbered and/or listed) -->
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
-      <xsl:if test="$man.links.list.enabled != 0">
+      <xsl:if test="$man.links.list.enabled != 0 or
+                    $man.links.are.numbered != 0">
         <xsl:call-template name="links.list"/>
       </xsl:if>
-    </xsl:variable>
+    </xsl:variable> <!-- * end of manpage.contents -->
 
     <!-- * Prepare the page contents for final output, then store in -->
     <!-- * $manpage.contents.prepared so the we can pass it on to the -->
diff --git a/xsl/manpages/inline.xsl b/xsl/manpages/inline.xsl
index 8b166974e..776a96dc9 100644
--- a/xsl/manpages/inline.xsl
+++ b/xsl/manpages/inline.xsl
@@ -13,63 +13,6 @@
 
      ******************************************************************** -->
 
-<xsl:param name="man.links.list.enabled">1</xsl:param>
-
-<!-- ==================================================================== -->
-
-<!-- * Make per-Refentry sets of all links in each Refentry which do not -->
-<!-- * have the same URL as any preceding link in that same Refentry -->
-<!-- * -->
-<!-- * Note that we don't get links in *info sections -->
-<!-- * or Refmeta or Refnamediv or Indexterm, because, in manpages -->
-<!-- * output, contents of those are either suppressed or are -->
-<!-- * displayed out of document order - for example, the Info/Author -->
-<!-- * content gets moved to the end of the page. So, if we were to -->
-<!-- * number links in the Author content, it would "throw off" the -->
-<!-- * numbering at the beginning of the main text flow. -->
-<xsl:variable name="get.all.unique.links">
-  <xsl:if test="$man.links.are.numbered != 0">
-    <xsl:for-each select="//refentry">
-      <refentry.link.set>
-        <xsl:attribute name="idref">
-          <xsl:value-of select="generate-id()"/>
-        </xsl:attribute>
-        <xsl:for-each
-            select=".//ulink[node()
-                    and not(ancestor::refentryinfo)
-                    and not(ancestor::info)
-                    and not(ancestor::docinfo)
-                    and not(ancestor::refmeta)
-                    and not(ancestor::refnamediv)
-                    and not(ancestor::indexterm)
-                    and not(@url =
-                    preceding::ulink[node()
-                    and not(ancestor::refentryinfo)
-                    and not(ancestor::info)
-                    and not(ancestor::docinfo)
-                    and not(ancestor::refmeta)
-                    and not(ancestor::refnamediv)
-                    and not(ancestor::indexterm)
-                    and (generate-id(ancestor::refentry)=generate-id(current()))]/@url)]">
-          <link>
-            <xsl:attribute name="idref">
-              <xsl:value-of select="generate-id()"/>
-            </xsl:attribute>
-            <xsl:attribute name="url">
-              <xsl:value-of select="@url"/>
-            </xsl:attribute>
-            <xsl:copy>
-              <xsl:copy-of select="node()"/>
-            </xsl:copy>
-          </link>
-        </xsl:for-each>
-      </refentry.link.set>
-    </xsl:for-each>
-  </xsl:if>
-</xsl:variable>
-
-<xsl:variable name="all.unique.links" select="exsl:node-set($get.all.unique.links)"/>
-
 <!-- ==================================================================== -->
 
 <xsl:template match="filename|replaceable|varname">
@@ -141,238 +84,4 @@
   </xsl:choose>
 </xsl:template>
 
-<!-- ==================================================================== -->
-
-<!-- * Here we deal with Ulink... -->
-<!-- * -->
-<!-- * Other link types are handled by templates from html/xref.xsl, -->
-<!-- * which the manpages stylesheets import. But Ulinks - in -->
-<!-- * particular, non-empty Ulinks - must be handled differently. -->
-<!-- * -->
-<!-- * So this is what we do: -->
-<!-- * -->
-<!-- * We first find out if the Ulink is empty; if it is, we just -->
-<!-- * display the contents of its URL (that is, the value of its "Url" -->
-<!-- * attribute), and stop there. -->
-<!-- * -->
-<!-- * On the other hand, if it is NON-empty, we need to display its -->
-<!-- * contents AND (optionally) display its URL. We could display the -->
-<!-- * URL inline, after the contents (as we did previously), but that -->
-<!-- * ends up looking horrible if you have a lot of links. -->
-<!-- * -->
-<!-- * So, we instead need to display the URL out-of-line, in a way -->
-<!-- * that associates it with the content. How to do that in a -->
-<!-- * text-based output format that lacks hyperlinks? -->
-<!-- * -->
-<!-- * Here's how: Do it the way that most text/curses-based browsers -->
-<!-- * (e.g., w3m and lynx) do in the "-dump" output: Put a number -->
-<!-- * (in brackets) before the contents, and then put the URL, with -->
-<!-- * the corresponding number, in a generated section -->
-<!-- * at the end of the page. -->
-
-<xsl:template match="ulink">
-
-<xsl:variable name="get.unique.links">
-  <xsl:copy-of
-      select="$all.unique.links/refentry.link.set
-              [@idref = generate-id(current()/ancestor::refentry)]/link"/>
-</xsl:variable>
-<xsl:variable name="unique.links" select="exsl:node-set($get.unique.links)"/>
-
-  <xsl:variable name="url">
-    <xsl:value-of select="@url"/>
-  </xsl:variable>
-  <xsl:variable name="link">
-    <xsl:choose>
-      <!-- * check to see if the element is empty or not; if it's non-empty, -->
-      <!-- * get the content -->
-      <xsl:when test="node()">
-        <xsl:apply-templates/>
-      </xsl:when>
-      <xsl:otherwise>
-        <!-- * the element is empty, so we just get the value of the URL; -->
-        <!-- * note that we don't number empty links -->
-        <xsl:value-of select="$url"/>
-      </xsl:otherwise>
-    </xsl:choose>
-  </xsl:variable>
-  <!-- * if link is non-empty AND user wants links numbered, output -->
-  <!-- * a number for it -->
-  <xsl:if test="node() and $man.links.are.numbered != 0">
-    <xsl:text>[</xsl:text>
-    <xsl:choose>
-      <xsl:when test="$url = $unique.links/link/@url">
-        <xsl:apply-templates
-            select="$unique.links/link[@url = $url][1]"
-            mode="link.number"/>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:apply-templates select="." mode="link.number"/>
-      </xsl:otherwise>
-    </xsl:choose>
-    <xsl:text>]</xsl:text>
-  </xsl:if>
-  <xsl:choose>
-    <!-- * if user wants links underlined, underline (ital) it -->
-    <xsl:when test="$man.links.are.underlined != 0">
-      <xsl:variable name="link.wrapper">
-        <italic><xsl:value-of select="$link"/></italic>
-      </xsl:variable>
-      <xsl:apply-templates mode="italic" select="exsl:node-set($link.wrapper)"/>
-    </xsl:when>
-    <xsl:otherwise>
-      <!-- * user doesn't want links underlined, so just display content -->
-      <xsl:value-of select="$link"/>
-    </xsl:otherwise>
-  </xsl:choose>
-</xsl:template>
-
-<!-- ==================================================================== -->
-
-<xsl:template match="*" mode="link.number">
-  
-  <!-- * Count all links in this Refentry which do not -->
-  <!-- * have the same URL as any preceding link in this same Refentry -->
-  <!-- * -->
-  <!-- * Note that we don't get links in *info sections -->
-  <!-- * or Refmeta or Refnamediv or Indexterm, because, in manpages -->
-  <!-- * output, contents of those are either suppressed or are -->
-  <!-- * displayed out of document order - for example, the Info/Author -->
-  <!-- * content gets moved to the end of the page. So, if we were to -->
-  <!-- * number links in the Author content, it would "throw off" the -->
-  <!-- * numbering at the beginning of the main text flow. -->
-  <xsl:value-of select="count(preceding::ulink[node()
-                        and not(ancestor::refentryinfo)
-                        and not(ancestor::info)
-                        and not(ancestor::docinfo)
-                        and not(ancestor::refmeta)
-                        and not(ancestor::refnamediv)
-                        and not(ancestor::indexterm)
-                        and not(@url = preceding::ulink[node()
-                        and not(ancestor::refentryinfo)
-                        and not(ancestor::info)
-                        and not(ancestor::docinfo)
-                        and not(ancestor::refmeta)
-                        and not(ancestor::refnamediv)
-                        and not(ancestor::indexterm)
-                        and (generate-id(ancestor::refentry)
-                        = generate-id(current()/ancestor::refentry))]/@url)]
-                        [generate-id(ancestor::refentry)
-                        = generate-id(current()/ancestor::refentry)]) + 1"/>
-</xsl:template>
-
-<!-- ==================================================================== -->
-
-<xsl:template name="links.list">
-  <!-- * Get all links in this Refentry which do not -->
-  <!-- * have the same URL as any preceding link in this same Refentry -->
-  <!-- * -->
-  <!-- * Note that we don't get links in *info sections -->
-  <!-- * or Refmeta or Refnamediv or Indexterm, because, in manpages -->
-  <!-- * output, contents of those are either suppressed or are -->
-  <!-- * displayed out of document order - for example, the Info/Author -->
-  <!-- * content gets moved to the end of the page. So, if we were to -->
-  <!-- * number links in the Author content, it would "throw off" the -->
-  <!-- * numbering at the beginning of the main text flow. -->
-  <xsl:variable name="links"
-                select=".//ulink[node()
-                  and not(ancestor::refentryinfo)
-                  and not(ancestor::info)
-                  and not(ancestor::docinfo)
-                  and not(ancestor::refmeta)
-                  and not(ancestor::refnamediv)
-                  and not(ancestor::indexterm)
-                  and not(@url =
-                  preceding::ulink[node()
-                  and not(ancestor::refentryinfo)
-                  and not(ancestor::info)
-                  and not(ancestor::docinfo)
-                  and not(ancestor::refmeta)
-                  and not(ancestor::refnamediv)
-                  and not(ancestor::indexterm)
-                  and (generate-id(ancestor::refentry)
-                  = generate-id(current()))]/@url)]"/>
-  <xsl:if test="$links/node()">
-    <xsl:call-template name="format.links.list">
-      <xsl:with-param name="links" select="$links"/>
-    </xsl:call-template>
-  </xsl:if>
-</xsl:template>
-
-<!-- ==================================================================== -->
-
-<xsl:template name="format.links.list">
-  <xsl:param name="links"/>
-  <xsl:param name="heading">
-    <xsl:choose>
-      <xsl:when test="$man.links.section.heading != ''">
-        <xsl:value-of select="$man.links.section.heading"/>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:text>Links</xsl:text>
-      </xsl:otherwise>
-    </xsl:choose>
-  </xsl:param>
-  <!-- * The value of $padding.length is used for determining how much -->
-  <!-- * to right-pad numbers in the LINKS list. So, for $length, we -->
-  <!-- * count how many links there are, then take the number of digits -->
-  <!-- * in that count, and add 2 to it. The reason we add 2 is that we -->
-  <!-- * also prepend a dot and no-break space to each link number in -->
-  <!-- * the list, so we need to consider what length to pad out to. -->
-  <xsl:param name="padding.length">
-    <xsl:choose>
-      <xsl:when test="$man.links.are.numbered != 0">
-        <xsl:value-of select="string-length(count($links)) + 2"/>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:value-of select="0"/>
-      </xsl:otherwise>
-    </xsl:choose>
-  </xsl:param>
-  <xsl:call-template name="mark.subheading"/>
-  <!-- * make the LINKS section heading -->
-  <xsl:text>.SH "</xsl:text>
-  <xsl:call-template name="string.upper">
-    <xsl:with-param name="string">
-      <xsl:choose>
-        <xsl:when test="$man.links.section.heading != ''">
-          <xsl:value-of select="$man.links.section.heading"/>
-        </xsl:when>
-        <xsl:otherwise>
-          <xsl:call-template name="gentext">
-            <xsl:with-param name="key" select="'Links'"/>
-          </xsl:call-template>
-        </xsl:otherwise>
-      </xsl:choose>
-    </xsl:with-param>
-  </xsl:call-template>
-  <xsl:text>"&#10;</xsl:text>
-  <xsl:for-each select="$links">
-    <xsl:variable name="link.number">
-      <xsl:apply-templates select="." mode="link.number"/>
-      <xsl:text>.&#160;</xsl:text>
-    </xsl:variable>
-    <xsl:text>.PP&#10;</xsl:text>
-    <!-- * right-pad each number out to the correct length -->
-    <xsl:call-template name="prepend-pad">
-      <xsl:with-param name="padVar" select="$link.number"/>
-      <xsl:with-param name="length" select="$padding.length"/>
-    </xsl:call-template>
-    <xsl:variable name="link.contents">
-      <xsl:apply-templates/>
-    </xsl:variable>
-    <xsl:value-of select="normalize-space($link.contents)"/>
-    <xsl:text>&#10;</xsl:text>
-    <xsl:text>.br&#10;</xsl:text>
-    <!-- * pad leader for URL -->
-    <xsl:call-template name="prepend-pad">
-      <xsl:with-param name="padVar" select="' '"/>
-      <xsl:with-param name="length" select="$padding.length"/>
-    </xsl:call-template>
-    <!-- * print the Ulink's URL -->
-    <xsl:value-of select="@url"/>
-    <xsl:text>&#10;</xsl:text>
-  </xsl:for-each>
-</xsl:template>
-
 </xsl:stylesheet>
diff --git a/xsl/manpages/links.xsl b/xsl/manpages/links.xsl
new file mode 100644
index 000000000..88d0212be
--- /dev/null
+++ b/xsl/manpages/links.xsl
@@ -0,0 +1,329 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:exsl="http://exslt.org/common"
+                version='1.0'>
+
+<!-- ********************************************************************
+     $Id$
+     ********************************************************************
+
+     This file is part of the XSL DocBook Stylesheet distribution.
+     See ../README or http://docbook.sf.net/release/xsl/current/ for
+     copyright and other information.
+
+     ******************************************************************** -->
+
+<!-- ==================================================================== -->
+
+<!-- * Make per-Refentry sets of all links in each Refentry which do not -->
+<!-- * have the same URL as any preceding link in that same Refentry -->
+<!-- * -->
+<!-- * We need this in order to have inline numbering match the -->
+<!-- * numbering of the link list. In both places, for any link whose -->
+<!-- * URL is a duplicate of that of a preceding link in the same -->
+<!-- * Refentry, we assign it the number of that previous link. -->
+<!-- * -->
+<!-- * Note that we don't get links in *info sections or Refmeta or -->
+<!-- * Refnamediv or Indexterm, because, in manpages output, contents -->
+<!-- * of those are either suppressed or are displayed out of document -->
+<!-- * order - for example, the Info/Author content gets moved to the -->
+<!-- * end of the page. So, if we were to number links in the Author -->
+<!-- * content, it would "throw off" the numbering at the beginning of -->
+<!-- * the main text flow. -->
+<!-- * -->
+<!-- * And note especially that the reason we don't use xsl:key here -->
+<!-- * is that the "match" value is an XSLT _pattern_, not an XSLT -->
+<!-- * _expression_; XSLT patterns can't contain function calls, but -->
+<!-- * XSLT expressions can. We need the calls to the generate-id() -->
+<!-- * function in order to determine whether or not two links have -->
+<!-- * the same Refentry parent -->
+<xsl:variable name="get.all.links.with.unique.urls">
+  <xsl:if test="$man.links.are.numbered != 0">
+    <xsl:for-each select="//refentry">
+      <refentry.link.set>
+        <xsl:attribute name="idref">
+          <xsl:value-of select="generate-id()"/>
+        </xsl:attribute>
+        <xsl:for-each
+            select=".//ulink[node()
+                    and not(ancestor::refentryinfo)
+                    and not(ancestor::info)
+                    and not(ancestor::docinfo)
+                    and not(ancestor::refmeta)
+                    and not(ancestor::refnamediv)
+                    and not(ancestor::indexterm)
+                    and not(@url =
+                    preceding::ulink[node()
+                    and not(ancestor::refentryinfo)
+                    and not(ancestor::info)
+                    and not(ancestor::docinfo)
+                    and not(ancestor::refmeta)
+                    and not(ancestor::refnamediv)
+                    and not(ancestor::indexterm)
+                    and (generate-id(ancestor::refentry)
+                    = generate-id(current()))]/@url)]">
+          <link>
+            <xsl:attribute name="url">
+              <xsl:value-of select="@url"/>
+            </xsl:attribute>
+            <xsl:copy>
+              <xsl:copy-of select="node()"/>
+            </xsl:copy>
+          </link>
+        </xsl:for-each>
+      </refentry.link.set>
+    </xsl:for-each>
+  </xsl:if>
+</xsl:variable>
+
+<xsl:variable name="all.links.with.unique.urls"
+              select="exsl:node-set($get.all.links.with.unique.urls)"/>
+
+<!-- ==================================================================== -->
+
+<!-- * We first find out if the link is empty; if it is, we just -->
+<!-- * display the contents of its URL (that is, the value of its "Url" -->
+<!-- * attribute), and stop there. -->
+<!-- * -->
+<!-- * On the other hand, if it is NON-empty, we need to display its -->
+<!-- * contents AND (optionally) display its URL. We could display the -->
+<!-- * URL inline, after the contents (as we did previously), but that -->
+<!-- * ends up looking horrible if you have a lot of links. -->
+<!-- * -->
+<!-- * So, we instead need to display the URL out-of-line, in a way -->
+<!-- * that associates it with the content. How to do that in a -->
+<!-- * text-based output format that lacks hyperlinks? -->
+<!-- * -->
+<!-- * Here's how: Do it the way that most text/curses-based browsers -->
+<!-- * (e.g., w3m and lynx) do in the "-dump" output: Put a number -->
+<!-- * (in brackets) before the contents, and then put the URL, with -->
+<!-- * the corresponding number, in a generated section -->
+<!-- * at the end of the page. -->
+<!-- * -->
+<!-- * For any link whose URL is a duplicate of that of a preceding -->
+<!-- * link in the same Refentry, we assign it the number of that -->
+<!-- * previous link. -->
+<xsl:template match="ulink">
+  <xsl:variable name="get.links.with.unique.urls">
+    <!-- * get the set of all unique links in the ancestor Refentry of -->
+    <!-- * this Ulink -->
+    <xsl:copy-of
+        select="$all.links.with.unique.urls/refentry.link.set
+                [@idref = generate-id(current()/ancestor::refentry)]/link"/>
+  </xsl:variable>
+  <xsl:variable name="links.with.unique.urls"
+                select="exsl:node-set($get.links.with.unique.urls)"/>
+  <!-- * store link URL in variable because we check it multiple times -->
+  <xsl:variable name="url">
+    <xsl:value-of select="@url"/>
+  </xsl:variable>
+  <!-- * $link is either the link contents (if the link is non-empty) or -->
+  <!-- * the URL (if the link is empty -->
+  <xsl:variable name="link">
+    <xsl:choose>
+      <!-- * check to see if the element is empty or not; if it's non-empty, -->
+      <!-- * get the content -->
+      <xsl:when test="node()">
+        <xsl:apply-templates/>
+      </xsl:when>
+      <xsl:otherwise>
+        <!-- * the element is empty, so we just get the value of the URL; -->
+        <!-- * note that we don't number empty links -->
+        <xsl:value-of select="$url"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+  <!-- * if link is non-empty AND user wants links numbered, output -->
+  <!-- * a number for it -->
+  <xsl:if test="node() and $man.links.are.numbered != 0">
+    <!-- * We number links by checking the $links.with.unique.urls set -->
+    <!-- * and finding the link whose URL matches the URL for this -->
+    <!-- * link. If this is the only instance in this Refentry of a link -->
+    <!-- * with this URL, then it gets a unique number. But if this is a -->
+    <!-- * link for which there are multiple instances of links in this -->
+    <!-- * Refentry that have the same URL as this link, then the number -->
+    <!-- * assigned is the number of the _first_ instance of a link in -->
+    <!-- * this Refentry with the URL for this link (which be the number -->
+    <!-- * of this link itself, if it happens to be the first instance). -->
+    <xsl:variable name="link.number">
+      <xsl:apply-templates
+          select="$links.with.unique.urls/link[@url = $url][1]"
+          mode="link.number"/>
+    </xsl:variable>
+    <!-- * format the number by placing it in square brackets. This -->
+    <!-- * formatting could be made user-configurable - something -->
+    <!-- * other than square brackets. But what else would work? -->
+    <!-- * <10> Angle brackets? {10} Braces? -->
+    <xsl:text>[</xsl:text> 
+    <xsl:value-of select="$link.number"/>
+    <xsl:text>]</xsl:text>
+  </xsl:if>
+  <xsl:choose>
+    <!-- * if user wants links underlined, underline (ital) it -->
+    <xsl:when test="$man.links.are.underlined != 0">
+      <xsl:variable name="link.wrapper">
+        <italic><xsl:value-of select="$link"/></italic>
+      </xsl:variable>
+      <xsl:apply-templates mode="italic" select="exsl:node-set($link.wrapper)"/>
+    </xsl:when>
+    <xsl:otherwise>
+      <!-- * user doesn't want links underlined, so just display content -->
+      <xsl:value-of select="$link"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<!-- ==================================================================== -->
+
+<xsl:template match="*" mode="link.number">
+  <!-- * Count all links in this Refentry which do not have the same -->
+  <!-- * URL as any preceding link in this same Refentry -->
+  <!-- * -->
+  <!-- * Note that we don't get links in *info sections or Refmeta or -->
+  <!-- * Refnamediv or Indexterm, because, in manpages output, -->
+  <!-- * contents of those are either suppressed or are displayed out -->
+  <!-- * of document order -->
+  <!-- * -->
+  <!-- * And note that the reason we don't just use xsl:number here -->
+  <!-- * is that the "match" value is an XSLT _pattern_, not an XSLT -->
+  <!-- * _expression_; XSLT patterns can't contain function calls, but -->
+  <!-- * XSLT expressions can. We need the calls to the generate-id() -->
+  <!-- * function in order to determine whether or not two links have -->
+  <!-- * the same Refentry parent -->
+  <xsl:value-of select="count(preceding::ulink[node()
+                        and not(ancestor::refentryinfo)
+                        and not(ancestor::info)
+                        and not(ancestor::docinfo)
+                        and not(ancestor::refmeta)
+                        and not(ancestor::refnamediv)
+                        and not(ancestor::indexterm)
+                        and not(@url =
+                        preceding::ulink[node()
+                        and not(ancestor::refentryinfo)
+                        and not(ancestor::info)
+                        and not(ancestor::docinfo)
+                        and not(ancestor::refmeta)
+                        and not(ancestor::refnamediv)
+                        and not(ancestor::indexterm)
+                        and (generate-id(ancestor::refentry)
+                        = generate-id(current()/ancestor::refentry))]/@url)]
+                        [generate-id(ancestor::refentry)
+                        = generate-id(current()/ancestor::refentry)]) + 1"/>
+</xsl:template>
+
+<!-- ==================================================================== -->
+
+<xsl:template name="links.list">
+  <!-- * Get all links in this Refentry which do not have the same URL -->
+  <!-- * as any preceding link in this same Refentry -->
+  <!-- * -->
+  <!-- * Note that we don't get links in *info sections or Refmeta or -->
+  <!-- * Refnamediv or Indexterm, because, in manpages output, -->
+  <!-- * contents of those are either suppressed or are displayed out -->
+  <!-- * of document order -->
+  <xsl:variable name="links"
+                select=".//ulink[node()
+                  and not(ancestor::refentryinfo)
+                  and not(ancestor::info)
+                  and not(ancestor::docinfo)
+                  and not(ancestor::refmeta)
+                  and not(ancestor::refnamediv)
+                  and not(ancestor::indexterm)
+                  and not(@url =
+                  preceding::ulink[node()
+                  and not(ancestor::refentryinfo)
+                  and not(ancestor::info)
+                  and not(ancestor::docinfo)
+                  and not(ancestor::refmeta)
+                  and not(ancestor::refnamediv)
+                  and not(ancestor::indexterm)
+                  and (generate-id(ancestor::refentry)
+                  = generate-id(current()))]/@url)]"/>
+  <!-- * check to see if we have actually found any links; if we have, -->
+  <!-- * we generate the links list, if not, we do nothing -->
+  <xsl:if test="$links/node()">
+    <xsl:call-template name="format.links.list">
+      <xsl:with-param name="links" select="$links"/>
+    </xsl:call-template>
+  </xsl:if>
+</xsl:template>
+
+<!-- ==================================================================== -->
+
+<xsl:template name="format.links.list">
+  <xsl:param name="links"/>
+  <!-- * The value of $padding.length is used for determining how much -->
+  <!-- * to right-pad numbers in the LINKS list. So, for $length, we -->
+  <!-- * count how many links there are, then take the number of digits -->
+  <!-- * in that count, and add 2 to it. The reason we add 2 is that we -->
+  <!-- * also prepend a dot and no-break space to each link number in -->
+  <!-- * the list, so we need to consider what length to pad out to. -->
+  <xsl:param name="padding.length">
+    <xsl:choose>
+      <xsl:when test="$man.links.are.numbered != 0">
+        <xsl:value-of select="string-length(count($links)) + 2"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <!-- * if links aren't numbered, just set padding to zero -->
+        <xsl:value-of select="0"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:param>
+  <xsl:call-template name="mark.subheading"/>
+  <!-- * make the link-list section heading (REFERENCES) -->
+  <xsl:text>.SH "</xsl:text>
+  <xsl:call-template name="string.upper">
+    <xsl:with-param name="string">
+      <xsl:choose>
+        <!-- * if user has specified a heading, use that -->
+        <xsl:when test="$man.links.list.heading != ''">
+          <xsl:value-of select="$man.links.list.heading"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <!-- * otherwise, get localized heading from gentext -->
+          <xsl:call-template name="gentext">
+            <xsl:with-param name="key" select="'References'"/>
+          </xsl:call-template>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:with-param>
+  </xsl:call-template>
+  <xsl:text>"&#10;</xsl:text>
+  <xsl:for-each select="$links">
+    <!-- * number the link, in the form " 1." followed by a -->
+    <!-- * non-breaking space; -->
+    <xsl:variable name="link.number">
+      <xsl:apply-templates select="." mode="link.number"/>
+      <xsl:text>.&#160;</xsl:text>
+    </xsl:variable>
+    <!-- * make paragraph with hanging indent; length of indent is -->
+    <!-- * same as value of $padding.length -->
+    <xsl:text>.TP </xsl:text>
+    <xsl:value-of select="$padding.length"/>
+    <xsl:text>&#10;</xsl:text>
+    <!-- * right-pad each number out to the correct length -->
+    <!-- * So, if there are 10 or more links, numbers -->
+    <!-- * 1 through 9 will have a space in front of them; if -->
+    <!-- * there are 100 or more, 1 through 9 will have two -->
+    <!-- * spaces, 10 through 99 will have one space, etc. -->
+    <xsl:call-template name="prepend-pad">
+      <xsl:with-param name="padVar" select="$link.number"/>
+      <xsl:with-param name="length" select="$padding.length"/>
+    </xsl:call-template>
+    <!-- * Print the links contents -->
+    <!-- * IMPORTANT: If there are multiple links in this Refentry -->
+    <!-- * with the same URL, this gets the contents of the _first -->
+    <!-- * instance_ of the link in this Refentry with that URL -->
+    <xsl:variable name="link.contents">
+      <xsl:apply-templates/>
+    </xsl:variable>
+    <xsl:value-of select="normalize-space($link.contents)"/>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:text>.br&#10;</xsl:text>
+    <!-- * Print the link's URL -->
+    <xsl:value-of select="@url"/>
+    <xsl:text>&#10;</xsl:text>
+  </xsl:for-each>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 5339f513d..10202a659 100644
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -5,7 +5,8 @@
 <!ENTITY man.output.encoding SYSTEM "../params/man.output.encoding.xml">
 <!ENTITY man.links.are.numbered SYSTEM "../params/man.links.are.numbered.xml">
 <!ENTITY man.links.are.underlined SYSTEM "../params/man.links.are.underlined.xml">
-<!ENTITY man.links.section.heading SYSTEM "../params/man.links.section.heading.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 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 c25ebfdb3..cd838af1a 100644
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -29,20 +29,17 @@
   </preface>
 
   <reference id="general">
-  <title>General</title>
+  <title>General formatting</title>
 &man.break.after.slash;
 &man.hyphenate;
 &man.justify;
-&man.output.quietly;
-&man.output.encoding;
-&man.subheading.divider.enabled;
-&man.subheading.divider;
   </reference>
   <reference id="links">
   <title>Link handling</title>
 &man.links.are.numbered;
 &man.links.are.underlined;
-&man.links.section.heading;
+&man.links.list.enabled;
+&man.links.list.heading;
   </reference>
   <reference id="charmap">
   <title>Character/string substitution</title>
@@ -75,6 +72,13 @@
 &man.th.title.max.length;
 &man.th.extra2.max.length;
 &man.th.extra3.max.length;
+  </reference>
+  <reference id="other">
+  <title>Other</title>
+&man.output.quietly;
+&man.output.encoding;
+&man.subheading.divider.enabled;
+&man.subheading.divider;
   </reference>
   <appendix id="stylesheet">
     <title>The Stylesheet</title>
@@ -107,7 +111,8 @@
 <src:fragref linkend="man.string.subst.map.frag"/>
 <src:fragref linkend="man.links.are.numbered.frag"/>
 <src:fragref linkend="man.links.are.underlined.frag"/>
-<src:fragref linkend="man.links.section.heading.frag"/>
+<src:fragref linkend="man.links.list.enabled.frag"/>
+<src:fragref linkend="man.links.list.heading.frag"/>
 <src:fragref linkend="man.charmap.enabled.frag"/>
 <src:fragref linkend="man.charmap.uri.frag"/>
 <src:fragref linkend="man.charmap.use.subset.frag"/>