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"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink></literallayout>
|
---|
28 | an “empty” notesource is on that looks like this:<literallayout class="monospaced"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/></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>
|
---|