<refentry xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          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>
