<refentry xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          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 links
    that is generated at the end of each man page; the number for each
    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>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, 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,
  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/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
  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>
