From e9164a19caf466657b8b654e294a716a2586d3c4 Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Sat, 8 Mar 2008 17:50:28 +0000
Subject: [PATCH] Added new param man.base.url.for.relative.links .. specifies
 a base URL for relative links (for ulink, @xlink:href, imagedata, audiodata,
 videodata) shown in the generated NOTES section of man-page output. The value
 of man.base.url.for.relative.links is prepended to any relative URI that is a
 value of ulink url, xlink:href, or fileref attribute.

If you use relative URIs in link sources in your DocBook refentry
source, and you leave man.base.url.for.relative.links unset, the
relative links will appear "as is" in the NOTES section of any
man-page output generated from your source. That's probably not
what you want, because such relative links are only usable in the
context of HTML output. So, to make the links meaningful and
usable in the context of man-page output, set a value for
man.base.url.for.relative.links that points
to the online version of HTML output generated from your DocBook
refentry source. For example:

  <xsl:param name="man.base.url.for.relative.links"
  >http://www.kernel.org/pub/software/scm/git/docs/</xsl:param>
---
 xsl/manpages/endnotes.xsl                     | 38 ++++++++--
 xsl/manpages/param.ent                        |  1 +
 xsl/manpages/param.xweb                       |  2 +
 .../man.base.url.for.relative.links.xml       | 76 +++++++++++++++++++
 4 files changed, 109 insertions(+), 8 deletions(-)
 create mode 100644 xsl/params/man.base.url.for.relative.links.xml

diff --git a/xsl/manpages/endnotes.xsl b/xsl/manpages/endnotes.xsl
index 1b81be54e..c78f95885 100644
--- a/xsl/manpages/endnotes.xsl
+++ b/xsl/manpages/endnotes.xsl
@@ -42,8 +42,8 @@
 <!-- *    Notesources with the same earmark are assigned the same -->
 <!-- *    number. -->
 <!-- * -->
-<!-- *    By design, that index excludes any element whose whose string -->
-<!-- *    value is identical to value of its url xlink:href attribute). -->
+<!-- *    By design, that index excludes any element whose string value -->
+<!-- *    is identical to the value of its url xlink:href attribute). -->
 <!-- * -->
 <!-- * 2. Puts a numbered marker inline to mark the place where the -->
 <!-- *    notesource occurs in the main text flow. -->
@@ -68,8 +68,8 @@
 <!-- * earmarks is that we need to get and check the sets of -->
 <!-- * earmarks for uniqueness per-Refentry (not per-document). -->
 <!-- * -->
-<!-- * FIXME: as -->
-<!-- * with "repeat" URLS, alt instances that have the same string value -->
+<!-- * FIXME: -->
+<!-- * as with "repeat" URLS, alt instances that have the same string value -->
 <!-- * as preceding ones (likely to occur for repeat acroynyms and -->
 <!-- * abbreviations) should be listed only once in the endnotes list, -->
 <!-- * and numbered accordingly inline; split man.indent.width into -->
@@ -481,13 +481,15 @@
       </xsl:when>
       <xsl:otherwise>
         <!-- * otherwise, this earmark has empty content, -->
-        <!-- * which means its corresponding notesources is an -->
+        <!-- * which means its corresponding notesource is an -->
         <!-- * imagedata, audiodata, or videodata instance; in -->
-        <!-- * that case, we use the value of the notesoures's -->
+        <!-- * that case, we use the value of the notesource's -->
         <!-- * @fileref attribute (which is stored in the -->
         <!-- * earmark uri attribute) as the "contents" for -->
         <!-- * this endnote/notesource -->
-        <xsl:value-of select="@uri"/>
+        <xsl:call-template name="display.uri">
+          <xsl:with-param name="uri" select="@uri"/>
+        </xsl:call-template>
       </xsl:otherwise>
     </xsl:choose>
     <xsl:text>&#10;</xsl:text>
@@ -520,7 +522,9 @@
         <xsl:call-template name="suppress.hyphenation"/>
         <xsl:text>\%</xsl:text>
       </xsl:if>
-      <xsl:value-of select="@uri"/>
+      <xsl:call-template name="display.uri">
+        <xsl:with-param name="uri" select="@uri"/>
+      </xsl:call-template>
       <xsl:text>&#10;</xsl:text>
       <xsl:text>.RE</xsl:text>
       <xsl:text>&#10;</xsl:text>
@@ -529,4 +533,22 @@
   </xsl:for-each>
 </xsl:template>
 
+<xsl:template name="display.uri">
+  <xsl:param name="uri"/>
+  <xsl:choose>
+    <xsl:when test="contains($uri, ':')">
+      <!-- * if this URI contains a colon character, it’s probably -->
+      <!-- * an absolute URI with a scheme, so we output it as-is -->
+      <xsl:value-of select="$uri"/>
+    </xsl:when>
+    <xsl:otherwise>
+      <!-- * otherwise this is probably not an absolute URI, so we -->
+      <!-- * need to prepend $man.base.url.for.relative.links to -->
+      <!-- * give the URI some "context" in man-page output -->
+      <xsl:value-of
+        select="concat($man.base.url.for.relative.links, $uri)"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 87f5a442b..034b3ca2d 100644
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -1,5 +1,6 @@
 <!ENTITY man.authors.section.enabled SYSTEM "../params/man.authors.section.enabled.xml">
 <!ENTITY man.break.after.slash SYSTEM "../params/man.break.after.slash.xml">
+<!ENTITY man.base.url.for.relative.links SYSTEM "../params/man.base.url.for.relative.links.xml">
 <!ENTITY man.charmap.enabled SYSTEM "../params/man.charmap.enabled.xml">
 <!ENTITY man.charmap.subset.profile SYSTEM "../params/man.charmap.subset.profile.xml">
 <!ENTITY man.charmap.subset.profile.english SYSTEM "../params/man.charmap.subset.profile.english.xml">
diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index d297664a7..b2b8f51fe 100644
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -68,6 +68,7 @@
 &man.endnotes.list.enabled;
 &man.endnotes.list.heading;
 &man.endnotes.are.numbered;
+&man.base.url.for.relative.links;
 &man.links.are.underlined;
   </reference>
   <reference xml:id="lists">
@@ -152,6 +153,7 @@
 
 <src:fragref linkend="man.authors.section.enabled.frag"/>
 <src:fragref linkend="man.break.after.slash.frag"/>
+<src:fragref linkend="man.base.url.for.relative.links.frag"/>
 <src:fragref linkend="man.charmap.enabled.frag"/>
 <src:fragref linkend="man.charmap.subset.profile.frag"/>
 <src:fragref linkend="man.charmap.subset.profile.english.frag"/>
diff --git a/xsl/params/man.base.url.for.relative.links.xml b/xsl/params/man.base.url.for.relative.links.xml
new file mode 100644
index 000000000..a802ec80a
--- /dev/null
+++ b/xsl/params/man.base.url.for.relative.links.xml
@@ -0,0 +1,76 @@
+<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.base.url.for.relative.links">
+  <refmeta>
+    <refentrytitle>man.base.url.for.relative.links</refentrytitle>
+    <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>man.base.url.for.relative.links</refname>
+    <refpurpose>Specifies a base URL for relative links</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <src:fragment xml:id="man.base.url.for.relative.links.frag"><xsl:param name="man.base.url.for.relative.links">[set $man.base.url.for.relative.links]/</xsl:param></src:fragment>
+  </refsynopsisdiv>
+
+  <refsection><info><title>Description</title></info>
+
+    <para>For any “notesource” listed in the auto-generated
+      “NOTES” section of output man pages (which is generated when
+      the value of the
+      <parameter>man.endnotes.list.enabled</parameter> parameter
+      is non-zero), if the notesource is a link source with a
+      relative URI, the URI is displayed in output with the value
+      of the
+      <parameter>man.base.url.for.relative.links</parameter>
+      parameter prepended to the value of the link URI.</para>
+
+    <note>
+      <para>A link source is an notesource that references an
+        external resource:
+        <itemizedlist>
+          <listitem>
+            <para>a <tag>ulink</tag> element with a <tag
+                class="attribute">url</tag> attribute</para>
+          </listitem>
+          <listitem>
+            <para>any element with an <tag
+                class="attribute">xlink:href</tag> attribute</para>
+          </listitem>
+          <listitem>
+            <para>an <tag>imagedata</tag>, <tag>audiodata</tag>, or
+              <tag>videodata</tag> element</para>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </note>
+
+    <para>If you use relative URIs in link sources in your DocBook
+      <tag>refentry</tag> source, and you leave
+      <parameter>man.base.url.for.relative.links</parameter>
+      unset, the relative links will appear “as is” in the “Notes”
+      section of any man-page output generated from your source.
+      That’s probably not what you want, because such relative
+      links are only usable in the context of HTML output. So, to
+      make the links meaningful and usable in the context of
+      man-page output, set a value for
+      <parameter>man.base.url.for.relative.links</parameter> that
+      points to the online version of HTML output generated from
+      your DocBook <tag>refentry</tag> source. For
+      example:
+      <programlisting
+        >&lt;xsl:param name="man.base.url.for.relative.links"
+        >http://www.kernel.org/pub/software/scm/git/docs/&lt;/xsl:param></programlisting>
+    </para>
+
+  </refsection>
+
+  <refsection><info><title>Related Parameters</title></info>
+    <para><parameter>man.endnotes.list.enabled</parameter></para>
+  </refsection>
+
+</refentry>
-- 
2.40.0