git-scribe 0.0.3 → 0.0.4

data/docbook-xsl/params/man.charmap.uri.xml

@@ -0,0 +1,42 @@
+<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.charmap.uri">
+<refmeta>
+<refentrytitle>man.charmap.uri</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">uri</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.uri</refname>
+<refpurpose>URI for custom roff character map</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.charmap.uri.frag">
+<xsl:param name="man.charmap.uri"></xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>For converting certain Unicode symbols and special characters in
+UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
+equivalents in man-page output, the DocBook XSL Stylesheets
+distribution includes an <link xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
+map</link>. That character map can be considered the standard roff
+character map for the distribution.</para>
+
+<para>If the value of the <parameter>man.charmap.uri</parameter>
+parameter is non-empty, that value is used as the URI for the location
+for an alternate roff character map to use in place of the standard
+roff character map provided in the distribution.</para>
+
+<warning>
+<para>Do not set a value for <parameter>man.charmap.uri</parameter>
+unless you have a custom roff character map that differs from the
+standard one provided in the distribution.</para>
+</warning>
+</refsection>
+</refentry>

data/docbook-xsl/params/man.charmap.use.subset.xml

@@ -0,0 +1,80 @@
+<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.charmap.use.subset">
+<refmeta>
+<refentrytitle>man.charmap.use.subset</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.use.subset</refname>
+<refpurpose>Use subset of character map instead of full map?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.charmap.use.subset.frag">
+<xsl:param name="man.charmap.use.subset" select="1"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If the value of the
+<parameter>man.charmap.use.subset</parameter> parameter is non-zero,
+a subset of the roff character map is used instead of the full roff
+character map. The profile of the subset used is determined either
+by the value of the
+<parameter>man.charmap.subset.profile</parameter>
+parameter (if the source is not in English) or the
+<parameter>man.charmap.subset.profile.english</parameter>
+parameter (if the source is in English).</para>
+
+<note>
+  <para>You may want to experiment with setting a non-zero value of
+  <parameter>man.charmap.use.subset</parameter>, so that the full
+  character map is used. Depending on which XSLT engine you run,
+  setting a non-zero value for
+  <parameter>man.charmap.use.subset</parameter> may significantly
+  increase the time needed to process your documents. Or it may
+  not. For example, if you set it and run it with xsltproc, it seems
+  to dramatically increase processing time; on the other hand, if you
+  set it and run it with Saxon, it does not seem to increase
+  processing time nearly as much.</para>
+
+  <para>If processing time is not a important concern and/or you can
+  tolerate the increase in processing time imposed by using the full
+  character map, set <parameter>man.charmap.use.subset</parameter> to
+  zero.</para>
+</note>
+
+<refsection><info><title>Details</title></info>
+
+<para>For converting certain Unicode symbols and special characters in
+UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
+equivalents in man-page output, the DocBook XSL Stylesheets
+distribution includes a <link xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">roff character map</link> that is compliant with the <link xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
+map</link> format as detailed in the XSLT 2.0 specification. The map
+contains more than 800 character mappings and can be considered the
+standard roff character map for the distribution.</para>
+
+<note>
+<para>You can use the <parameter>man.charmap.uri</parameter>
+parameter to specify a URI for the location for an alternate roff
+character map to use in place of the standard roff character map
+provided in the distribution.</para>
+</note>
+
+<para>Because it is not terrifically efficient to use the standard
+800-character character map in full -- and for most (or all) users,
+never necessary to use it in full -- the DocBook XSL Stylesheets
+support a mechanism for using, within any given character map, a
+subset of character mappings instead of the full set. You can use the
+<parameter>man.charmap.subset.profile</parameter> or
+<parameter>man.charmap.subset.profile.english</parameter>
+parameter to tune the profile of that subset to use.</para>
+
+</refsection>
+</refsection>
+</refentry>

data/docbook-xsl/params/man.copyright.section.enabled.xml

@@ -0,0 +1,46 @@
+<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.copyright.section.enabled">
+<refmeta>
+<refentrytitle>man.copyright.section.enabled</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.copyright.section.enabled</refname>
+<refpurpose>Display auto-generated COPYRIGHT section?</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<src:fragment xml:id="man.copyright.section.enabled.frag">
+<xsl:param name="man.copyright.section.enabled">1</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+<refsection><info><title>Description</title></info>
+
+<para>If the value of
+<parameter>man.copyright.section.enabled</parameter> is non-zero
+(the default), then a <literal>COPYRIGHT</literal> section is
+generated near the end of each man page. The output of the
+<literal>COPYRIGHT</literal> section is assembled from any
+<tag>copyright</tag> and <tag>legalnotice</tag> metadata found in
+the contents of the child <tag>info</tag> or
+<tag>refentryinfo</tag> (if any) of the <tag>refentry</tag>
+itself, or from any <tag>copyright</tag> and
+<tag>legalnotice</tag> metadata that may appear in <tag>info</tag>
+contents of any ancestors of the <tag>refentry</tag>.</para>
+
+<para>If the value of
+<parameter>man.copyright.section.enabled</parameter> is zero, the
+the auto-generated <literal>COPYRIGHT</literal> section is
+suppressed.</para>
+
+<para>Set the value of
+  <parameter>man.copyright.section.enabled</parameter> to zero if
+  you want to have a manually created <literal>COPYRIGHT</literal>
+  section in your source, and you want it to appear in output
+  instead of the auto-generated <literal>COPYRIGHT</literal>
+  section.</para>
+</refsection>
+</refentry>

data/docbook-xsl/params/man.endnotes.are.numbered.xml

@@ -0,0 +1,106 @@
+<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">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>
+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>
+</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>

data/docbook-xsl/params/man.endnotes.list.enabled.xml

@@ -0,0 +1,105 @@
+<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.list.enabled">
+<refmeta>
+<refentrytitle>man.endnotes.list.enabled</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.endnotes.list.enabled</refname>
+<refpurpose>Display endnotes list at end of man page?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.endnotes.list.enabled.frag">
+<xsl:param name="man.endnotes.list.enabled">1</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
+non-zero (the default), then an endnotes list is added to the end of
+the output man page.</para>
+
+<para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
+zero, the list is suppressed — unless link numbering is enabled (that
+is, if <parameter>man.endnotes.are.numbered</parameter> is non-zero), in
+which case, that setting overrides the
+<parameter>man.endnotes.list.enabled</parameter> setting, and the
+endnotes list is still displayed. The reason is that inline
+numbering of notesources associated with endnotes only makes sense
+if a (numbered) list of endnotes is also generated.</para>
+
+<note>
+  <para>Leaving
+  <parameter>man.endnotes.list.enabled</parameter> at its default
+  (non-zero) value ensures that no “out of line” information (such
+  as the URLs for hyperlinks and images) gets lost in your
+  man-page output. It just gets “rearranged”.</para>
+  <para>So if you’re thinking about disabling endnotes listing by
+    setting the value of
+    <parameter>man.endnotes.list.enabled</parameter> to zero:
+    Before you do so, first take some time to carefully consider
+    the information needs and experiences of your users. The “out
+    of line” information has value even if the presentation of it
+    in text output is not as interactive as it may be in other
+    output formats.</para>
+  <para>As far as the specific case of URLs: Even though the URLs
+    displayed in text output may not be “real” (clickable)
+    hyperlinks, many X terminals have convenience features for
+    recognizing URLs and can, for example, present users with
+    an options to open a URL in a browser with the user clicks on
+    the URL is a terminal window. And short of those, users with X
+    terminals can always manually cut and paste the URLs into a web
+    browser.</para>
+  <para>Also, note that various “man to html” tools, 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, automatically mark up URLs with <literal>a@href</literal> markup
+  during conversion — resulting in “real” hyperlinks in HTML
+  output from those tools.</para>
+</note>
+
+<para>To “turn off” numbering of endnotes in the
+endnotes list, set <parameter>man.endnotes.are.numbered</parameter>
+to zero. The endnotes list will
+still be displayed; it will just be displayed without the
+numbers<footnote><para>It can still make sense to have
+the list of endnotes displayed even if you have endnotes numbering turned
+off. In that case, your endnotes list basically becomes a “list
+of references” without any association with specific text in
+your document. This is probably the best option if you find the inline
+endnotes numbering obtrusive. Your users will still have access to all the “out of line”
+such as URLs for hyperlinks.</para></footnote>
+</para>
+
+<para>The default heading for the endnotes list is
+<literal>NOTES</literal>. To change that, set a non-empty
+value for the <parameter>man.endnotes.list.heading</parameter>
+parameter.</para>
+
+<para>In the case of notesources that are links: Along with the
+URL for each link, the endnotes list includes the contents of the
+link. The list thus includes only non-empty<footnote>
+
+<para>A “non-empty” link is one that looks like
+this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>
+an “empty link” is on that looks like this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/&gt;</literallayout>
+</para></footnote> links.
+
+Empty links are never included, and never numbered. They are simply
+displayed inline, without any numbering.</para>
+
+<para>In addition, if there are multiple instances of links in a
+<tag>refentry</tag> that have the same URL, the URL is listed only
+once. The contents listed for that link in the endnotes list are
+the contents of the first link which has that URL.</para>
+
+<para>If you disable endnotes listing, you should probably also set
+<parameter>man.links.are.underlined</parameter> to zero (to disable
+link underlining).</para>
+</refsection>
+</refentry>

data/docbook-xsl/params/man.endnotes.list.heading.xml

@@ -0,0 +1,36 @@
+<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.list.heading">
+<refmeta>
+<refentrytitle>man.endnotes.list.heading</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.endnotes.list.heading</refname>
+<refpurpose>Specifies an alternate name for endnotes list</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.endnotes.list.heading.frag">
+<xsl:param name="man.endnotes.list.heading"></xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If the value of the
+<parameter>man.endnotes.are.numbered</parameter> parameter
+and/or the <parameter>man.endnotes.list.enabled</parameter>
+parameter is non-zero (the defaults for both are non-zero), a
+numbered list of endnotes is generated near the end of each man
+page. The default heading for the list of endnotes is the
+equivalent of the English word <literal>NOTES</literal> in
+the current locale. To cause an alternate heading to be displayed,
+set a non-empty value for the
+<parameter>man.endnotes.list.heading</parameter> parameter —
+for example, <literal>REFERENCES</literal>.</para>
+</refsection>
+</refentry>

data/docbook-xsl/params/man.font.funcprototype.xml

@@ -0,0 +1,30 @@
+<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.font.funcprototype">
+<refmeta>
+<refentrytitle>man.font.funcprototype</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.font.funcprototype</refname>
+<refpurpose>Specifies font for funcprototype output</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.font.funcprototype.frag">
+  <xsl:param name="man.font.funcprototype">BI</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>The <parameter>man.font.funcprototype</parameter> parameter
+specifies the font for <tag>funcprototype</tag> output. It
+should be a valid roff font name, such as <literal>BI</literal> or
+<literal>B</literal>.</para>
+
+</refsection>
+</refentry>