man.links.list.enabled
Prev Link handling Next

Name

man.links.list.enabled — Display list of links at end of man page?

Synopsis

<xsl:param name="man.links.list.enabled">1</xsl:param>

Description

If the value of man.links.list.enabled is non-zero (the default), then a list of links is added to the end of the output man page.

If the value of man.links.list.enabled is zero, the list is suppressed -- unless link numbering is enabled (that is, if man.links.are.numbered is non-zero), in which case, that setting overrides the man.links.list.enabled 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.

[Note]

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.list.enabled at its default (non-zero) value ensures that no link URLs are lost in your man-page output. They just get “rearranged”. So if you are thinking about disabling link listing by setting the value of man.links.list.enabled 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 “real” (clickable) hyperlinks.

To “turn off” numbering of links in the list, set man.links.are.numbered to zero. The list will still be displayed; it will just be displayed without the numbers[4]

The default heading for the section in which the list appears is REFERENCES. To change that, set a non-empty value for the man.links.list.heading parameter.

Along with the URL for each link, the link list includes the contents of the link. The list thus includes only non-empty[5] links. Empty links are never included, and never numbered. They are simply displayed inline, without any numbering.

In addition, if there are multiple instances of links in a refentry 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.

[Note]

Currently, this parameter only affects output for ulinks.

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


[4] It can still “make sense” 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 “list of references” 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.

[5] 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/"/>

Prev Up Next
man.links.are.underlined Home man.links.list.heading