]> git.stg.codes - stg.git/blob - doc/xslt/params/man.charmap.subset.profile.xml
Merge branch 'new-daily-fee'
[stg.git] / 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>