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