summaryrefslogtreecommitdiff
path: root/info/xetexref/xetex-reference.tex
blob: ae859e3b327cbe53137581570dae0ed9f78da981 (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
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
% Copyright for this work included in README.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%   https://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Will Robertson.
%
% This work consists of the files xetex-reference.tex,
% README.txt, and the derived file xetex-reference.pdf.

\documentclass[12pt]{article}

\title{The \xetex reference guide\\\url{https://ctan.org/pkg/xetexref}}
\author{Will Robertson \and Khaled Hosny \and Karl Berry}
\date{\today}

\suppressfontnotfounderror=1
\tracinglostchars=1

\makeatletter
\def\@dotsep{999}
\makeatother

\usepackage{refstyle} % must load before unicode-math with 2023 LaTeX.
% https://tex.stackexchange.com/questions/675145

\usepackage{fontspec,unicode-math}
\setmainfont{texgyrepagella}[
    Extension      = .otf ,
    UprightFont    = *-regular ,
    ItalicFont     = *-italic ,
    BoldFont       = *-bold ,
    BoldItalicFont = *-bolditalic ,
    Scale=MatchLowercase
  ]
\setsansfont{texgyreheros}[
    Extension      = .otf ,
    UprightFont    = *-regular ,
    ItalicFont     = *-italic ,
    BoldFont       = *-bold ,
    BoldItalicFont = *-bolditalic ,
    Scale=MatchLowercase
  ]
\iffalse \setmonofont{inconsolata}[
  Scale=MatchLowercase,
  StylisticSet=3, % <- straight quotes
  AutoFakeSlant=.2]\fi
\setmathfont{texgyrepagella-math.otf}

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

\newcommand\tex    {\hologo{TeX}\xspace}
\newcommand\xetex  {\hologo{XeTeX}\xspace}
\newcommand\pdftex {\hologo{pdfTeX}\xspace}
\newcommand\luatex {\hologo{LuaTeX}\xspace}
\newcommand\latex  {\hologo{LaTeX}\xspace}
\newcommand\context{\hologo{ConTeXt}\xspace}

\hypersetup{
  colorlinks,
  linkcolor=black,
  urlcolor=black,
  pdfsubject={The XeTeX reference guide},
  pdfauthor={Will Robertson \& Khaled Hosny \& Karl Berry},
  pdfkeywords={xetex, tex, typesetting, unicode, math, opentype, graphite, aat}
}

\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}
        \parindent=2em\relax\noindent
        \UseVerb{CMD}}]{CMD}}
\edef\|{|}
\DefineShortVerb{\|}
\newcommand\xarg[1]{$\langle\hbox{\rmfamily\itshape #1}\rangle$}
\def\<#1>{\xarg{#1}}
\newcommand\oarg[1]{\texttt{[\,#1\,]}}
\newcommand\barg[1]{\mbox{{\tt\char`\{\,}#1\,{\tt\char`\}}}}% braced arg
\newcommand\desc[1]{\par\noindent\ignorespaces#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{examplenooutput}
  {\wlog{^^Jstarting examplenooutput at line \the\inputlineno}
   \VerbatimEnvironment
   \begin{VerbatimOut}{\examplefilename}}
  {\end{VerbatimOut}
   \def\typesetoutput{[No output for the example, since no AAT or
                       Graphite fonts are available.}
   \typesetexample}

\newenvironment{example}
  {\wlog{^^Jstarting example at line \the\inputlineno}
   \VerbatimEnvironment
   \begin{VerbatimOut}{\examplefilename}}
  {\end{VerbatimOut}
   \def\typesetoutput{\color[rgb]{0.7,0,0}\input\examplefilename\relax}%
   \typesetexample}


\newcommand\typesetexample{%
  \begin{trivlist}\item[]
  \vrule
  \hspace{\exampleindent}
  \begin{minipage}{\linewidth-\exampleindent-\exampleindent}
    \hfuzz=24pt % italic small caps example has overfull line
    \textit{Example:}\par
    \vspace{0.4\baselineskip}
    \BVerbatimInput[fontsize=\small]{\examplefilename}\par
    \vspace{0.4\baselineskip}
    \typesetoutput
  \end{minipage}\par
  \end{trivlist}}


\let\strong\textbf
\newcommand\hlink[2]{\href{#1}{#2}\footnote{\url{#1}}}

\let\latin\relax % let existing font continue
\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}
\maketitle

\vfill

\section*{Introduction}

This document serves as a reference for additional features of \xetex.
It is not a users' guide. Much of the functionality addressed here is
provided in abstracted form in various \latex packages and \context
modules.

The descriptions here are intended to be a reasonably complete, though
terse, list of the new primitives and features of \xetex.

For contributions (very welcome!), bug reports, etc., see links from
the CTAN package page: \url{https://ctan.org/pkg/xetexref}.

\section*{License}

This work, is distributed under the terms of the LaTeX Project Public License
(\url{https://www.latex-project.org/lppl.txt}).

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

\section{The \cs{font} command}

Traditionally, fonts were selected in \tex like this:
|\font\1=|\xarg{tfm name} \xarg{\tex font options}, where the \xarg{\tex
font options} included possibilities such as
\ ‘| at 10pt|’ \
or \ ‘| scaled 1200|’,
with evident meaning. This syntax still works, but it has been greatly
extended in \xetex.

The extended syntax looks schematically like this:

\begin{quote}
 |\font\1="|\xarg{font identifier}
              \xarg{font options}%
              |:|\xarg{font features}%
         |"|\ \xarg{\tex font options}
\end{quote}

\noindent Each part of this command is discussed in the following, but
here is an overview, starting from the end:

\begin{itemize}
\item The \xarg{\tex font options} are unchanged from traditional \tex.

\item The ASCII double quote character |"| (hex 0x22) surrounds any font
definition using the extended syntax.

\item The \xarg{font features} are an optional list of names,
comma or semi-colon separated, preceded by an ASCII colon |:| (0x3a).

\item The \xarg{font options} are an optional list of specifiers which
can only be used with system fonts (see next).

\item The \xarg{font identifier} is the only mandatory part of the
above syntax.  If it is given in square brackets, (\eg,
|\font\1="[lmroman10-regular]"|), it is taken as a font file name.
Without brackets, the name is looked up as both a file name and a system
font name.

\end{itemize}

This distinction between file name lookups and system font name lookups
is crucial to understanding \xetex's behavior and to writing portable
documents (in short: don't use system fonts).

System font name lookups use (except on Mac~OS~X) the
|fontconfig| library; running |fc-list| should show you the font names
available.  \Eg,
\begin{quote}\small
|\font\1="Liberation Serif"| \hfill \emph{look for OS-installed font}
\end{quote}

Fonts have many internal names, and XeTeX does the system font lookups
in the following order:
\vskip1ex
\begin{itemize}
  \item Full Name;
  \item if the name has a hyphen, it is split into Family-Style pair then matched;
  \item PostScript Name;
  \item Family Name, if there is more than one match;
  \begin{itemize}
    \item look for font with “regular” bit set in OS/2 table, if no match;
    \item look for font with style “Regular”, “Plain”, “Normal” or “Roman”, in that order.
  \end{itemize}
\end{itemize}
\bigskip

When using a file name, the |xdvipdfmx| driver must be used (this is the
default). The current directory and the |texmf| trees are searched for
files matching the name, or the path may be embedded in the font
declaration, as usual with |kpathsea|. \Eg,
\begin{quote}\small
|\font\1="[lmroman10-regular]"| \hfill
  {\em find |lmroman10-regular.otf| in any tree}
|\font\2="[/myfonts/fp9r8a]"| \hfill
  {\em look for |fp9r8a| only in |/myfonts/|}
\end{quote}

A file with either an |.otf|, |.ttf| or |.pfb| extension (in that order) will be found.  The
extension can also be specified explicitly.

\subsection{Font collection files}

One more special case about the \xarg{font identifier}: if the file is a
font collection (\eg, |.ttc| or |.dfont|), the index of the font can be
specified using a colon followed by zero-based font index inside the
square brackets (in contrast to the font features we'll describe soon,
which follow a colon outside any square brackets). \Eg,
\begin{quote}\small
|\font\2="[myfont.ttc:1]"| \hfill {\em load the second font from |myfont.ttc| file}
\end{quote}


\subsection{Font options: For OS-selected fonts only}

The following \xarg{font options} are only applicable when the font is selected
through the operating system (\ie, without square brackets):
\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.
\end{optdesc}

The following \xarg{font options} control which `renderer' \xetex uses to interface with the font:
\begin{optdesc}
\item[/AAT] Explicitly use the AAT renderer (Mac~OS~X only).
\item[/OT] Explicitly use the OpenType renderer (new in 0.9999).
\item[/GR] Explicitly use the Graphite renderer.%
           \footnote{\raggedright \url{https://scripts.sil.org/cms/scripts/page.php?site_id=projects&item_id=graphite_home}}
\item[/ICU] Explicitly use the OpenType renderer (deprecated since 0.9999).
\end{optdesc}


\subsection{Font features: For all fonts}

The \xarg{font features} is a comma or semi-colon separated list
activating or deactivating various OpenType, Graphite, or AAT font
features; these vary by font.  In contrast to font options,
features work whether the font is selected by file name or through the
operating system.

The \xetex utility files \path{aat-info.tex} and
\path{opentype-info.tex} provide lists of supported features for a given
font (see comments at the top of each).

\subsubsection{Font features specific to OpenType, Graphite, or AAT}

OpenType font features are usually specified with
\hlink{https://www.microsoft.com/typography/otspec/featuretags.htm}{standard
tags} in the \cs{font} command. They may be either comma- or
semicolon-separated, and prefixed with a |+| to turn them on and a |-|
to turn them off, optionally followed by |=| and a 0-based index for
selecting alternates from multiple alternates features (ignored for |-|
prefixed tags).

\begin{example}
\font\liber="[LinLibertine_RI.otf]/I=5:+smcp" at 12pt
\liber This is the OpenType font Linux Libertine in italic with small caps.
\end{example}

OpenType features can be activated by default:

\begin{example}
\font\antt="[AntykwaTorunska-Regular.otf]"         at 12pt \antt 0
\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=0" at 12pt \antt 0
\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=1" at 12pt \antt 0
\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=2" at 12pt \antt 0
\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=3" at 12pt \antt 0
\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=4" at 12pt \antt 0
\end{example}

AAT font features and Graphite font features are specified by strings
within each font rather than standardised tags. Therefore, even
equivalent features can and do have different names in different fonts.

\begin{examplenooutput}
\font\gra="[CharisSIL-Regular.ttf]/GR:Small Caps=True" at 12pt
\gra This is the Graphite font Charis SIL with small caps.
\end{examplenooutput}

\subsubsection{Features for all fonts}

Some font features may be applied for any font. These are
\begin{optdesc}

\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.

\begin{example}
\font\9="[lmsans10-regular.otf]:color=0000FF,mapping=tex-text"
\9 A sans blue quoted em-dash: ``---''.
\end{example}

\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$ (\ie, $x=1$
corresponds to no change).

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

\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 ASCII |``---''| to proper typographical
glyphs “—”, and so on.

\item[slant=$x$]
Slant each glyph by the set amount. $x=0$ corresponds to no change;
$x=0.2$ is a good default value. The slant is given by $x=R/S$ where $R$
is the displacement of the top edge of each glyph and $S$ is the point
size.

\end{optdesc}

\subsubsection{OpenType script and language support}\seclabel{script}

OpenType font features (and font behavior) can vary by
\hlink{https://www.microsoft.com/typography/otspec/scripttags.htm}{script}
(‘alphabet’) and by
\hlink{https://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}

\section{Font primitives}

\cmd|\XeTeXtracingfonts|
\desc{If nonzero, reports where fonts are found in the log file.}
\endcmd

\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 AAT;
    \item [2] for OpenType;
    \item [3] for Graphite.
  \end{optdesc}
}
\endcmd

\begin{example}
\newcommand\whattype[1]{%
  \texttt{\fontname#1} is rendered by
  \ifcase\XeTeXfonttype#1\TeX\or AAT\or OpenType\or Graphite\fi.\par}
\font\1="cmr10"
\font\2="[CharisSIL-Regular.ttf]"
\font\3="[CharisSIL-Regular.ttf]/OT"
\whattype\1 \whattype\2 \whattype\3
\end{example}

\cmd|\XeTeXfirstfontchar|
\xarg{font}
\desc{Expands to the code of the first character in \xarg{font}.}
\endcmd

\cmd|\XeTeXlastfontchar|
\xarg{font}
\desc{Expands to the code of the last character in \xarg{font}.}
\endcmd

\begin{example}
\font\1="[CharisSIL-Regular.ttf]"\1
The first character in Charis SIL is: "\char\XeTeXfirstfontchar\1"
and the last character is: "\char\XeTeXlastfontchar\1".
\end{example}

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

\cmd|\XeTeXcountglyphs|
\xarg{font}
\desc{The count of the number of glyphs in the specified \xarg{font}.}
\endcmd

\cmd|\XeTeXglyphname|
\xarg{font}
\xarg{glyph slot}
\desc{Expands to the name of the glyph in \xarg{glyph slot} of \xarg{font}.
\strong{Font specific}, so will give different output for different fonts and
possibly even different versions of the same font.}
\endcmd

\cmd|\XeTeXglyphindex|
|"|\xarg{glyph name}|"| \xarg{space} \emph{or} \cs{relax}
\desc{Expands to the 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="[CharisSIL-Regular.ttf]"\1
The glyph slot in Charis SIL for the Yen symbol is:
    \the\XeTeXglyphindex"yen" . % font-specific glyph name
Or: \the\XeTeXcharglyph"00A5.   % 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 slot}
\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 the
left/top/right/bottom edge respectively, and \xarg{glyph slot} is an
integer glyph index in the current font (only valid for non 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 measurements 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="[CharisSIL-Italic.ttf]" at 24pt \x
\shadebbox{A} \shadebbox{W} \shadebbox{a} \shadebbox{f}
\shadebbox{;} \shadebbox{*} \shadebbox{=}
\end{example}

\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|\XeTeXgenerateactualtext|
\xarg{integer}
\desc{Controls the output of \texttt{/ActualText} entry. Default is 0.
When set to 1, the \texttt{/ActualText} entry is added to the output PDF
for better copy/paste and search in PDF viewers.}
\endcmd

\subsection{OpenType fonts}

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

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

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

\cmd|\XeTeXOTlanguagetag|
\xarg{font}
\xarg{script tag}
\xarg{integer, $n$}
\desc{Expands to the $n$-th language tag in the script of \xarg{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 \xarg{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 \xarg{font}.}
\endcmd


\subsection{AAT and Graphite fonts}

These commands apply to AAT and Graphite fonts; for other kinds of
fonts, they produce an error.

\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

\cmd|\XeTeXfindfeaturebyname|
\xarg{font}
\xarg{feature name}
\desc{This command provides a method to query whether a feature name
corresponds to a feature contained in the font. It returns an integer
corresponding to the feature number used to access the feature
numerically. If the feature does not exist, the integer is
\texttt{-1}. Also see \cs{XeTeXfindselectorbyname}.}
\endcmd

\begin{examplenooutput}
\font\1="[CharisSIL-Regular.ttf]/GR" at 10pt
\def\featname{Uppercase Eng alternates}
The feature ‘\featname’ has index
\the\XeTeXfindfeaturebyname\1 "\featname"\relax
\end{examplenooutput}

\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

\cmd|\XeTeXfindselectorbyname|
\xarg{font}
\xarg{feature name}
\xarg{selector name}
\desc{This command provides a method to query whether a feature selector
name corresponds to a selector of a specific feature contained in the
font. It returns an integer corresponding to the selector number used
to access the feature selector numerically. If the feature selector does
not exist, the integer is \texttt{-1}.

The indices given by this command and by \cs{XeTeXfindfeaturebyname} can
be used in Graphite fonts to select font features directly (see example
below). Alternatively, they can be used as a means of checking whether a
feature/selector exists before attempting to use it.}
\endcmd

\begin{examplenooutput}
\font\1="[CharisSIL-Regular.ttf]/GR" at 10pt
\def\featname{Uppercase Eng alternates}
\newcount\featcount
\featcount=\XeTeXfindfeaturebyname\1 "\featname"\relax

\def\selecname{Large eng on baseline}
\newcount\seleccount
\seleccount=\XeTeXfindselectorbyname\1 \featcount "\selecname"\relax
The feature selector ‘\selecname’ has index \the\seleccount

\font\2="[CharisSIL-Regular.ttf]/GR:\featname=\selecname" at 10pt
\font\3="[CharisSIL-Regular.ttf]/GR:\the\featcount=\the\seleccount" at 10pt

Activating the feature: \1 Ŋ \2 Ŋ \3 Ŋ
\end{examplenooutput}

\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

\cmd|\XeTeXfindvariationbyname|
\xarg{font}
\xarg{variation name}
\desc{An integer corresponding to the internal index corresponding to
the \xarg{variation name}. This index cannot be used directly but may be
used to error-check that a specified variation name exists before
attempting to use it.}
\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.

Before version 0.9999.0 the following primitives had |\XeTeX| prefix instead of
|\U|, the old names are deprecated and will be removed in the future.

\cmd|\Umathcode|
\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|\Umathcodenum|
\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|\Umathchar|
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Typesets the math character in the \xarg{glyph slot} in the family
specified.}
\endcmd

\cmd|\Umathcharnum|
\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|\Umathchardef|
\xarg{control sequence}
\opteq
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Defines a maths glyph accessible via a control sequence.}
\endcmd

\cmd|\Umathcharnumdef|
\xarg{control sequence}
\opteq
\xarg{type/fam./glyph slot}
\desc{Defines a control sequence for accessing a maths glyph using the
‘bit-packed’ number output by, \eg, \cs{Umathcodenum}. This would
be used to replace legacy code such as
\cs{mathchardef}\cs{foo}\texttt{=}\cs{mathcode}\texttt{`}\cs{\-}.}
\endcmd

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

\cmd|\Udelcodenum|
\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|\Udelimiter|
\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|\Umathaccent|
\oarg{keyword}
\xarg{math type}
\xarg{fam.}
\xarg{glyph slot}
\desc{Typesets the math accent character in the \xarg{glyph slot} in the
family specified. Starting from version 0.9998, \cs{Umathaccent} accepts
optional keyword:\medskip
\begin{optdesc}
\item[fixed] Don’t stretch the accent, the default is to stretch it:
             $\widehat{M}$ vs $\hat{M}$.
\item[bottom] Place the accent below its base. Can be followed by the
             \texttt{fixed} keyword.
\end{optdesc}}
\endcmd

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

\section{Characters}

\cmd|\char|
\xarg{number}
\desc{This and related \TeX\ primitives have been extended to take any
16-bit number, that is, up to 65536. As usual, hex digits must be
specific in uppercase: \cs{char"FF}, not \cs{char"ff}.}
\endcmd

\cmd|\Uchar|
\xarg{number}
\desc{Expands to a character token with specified slot \xarg{number}
(range 0 to 1,114,111) with category code 12. While it looks
superficially like the \TeX\ primitive \cs{char}, \cs{Uchar} is an
expandable operation.}
\endcmd

\begin{example}
\edef\x{\Uchar`\$}
\ttfamily\meaning\x\par
\expandafter\ifcat\x.[`other']\fi
\end{example}

\cmd|\Ucharcat|
\xarg{number}
\xarg{catcode}
\desc{Expands to a character token with slot \xarg{number} and
\xarg{catcode} specified. The values allowed for \xarg{catcode} are:
1--4, 6--8 and 10--13.}
\endcmd

\begin{example}
\edef\x{\Ucharcat`\# 3}
\ttfamily\meaning\x\par
\expandafter\ifcat\x$[`mathshift']\fi
\end{example}

\subsection{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–4095) 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 4095,
wherever there is a boundary between a ‘run’ of characters and something
else — glue, kern, math, box, etc. Special case class 4096 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 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\upshape]a A a \bgroup\color{blue}B\egroup aBa B.B|\par}

\newpage
\section{Encodings}

\cmd|\XeTeXinputnormalization|
\xarg{integer}
\desc{Specify whether \xetex is to perform normalisation on the input
text and, if so, what type of normalisation to use. See
\url{https://unicode.org/reports/tr15/} for a description of Unicode
normalisation. The \<Integer> value can be:\medskip
\begin{optdesc}
\item[0] (default) do not perform normalisation.
\item[1] normalise to NFC form, using precomposed characters where possible
         instead base characters with combining marks.
\item[2] normalise to NFD form, using base characters with combining marks
         instead of precomposed characters.
\end{optdesc}}
\endcmd

\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}

Thanks to Heiko Oberdiek, Paul Isambert, and William Adams for their
help with the documentation in this section.

\cmd|\XeTeXpicfile|
\xarg{filename}
\oarg{ scaled \xarg{int} \|
  xscaled \xarg{int} \|
  yscaled \xarg{int} \| \\\hspace*{2em}
  width \xarg{dimen} \|
  height \xarg{dimen} \|
  rotated \xarg{decimal} }
\desc{Insert an image. See below for explanation of optional arguments.}
\endcmd

\cmd|\XeTeXpdffile|
\xarg{filename}
\oarg{page \xarg{int}}
\oarg{ crop \| media \| bleed \| trim \| art }\\\hspace*{2em}
\oarg{scaled \xarg{int} \|
  xscaled \xarg{int} \|
  yscaled \xarg{int} \|
  width \xarg{dimen} \|\\\hspace*{2em}~
  height \xarg{dimen} \|
  rotated \xarg{decimal}}
\desc{Insert (pages of) a PDF. See below for explanation of optional
arguments.}
\endcmd

\noindent In the graphic/PDF commands above, \xarg{filename} is the
usual file name argument of \cs{input}, \cs{openin}, \etc.  It must not
terminated by \cs{relax} if options are given.  \xarg{int} and
\xarg{dimen} are the usual integer or dimen specifications of regular
\tex.

The rotation is specified in degrees (\ie, an input of ‘|360|’ is full
circle) and the rotation is counterclockwise. The syntax of
\xarg{decimal} require some explanation:
\begin{quote}
\<decimal> $\to$ \<optional signs>\<unsigned decimal>\\
\<unsigned decimal> $\to$ \<normal decimal>
  \| \<coerced dimen> \| \<internal dimen>\\
\<normal decimal> $\to$ \<normal integer> \| \<decimal constant>
\end{quote}
A \xarg{coerced dimen} or \xarg{internal dimen} is interpreted as a number
with unit ‘|pt|’. For example, for a rotation specified with a dimension
\cs{testdim},
\begin{itemize}
\item \verb|\testdim=45pt  | results in a rotation of 45\textdegree,
\item \verb|\testdim=1in    | is 72.27\textdegree, and
\item \verb|\testdim=100sp| is (100/65536)\textdegree.
\end{itemize}
In all cases, the final decimal number for rotation $x$ must be
within the limits $-16384 < x < 16384$.

The \cs{XeTeXpdffile} command takes one more optional argument for
specifying to which ‘box’ the PDF should be cropped before inserting
it (the second optional argument listed in the syntax of
\cs{XeTeXpdffile} above). The PDF standard defines a number of
(rectangular) bounding boxes that may be specified for various
purposes. These are described in the PDF Standard\footnote{Adobe
Systems Incorporated, 2008:\\
\url{https://adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf}} and
summarised below.
\begin{quote}
\begin{description}[style=nextline,leftmargin=1.5cm]
\item [media] the box defining the physical page size.
\item [crop] the box of the page contents for display/printing purposes.
\item [bleed] the box containing the page contents plus whatever extra
space required for printing purposes.
\item [trim] the box of the finished page after trimming the printed
‘bleed box’.
\item [art] the box containing the ‘meaningful content’ of the
page. This could be the crop box with boilerplate text/logos trimmed
off.
\end{description}
\end{quote}
When not specified in the PDF to be inserted, the crop box defaults
to the media box, and the bleed, trim, and art boxes default to the crop
box.

\cmd|\XeTeXpdfpagecount|
\xarg{filename}
\desc{Expands to the number of pages in a PDF file.}
\endcmd


\section{Character protrusion}

\cmd|\XeTeXprotrudechars|
\xarg{integer}
\desc{Equivalent to \cs{pdfprotrudechars} in pdf\TeX{} for controlling
character protrusion or ‘margin kerning’. When set to zero (default), character
protrusion is turned off. When set to one, it is activated but will not affect
line-breaking. When set to two, line-breaking decisions will change as a result
of the character protrusion.}
\begin{example}
\XeTeXprotrudechars=2
\font\rm="[texgyrepagella-regular.otf]"\relax
\rm
\rpcode\font\XeTeXcharglyph\hyphenchar\font=250
\hsize=20mm
a a a a a a a a a a abbabbabb aabbabbabb abbabb
\end{example}
See the pdf\TeX{} documentation for further details.
\endcmd

\cmd|\rpcode| \xarg{font} \xarg{char slot} (integer, $n$)
\desc{Sets the right-side character protrusion value of the \xarg{char slot} in
the specified \xarg{font} to $n/1000$\,em. $n$ is clipped to $\pm1000$.}
\endcmd

\cmd|\lpcode| \xarg{font} \xarg{char slot} (integer, $n$)
\desc{Sets the left-side character protrusion value of the \xarg{char slot} in
the specified \xarg{font} to $n/1000$\,em. $n$ is clipped to $\pm1000$.}
\endcmd


\section{Cross-compatibility with other \TeX\ engines}

All of the major (non-frozen) \TeX\ engines support most of the
functionality described in this section, in one way or another, so that
macro formats (e.g., \LaTeX) can make use of it. Please see the
pdf\TeX{} manual for details (where all these primitive names begin with
\verb|\pdf...|).

\subsection{Geometry}

\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

\subsection{Programming}

\cmd|\expanded|
\xarg{general text}
\desc{Carries out full expansion of a token list like \texttt{\char`\\message},
but it is still expandable.}
\endcmd

\cmd|\ifincsname...[\else...]\fi|
\desc{\tex conditional, 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
which still has its primitive meaning, \ie, has not been redefined or
undefined.}
\endcmd

\cmd|\partokencontext|
\xarg{integer}
\desc{Specifies the cases in which \cs{par}, or the given
\cs{partokenname} (see next) is internally emitted. The default is zero,
yielding the standard behavior. See the \pdftex\ manual for more.}
\endcmd

\cmd|\partokenname|
\xarg{control sequence}
\desc{By default, \TeX\ emits a control sequence \cs{par} at blank lines
and other situations. This command changes the name of what is emitted
to the given control sequence. See the \pdftex\ manual for more.}
\endcmd

\cmd|\primitive|
\xarg{control sequence}
\desc{This command executes the primitive meaning of the following control
sequence, regardless of whether the control sequence has been redefined
or made undefined.  If the primitive was expandable, \cs{primitive} expands
also.  On the other hand, if the control sequence never was a primitive,
nothing happens and no error is raised.}
\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|\showstream|
\xarg{integer}
\desc{If this primitive parameter has a value corresponding to an open output
stream (which has been opened with \cs{openout}), then any
\cs{show}, \cs{showthe}, \cs{showbox} or \cs{showlists}
commands do not write output to the terminal, but instead write to only
the referenced output stream, as if they were written with
\cs{immediate}\cs{write}.}
\endcmd

\cmd|\special shipout |
\xarg{token list}
\desc{With the additional ``keyword'' \texttt{shipout}, expansion of the
\xarg{token listr} is delayed until \cs{shipout}, like
non-\cs{immediate}\cs{write}.}
\endcmd

\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, $-1$ if the
first argument sorts lower (lexicographically) than the second argument,
and~$1$ 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}

\cmd|\tracingstacklevels|
\xarg{integer}
\desc{If this integer parameter is positive, and \cs{tracingmacros}
is also positive, a prefix indicating the macro expansion depth
is output on each relevant log line (e.g., \texttt{\char`\~..}\ at depth~2).
Also, macro logging is truncated at a depth $\ge$ the parameter value.}
\endcmd

\subsection{Randomness}

\cmd|\normaldeviate|
\xarg{number}
\desc{Generate a normally-distributed random integer with a mean of $0$ and
standard deviation $65\,536$. That is, about $68$\% of the time, the result
will be between $−65\,536$ and $65\,536$ (one standard
deviation away from
the mean). About $95\%$ of results will be within two standard deviations, and
$99.7$\% within three.}
\endcmd

\cmd|\randomseed|
\desc{A read-only integer which allows querying of the random seed.}
\endcmd

\cmd|\setrandomseed|
\xarg{number}
\desc{Set the random seed to a specific value, allowing you to replay
sequences of semi-randoms at a later moment.}
\endcmd

\cmd|\uniformdeviate|
\xarg{number}
\desc{Generate a uniformly-distributed random integer value between $0$
(inclusive) and ⟨number⟩ (exclusive).}
\endcmd

\cmd|SOURCE_DATE_EPOCH|
(environment variable)
\desc{If this environment variable is set, its value is used as the current
time in seconds since the usual Unix ``epoch'': the beginning of
1970-01-01, UTC. Negative or non-integer values cause a fatal error.
Thus, a value of \texttt{32} would result in a \texttt{/CreationDate} and
\texttt{/ModDate} values of \texttt{19700101000032Z}. This is useful for
reproducible builds of documents.}
\endcmd

\cmd|FORCE_SOURCE_DATE|
(environment variable)
\par\noindent % no \desc because of _'s
If this is set to~\texttt{1}, \xetex's time-related primitives are also
initialized from the value of \verb|SOURCE_DATE_EPOCH|. These primitives
are \cs{year}, \cs{month}, \cs{day}, and \cs{time}. If
\verb|SOURCE_DATE_EPOCH| is not set, setting \verb|FORCE_SOURCE_DATE|
has no effect. (See the \pdftex\ manual for pathological cases.)
\endcmd

\subsection{Timing}

\cmd|\elapsedtime|
\desc{Return a number that represents the time elapsed from the moment of
the start of the run or the last point at which the timer was reset.
The elapsed time is returned in `scaled seconds', meaning seconds divided by
$65\,536$. If the time exceeds $32\,767$ seconds, the constant value
$2^{31} − 1$ will be returned.}
\endcmd

\cmd|\resettimer|
\desc{Reset the internal timer to $0$.}
\endcmd

\subsection{File handling}

\cmd|\filedump|
\texttt{[offset]} \xarg{number}
\texttt{[length]} \xarg{number}
\barg{\xarg{filename}}
\desc{Expands to a hexadecimal dump of the contents of the file, starting
from position zero and extending to the end of the file unless either an
offset or length are given.}
\endcmd

\cmd|\filemoddate|
\barg{\xarg{filename}}
\desc{Expands to the date the file was last modified in the format
\texttt{D:YYYYMMDDHHMMSS+ZZZZ} as a string.}
\endcmd

\cmd|\filesize|
\barg{\xarg{filename}}
\desc{Expands to the size of the file in bytes.}
\endcmd

\cmd|\mdfivesum|
\oarg{file}
\barg{\xarg{text}}
\desc{Expands to the MD5 sum of the \xarg{text}, or if the \texttt{file}
keyword is given, the MD5 sum of the contents of the file named \xarg{text}.}
\endcmd

\cmd|\input|
\barg{\xarg{filename}}
\desc{As of \TeX~Live 2020, the \cs{input} primitive in all \TeX\
engines, including \xetex, now also accepts a group-delimited filename
argument, as a system-dependent extension, as in
\cs{input\barg{foo.tex}}. The usage of \cs{input} with a standard
space/token-delimited filename is completely unchanged.

This group-delimited argument was previously implemented in \luatex; now
it is available in all engines. ASCII double quote characters
(\texttt{"}) are removed from the filename, but it is otherwise left
unchanged after tokenization.

This extension is unlike most others in that it affects a primitive in
standard \TeX\ (\cs{input}), rather than being related to a new
primitive, command line option, etc. This is allowed because additional
methods of recognizing filenames are explicitly mentioned in
\texttt{tex.web} as acceptable system-dependent extensions.

Incidentally, this does not directly affect \LaTeX's \cs{input} command
(which takes a group-delimited argument), as that is a macro
redefinition of the \cs{input} primitive.}
\endcmd


\subsection{Fonts}

\cmd|\pdfmapfile|
\barg{\xarg{map file}}
\desc{Defined in \texttt{xe(la)tex.ini} to place a whatsit special for \texttt{xdvipdfmx} to set a font map file. See the \pdftex user manual for full details.}
\endcmd

\cmd|\pdfmapline|
\barg{\xarg{line from map file}}
\desc{Defined in \texttt{xe(la)tex.ini} to place a whatsit special for \texttt{xdvipdfmx} to set up a font map. See the \pdftex user manual for full details.}
\endcmd

\cmd|\tracinglostchars|
\xarg{integer}
\desc{When set to 3 or larger, a character missing from a font provokes
a full error, not just a diagnostic message (perhaps only in the log
file, depending on \texttt{\char`\\tracingonline}. Also, the missing
character code is always reported in hex, two digits for normal \TeX\
fonts or \texttt{U+....} format for system fonts, in addition to its ASCII
character, if printable.}
\endcmd

\cmd|\suppressfontnotfounderror|
\xarg{integer}
\desc{When set to zero (default) if a font is loaded that cannot be
located by \xetex, an error message results and typesetting is
halted. When set to one, this error message is
suppressed and the font control sequence being defined is set to
\cs{nullfont}.}
\begin{example}
\suppressfontnotfounderror=1
\font\x="ImpossibleFont" at 10pt
\ifx\x\nullfont
  \font\x="[texgyrepagella-regular.otf]" at 10pt
\fi
\x This would be ‘ImpossibleFont’, if it existed.
\end{example}
\endcmd

\subsection{Invoking \xetex}

\xetex\ has many command line options. They are almost all inherited
from the common framework for \TeX\ engines as implemented in Web2C
(its manual is available at \url{https://tug.org/web2c}).

The main exceptions are \verb|-no-pdf|, which tells \xetex\ to output
its XDV (extended DVI) without further processing, and
\verb|-output-driver=|\xarg{cmd}, which processes the XDV output with
\xarg{cmd}; the default is \texttt{xdvipdfmx}.


\section{Engine version}

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

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

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

\end{document}