<refentry xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          id="man.charmap.subset.profile">
<refmeta>
<refentrytitle>man.charmap.subset.profile</refentrytitle>
<refmiscinfo role="type">string</refmiscinfo>
</refmeta>
<refnamediv>
<refname>man.charmap.subset.profile</refname>
<refpurpose>Profile of character map subset</refpurpose>
</refnamediv>

<refsynopsisdiv>
<src:fragment 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() = '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>

<refsect1><title>Description</title>

<para>If the value of the
<parameter>man.charmap.use.subset</parameter> parameter is non-zero,
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>The value of <parameter>man.charmap.subset.profile</parameter>
is a string representating 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 <ulink
url="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl"
>standard roff character map included in the distribution</ulink> 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 representating 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> extensio 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 <ulink
url="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl"
>standard roff character map</ulink> 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>

<refsect2 id="BlocksAndClasses">
  <title>Supported Unicode block names and "class" values</title>

  <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><ulink
                url="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)</ulink> (x00a0 to x00ff)
      <itemizedlist>
        <title>class values</title>
        <listitem>
          <para>symbols</para>
        </listitem>
        <listitem>
          <para>letters</para>
        </listitem>
      </itemizedlist></para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Latin%20Extended-A"
                >Latin Extended-A</ulink> (x0100 to x017f, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Spacing%20Modifier%20Letters"
                >Spacing Modifier Letters</ulink> (x02b0 to x02ee, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Greek%20and%20Coptic"
                >Greek and Coptic</ulink> (x0370 to x03ff, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=General%20Punctuation"
                >General Punctuation</ulink> (x2000 to x206f, partial)
      <itemizedlist>
        <title>class values</title>
        <listitem>
          <para><ulink
                    url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8192&amp;end=8203"
                    >spaces</ulink></para>
        </listitem>
        <listitem>
          <para><ulink
                    url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8208&amp;end=8213"
                    >dashes</ulink></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><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Superscripts%20and%20Subscripts"
                >Superscripts and Subscripts</ulink> (x2070 to x209f)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Currency%20Symbols"
                >Currency Symbols</ulink> (x20a0 to x20b1)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Letterlike%20Symbols"
                >Letterlike Symbols</ulink> (x2100 to x214b)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Number%20Forms"
                >Number Forms</ulink> (x2150 to x218f)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Arrows"
                >Arrows</ulink> (x2190 to x21ff, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Mathematical%20Operators"
                >Mathematical Operators</ulink> (x2200 to x22ff, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Control%20Pictures"
                >Control Pictures</ulink> (x2400 to x243f)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Enclosed%20Alphanumerics"
                >Enclosed Alphanumerics</ulink> (x2460 to x24ff)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Geometric%20Shapes"
                >Geometric Shapes</ulink> (x25a0 to x25f7, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Miscellaneous%20Symbols"
                >Miscellaneous Symbols</ulink> (x2600 to x26ff, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Dingbats"
                >Dingbats</ulink> (x2700 to x27be, partial)</para>
    </listitem>
    <listitem>
      <para><ulink
                url="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Alphabetic%20Presentation%20Forms"
                >Alphabetic Presentation Forms</ulink> (xfb00 to xfb04 only)</para>
    </listitem>
  </itemizedlist>
</refsect2>
</refsect1>
</refentry>
