doc/xslt/params/man.charmap.subset.profile.xml

   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.charmap.subset.profile">
   7 <refmeta>
   8 <refentrytitle>man.charmap.subset.profile</refentrytitle>
   9 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>man.charmap.subset.profile</refname>
  13 <refpurpose>Profile of character map subset</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17 <src:fragment xml:id="man.charmap.subset.profile.frag">
  18 <xsl:param name="man.charmap.subset.profile">
  19 @*[local-name() = 'block'] = 'Miscellaneous Technical' or
  20 (@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
  21  (@*[local-name() = 'class'] = 'symbols' or
  22   @*[local-name() = 'class'] = 'letters')
  23 ) or
  24 @*[local-name() = 'block'] = 'Latin Extended-A'
  25 or
  26 (@*[local-name() = 'block'] = 'General Punctuation' and
  27  (@*[local-name() = 'class'] = 'spaces' or
  28   @*[local-name() = 'class'] = 'dashes' or
  29   @*[local-name() = 'class'] = 'quotes' or
  30   @*[local-name() = 'class'] = 'bullets'
  31  )
  32 ) or
  33 @*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
  34 @*[local-name() = 'name'] = 'WORD JOINER' or
  35 @*[local-name() = 'name'] = 'SERVICE MARK' or
  36 @*[local-name() = 'name'] = 'TRADE MARK SIGN' or
  37 @*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
  38 </xsl:param>
  39 </src:fragment>
  40 </refsynopsisdiv>
  41
  42 <refsection><info><title>Description</title></info>
  43
  44 <para>If the value of the
  45 <parameter>man.charmap.use.subset</parameter> parameter is non-zero,
  46 and your DocBook source is not written in English (that
  47   is, if the <tag class="attribute">lang</tag> or <tag
  48     class="attribute">xml:lang</tag> attribute on the root element
  49   in your DocBook source or on the first <tag>refentry</tag>
  50   element in your source has a value other than
  51   <literal>en</literal>), then the character-map subset specified
  52   by the <parameter>man.charmap.subset.profile</parameter>
  53   parameter is used instead of the full roff character map.</para>
  54
  55 <para>Otherwise, if the <tag class="attribute">lang</tag> or <tag
  56     class="attribute">xml:lang</tag> attribute on the root
  57   element in your DocBook
  58   source or on the first <tag>refentry</tag> element in your source
  59   has the value <literal>en</literal> or if it has no <tag
  60     class="attribute">lang</tag> or <tag
  61     class="attribute">xml:lang</tag> attribute, then the character-map
  62   subset specified by the
  63   <parameter>man.charmap.subset.profile.english</parameter>
  64   parameter is used instead of
  65   <parameter>man.charmap.subset.profile</parameter>.</para>
  66
  67 <para>The difference between the two subsets is that
  68   <parameter>man.charmap.subset.profile</parameter> provides
  69   mappings for characters in Western European languages that are
  70   not part of the Roman (English) alphabet (ASCII character set).</para>
  71
  72 <para>The value of <parameter>man.charmap.subset.profile</parameter>
  73 is a string representing an XPath expression that matches attribute
  74 names and values for <tag
  75   namespace="http://docbook.sf.net/xmlns/unichar/1.0">output-character</tag>
  76 elements in the character map.</para>
  77
  78 <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:
  79 <variablelist>
  80   <varlistentry>
  81     <term>character</term>
  82     <listitem>
  83       <simpara>a raw Unicode character or numeric Unicode
  84       character-entity value (either in decimal or hex); all
  85       characters have this attribute</simpara>
  86     </listitem>
  87   </varlistentry>
  88   <varlistentry>
  89     <term>name</term>
  90     <listitem>
  91       <simpara>a standard full/long ISO/Unicode character name (e.g.,
  92       "OHM SIGN"); all characters have this attribute</simpara>
  93     </listitem>
  94   </varlistentry>
  95   <varlistentry>
  96     <term>block</term>
  97     <listitem>
  98       <simpara>a standard Unicode "block" name (e.g., "General
  99       Punctuation"); all characters have this attribute. For the full
 100       list of Unicode block names supported in the standard roff
 101       character map, see <xref linkend="BlocksAndClasses"/>.</simpara>
 102     </listitem>
 103   </varlistentry>
 104   <varlistentry>
 105     <term>class</term>
 106     <listitem>
 107       <simpara>a class of characters (e.g., "spaces"). Not all
 108       characters have this attribute; currently, it is used only with
 109       certain characters within the "C1 Controls And Latin-1
 110       Supplement" and "General Punctuation" blocks. For details, see
 111       <xref linkend="BlocksAndClasses"/>.</simpara>
 112     </listitem>
 113   </varlistentry>
 114   <varlistentry>
 115     <term>entity</term>
 116     <listitem>
 117       <simpara>an ISO entity name (e.g., "ohm"); not all characters
 118       have this attribute, because not all characters have ISO entity
 119       names; for example, of the 800 or so characters in the standard
 120       roff character map included in the distribution, only around 300
 121       have ISO entity names.
 122       </simpara>
 123     </listitem>
 124   </varlistentry>
 125   <varlistentry>
 126     <term>string</term>
 127     <listitem>
 128       <simpara>a string representing an roff/groff escape-code (with
 129       "@esc@" used in place of the backslash), or a simple ASCII
 130       string; all characters in the roff character map have this
 131       attribute</simpara>
 132     </listitem>
 133   </varlistentry>
 134 </variablelist>
 135 </para>
 136 <para>The value of <parameter>man.charmap.subset.profile</parameter>
 137 is evaluated as an XPath expression at run-time to select a portion of
 138 the roff character map to use. You can tune the subset used by adding
 139 or removing parts. For example, if you need to use a wide range of
 140 mathematical operators in a document, and you want to have them
 141 converted into roff markup properly, you might add the following:
 142
 143 <literallayout class="monospaced">  @*[local-name() = 'block'] ='MathematicalOperators' </literallayout>
 144
 145 That will cause a additional set of around 67 additional "math"
 146 characters to be converted into roff markup. </para>
 147
 148 <note>
 149 <para>Depending on which XSLT engine you use, either the EXSLT
 150 <function>dyn:evaluate</function> extension function (for xsltproc or
 151 Xalan) or <function>saxon:evaluate</function> extension function (for
 152 Saxon) are used to dynamically evaluate the value of
 153 <parameter>man.charmap.subset.profile</parameter> at run-time. If you
 154 don't use xsltproc, Saxon, Xalan -- or some other XSLT engine that
 155 supports <function>dyn:evaluate</function> -- you must either set the
 156 value of the <parameter>man.charmap.use.subset</parameter> parameter
 157 to zero and process your documents using the full character map
 158 instead, or set the value of the
 159 <parameter>man.charmap.enabled</parameter> parameter to zero instead
 160 (so that character-map processing is disabled completely.</para>
 161 </note>
 162
 163 <para>An alternative to using
 164 <parameter>man.charmap.subset.profile</parameter> is to create your
 165 own custom character map, and set the value of
 166 <parameter>man.charmap.uri</parameter> to the URI/filename for
 167 that. If you use a custom character map, you will probably want to
 168 include in it just the characters you want to use, and so you will
 169 most likely also want to set the value of
 170 <parameter>man.charmap.use.subset</parameter> to zero.</para>
 171 <para>You can create a
 172 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
 173 then adding to, changing, and/or deleting from that.</para>
 174
 175 <caution>
 176 <para>If you author your DocBook XML source in UTF-8 or UTF-16
 177 encoding and aren't sure what OSes or environments your man-page
 178 output might end up being viewed on, and not sure what version of
 179 nroff/groff those environments might have, you should be careful about
 180 what Unicode symbols and special characters you use in your source and
 181 what parts you add to the value of
 182 <parameter>man.charmap.subset.profile</parameter>.</para>
 183 <para>Many of the escape codes used are specific to groff and using
 184 them may not provide the expected output on an OS or environment that
 185 uses nroff instead of groff.</para>
 186 <para>On the other hand, if you intend for your man-page output to be
 187 viewed only on modern systems (for example, GNU/Linux systems, FreeBSD
 188 systems, or Cygwin environments) that have a good, up-to-date groff,
 189 then you can safely include a wide range of Unicode symbols and
 190 special characters in your UTF-8 or UTF-16 encoded DocBook XML source
 191 and add any of the supported Unicode block names to the value of
 192 <parameter>man.charmap.subset.profile</parameter>.</para>
 193 </caution>
 194
 195
 196 <para>For other details, see the documentation for the
 197 <parameter>man.charmap.use.subset</parameter> parameter.</para>
 198
 199 <refsection xml:id="BlocksAndClasses"><info><title>Supported Unicode block names and "class" values</title></info>
 200
 201
 202   <para>Below is the full list of Unicode block names and "class"
 203   values supported in the standard roff stylesheet provided in the
 204   distribution, along with a description of which codepoints from the
 205   Unicode range corresponding to that block name or block/class
 206   combination are supported.</para>
 207
 208   <itemizedlist>
 209     <listitem>
 210       <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)
 211       <itemizedlist><info><title>class values</title></info>
 212
 213         <listitem>
 214           <para>symbols</para>
 215         </listitem>
 216         <listitem>
 217           <para>letters</para>
 218         </listitem>
 219       </itemizedlist></para>
 220     </listitem>
 221     <listitem>
 222       <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>
 223     </listitem>
 224     <listitem>
 225       <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>
 226     </listitem>
 227     <listitem>
 228       <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>
 229     </listitem>
 230     <listitem>
 231       <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)
 232       <itemizedlist><info><title>class values</title></info>
 233
 234         <listitem>
 235           <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8192&amp;end=8203">spaces</link></para>
 236         </listitem>
 237         <listitem>
 238           <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8208&amp;end=8213">dashes</link></para>
 239         </listitem>
 240         <listitem>
 241           <para>quotes</para>
 242         </listitem>
 243         <listitem>
 244           <para>daggers</para>
 245         </listitem>
 246         <listitem>
 247           <para>bullets</para>
 248         </listitem>
 249         <listitem>
 250           <para>leaders</para>
 251         </listitem>
 252         <listitem>
 253           <para>primes</para>
 254         </listitem>
 255       </itemizedlist>
 256       </para>
 257     </listitem>
 258     <listitem>
 259       <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>
 260     </listitem>
 261     <listitem>
 262       <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>
 263     </listitem>
 264     <listitem>
 265       <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>
 266     </listitem>
 267     <listitem>
 268       <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>
 269     </listitem>
 270     <listitem>
 271       <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Arrows">Arrows</link> (x2190 to x21ff, partial)</para>
 272     </listitem>
 273     <listitem>
 274       <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>
 275     </listitem>
 276     <listitem>
 277       <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>
 278     </listitem>
 279     <listitem>
 280       <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>
 281     </listitem>
 282     <listitem>
 283       <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>
 284     </listitem>
 285     <listitem>
 286       <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>
 287     </listitem>
 288     <listitem>
 289       <para><link xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Dingbats">Dingbats</link> (x2700 to x27be, partial)</para>
 290     </listitem>
 291     <listitem>
 292       <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>
 293     </listitem>
 294   </itemizedlist>
 295 </refsection>
 296 </refsection>
 297 </refentry>