stylesheets/styleguide/docbook-xsl-1.75.2/params/man.endnotes.are.numbered.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.are.numbered">\r
   7 <refmeta>\r
   8 <refentrytitle>man.endnotes.are.numbered</refentrytitle>\r
   9 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>\r
  10 </refmeta>\r
  11 <refnamediv>\r
  12 <refname>man.endnotes.are.numbered</refname>\r
  13 <refpurpose>Number endnotes?</refpurpose>\r
  14 </refnamediv>\r
  15 \r
  16 <refsynopsisdiv>\r
  17 <src:fragment xml:id="man.endnotes.are.numbered.frag">\r
  18 <xsl:param name="man.endnotes.are.numbered">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.are.numbered</parameter> is\r
  25 non-zero (the default), then for each non-empty<footnote>\r
  26 <para>A “non-empty” notesource is one that looks like\r
  27 this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>\r
  28 an “empty” notesource is on that looks like this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/&gt;</literallayout>\r
  29 </para></footnote> “notesource”:\r
  30 \r
  31 <itemizedlist>\r
  32   <listitem>\r
  33     <para>a number (in square brackets) is displayed inline after the\r
  34     rendered inline contents (if any) of the notesource</para>\r
  35   </listitem>\r
  36   <listitem>\r
  37     <para>the contents of the notesource are included in a\r
  38       numbered list of endnotes that is generated at the end of\r
  39       each man page; the number for each endnote corresponds to\r
  40       the inline number for the notesource with which it is\r
  41       associated</para>\r
  42   </listitem>\r
  43 </itemizedlist>\r
  44 The default heading for the list of endnotes is\r
  45 <literal>NOTES</literal>. To output a different heading, set a value\r
  46 for the <parameter>man.endnotes.section.heading</parameter>\r
  47 parameter.</para>\r
  48 \r
  49 <note>\r
  50   <para>The endnotes list is also displayed (but without\r
  51     numbers) if the value of\r
  52     <parameter>man.endnotes.list.enabled</parameter> is\r
  53     non-zero.</para>\r
  54 </note>\r
  55 \r
  56 \r
  57 <para>If the value of <parameter>man.endnotes.are.numbered</parameter> is\r
  58 zero, numbering of endnotess is suppressed; only inline\r
  59 contents (if any) of the notesource are displayed inline.\r
  60 <important>\r
  61   <para>If you are thinking about disabling endnote numbering by setting\r
  62   the value of <parameter>man.endnotes.are.numbered</parameter> to zero,\r
  63   before you do so, first take some time to carefully\r
  64   consider the information needs and experiences of your users. The\r
  65   square-bracketed numbers displayed inline after notesources may seem\r
  66   obstrusive and aesthetically unpleasing<footnote><para>As far as notesources that are links, ytou might\r
  67   think it would be better to just display URLs for non-empty\r
  68   links inline, after their content, rather than displaying\r
  69   square-bracketed numbers all over the place. But it's not better. In\r
  70   fact, it's not even practical, because many (most) URLs for links\r
  71   are too long to be displayed inline. They end up overflowing the\r
  72   right margin. You can set a non-zero value for\r
  73   <parameter>man.break.after.slash</parameter> parameter to deal with\r
  74   that, but it could be argued that what you end up with is at least\r
  75   as ugly, and definitely more obstrusive, then having short\r
  76   square-bracketed numbers displayed inline.</para></footnote>,\r
  77 \r
  78   but in a text-only output format, the\r
  79   numbered-notesources/endnotes-listing mechanism is the only\r
  80   practical way to handle this kind of content.</para>\r
  81 \r
  82   <para>Also, users of “text based” browsers such as\r
  83   <command>lynx</command> will already be accustomed to seeing inline\r
  84   numbers for links. And various "man to html" applications, such as\r
  85   the widely used <command><link xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)\r
  86   application, can automatically turn URLs into "real" HTML hyperlinks\r
  87   in output. So leaving <parameter>man.endnotes.are.numbered</parameter>\r
  88   at its default (non-zero) value ensures that no information is\r
  89   lost in your man-page output. It just gets\r
  90   “rearranged”.</para>\r
  91 </important>\r
  92 </para>\r
  93 <para>The handling of empty links is not affected by this\r
  94 parameter. Empty links are handled simply by displaying their URLs\r
  95 inline. Empty links are never auto-numbered.</para>\r
  96 \r
  97 <para>If you disable endnotes numbering, you should probably also set\r
  98 <parameter>man.font.links</parameter> to an empty value (to\r
  99 disable font formatting for links.</para>\r
 100 </refsection>\r
 101 \r
 102 <refsection><info><title>Related Parameters</title></info>\r
 103   <para><parameter>man.endnotes.list.enabled</parameter>,\r
 104     <parameter>man.font.links</parameter></para>\r
 105 </refsection>\r
 106 </refentry>\r