| OLD | NEW |
|---|
| (Empty) |
| 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/sn
apshot/xsl/doc/manpages/">manpages</ulink></literallayout> | |
| 28 an “empty” notesource is on that looks like this:<literallayout class="monospace
d"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/></lite
rallayout> | |
| 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 t
hat 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> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1394993002:
Doing some cleanup. (Closed)
Base URL: https://github.com/dart-lang/www.dartlang.org.git@master