Added new params for controlling link handling.

diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 27b259ff97d1b2cb309b20176c11db38f600804c..5339f513d4fc251066ada85eca673a6fecb275d4 100644 (file)
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -3,6 +3,9 @@
 <!ENTITY man.justify SYSTEM "../params/man.justify.xml">
 <!ENTITY man.output.quietly SYSTEM "../params/man.output.quietly.xml">
 <!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.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 5fbca9217e0ed99303aa576e7dfded32d72fe4d6..c25ebfdb32850096fd093787caa930ec49e21c07 100644 (file)
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -35,16 +35,22 @@
 &man.justify;
 &man.output.quietly;
 &man.output.encoding;
-&man.string.subst.map;
 &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;
   </reference>
   <reference id="charmap">
-  <title>Character map</title>
+  <title>Character/string substitution</title>
 &man.charmap.enabled;
 &man.charmap.uri;
 &man.charmap.use.subset;
 &man.charmap.subset.profile;
+&man.string.subst.map;
   </reference>
   <reference id="refmeta">
   <title>Refentry metadata gathering</title>
@@ -99,6 +105,9 @@
 <src:fragref linkend="man.output.quietly.frag"/>
 <src:fragref linkend="man.output.encoding.frag"/>
 <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.charmap.enabled.frag"/>
 <src:fragref linkend="man.charmap.uri.frag"/>
 <src:fragref linkend="man.charmap.use.subset.frag"/>

diff --git a/xsl/params/man.links.are.numbered.xml b/xsl/params/man.links.are.numbered.xml
new file mode 100644 (file)
index 0000000..0e71119
--- /dev/null
+++ b/xsl/params/man.links.are.numbered.xml
@@ -0,0 +1,95 @@
+<refentry id="man.links.are.numbered">
+<refmeta>
+<refentrytitle>man.links.are.numbered</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.links.are.numbered</refname>
+<refpurpose>Number links?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.links.are.numbered.frag'>
+<xsl:param name="man.links.are.numbered">1</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of <parameter>man.links.are.numbered</parameter> is
+non-zero (the default), then for each 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> link:
+
+<itemizedlist>
+  <listitem>
+    <para>a number (in square brackets) is displayed inline before the
+    rendered contents of the link</para>
+  </listitem>
+  <listitem>
+    <para>the URL for the link is included in a numbered list of URLs
+    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
+    associated</para>
+  </listitem>
+</itemizedlist>
+The default heading for the list of links is
+<literal>LINKS</literal>. To output a different heading, set a value
+for the <parameter>man.links.section.heading</parameter>
+parameter.</para>
+
+<para>If the value of <parameter>man.links.are.numbered</parameter> is
+zero, URLs for links are suppressed; only the link contents are
+displayed.
+<important>
+  <para>If you are thinking about disabling link numbering by setting
+  the value of <parameter>man.links.are.numbered</parameter> to zero,
+  before you do so, first take some time to carefully
+  consider the information needs and experiences of your users. The
+  square-bracketed numbers displayed inline before links may seem
+  obstrusive and aesthetically unpleasing<footnote 
+  
+  ><para>You might
+  think that it would be better to just display URLs for non-empty
+  links inline, after their content, rather than displaying
+  square-bracketed numbers all over the place. But it's not better. In
+  fact, it's not even practical, because many (most) URLs for links
+  are too long to be displayed inline. They end up overflowing the
+  right margin. You can set a non-zero value for
+  <parameter>man.break.after.slash</parameter> parameter to deal with
+  that, but it could be argued that what you end up with is at least
+  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>
+  <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
+  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 "real" HTML hyperlinks
+  in output. So leaving <parameter>man.links.are.numbered</parameter>
+  at its default (non-zero) value ensures that no link information is
+  lost in your man-page output. It just gets
+  <quote>rearranged</quote>.</para>
+</important>
+</para>
+<para>The handling of empty links is not affected by this
+parameter. Empty links are handled simply by displaying their URLs
+inline. Empty links are never auto-numbered.</para>
+<note>
+  <para>Currently, this parameter only affects output for
+  <tag>ulink</tag>s.</para>
+</note>
+
+<para>If you disable link numbering, you should probably also set
+<parameter>man.links.are.underlined</parameter> to zero (to disable
+link underlining).</para>
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.links.are.underlined.xml b/xsl/params/man.links.are.underlined.xml
new file mode 100644 (file)
index 0000000..9d1907c
--- /dev/null
+++ b/xsl/params/man.links.are.underlined.xml
@@ -0,0 +1,54 @@
+<refentry id="man.links.are.underlined">
+<refmeta>
+<refentrytitle>man.links.are.underlined</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.links.are.underlined</refname>
+<refpurpose>Underline links?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.links.are.underlined.frag'>
+<xsl:param name="man.links.are.underlined">1</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<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> 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>
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.links.section.heading.xml b/xsl/params/man.links.section.heading.xml
new file mode 100644 (file)
index 0000000..efb5c52
--- /dev/null
+++ b/xsl/params/man.links.section.heading.xml
@@ -0,0 +1,29 @@
+<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>