doc/xslt/params/man.charmap.use.subset.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.use.subset">
   7 <refmeta>
   8 <refentrytitle>man.charmap.use.subset</refentrytitle>
   9 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>man.charmap.use.subset</refname>
  13 <refpurpose>Use subset of character map instead of full map?</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17 <src:fragment xml:id="man.charmap.use.subset.frag">
  18 <xsl:param name="man.charmap.use.subset" select="1"/>
  19 </src:fragment>
  20 </refsynopsisdiv>
  21
  22 <refsection><info><title>Description</title></info>
  23
  24 <para>If the value of the
  25 <parameter>man.charmap.use.subset</parameter> parameter is non-zero,
  26 a subset of the roff character map is used instead of the full roff
  27 character map. The profile of the subset used is determined either
  28 by the value of the
  29 <parameter>man.charmap.subset.profile</parameter>
  30 parameter (if the source is not in English) or the
  31 <parameter>man.charmap.subset.profile.english</parameter>
  32 parameter (if the source is in English).</para>
  33
  34 <note>
  35   <para>You may want to experiment with setting a non-zero value of
  36   <parameter>man.charmap.use.subset</parameter>, so that the full
  37   character map is used. Depending on which XSLT engine you run,
  38   setting a non-zero value for
  39   <parameter>man.charmap.use.subset</parameter> may significantly
  40   increase the time needed to process your documents. Or it may
  41   not. For example, if you set it and run it with xsltproc, it seems
  42   to dramatically increase processing time; on the other hand, if you
  43   set it and run it with Saxon, it does not seem to increase
  44   processing time nearly as much.</para>
  45
  46   <para>If processing time is not a important concern and/or you can
  47   tolerate the increase in processing time imposed by using the full
  48   character map, set <parameter>man.charmap.use.subset</parameter> to
  49   zero.</para>
  50 </note>
  51
  52 <refsection><info><title>Details</title></info>
  53
  54 <para>For converting certain Unicode symbols and special characters in
  55 UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
  56 equivalents in man-page output, the DocBook XSL Stylesheets
  57 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
  58 map</link> format as detailed in the XSLT 2.0 specification. The map
  59 contains more than 800 character mappings and can be considered the
  60 standard roff character map for the distribution.</para>
  61
  62 <note>
  63 <para>You can use the <parameter>man.charmap.uri</parameter>
  64 parameter to specify a URI for the location for an alternate roff
  65 character map to use in place of the standard roff character map
  66 provided in the distribution.</para>
  67 </note>
  68
  69 <para>Because it is not terrifically efficient to use the standard
  70 800-character character map in full -- and for most (or all) users,
  71 never necessary to use it in full -- the DocBook XSL Stylesheets
  72 support a mechanism for using, within any given character map, a
  73 subset of character mappings instead of the full set. You can use the
  74 <parameter>man.charmap.subset.profile</parameter> or
  75 <parameter>man.charmap.subset.profile.english</parameter>
  76 parameter to tune the profile of that subset to use.</para>
  77
  78 </refsection>
  79 </refsection>
  80 </refentry>