git-scribe 0.0.3 → 0.0.4

data/docbook-xsl/params/make.valid.html.xml

@@ -0,0 +1,35 @@
+<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="make.valid.html">
+<refmeta>
+<refentrytitle>make.valid.html</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>make.valid.html</refname>
+<refpurpose>Attempt to make sure the HTML output is valid HTML</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="make.valid.html.frag">
+<xsl:param name="make.valid.html" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If <parameter>make.valid.html</parameter> is true, the stylesheets take
+extra effort to ensure that the resulting HTML is valid. This may mean that some
+<tag>para</tag> tags are translated into HTML <tag>div</tag>s or
+that other substitutions occur.</para>
+
+<para>This parameter is different from <parameter>html.cleanup</parameter>
+because it changes the resulting markup; it does not use extension functions
+to manipulate result-tree-fragments and is therefore applicable to any
+XSLT processor.</para>
+
+</refsection>
+</refentry>

data/docbook-xsl/params/make.year.ranges.xml

@@ -0,0 +1,31 @@
+<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="make.year.ranges">
+<refmeta>
+<refentrytitle>make.year.ranges</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>make.year.ranges</refname>
+<refpurpose>Collate copyright years into ranges?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="make.year.ranges.frag"><xsl:param name="make.year.ranges" select="0"/></src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If non-zero, multiple copyright <tag>year</tag> elements will be
+collated into ranges.
+This works only if each year number is put into a separate
+year element.  The copyright element permits multiple
+year elements. The stylesheet will not successfully parse
+a complex year element such as <literal>&lt;year>2001,2002,2003&lt;/year></literal> into
+a range.</para>
+
+</refsection>
+</refentry>

data/docbook-xsl/params/man.authors.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.authors.section.enabled">
+<refmeta>
+<refentrytitle>man.authors.section.enabled</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.authors.section.enabled</refname>
+<refpurpose>Display auto-generated AUTHORS section?</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<src:fragment xml:id="man.authors.section.enabled.frag">
+<xsl:param name="man.authors.section.enabled">1</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+<refsection><info><title>Description</title></info>
+
+<para>If the value of
+<parameter>man.authors.section.enabled</parameter> is non-zero
+(the default), then an <literal>AUTHORS</literal> section is
+generated near the end of each man page. The output of the
+<literal>AUTHORS</literal> section is assembled from any
+<tag>author</tag>, <tag>editor</tag>, and <tag>othercredit</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>author</tag>, <tag>editor</tag>, and
+<tag>othercredit</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.authors.section.enabled</parameter> is zero, the
+the auto-generated <literal>AUTHORS</literal> section is
+suppressed.</para>
+
+<para>Set the value of
+  <parameter>man.authors.section.enabled</parameter> to zero if
+  you want to have a manually created <literal>AUTHORS</literal>
+  section in your source, and you want it to appear in output
+  instead of the auto-generated <literal>AUTHORS</literal>
+  section.</para>
+</refsection>
+</refentry>

data/docbook-xsl/params/man.base.url.for.relative.links.xml

@@ -0,0 +1,76 @@
+<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.base.url.for.relative.links">
+  <refmeta>
+    <refentrytitle>man.base.url.for.relative.links</refentrytitle>
+    <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>man.base.url.for.relative.links</refname>
+    <refpurpose>Specifies a base URL for relative links</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <src:fragment xml:id="man.base.url.for.relative.links.frag"><xsl:param name="man.base.url.for.relative.links">[set $man.base.url.for.relative.links]/</xsl:param></src:fragment>
+  </refsynopsisdiv>
+
+  <refsection><info><title>Description</title></info>
+
+    <para>For any “notesource” listed in the auto-generated
+      “NOTES” section of output man pages (which is generated when
+      the value of the
+      <parameter>man.endnotes.list.enabled</parameter> parameter
+      is non-zero), if the notesource is a link source with a
+      relative URI, the URI is displayed in output with the value
+      of the
+      <parameter>man.base.url.for.relative.links</parameter>
+      parameter prepended to the value of the link URI.</para>
+
+    <note>
+      <para>A link source is an notesource that references an
+        external resource:
+        <itemizedlist>
+          <listitem>
+            <para>a <tag>ulink</tag> element with a <tag
+                class="attribute">url</tag> attribute</para>
+          </listitem>
+          <listitem>
+            <para>any element with an <tag
+                class="attribute">xlink:href</tag> attribute</para>
+          </listitem>
+          <listitem>
+            <para>an <tag>imagedata</tag>, <tag>audiodata</tag>, or
+              <tag>videodata</tag> element</para>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </note>
+
+    <para>If you use relative URIs in link sources in your DocBook
+      <tag>refentry</tag> source, and you leave
+      <parameter>man.base.url.for.relative.links</parameter>
+      unset, the relative links will appear “as is” in the “Notes”
+      section of any man-page output generated from your source.
+      That’s probably not what you want, because such relative
+      links are only usable in the context of HTML output. So, to
+      make the links meaningful and usable in the context of
+      man-page output, set a value for
+      <parameter>man.base.url.for.relative.links</parameter> that
+      points to the online version of HTML output generated from
+      your DocBook <tag>refentry</tag> source. For
+      example:
+      <programlisting
+        >&lt;xsl:param name="man.base.url.for.relative.links"
+        >http://www.kernel.org/pub/software/scm/git/docs/&lt;/xsl:param></programlisting>
+    </para>
+
+  </refsection>
+
+  <refsection><info><title>Related Parameters</title></info>
+    <para><parameter>man.endnotes.list.enabled</parameter></para>
+  </refsection>
+
+</refentry>

data/docbook-xsl/params/man.break.after.slash.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.break.after.slash">
+<refmeta>
+<refentrytitle>man.break.after.slash</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.break.after.slash</refname>
+<refpurpose>Enable line-breaking after slashes?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.break.after.slash.frag">
+<xsl:param name="man.break.after.slash">0</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If non-zero, line-breaking after slashes is enabled. This is
+mainly useful for causing long URLs or pathnames/filenames to be
+broken up or "wrapped" across lines (though it also has the side
+effect of sometimes causing relatively short URLs and pathnames to be
+broken up across lines too).</para>
+
+<para>If zero (the default), line-breaking after slashes is
+disabled. In that case, strings containing slashes (for example, URLs
+or filenames) are not broken across lines, even if they exceed the
+maximum column widith.</para>
+
+<warning>
+  <para>If you set a non-zero value for this parameter, check your
+  man-page output carefuly afterwards, in order to make sure that the
+  setting has not introduced an excessive amount of breaking-up of URLs
+  or pathnames. If your content contains mostly short URLs or
+  pathnames, setting a non-zero value for
+  <parameter>man.break.after.slash</parameter> will probably result in
+  in a significant number of relatively short URLs and pathnames being
+  broken across lines, which is probably not what you want.</para>
+</warning>
+
+</refsection>
+</refentry>

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

@@ -0,0 +1,55 @@
+<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.enabled">
+<refmeta>
+<refentrytitle>man.charmap.enabled</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.enabled</refname>
+<refpurpose>Apply character map before final output?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.charmap.enabled.frag">
+<xsl:param name="man.charmap.enabled" select="1"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If the value of the <parameter>man.charmap.enabled</parameter>
+parameter is non-zero, a "character map" is used to substitute certain
+Unicode symbols and special characters with appropriate roff/groff
+equivalents, just before writing each man-page file to the
+filesystem. If instead the value of
+<parameter>man.charmap.enabled</parameter> is zero, Unicode characters
+are passed through "as is".</para>
+
+<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>
+
+<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>
+
+<para>You can also use a subset of a character map. For details,
+see the <parameter>man.charmap.use.subset</parameter>,
+<parameter>man.charmap.subset.profile</parameter>, and
+<parameter>man.charmap.subset.profile.english</parameter>
+parameters.</para>
+
+</refsection>
+</refsection>
+</refentry>

data/docbook-xsl/params/man.charmap.subset.profile.english.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.subset.profile.english">
+<refmeta>
+<refentrytitle>man.charmap.subset.profile.english</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.subset.profile.english</refname>
+<refpurpose>Profile of character map subset</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.charmap.subset.profile.english.frag">
+<xsl:param name="man.charmap.subset.profile.english">
+@*[local-name() = 'block'] = 'Miscellaneous Technical' or
+(@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
+ @*[local-name() = 'class'] = 'symbols')
+or
+(@*[local-name() = 'block'] = 'General Punctuation' and
+ (@*[local-name() = 'class'] = 'spaces' or
+  @*[local-name() = 'class'] = 'dashes' or
+  @*[local-name() = 'class'] = 'quotes' or
+  @*[local-name() = 'class'] = 'bullets'
+ )
+) or
+@*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
+@*[local-name() = 'name'] = 'WORD JOINER' or
+@*[local-name() = 'name'] = 'SERVICE MARK' or
+@*[local-name() = 'name'] = 'TRADE MARK SIGN' or
+@*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
+</xsl:param>
+</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, and your DocBook source is written in English (that
+  is, if its <tag class="attribute">lang</tag> or <tag
+    class="attribute">xml:lang</tag> attribute on the root element
+  in your DocBook source or on the first <tag>refentry</tag>
+  element in your source has the value <literal>en</literal> or if
+  it has no <tag class="attribute">lang</tag> or <tag
+    class="attribute">xml:lang</tag> attribute), then the
+  character-map subset specified by the
+  <parameter>man.charmap.subset.profile.english</parameter>
+  parameter is used instead of the full roff character map.</para>
+
+<para>Otherwise, if the <tag class="attribute">lang</tag> or <tag
+    class="attribute">xml:lang</tag> attribute
+  on the root element in your DocBook source or on the first
+  <tag>refentry</tag> element in your source has a value other
+  than <literal>en</literal>, then the character-map subset
+  specified by the
+  <parameter>man.charmap.subset.profile</parameter> parameter is
+  used instead of
+  <parameter>man.charmap.subset.profile.english</parameter>.</para>
+
+<para>The difference between the two subsets is that
+  <parameter>man.charmap.subset.profile</parameter> provides
+  mappings for characters in Western European languages that are
+  not part of the Roman (English) alphabet (ASCII character set).</para>
+
+<para>The value of <parameter>man.charmap.subset.profile.english</parameter>
+is a string representing an XPath expression that matches attribute
+names and values for <tag
+  namespace="http://docbook.sf.net/xmlns/unichar/1.0"
+  >output-character</tag> elements in the character map.</para>
+
+<para>For other details, see the documentation for the
+<parameter>man.charmap.subset.profile.english</parameter> and
+<parameter>man.charmap.use.subset</parameter> parameters.</para>
+
+</refsection>
+</refentry>

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

@@ -0,0 +1,297 @@
+<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.subset.profile">
+<refmeta>
+<refentrytitle>man.charmap.subset.profile</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.subset.profile</refname>
+<refpurpose>Profile of character map subset</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.charmap.subset.profile.frag">
+<xsl:param name="man.charmap.subset.profile">
+@*[local-name() = 'block'] = 'Miscellaneous Technical' or
+(@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
+ (@*[local-name() = 'class'] = 'symbols' or
+  @*[local-name() = 'class'] = 'letters')
+) or
+@*[local-name() = 'block'] = 'Latin Extended-A'
+or
+(@*[local-name() = 'block'] = 'General Punctuation' and
+ (@*[local-name() = 'class'] = 'spaces' or
+  @*[local-name() = 'class'] = 'dashes' or
+  @*[local-name() = 'class'] = 'quotes' or
+  @*[local-name() = 'class'] = 'bullets'
+ )
+) or
+@*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
+@*[local-name() = 'name'] = 'WORD JOINER' or
+@*[local-name() = 'name'] = 'SERVICE MARK' or
+@*[local-name() = 'name'] = 'TRADE MARK SIGN' or
+@*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
+</xsl:param>
+</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,
+and your DocBook source is not written in English (that
+  is, if the <tag class="attribute">lang</tag> or <tag
+    class="attribute">xml:lang</tag> attribute on the root element
+  in your DocBook source or on the first <tag>refentry</tag>
+  element in your source has a value other than
+  <literal>en</literal>), then the character-map subset specified
+  by the <parameter>man.charmap.subset.profile</parameter>
+  parameter is used instead of the full roff character map.</para>
+
+<para>Otherwise, if the <tag class="attribute">lang</tag> or <tag
+    class="attribute">xml:lang</tag> attribute on the root
+  element in your DocBook
+  source or on the first <tag>refentry</tag> element in your source
+  has the value <literal>en</literal> or if it has no <tag
+    class="attribute">lang</tag> or <tag
+    class="attribute">xml:lang</tag> attribute, then the character-map
+  subset specified by the
+  <parameter>man.charmap.subset.profile.english</parameter>
+  parameter is used instead of
+  <parameter>man.charmap.subset.profile</parameter>.</para>
+
+<para>The difference between the two subsets is that
+  <parameter>man.charmap.subset.profile</parameter> provides
+  mappings for characters in Western European languages that are
+  not part of the Roman (English) alphabet (ASCII character set).</para>
+
+<para>The value of <parameter>man.charmap.subset.profile</parameter>
+is a string representing an XPath expression that matches attribute
+names and values for <tag
+  namespace="http://docbook.sf.net/xmlns/unichar/1.0">output-character</tag>
+elements in the character map.</para>
+
+<para>The attributes supported in the <link xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">standard roff character map included in the distribution</link> are:
+<variablelist>
+  <varlistentry>
+    <term>character</term>
+    <listitem>
+      <simpara>a raw Unicode character or numeric Unicode
+      character-entity value (either in decimal or hex); all
+      characters have this attribute</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>name</term>
+    <listitem>
+      <simpara>a standard full/long ISO/Unicode character name (e.g.,
+      "OHM SIGN"); all characters have this attribute</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>block</term>
+    <listitem>
+      <simpara>a standard Unicode "block" name (e.g., "General
+      Punctuation"); all characters have this attribute. For the full
+      list of Unicode block names supported in the standard roff
+      character map, see <xref linkend="BlocksAndClasses"/>.</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>class</term>
+    <listitem>
+      <simpara>a class of characters (e.g., "spaces"). Not all
+      characters have this attribute; currently, it is used only with
+      certain characters within the "C1 Controls And Latin-1
+      Supplement" and "General Punctuation" blocks. For details, see
+      <xref linkend="BlocksAndClasses"/>.</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>entity</term>
+    <listitem>
+      <simpara>an ISO entity name (e.g., "ohm"); not all characters
+      have this attribute, because not all characters have ISO entity
+      names; for example, of the 800 or so characters in the standard
+      roff character map included in the distribution, only around 300
+      have ISO entity names.
+      </simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>string</term>
+    <listitem>
+      <simpara>a string representing an roff/groff escape-code (with
+      "@esc@" used in place of the backslash), or a simple ASCII
+      string; all characters in the roff character map have this
+      attribute</simpara>
+    </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>The value of <parameter>man.charmap.subset.profile</parameter>
+is evaluated as an XPath expression at run-time to select a portion of
+the roff character map to use. You can tune the subset used by adding
+or removing parts. For example, if you need to use a wide range of
+mathematical operators in a document, and you want to have them
+converted into roff markup properly, you might add the following:
+
+<literallayout class="monospaced">  @*[local-name() = 'block'] ='MathematicalOperators' </literallayout>
+
+That will cause a additional set of around 67 additional "math"
+characters to be converted into roff markup. </para>
+
+<note>
+<para>Depending on which XSLT engine you use, either the EXSLT
+<function>dyn:evaluate</function> extension function (for xsltproc or
+Xalan) or <function>saxon:evaluate</function> extension function (for
+Saxon) are used to dynamically evaluate the value of
+<parameter>man.charmap.subset.profile</parameter> at run-time. If you
+don't use xsltproc, Saxon, Xalan -- or some other XSLT engine that
+supports <function>dyn:evaluate</function> -- you must either set the
+value of the <parameter>man.charmap.use.subset</parameter> parameter
+to zero and process your documents using the full character map
+instead, or set the value of the
+<parameter>man.charmap.enabled</parameter> parameter to zero instead
+(so that character-map processing is disabled completely.</para>
+</note>
+
+<para>An alternative to using
+<parameter>man.charmap.subset.profile</parameter> is to create your
+own custom character map, and set the value of
+<parameter>man.charmap.uri</parameter> to the URI/filename for
+that. If you use a custom character map, you will probably want to
+include in it just the characters you want to use, and so you will
+most likely also want to set the value of
+<parameter>man.charmap.use.subset</parameter> to zero.</para>
+<para>You can create a
+custom character map by making a copy of the <link xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">standard roff character map</link> provided in the distribution, and
+then adding to, changing, and/or deleting from that.</para>
+
+<caution>
+<para>If you author your DocBook XML source in UTF-8 or UTF-16
+encoding and aren't sure what OSes or environments your man-page
+output might end up being viewed on, and not sure what version of
+nroff/groff those environments might have, you should be careful about
+what Unicode symbols and special characters you use in your source and
+what parts you add to the value of
+<parameter>man.charmap.subset.profile</parameter>.</para>
+<para>Many of the escape codes used are specific to groff and using
+them may not provide the expected output on an OS or environment that
+uses nroff instead of groff.</para>
+<para>On the other hand, if you intend for your man-page output to be
+viewed only on modern systems (for example, GNU/Linux systems, FreeBSD
+systems, or Cygwin environments) that have a good, up-to-date groff,
+then you can safely include a wide range of Unicode symbols and
+special characters in your UTF-8 or UTF-16 encoded DocBook XML source
+and add any of the supported Unicode block names to the value of
+<parameter>man.charmap.subset.profile</parameter>.</para>
+</caution>
+
+
+<para>For other details, see the documentation for the
+<parameter>man.charmap.use.subset</parameter> parameter.</para>
+
+<refsection xml:id="BlocksAndClasses"><info><title>Supported Unicode block names and "class" values</title></info>
+  
+
+  <para>Below is the full list of Unicode block names and "class"
+  values supported in the standard roff stylesheet provided in the
+  distribution, along with a description of which codepoints from the
+  Unicode range corresponding to that block name or block/class
+  combination are supported.</para>
+
+  <itemizedlist>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=C1%20Controls%20and%20Latin-1%20Supplement%20(Latin-1%20Supplement)">C1 Controls And Latin-1 Supplement (Latin-1 Supplement)</link> (x00a0 to x00ff)
+      <itemizedlist><info><title>class values</title></info>
+        
+        <listitem>
+          <para>symbols</para>
+        </listitem>
+        <listitem>
+          <para>letters</para>
+        </listitem>
+      </itemizedlist></para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Latin%20Extended-A">Latin Extended-A</link> (x0100 to x017f, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Spacing%20Modifier%20Letters">Spacing Modifier Letters</link> (x02b0 to x02ee, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Greek%20and%20Coptic">Greek and Coptic</link> (x0370 to x03ff, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=General%20Punctuation">General Punctuation</link> (x2000 to x206f, partial)
+      <itemizedlist><info><title>class values</title></info>
+        
+        <listitem>
+          <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8192&amp;end=8203">spaces</link></para>
+        </listitem>
+        <listitem>
+          <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8208&amp;end=8213">dashes</link></para>
+        </listitem>
+        <listitem>
+          <para>quotes</para>
+        </listitem>
+        <listitem>
+          <para>daggers</para>
+        </listitem>
+        <listitem>
+          <para>bullets</para>
+        </listitem>
+        <listitem>
+          <para>leaders</para>
+        </listitem>
+        <listitem>
+          <para>primes</para>
+        </listitem>
+      </itemizedlist>
+      </para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Superscripts%20and%20Subscripts">Superscripts and Subscripts</link> (x2070 to x209f)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Currency%20Symbols">Currency Symbols</link> (x20a0 to x20b1)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Letterlike%20Symbols">Letterlike Symbols</link> (x2100 to x214b)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Number%20Forms">Number Forms</link> (x2150 to x218f)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Arrows">Arrows</link> (x2190 to x21ff, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Mathematical%20Operators">Mathematical Operators</link> (x2200 to x22ff, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Control%20Pictures">Control Pictures</link> (x2400 to x243f)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Enclosed%20Alphanumerics">Enclosed Alphanumerics</link> (x2460 to x24ff)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Geometric%20Shapes">Geometric Shapes</link> (x25a0 to x25f7, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Miscellaneous%20Symbols">Miscellaneous Symbols</link> (x2600 to x26ff, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Dingbats">Dingbats</link> (x2700 to x27be, partial)</para>
+    </listitem>
+    <listitem>
+      <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Alphabetic%20Presentation%20Forms">Alphabetic Presentation Forms</link> (xfb00 to xfb04 only)</para>
+    </listitem>
+  </itemizedlist>
+</refsection>
+</refsection>
+</refentry>