summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.ltx
blob: 914276bcbe9b2b31b84fd8f8f7e6e21acd73cb81 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
%!TEX TS-program = XeLaTeX+xdvipdfmx

\documentclass[12pt]{article}

\makeatletter
\def\@dotsep{999}

\usepackage{fontspec,xltxtra,xunicode}
\setromanfont[Mapping=tex-text, Scale=MatchLowercase]{TeX Gyre Bonum}
\setsansfont[Mapping=tex-text, Scale=MatchLowercase]{TeX Gyre Heros}
\setmonofont[Scale=MatchLowercase]{Monaco}

\usepackage{calc,fancyvrb,hyperref,refstyle,varioref,xcolor}
\usepackage{geometry}
%\geometry{screen,margin=3cm}

\hypersetup{colorlinks,linkcolor=black,urlcolor=black}

\usepackage[it]{titlesec}
\usepackage{enumitem}
\setlist{nolistsep}

\newenvironment{optdesc}
  {\begin{description}[font=\ttfamily,style=nextline,leftmargin=1.5cm]}
  {\end{description}}

\newcommand\cmd{%
  \noindent
  \begin{trivlist}\item[]
  \SaveVerb[%
    aftersave={%
      \begin{minipage}{\linewidth}
        \UseVerb{CMD}}]{CMD}}
\DefineShortVerb{\|}
\newcommand\xarg[1]{‹\textit{#1}›}
\newcommand\desc[1]{\par#1\par}
\def\endcmd{%
  \end{minipage}  
  \end{trivlist}}

\def\cs#1{\texttt{\textbackslash#1}}

\newsavebox\verbatimbox
\edef\examplefilename{\jobname.example}
\newlength\exampleindent
\setlength\exampleindent{1em}

\newenvironment{example}
  {\VerbatimEnvironment
   \begin{VerbatimOut}{\examplefilename}}
  {\end{VerbatimOut}
   \typesetexample}
   
\newcommand\typesetexample{%
  \begin{trivlist}\item[]
  \vrule
  \hspace{\exampleindent}
  \begin{minipage}{\linewidth-\exampleindent}
    \textit{Example:}\par
    \vspace{0.4\baselineskip}
    \BVerbatimInput[fontsize=\small]{\examplefilename}\par
    \vspace{0.4\baselineskip}
    \color[rgb]{0.7,0,0}\input\examplefilename\relax
  \end{minipage}\par
  \end{trivlist}}

\let\strong\textbf
\providecommand\pdfTeX{pdf\/\TeX}
\newcommand\hlink[2]{\href{#1}{#2}\footnote{\url{#1}}}

\let\latin\textit
\def\eg{\latin{e.g.}}
\def\ie{\latin{i.e.}}
\def\Eg{\latin{E.g.}}
\def\Ie{\latin{I.e.}}
\def\etc{\@ifnextchar.{\latin{etc}}{\latin{etc.}\@}}

\def\opteq{\unskip\,\textcolor{gray}{[\textcolor{black}{=}]}\,}

\setlength\parskip{0pt}
\setlength\parindent{2em}
\raggedbottom

\begin{document}
\title{The \texorpdfstring{\XeTeX}{XeTeX} reference guide}
\author{Will Robertson}
\date{October 5, 2009}
\maketitle

\vfill 

\section*{Introduction}
This document serves to summarise \XeTeX's additional features without being so much as a `users' guide'. Note that much of the functionality addressed here is provided in abstracted form in various \LaTeX\ packages and Con\TeX{}t modules.

The descriptions here should be a fairly exhaustive list of the new primitives and features of \XeTeX. Descriptions are still a little aenemic, however. I don't have much time to maintain this document, so contributions are highly welcomed \verb|:)|

\section*{License}
Copyright 2007--2009 Will Robertson. This work, \verb|XeTeX-reference.ltx|, also known as `\verb|xetexref|', is distributed under the terms of the LaTeX Project Public License \textup(\,\url{http://www.latex-project.org/lppl.txt}\,\textup), version 1.3c or later (your choice), and maintained by Will Robertson.

This basically means you are free to re-distribute this file as you wish; you may also make changes to this file or use its contents for another purpose, in which case you should make it clear, by way of a name-change or some other means, that your changed version is a modified version of the original. Please read the license text for more detailed information.

\vfill\vfill\vfill\null

\newpage
\tableofcontents

\part{\texorpdfstring{\XeTeX}{XeTeX}\ specifics}

\section{The \cs{font} command}
The |\font| command has seen significant addition in \XeTeX\ to facilitate rich font feature selection. Under \TeX, fonts were selected like so: |\font\1="|\xarg{font name}|"| with various options appended such as `|at 10pt|' or `|scaled 1.2|', with obvious meaning. This syntax has been extended in \XeTeX\ by passing additions options through the \xarg{font name}.

This syntax looks something like\par
{\centering|\font\1="|\xarg{font name}\xarg{font options}|:|\xarg{font features}|"| \xarg{\TeX\ font features}\par}\noindent
The \xarg{font name} is the actual name of the font (e.g., `|Charis SIL|') and the only mandatory part of the above syntax. 

When using the |xdvipdfmx| driver (not yet the default in Mac~OS~X), it is possible to use fonts
that aren't installed in the operating system by surrounding their name with square brackets. The current directory and the |texmf| trees are searched for files named in this way, or the path may be embedded in the
font declaration. \Eg,
\begin{quote}\small
|\font\1="[fp9r8a]"| \hfill \emph{Selects `FPL Neu' in the current directory}
|\font\1="[/myfonts/fp9r8a]"| \hfill \emph{Selects `FPL Neu' somewhere else}
|\font\1="[lmroman10-regular]"| \hfill \emph{Selects a Latin Modern font in the \emph{TDS}}
\end{quote}

\subsection{Font options}

\xarg{Font options} are only applicable when the font is selected through the operating system (\ie, without square brackets), and may be any concatenation of the following: 

\begin{optdesc}
\item[/B] Use the bold version of the selected font.
\item[/I] Use the italic version of the selected font.
\item[/BI] Use the bold italic version of the selected font.
\item[/IB] Same as \texttt{/BI}.
\item[/S=$x$] Use the version of the selected font corresponding to the optical size $x$\,pt.
\item[/AAT] Explicitly use the ATSUI renderer (Mac OS X only).
\item[/ICU] Explicitly use the ICU OpenType renderer (only useful on Mac OS X).
\end{optdesc}

\subsection{Font features}

The \xarg{font features} is a comma or semi-colon separated list activating or deactivating various AAT or OpenType font features, which will vary by font. 
The \XeTeX\ documentation files \path{aat-info.tex} and \path{opentype-info.tex} provide per-font lists of supported features.

\subsubsection{Arbitrary AAT or OpenType features}
OpenType font features are chosen with \hlink{http://www.microsoft.com/typography/otspec/featuretags.htm}{standard tags}. They may be either comma- or semicolon-separated, and prepended with a |+| to turn them on and a |-| to turn them off.
\begin{example}
\font\warnock="Warnock Pro/I/S=5:+smcp" at 12pt
\warnock This is the OpenType font Warnock Pro in italic 
         with small caps at a small optical size.
\end{example}

Varying depending on the language and script in use (see \secref[vref]{script}), a small number of OpenType features, if they exist, will be activated by default.

AAT font features are specified by strings within each font. Therefore, even equivalent features between different fonts can have different names.
\begin{example}
\font\hoefler="Hoefler Text/B:Letter Case=Small Caps" at 12pt
\hoefler This is the AAT font Hoefler Text in bold with small caps.
\end{example}

\subsubsection{Options for all fonts}
Some font features may be applied for any font. These are
\begin{optdesc}
\item[mapping=\textsl{<font map>}] 
Uses the specified font mapping for this font. This uses the TECKit engine to transform unicode characters in the last-minute processing stage of the source. For example, |mapping=tex-text| will enable the classical mappings from ugly ascii |``---''| to proper typographical glyphs ``---'', and so on.

\item[color={\slshape RRGGBB}{[{\slshape TT}]}] 
Triple pair of hex values to specify the colour in RGB space, with an optional value for the transparency. 

\item[letterspace=$x$] 
Adds $x/S$ space between letters in words, where $S$ is the font size.

\item[embolden=$x$]
Increase the envelope of each glyph by the set amount (this makes the letters look `more bold'). $x=0$ corresponds to no change; $x=1.5$ is a good default value.

\item[extend=$x$]
Stretch each glyph horizontally by a factor of $x$ (i.e., $x=1$ corresponds to no change).

\item[slant=$x$]
Slant each glyph by the set amount. $x=0$ corresponds to no change; $x=0.2$ is a good default value.

\end{optdesc}

\subsubsection{OpenType script and language support}\seclabel{script}
OpenType font features (and font behaviour) can vary by \hlink{http://www.microsoft.com/typography/otspec/scripttags.htm}{script} (`alphabet') and by \hlink{http://www.microsoft.com/typography/otspec/languagetags.htm}{language}. These are selected with four and three letter tags, respectively.
\begin{optdesc}
\item[script=\textsl{<script tag>}] Selects the font script.
\item[language=\textsl{<lang tag>}] Selects the font language.
\end{optdesc}

\subsubsection{Multiple Master and Variable Axes AAT font support}

\begin{optdesc}
\item[weight=$x$] Selects the normalised font weight, $x$.
\item[width=$x$] Selects the normalised font width, $x$.
\item[optical size=$x$] Selects the optical size, $x$\,pt. Note the difference between the \texttt{/S} font option, which selects discrete fonts.
\end{optdesc}

\subsubsection{Vertical typesetting}
\begin{optdesc}
\item[vertical] 
Enables glyph rotation in the output so vertical typesetting can be performed.
\end{optdesc}

\part{New commands}

\section{Font primitives}

\cmd|\XeTeXuseglyphmetrics|
\desc{Counter to specify if the height and depth of characters are taken into account while typesetting ($\ge\mathtt1$). Otherwise ($<\mathtt1$), a single height and depth for the entire alphabet is used. Gives better output but is slower. Activated ($\ge\mathtt1$) by default.}
\endcmd

\begin{example}
\XeTeXuseglyphmetrics=0 \fbox{a}\fbox{A}\fbox{j}\fbox{J} vs.
\XeTeXuseglyphmetrics=1 \fbox{a}\fbox{A}\fbox{j}\fbox{J}
\end{example}

\cmd|\XeTeXglyph|
\xarg{Glyph slot}
\desc{Inserts the glyph in \xarg{slot} of the current font. \strong{Font specific}, so will give different output for different fonts.}
\endcmd

\cmd|\XeTeXglyphindex|
|"|\xarg{Glyph name}|"| \xarg{space} \emph{or} \cs{relax}
\desc{Expands to the \xarg{glyph slot} corresponding to the (possibly font specific) \xarg{glyph name} in the currently selected font. Only works for TrueType fonts (or TrueType-based OpenType fonts) at present. Use \texttt{fontforge} or similar to discover glyph names.}
\endcmd

\cmd|\XeTeXcharglyph|
\xarg{Char code} 
\desc{Expands to the default glyph number of character \xarg{Char code} in the current font, or 0 if the character is not available in the font.}
\endcmd

\begin{example}
\font\1="Charis SIL"\1
The glyph slot in Charis SIL for the Yen symbol is:
    \the\XeTeXglyphindex"yen" . % the font-specific glyph name
Or: \the\XeTeXcharglyph"00A5.   % the unicode character slot

This glyph may be typeset with the font-specific glyph slot:
\XeTeXglyph150, 
or the unicode character slot:
\char"00A5.
\end{example}

\cmd|\XeTeXglyphbounds|
\xarg{edge} \xarg{glyph number}
\desc{Expands to a dimension corresponding to one of the bounds of a glyph,
where \xarg{edge} is an integer from 1 to 4 indicating left/top/right/bottom
edge respectively, and \xarg{glyph number} is an integer glyph index in the
current font (only valid for TrueType/OpenType/PostScript fonts loaded
`natively', not TFM-based fonts). The left and right
measurements are the glyph sidebearings, measured `inwards' from the
origin and advance respectively, so for a glyph that fits completely
within its `cell' they will both be positive; for a glyph that
`overhangs' to the left or right, they will be negative. The actual
width of the glyph's bounding box, therefore, is the character width
(advance) minus both these sidebearings. The top and bottom are
measured from the baseline, like \TeX's height and depth; the height of
the bounding box is the sum of these two dimensions.}
\endcmd

\begin{example}
\def\shadebbox#1{%
\leavevmode\rlap{%
  \dimen0=\fontcharwd\font`#1%
  \edef\gid{\the\XeTeXcharglyph`#1}%
  \advance\dimen0 by -\XeTeXglyphbounds1 \gid
  \advance\dimen0 by -\XeTeXglyphbounds3 \gid
  \kern\XeTeXglyphbounds1 \gid
  \special{color push rgb 1 1 0.66667}%
  \vrule width \dimen0
         height \XeTeXglyphbounds2 \gid
         depth \XeTeXglyphbounds4 \gid
  \special{color pop}%
  \kern\XeTeXglyphbounds3 \gid}%
  #1}
	
\noindent
\font\x="Charis SIL/I" at 24pt \x
\shadebbox{A} \shadebbox{W} \shadebbox{a} \shadebbox{f}
\shadebbox{;} \shadebbox{*} \shadebbox{=}
\end{example}

\cmd|\XeTeXfonttype|
\xarg{font}
\desc{
  Expands to a number corresponding to which renderer is used for a \xarg{font}:
  \begin{optdesc}
    \item [0] for \TeX\ (a legacy TFM-based font);
    \item [1] for ATSUI (usually an AAT font);
    \item [2] for ICU (an OpenType font);
    \item [3] for Graphite.
  \end{optdesc}
}
\endcmd

\begin{example}
\newcommand\whattype[1]{%
  \texttt{\fontname#1} is rendered by
  \ifcase\XeTeXfonttype#1\TeX\or ATSUI\or ICU\fi.\par}
\font\1="cmr10"
\font\2="Hoefler Text"
\font\3="Charis SIL"
\font\4="Charis SIL/AAT" 
\whattype\1\whattype\2\whattype\3\whattype\4
\end{example}

\subsection{OpenType fonts}

\cmd|\XeTeXOTcountscripts|
\xarg{Font}
\desc{Expands to the number of scripts in a font.}
\endcmd

\cmd|\XeTeXOTscripttag|
\xarg{Font}
\xarg{Integer, $n$}
\desc{Expands to the $n$-th script tag of a font.}
\endcmd

\cmd|\XeTeXOTcountlanguages|
\xarg{Font}
\xarg{Script tag}
\desc{Expands to the number of languages in the script of a font.}
\endcmd

\cmd|\XeTeXOTlanguagetag|
\xarg{Font}
\xarg{Script tag}
\xarg{Integer, $n$}
\desc{Expands to the $n$-th language tag in the script of a font.}
\endcmd

\cmd|\XeTeXOTcountfeatures|
\xarg{Font}
\xarg{Script tag}
\xarg{Language tag}
\desc{Expands to the number of features in the language of a script of a font.}
\endcmd

\cmd|\XeTeXOTfeaturetag|
\xarg{Font}
\xarg{Script tag}
\xarg{Language tag}
\xarg{Integer, $n$}
\desc{Expands to the $n$-th feature tag in the language of a script of a font.}
\endcmd


\subsection{AAT fonts}

\subsubsection{Features}

\cmd|\XeTeXcountfeatures|
\xarg{font}
\desc{Expands to the number of features in the \xarg{font}.}
\endcmd

\cmd|\XeTeXfeaturecode|
\xarg{font}
\xarg{integer, $n$}
\desc{Expands to the feature code for the $n$-th feature in the \xarg{font}.}
\endcmd

\cmd|\XeTeXfeaturename|
\xarg{font}
\xarg{feature code}
\desc{Expands to the name corresponding to the \xarg{feature code} in the \xarg{font}.}
\endcmd

\cmd|\XeTeXisexclusivefeature|
\xarg{font}
\xarg{feature code}
\desc{Expands to a number greater than zero if the feature of a font is exclusive (can only take a single selector).}
\endcmd

\subsubsection{Feature selectors}

\cmd|\XeTeXcountselectors|
\xarg{font}
\xarg{feature}
\desc{Expands to the number of selectors in a \xarg{feature} of a \xarg{font}.}
\endcmd

\cmd|\XeTeXselectorcode|
\xarg{font}
\xarg{feature code}
\xarg{integer, $n$}
\desc{Expands to the selector code for the $n$-th selector in a \xarg{feature} of a \xarg{font}.}
\endcmd

\cmd|\XeTeXselectorname|
\xarg{font}
\xarg{feature code}
\xarg{selector code}
\desc{Expands to the name corresponding to the \xarg{selector code} of a feature of a \xarg{font}.}
\endcmd

\cmd|\XeTeXisdefaultselector|
\xarg{font}
\xarg{feature code}
\xarg{selector code}
\desc{Expands to a number greater than zero if the selector of a feature of a font is on by default.}
\endcmd

\subsubsection{Variation axes}

\cmd|\XeTeXcountvariations|
\xarg{font}
\desc{Expands to the number of variation axes in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariation|
\xarg{font}
\xarg{integer, $n$}
\desc{Expands to the variation code for the $n$-th feature in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariationname|
\xarg{font}
\xarg{variation code}
\desc{Expands to the name corresponding to the \xarg{feature code} in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariationmin|
\xarg{font}
\xarg{variation code}
\desc{Expands to the minimum value of the variation corresponding to the \xarg{variation code} in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariationmax|
\xarg{font}
\xarg{variation code}
\desc{Expands to the maximum value of the variation corresponding to the \xarg{variation code} in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariationdefault|
\xarg{font}
\xarg{variation code}
\desc{Expands to the default value of the variation corresponding to the \xarg{variation code} in the \xarg{font}.}
\endcmd

\subsection{Maths fonts}

The primitives described following are extensions of \TeX's 8-bit primitives.

In the following commands, \xarg{fam.} is a number (0--255) representing font to use in maths. \xarg{math type} is the 0--7 number corresponding to the type of math symbol; see a \TeX\ reference for details.

\cmd|\XeTeXmathcode|
\xarg{char slot}
\opteq
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Defines a maths glyph accessible via an input character. Note that the input takes \emph{three} arguments unlike \TeX's \cs{mathcode}.}
\endcmd

\cmd|\XeTeXmathcodenum|
\xarg{char slot}
\opteq
\xarg{math type/fam./glyph slot}
\desc{Pure extension of \cs{mathcode} that uses a `bit-packed' single number argument. Can also be used to extract the bit-packed mathcode number of the \xarg{char slot} if no assignment is given.}
\endcmd

\cmd|\XeTeXmathchar|
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Typesets the math character in the \xarg{glyph slot} in the family specified.}
\endcmd

\cmd|\XeTeXmathcharnum|
\xarg{type/fam./glyph slot}
\desc{Pure extension of \cs{mathchar} that uses a `bit-packed' single number argument. Can also be used to extract the bit-packed mathcode number of the \xarg{char slot} if no assignment is given.}
\endcmd

\cmd|\XeTeXmathchardef|
\xarg{control sequence}
\opteq
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Defines a maths glyph accessible via a control sequence.}
\endcmd

\cmd|\XeTeXdelcode|
\xarg{char slot}
\opteq
\xarg{fam.}
\xarg{glyph slot}
\desc{Defines a delimiter glyph accessible via an input character.}
\endcmd

\cmd|\XeTeXdelcodenum|
\xarg{char slot}
\opteq
\xarg{fam./glyph slot}
\desc{Pure extension of \cs{delcode} that uses a `bit-packed' single number argument. Can also be used to extract the bit-packed delcode number of the \xarg{char slot} if no assignment is given.}
\endcmd

\cmd|\XeTeXdelimiter|
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Typesets the delimiter in the \xarg{glyph slot} in the family specified of either \xarg{math type} 4 (opening) or 5 (closing).}
\endcmd

\cmd|\XeTeXmathaccent|
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Typesets the math accent character in the \xarg{glyph slot} in the family specified.}
\endcmd

\cmd|\XeTeXradical|
\xarg{fam.}
\xarg{glyph slot}
\desc{Typesets the radical in the \xarg{glyph slot} in the family specified.}
\endcmd

\section{Character classes}

The idea behind character classes is to define a boundary where tokens can be added to the input stream without explicit markup. It was originally intended to add glue around punctuation to effect correct Japanese typesetting. This feature can also be used to adjust space around punctuation for European traditions. The general nature of this feature, however, lends it to several other useful applications including automatic font switching when small amounts of another language (in another script) is present in the text.

\cmd|\XeTeXinterchartokenstate|
\desc{Counter. If positive, enables the character classes functionality.}
\endcmd

\cmd|\newXeTeXintercharclass|
\xarg{control sequence}
\desc{Allocates a new interchar class and assigns it to the \xarg{control sequence} argument.}
\endcmd

\cmd|\XeTeXcharclass|
\xarg{char slot}
\opteq
\xarg{interchar class}
\desc{Assigns a class corresponding to \xarg{interchar class} (range 0--255) to a \xarg{char slot}. Most characters are class 0 by default. Class 1 is for CJK ideographs, classes 2 and 3 are CJK punctuation. The boundary of a text string is considered class 255, wherever there is a boundary between a `run' of characters and something else --- glue, kern, math, box, etc. Special case class 256 is ignored; useful for diacritics so I'm told.}
\endcmd

\cmd|\XeTeXinterchartoks|
\xarg{interchar class 1}
\xarg{interchar class\ 2}
\opteq
|{|\xarg{token list}|}|
\desc{Defines tokens to be inserted at the interface between \xarg{interchar class 1} and \xarg{interchar class 2} (in that order).}
\endcmd

\begin{example}
\XeTeXinterchartokenstate = 1
\newXeTeXintercharclass \mycharclassa
\newXeTeXintercharclass \mycharclassA
\newXeTeXintercharclass \mycharclassB
\XeTeXcharclass `\a \mycharclassa
\XeTeXcharclass `\A \mycharclassA
\XeTeXcharclass `\B \mycharclassB

% between "a" and "A":
\XeTeXinterchartoks \mycharclassa \mycharclassA = {[\itshape}
\XeTeXinterchartoks \mycharclassA \mycharclassa = {\upshape]}

% between " " and "B":
\XeTeXinterchartoks 255 \mycharclassB = {\bgroup\color{blue}}
\XeTeXinterchartoks \mycharclassB 255 = {\egroup}

% between "B" and "B":
\XeTeXinterchartoks \mycharclassB \mycharclassB = {.}

aAa A a B aBa BB
\end{example}

\noindent In the above example the input text is typeset as\par
{\centering\verb|a[\itshape A\unshape]a A a \bgroup\color{blue}B\egroup aBa B.B|\par}

\newpage
\section{Encodings}

\cmd|\XeTeXinputencoding|
\xarg{Charset name}
\desc{Defines the input encoding of the following text.}
\endcmd

\cmd|\XeTeXdefaultencoding|
\xarg{Charset name}
\desc{Defines the input encoding of subsequent files to be read.}
\endcmd

\section{Line breaking}

\cmd|\XeTeXdashbreakstate|
\xarg{Integer}
\desc{Specify whether line breaks after en- and em-dashes are allowed. Off, 0, by default.}
\endcmd

\cmd|\XeTeXlinebreaklocale|
\xarg{Locale ID}
\desc{Defines how to break lines for multilingual text.}
\endcmd

\cmd|\XeTeXlinebreakskip|
\xarg{Glue}
\desc{Inter-character linebreak stretch}
\endcmd

\cmd|\XeTeXlinebreakpenalty|
\xarg{Integer}
\desc{Inter-character linebreak penalty}
\endcmd

\cmd|\XeTeXupwardsmode|
\xarg{Integer} 
\desc{If greater than zero, successive lines of text (and rules, boxes, etc.) will be stacked upwards instead of downwards.}
\endcmd

\section{Graphics}

This description is incomplete.

\cmd|\XeTeXpicfile|
\xarg{filename}
\xarg{optional options}
\desc{Insert an image.}
\endcmd

\cmd|\XeTeXpdffile|
\xarg{filename}
\xarg{optional options}
\desc{Insert (pages of) a PDF.}
\endcmd

\section{Parity with \pdfTeX}

\cmd|\pdfpageheight|
\xarg{dimension}
\desc{The height of the PDF page.}
\endcmd

\cmd|\pdfpagewidth|
\xarg{dimension}
\desc{The width of the PDF page.}
\endcmd

\cmd|\pdfsavepos|
\desc{Saves the current location of the page in the typesetting stream.}
\endcmd

\cmd|\pdflastxpos|
\desc{Retrieves the horizontal position saved by \texttt{\char`\\pdfsavepos}.}
\endcmd

\cmd|\pdflastypos|
\desc{Retrieves the vertical position saved by \texttt{\char`\\pdfsavepos}.}
\endcmd

\cmd|\ifincsname...(\else...)\fi|
\desc{\TeX\ conditional to branch true if the expansion occurs within \texttt{\char`\\csname ... \char`\\endcsname}.}
\endcmd

\begin{example}
\def\x{\ifincsname y\else hello\fi}
\def\y{goodbye}
\x/\csname\x\endcsname
\end{example}

\cmd|\ifprimitive| \xarg{control sequence} |...(\else...)\fi|
\desc{\TeX\ conditional to test if a control sequence is a primitive and that it has not been redefined.}
\endcmd

\cmd|\primitive|
\xarg{control sequence}
\desc{If the control sequence is a primitive that's been redefined, this command causes it to expand with its original (i.e., primitive) definition.}
\endcmd

\cmd|\shellescape|
\desc{Read-only status indicating the level of `shell escape' allowed. That is, whether commands are allowed to be executed through \texttt{\char`\\write18\char`\{...\char`\}}. Expands to zero for off; one for on (allowed); two is `restricted' (default in TeX Live 2009 and greater) in which a subset of commands only are allowed.}
\endcmd

\begin{example}
Shell escape \ifnum\shellescape>0 is \else is not \fi enabled.
\end{example}

\cmd|\strcmp|
\xarg{arg one}
\xarg{arg two}
\desc{Compares the full expansion of the two token list arguments. Expands to zero if they are the same, less than one if the first argument sorts lower (lexicographically) than the second argument, and greater than one if vice versa.}
\endcmd

\begin{example}
`a' is less than `z': \strcmp{a}{z}

\def\z{a}
The tokens expand before being compared: \strcmp{a}{\z}

\def\a{z}
Therefore, |\a| is greater than |\z|: \strcmp{\a}{\z}

\edef\b{\string b}
Also note that catcodes are ignored: \strcmp{b}{\b}
\end{example}

\section{Misc.}

\cmd|\XeTeXversion|
\desc{Expands to a number corresponding to the \XeTeX\ version.}
\endcmd

\cmd|\XeTeXrevision|
\desc{Expands to a string corresponding to the \XeTeX\ revision number.}
\endcmd

\begin{example}
The \XeTeX\ version used to typeset this document is: 
\the\XeTeXversion\XeTeXrevision
\end{example}

\end{document}