man.links.are.numbered

man.links.are.numbered
Prev	Link handling	Next

Name

man.links.are.numbered — Number links?

Synopsis

<xsl:param name="man.links.are.numbered">1</xsl:param>

Description

If the value of man.links.are.numbered is non-zero (the default), then for each non-empty^[1] link:

a number (in square brackets) is displayed inline before the rendered contents of the link
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

The default heading for the list of links is REFERENCES. To output a different heading, set a value for the man.links.section.heading parameter.


	The link list is also displayed (but without numbers) if the value of `man.links.list.enabled` is non-zero.

If the value of man.links.are.numbered is zero, numbering of links is suppressed; only the link contents are displayed inline.

If you are thinking about disabling link numbering by setting the value of man.links.are.numbered 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^[2], but in a text-only output format, the numbered-links/link-listing mechanism is the only practical way of associating inline text with URLs.

Also, users of “text based” browsers such as lynx will already be accustomed to seeing inline numbers for links. And various "man to html" applications, such as the widely used man2html (VH-Man2html) application, can automatically turn URLs into "real" HTML hyperlinks in output. So leaving man.links.are.numbered at its default (non-zero) value ensures that no link information is lost in your man-page output. It just gets “rearranged”.

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.


	Currently, this parameter only affects output for `ulink`s.

If you disable link numbering, you should probably also set man.links.are.underlined to zero (to disable link underlining).

^[1]A “non-empty” link is one that looks like this:

  <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink>

an “empty link” is on that looks like this:

  <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/>

^[2]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 man.break.after.slash 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.