107 lines
4.8 KiB
XML
107 lines
4.8 KiB
XML
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
|
|
xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
|
||
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
||
|
|
version="5.0" xml:id="man.endnotes.are.numbered">
|
||
|
|
<refmeta>
|
||
|
|
<refentrytitle>man.endnotes.are.numbered</refentrytitle>
|
||
|
|
<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
|
||
|
|
</refmeta>
|
||
|
|
<refnamediv>
|
||
|
|
<refname>man.endnotes.are.numbered</refname>
|
||
|
|
<refpurpose>Number endnotes?</refpurpose>
|
||
|
|
</refnamediv>
|
||
|
|
|
||
|
|
<refsynopsisdiv>
|
||
|
|
<src:fragment xml:id="man.endnotes.are.numbered.frag">
|
||
|
|
<xsl:param name="man.endnotes.are.numbered">1</xsl:param>
|
||
|
|
</src:fragment>
|
||
|
|
</refsynopsisdiv>
|
||
|
|
|
||
|
|
<refsection><info><title>Description</title></info>
|
||
|
|
|
||
|
|
<para>If the value of <parameter>man.endnotes.are.numbered</parameter> is
|
||
|
|
non-zero (the default), then for each non-empty<footnote>
|
||
|
|
<para>A “non-empty” notesource is one that looks like
|
||
|
|
this:<literallayout class="monospaced"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink></literallayout>
|
||
|
|
an “empty” notesource is on that looks like this:<literallayout class="monospaced"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/></literallayout>
|
||
|
|
</para></footnote> “notesource”:
|
||
|
|
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem>
|
||
|
|
<para>a number (in square brackets) is displayed inline after the
|
||
|
|
rendered inline contents (if any) of the notesource</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>the contents of the notesource are included in a
|
||
|
|
numbered list of endnotes that is generated at the end of
|
||
|
|
each man page; the number for each endnote corresponds to
|
||
|
|
the inline number for the notesource with which it is
|
||
|
|
associated</para>
|
||
|
|
</listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
The default heading for the list of endnotes is
|
||
|
|
<literal>NOTES</literal>. To output a different heading, set a value
|
||
|
|
for the <parameter>man.endnotes.section.heading</parameter>
|
||
|
|
parameter.</para>
|
||
|
|
|
||
|
|
<note>
|
||
|
|
<para>The endnotes list is also displayed (but without
|
||
|
|
numbers) if the value of
|
||
|
|
<parameter>man.endnotes.list.enabled</parameter> is
|
||
|
|
non-zero.</para>
|
||
|
|
</note>
|
||
|
|
|
||
|
|
|
||
|
|
<para>If the value of <parameter>man.endnotes.are.numbered</parameter> is
|
||
|
|
zero, numbering of endnotess is suppressed; only inline
|
||
|
|
contents (if any) of the notesource are displayed inline.
|
||
|
|
<important>
|
||
|
|
<para>If you are thinking about disabling endnote numbering by setting
|
||
|
|
the value of <parameter>man.endnotes.are.numbered</parameter> to zero,
|
||
|
|
before you do so, first take some time to carefully
|
||
|
|
consider the information needs and experiences of your users. The
|
||
|
|
square-bracketed numbers displayed inline after notesources may seem
|
||
|
|
obstrusive and aesthetically unpleasing<footnote><para>As far as notesources that are links, ytou might
|
||
|
|
think it would be better to just display URLs for non-empty
|
||
|
|
links inline, after their content, rather than displaying
|
||
|
|
square-bracketed numbers all over the place. But it's not better. In
|
||
|
|
fact, it's not even practical, because many (most) URLs for links
|
||
|
|
are too long to be displayed inline. They end up overflowing the
|
||
|
|
right margin. You can set a non-zero value for
|
||
|
|
<parameter>man.break.after.slash</parameter> parameter to deal with
|
||
|
|
that, but it could be argued that what you end up with is at least
|
||
|
|
as ugly, and definitely more obstrusive, then having short
|
||
|
|
square-bracketed numbers displayed inline.</para></footnote>,
|
||
|
|
|
||
|
|
but in a text-only output format, the
|
||
|
|
numbered-notesources/endnotes-listing mechanism is the only
|
||
|
|
practical way to handle this kind of content.</para>
|
||
|
|
|
||
|
|
<para>Also, users of “text based” browsers such as
|
||
|
|
<command>lynx</command> will already be accustomed to seeing inline
|
||
|
|
numbers for links. And various "man to html" applications, such as
|
||
|
|
the widely used <command><link xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)
|
||
|
|
application, can automatically turn URLs into "real" HTML hyperlinks
|
||
|
|
in output. So leaving <parameter>man.endnotes.are.numbered</parameter>
|
||
|
|
at its default (non-zero) value ensures that no information is
|
||
|
|
lost in your man-page output. It just gets
|
||
|
|
“rearranged”.</para>
|
||
|
|
</important>
|
||
|
|
</para>
|
||
|
|
<para>The handling of empty links is not affected by this
|
||
|
|
parameter. Empty links are handled simply by displaying their URLs
|
||
|
|
inline. Empty links are never auto-numbered.</para>
|
||
|
|
|
||
|
|
<para>If you disable endnotes numbering, you should probably also set
|
||
|
|
<parameter>man.font.links</parameter> to an empty value (to
|
||
|
|
disable font formatting for links.</para>
|
||
|
|
</refsection>
|
||
|
|
|
||
|
|
<refsection><info><title>Related Parameters</title></info>
|
||
|
|
<para><parameter>man.endnotes.list.enabled</parameter>,
|
||
|
|
<parameter>man.font.links</parameter></para>
|
||
|
|
</refsection>
|
||
|
|
</refentry>
|