olink.docbook-xsl.params.man.endnotes.are.numbered.xml Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of olink-maven-plugin Show documentation
There is a newer version: 1.2.6


man.endnotes.are.numbered
boolean


man.endnotes.are.numbered
Number endnotes?




1



Description

If the value of man.endnotes.are.numbered is
non-zero (the default), then for each non-empty
A “non-empty” notesource is one that looks like
this:  <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink>
an “empty” notesource is on that looks like this:  <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/>
 “notesource”:


  
    a number (in square brackets) is displayed inline after the
    rendered inline contents (if any) of the notesource
  
  
    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
  

The default heading for the list of endnotes is
NOTES. To output a different heading, set a value
for the man.endnotes.section.heading
parameter.


  The endnotes list is also displayed (but without
    numbers) if the value of
    man.endnotes.list.enabled is
    non-zero.



If the value of man.endnotes.are.numbered is
zero, numbering of endnotess is suppressed; only inline
contents (if any) of the notesource are displayed inline.

  If you are thinking about disabling endnote numbering by setting
  the value of man.endnotes.are.numbered 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 unpleasingAs 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
  man.break.after.slash 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.,

  but in a text-only output format, the
  numbered-notesources/endnotes-listing mechanism is the only
  practical way to handle this kind of content.

  Also, users of “text based” browsers such as
  lynx will already be accustomed to seeing inline
  numbers for links. And various "man to html" applications, such as
  the widely used man2html (VH-Man2html)
  application, can automatically turn URLs into "real" HTML hyperlinks
  in output. So leaving man.endnotes.are.numbered
  at its default (non-zero) value ensures that no information is
  lost in your man-page output. It just gets
  “rearranged”.


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.

If you disable endnotes numbering, you should probably also set
man.font.links to an empty value (to
disable font formatting for links.


Related Parameters
  man.endnotes.list.enabled,
    man.font.links