doc/xslt/params/man.endnotes.list.enabled.xml

   1 <refentry xmlns="http://docbook.org/ns/docbook"
   2           xmlns:xlink="http://www.w3.org/1999/xlink"
   3           xmlns:xi="http://www.w3.org/2001/XInclude"
   4           xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
   5           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   6           version="5.0" xml:id="man.endnotes.list.enabled">
   7 <refmeta>
   8 <refentrytitle>man.endnotes.list.enabled</refentrytitle>
   9 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>man.endnotes.list.enabled</refname>
  13 <refpurpose>Display endnotes list at end of man page?</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17 <src:fragment xml:id="man.endnotes.list.enabled.frag">
  18 <xsl:param name="man.endnotes.list.enabled">1</xsl:param>
  19 </src:fragment>
  20 </refsynopsisdiv>
  21
  22 <refsection><info><title>Description</title></info>
  23
  24 <para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
  25 non-zero (the default), then an endnotes list is added to the end of
  26 the output man page.</para>
  27
  28 <para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
  29 zero, the list is suppressed — unless link numbering is enabled (that
  30 is, if <parameter>man.endnotes.are.numbered</parameter> is non-zero), in
  31 which case, that setting overrides the
  32 <parameter>man.endnotes.list.enabled</parameter> setting, and the
  33 endnotes list is still displayed. The reason is that inline
  34 numbering of notesources associated with endnotes only makes sense
  35 if a (numbered) list of endnotes is also generated.</para>
  36
  37 <note>
  38   <para>Leaving
  39   <parameter>man.endnotes.list.enabled</parameter> at its default
  40   (non-zero) value ensures that no “out of line” information (such
  41   as the URLs for hyperlinks and images) gets lost in your
  42   man-page output. It just gets “rearranged”.</para>
  43   <para>So if you’re thinking about disabling endnotes listing by
  44     setting the value of
  45     <parameter>man.endnotes.list.enabled</parameter> to zero:
  46     Before you do so, first take some time to carefully consider
  47     the information needs and experiences of your users. The “out
  48     of line” information has value even if the presentation of it
  49     in text output is not as interactive as it may be in other
  50     output formats.</para>
  51   <para>As far as the specific case of URLs: Even though the URLs
  52     displayed in text output may not be “real” (clickable)
  53     hyperlinks, many X terminals have convenience features for
  54     recognizing URLs and can, for example, present users with
  55     an options to open a URL in a browser with the user clicks on
  56     the URL is a terminal window. And short of those, users with X
  57     terminals can always manually cut and paste the URLs into a web
  58     browser.</para>
  59   <para>Also, note that various “man to html” tools, such as the
  60     widely used <command><link xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)
  61     application, automatically mark up URLs with <literal>a@href</literal> markup
  62   during conversion — resulting in “real” hyperlinks in HTML
  63   output from those tools.</para>
  64 </note>
  65
  66 <para>To “turn off” numbering of endnotes in the
  67 endnotes list, set <parameter>man.endnotes.are.numbered</parameter>
  68 to zero. The endnotes list will
  69 still be displayed; it will just be displayed without the
  70 numbers<footnote><para>It can still make sense to have
  71 the list of endnotes displayed even if you have endnotes numbering turned
  72 off. In that case, your endnotes list basically becomes a “list
  73 of references” without any association with specific text in
  74 your document. This is probably the best option if you find the inline
  75 endnotes numbering obtrusive. Your users will still have access to all the “out of line”
  76 such as URLs for hyperlinks.</para></footnote>
  77 </para>
  78
  79 <para>The default heading for the endnotes list is
  80 <literal>NOTES</literal>. To change that, set a non-empty
  81 value for the <parameter>man.endnotes.list.heading</parameter>
  82 parameter.</para>
  83
  84 <para>In the case of notesources that are links: Along with the
  85 URL for each link, the endnotes list includes the contents of the
  86 link. The list thus includes only non-empty<footnote>
  87
  88 <para>A “non-empty” link is one that looks like
  89 this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>
  90 an “empty link” is on that looks like this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/&gt;</literallayout>
  91 </para></footnote> links.
  92
  93 Empty links are never included, and never numbered. They are simply
  94 displayed inline, without any numbering.</para>
  95
  96 <para>In addition, if there are multiple instances of links in a
  97 <tag>refentry</tag> that have the same URL, the URL is listed only
  98 once. The contents listed for that link in the endnotes list are
  99 the contents of the first link which has that URL.</para>
 100
 101 <para>If you disable endnotes listing, you should probably also set
 102 <parameter>man.links.are.underlined</parameter> to zero (to disable
 103 link underlining).</para>
 104 </refsection>
 105 </refentry>