From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Mon, 11 Jul 2005 10:03:48 +0000 (+0000)
Subject: Updated doc for link-related params.
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=cb4e3ceae6381b57c413b3ee12270598417a5c8a;p=docbook-dsssl

Updated doc for link-related params.
Renamed man.links.section.heading to man.links.list.heading.
---

diff --git a/xsl/params/man.links.are.numbered.xml b/xsl/params/man.links.are.numbered.xml
index 0e71119a5..dc6faa92e 100644
--- a/xsl/params/man.links.are.numbered.xml
+++ b/xsl/params/man.links.are.numbered.xml
@@ -31,20 +31,27 @@ an <quote>empty link</quote> is on that looks like this:<literallayout class="mo
     rendered contents of the link</para>
   </listitem>
   <listitem>
-    <para>the URL for the link is included in a numbered list of URLs
+    <para>the URL for the link is included in a numbered list of links
     that is generated at the end of each man page; the number for each
-    URL corresponds to the inline number for the link with which it is
+    links corresponds to the inline number for the link with which it is
     associated</para>
   </listitem>
 </itemizedlist>
 The default heading for the list of links is
-<literal>LINKS</literal>. To output a different heading, set a value
+<literal>REFERENCES</literal>. To output a different heading, set a value
 for the <parameter>man.links.section.heading</parameter>
 parameter.</para>
 
+<note>
+  <para>The link list is also displayed (but without numbers) if the
+  value of <parameter>man.links.list.enabled</parameter> is
+  non-zero.</para>
+</note>
+
+
 <para>If the value of <parameter>man.links.are.numbered</parameter> is
-zero, URLs for links are suppressed; only the link contents are
-displayed.
+zero, numbering of links is suppressed; only the link contents are
+displayed inline.
 <important>
   <para>If you are thinking about disabling link numbering by setting
   the value of <parameter>man.links.are.numbered</parameter> to zero,
@@ -65,8 +72,10 @@ displayed.
   as ugly, and definitely more obstrusive, then having short
   square-bracketed numbers displayed inline.</para></footnote>,
    
-  but in a text-only output format, the numbered-links mechanism is
-  the only practical way of associating URLs with links.</para>
+  but in a text-only output format, the numbered-links/link-listing
+  mechanism is the only practical way of associating inline text with
+  URLs.</para>
+
   <para>Also, users of <quote>text based</quote> browsers such as
   <command>lynx</command> will already be accustomed to seeing inline
   numbers for links. And various "man to html" applications, such as
diff --git a/xsl/params/man.links.are.underlined.xml b/xsl/params/man.links.are.underlined.xml
index 9d1907c45..1314aaadc 100644
--- a/xsl/params/man.links.are.underlined.xml
+++ b/xsl/params/man.links.are.underlined.xml
@@ -28,27 +28,27 @@ is zero, links are displayed without any underlining.</para>
   <tag>ulink</tag>s.</para>
 </note>
 
-<para>If you set <parameter>man.links.are.numbered</parameter> to zero
-(disabled), then you should probably also set
+<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
 <quote>clickable</quote>, given that links rendered in man pages are
 not <quote>real</quote> 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 URLs for links (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
-  <quote>context</quote> information about exactly what part of the
-  text is being <quote>annotated</quote> by the link. Depending on how
-  you use mark up your content, that context information may or may
-  not have value.</para></footnote>.</para>
+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
+<quote>context</quote> information about exactly what part of the text
+is being <quote>annotated</quote> by the link. Depending on how you
+use mark up your content, that context information may or may not have
+value.</para></footnote>.</para>
 </refsect1>
 </refentry>
diff --git a/xsl/params/man.links.list.heading.xml b/xsl/params/man.links.list.heading.xml
new file mode 100644
index 000000000..1b3e45239
--- /dev/null
+++ b/xsl/params/man.links.list.heading.xml
@@ -0,0 +1,30 @@
+<refentry id="man.links.list.heading">
+<refmeta>
+<refentrytitle>man.links.list.heading</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.links.list.heading</refname>
+<refpurpose>Specifies an alternate name for links list</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.links.list.heading.frag'>
+<xsl:param name="man.links.list.heading" select="''"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of the
+<parameter>man.links.are.numbered</parameter> parameter and/or the
+<parameter>man.links.list.enabled</parameter> parameter is non-zero
+(the defaults for both are non-zero), a numbered list of URLs is
+generated near the end of each man page. The default section heading
+for the list of links is the equivalent of the English word
+<literal>REFERENCES</literal> in the current locale. To cause an
+alternate heading to be displayed, set a non-empty value for the
+<parameter>man.links.list.heading</parameter> parameter -- for
+example, <literal>LINKS</literal>.</para>
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.links.section.heading.xml b/xsl/params/man.links.section.heading.xml
deleted file mode 100644
index efb5c5211..000000000
--- a/xsl/params/man.links.section.heading.xml
+++ /dev/null
@@ -1,29 +0,0 @@
-<refentry id="man.links.section.heading">
-<refmeta>
-<refentrytitle>man.links.section.heading</refentrytitle>
-<refmiscinfo role="type">string</refmiscinfo>
-</refmeta>
-<refnamediv>
-<refname>man.links.section.heading</refname>
-<refpurpose>Specifies an alternate name for LINKS section</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<src:fragment id='man.links.section.heading.frag'>
-<xsl:param name="man.links.section.heading" select="''"/>
-</src:fragment>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-
-<para>If the value of the
-<parameter>man.links.are.numbered</parameter> parameter is non-zero
-(the default), a numbered list of URLs is generated at the end of each
-man page. The default heading for the section containing the list of
-links is the equivalent of the English word <literal>LINKS</literal>
-in the current locale. To cause an alternate heading to be displayed,
-set a non-empty value for the
-<parameter>man.links.section.heading</parameter>, for example,
-<literal>REFERENCES</literal>.</para>
-</refsect1>
-</refentry>