stylesheets/evergreen_docbook_files/docbook-xsl-1.75.2/params/man.endnotes.list.enabled.xml

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