From 5ea24dcbf83ee4234b1ee6055222ff3ca8304823 Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Mon, 11 Jul 2005 10:04:34 +0000
Subject: [PATCH] Added man.links.list.enabled

---
 xsl/params/man.links.list.enabled.xml | 93 +++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 xsl/params/man.links.list.enabled.xml

diff --git a/xsl/params/man.links.list.enabled.xml b/xsl/params/man.links.list.enabled.xml
new file mode 100644
index 000000000..23a37bd92
--- /dev/null
+++ b/xsl/params/man.links.list.enabled.xml
@@ -0,0 +1,93 @@
+<refentry id="man.links.list.enabled">
+<refmeta>
+<refentrytitle>man.links.list.enabled</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.links.list.enabled</refname>
+<refpurpose>Display list of links at end of man page?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.links.list.enabled.frag'>
+<xsl:param name="man.links.list.enabled">1</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of <parameter>man.links.list.enabled</parameter> is
+non-zero (the default), then a list of links is added to the end of
+the output man page.</para>
+
+<para>If the value of <parameter>man.links.list.enabled</parameter> is
+zero, the list is suppressed -- unless link numbering is enabled (that
+is, if <parameter>man.links.are.numbered</parameter> is non-zero), in
+which case, that setting overrides the
+<parameter>man.links.list.enabled</parameter> setting, and the link
+list is still displayed. The reason is that link numbering only makes
+sense if a (numbered) list of links is also generated.</para>
+
+<note>
+  <para>Various <quote>man to html</quote> applications, such as the
+  widely used <command><ulink
+  url="http://users.actrix.gen.nz/michael/vhman2html.html"
+  >man2html</ulink></command> (<literal>VH-Man2html</literal>)
+  application, can automatically turn URLs into <quote>real</quote>
+  HTML hyperlinks in output. So leaving
+  <parameter>man.links.list.enabled</parameter> at its default
+  (non-zero) value ensures that no link URLs are lost in your man-page
+  output. They just get <quote>rearranged</quote>. So if you are
+  thinking about disabling link listing by setting the value of
+  <parameter>man.links.list.enabled</parameter> to zero, before you do
+  so, first take some time to carefully consider the information needs
+  and experiences of your users. The URLs are useful information even
+  if they aren't <quote>real</quote> (clickable) hyperlinks.</para>
+</note>
+
+<para>To <quote>turn off</quote> numbering of links in the list, set
+<parameter>man.links.are.numbered</parameter> to zero. The list will
+still be displayed; it will just be displayed without the
+numbers<footnote ><para>It can still <quote>make sense</quote> to have
+the list of links displayed even if you have link numbering turned
+off. In that case, your list of links basically becomes a <quote>list
+of references</quote> without any association with specific text in
+your document. This is probably the best option if you find the inline
+link numbering obtrusive. Your users will still have access to the
+URLs and link contents, without being annoyed by the presence of
+inline link numbering.</para></footnote>
+</para>
+
+<para>The default heading for the section in which the list appears is
+<literal>REFERENCES</literal>. To change that, set a non-empty value
+for the <parameter>man.links.list.heading</parameter>
+parameter.</para>
+
+<para>Along with the URL for each link, the link list includes the contents
+of the link. The list thus includes only non-empty<footnote
+ >
+
+<para>A <quote>non-empty</quote> link is one that looks like
+this:<literallayout class="monospaced" >  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages&lt;/ulink></literallayout>
+an <quote>empty link</quote> is on that looks like this:<literallayout
+class="monospaced" >  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/></literallayout>
+</para></footnote> links.
+
+Empty links are never included, and never numbered. They are simply
+displayed inline, without any numbering.</para>
+
+<para>In addition, if there are multiple instances of links in a
+<tag>refentry</tag> that have the same URL, the URL is listed only
+once. The contents listed for that link are the contents of the first
+link which has that URL.</para>
+
+<note>
+  <para>Currently, this parameter only affects output for
+  <tag>ulink</tag>s.</para>
+</note>
+
+<para>If you disable link listing, you should probably also set
+<parameter>man.links.are.underlined</parameter> to zero (to disable
+link underlining).</para>
+</refsect1>
+</refentry>
-- 
2.40.0