Debian Codegraph @

texmf-dist/doc/xetex/xetexref/xetex-reference.tex

raw
1 % Copyright for this work included in README.
2 %
3 % This work may be distributed and/or modified under the
4 % conditions of the LaTeX Project Public License, either version 1.3c
5 % of this license or (at your option) any later version.
6 % The latest version of this license is in
7 % https://www.latex-project.org/lppl.txt
8 % and version 1.3 or later is part of all distributions of LaTeX
9 % version 2005/12/01 or later.
10 %
11 % This work has the LPPL maintenance status `maintained'.
12 %
13 % The Current Maintainer of this work is Will Robertson.
14 %
15 % This work consists of the files xetex-reference.tex,
16 % README.txt, and the derived file xetex-reference.pdf.
17
18 \documentclass[12pt]{article}
19
20 \title{The \xetex reference guide\\\url{https://ctan.org/pkg/xetexref}}
21 \author{Will Robertson \and Khaled Hosny \and Karl Berry}
22 \date{\today}
23
24 \tracinglostchars=5
25
26 \usepackage{refstyle} % must load before unicode-math with 2023 LaTeX.
27 % https://tex.stackexchange.com/questions/675145
28
29 \usepackage{fontspec,unicode-math}
30 \setmainfont{texgyrepagella}[
31 Extension = .otf ,
32 UprightFont = *-regular ,
33 ItalicFont = *-italic ,
34 BoldFont = *-bold ,
35 BoldItalicFont = *-bolditalic ,
36 Scale=MatchLowercase
37 ]
38 \setsansfont{texgyreheros}[
39 Extension = .otf ,
40 UprightFont = *-regular ,
41 ItalicFont = *-italic ,
42 BoldFont = *-bold ,
43 BoldItalicFont = *-bolditalic ,
44 Scale=MatchLowercase
45 ]
46 \iffalse \setmonofont{inconsolata}[
47 Scale=MatchLowercase,
48 StylisticSet=3, % <- straight quotes
49 AutoFakeSlant=.2]\fi
50 \setmathfont{texgyrepagella-math.otf}
51
52 \usepackage{calc,fancyvrb,hyperref,varioref,verbatim,xcolor,hologo,xspace}
53 \usepackage{geometry}
54 %\geometry{screen,margin=3cm}
55
56 \newcommand\tex {\hologo{TeX}\xspace}
57 \newcommand\xetex {\hologo{XeTeX}\xspace}
58 \newcommand\pdftex {\hologo{pdfTeX}\xspace}
59 \newcommand\luatex {\hologo{LuaTeX}\xspace}
60 \newcommand\latex {\hologo{LaTeX}\xspace}
61 \newcommand\context{\hologo{ConTeXt}\xspace}
62
63 \hypersetup{
64 colorlinks,
65 linkcolor=black,
66 urlcolor=black,
67 pdfsubject={The XeTeX reference guide},
68 pdfauthor={Will Robertson \& Khaled Hosny \& Karl Berry},
69 pdfkeywords={xetex, tex, typesetting, unicode, math, opentype, graphite, aat}
70 }
71
72 \usepackage[it]{titlesec}
73 \usepackage{enumitem}
74 \setlist{nolistsep}
75
76 \newenvironment{optdesc}
77 {\begin{description}[font=\ttfamily,style=nextline,leftmargin=1.5cm]}
78 {\end{description}}
79
80 \newcommand\cmd{%
81 \noindent
82 \begin{trivlist}\item[]
83 \SaveVerb[%
84 aftersave={%
85 \begin{minipage}{\linewidth}
86 \parindent=2em\relax\noindent
87 \UseVerb{CMD}}]{CMD}}
88 \edef\|{|}
89 \DefineShortVerb{\|}
90 \newcommand\xarg[1]{$\langle\hbox{\rmfamily\itshape #1}\rangle$}
91 \def\<#1>{\xarg{#1}}
92 \newcommand\oarg[1]{\texttt{[\,#1\,]}}
93 \newcommand\barg[1]{\mbox{{\tt\char`\{\,}#1\,{\tt\char`\}}}}% braced arg
94 \newcommand\desc[1]{\par\noindent\ignorespaces#1\par}
95 \def\endcmd{%
96 \end{minipage}
97 \end{trivlist}}
98
99 \def\cs#1{\texttt{\textbackslash#1}}
100
101 \newsavebox\verbatimbox
102 \edef\examplefilename{\jobname.example}
103 \newlength\exampleindent
104 \setlength\exampleindent{1em}
105
106 \newenvironment{examplenooutput}
107 {\wlog{^^Jstarting examplenooutput at line \the\inputlineno}
108 \VerbatimEnvironment
109 \begin{VerbatimOut}{\examplefilename}}
110 {\end{VerbatimOut}
111 \def\typesetoutput{[No output for the example, since no AAT or
112 Graphite fonts are available.}
113 \typesetexample}
114
115 \newenvironment{example}
116 {\wlog{^^Jstarting example at line \the\inputlineno}
117 \VerbatimEnvironment
118 \begin{VerbatimOut}{\examplefilename}}
119 {\end{VerbatimOut}
120 \def\typesetoutput{\color[rgb]{0.7,0,0}\input\examplefilename\relax}%
121 \typesetexample}
122
123
124 \newcommand\typesetexample{%
125 \begin{trivlist}\item[]
126 \vrule
127 \hspace{\exampleindent}
128 \begin{minipage}{\linewidth-\exampleindent-\exampleindent}
129 \hfuzz=24pt % italic small caps example has overfull line
130 \textit{Example:}\par
131 \vspace{0.4\baselineskip}
132 \BVerbatimInput[fontsize=\small]{\examplefilename}\par
133 \vspace{0.4\baselineskip}
134 \typesetoutput
135 \end{minipage}\par
136 \end{trivlist}}
137
138
139 \let\strong\textbf
140 \newcommand\hlink[2]{\href{#1}{#2}\footnote{\url{#1}}}
141
142 \let\latin\relax % let existing font continue
143 \def\eg{\latin{e.g.}}
144 \def\ie{\latin{i.e.}}
145 \def\Eg{\latin{E.g.}}
146 \def\Ie{\latin{I.e.}}
147 \def\etc{\@ifnextchar.{\latin{etc}}{\latin{etc.}\@}}
148
149 \def\opteq{\unskip\,\textcolor{gray}{[\textcolor{black}{=}]}\,}
150
151 \setlength\parskip{0pt}
152 \setlength\parindent{2em}
153 \raggedbottom
154
155 \begin{document}
156 \maketitle
157
158 \vfill
159
160 \section*{Introduction}
161
162 This document serves as a reference for additional features of \xetex.
163 It is not a users' guide. Much of the functionality addressed here is
164 provided in abstracted form in various \latex packages and \context
165 modules.
166
167 The descriptions here are intended to be a reasonably complete, though
168 terse, list of the new primitives and features of \xetex.
169
170 For contributions (very welcome!), bug reports, etc., see links from
171 the CTAN package page: \url{https://ctan.org/pkg/xetexref}.
172
173 \section*{License}
174
175 This work, is distributed under the terms of the LaTeX Project Public License
176 (\url{https://www.latex-project.org/lppl.txt}).
177
178 This basically means you are free to re-distribute this file as you
179 wish; you may also make changes to this file or use its contents for
180 another purpose, in which case you should make it clear, by way of a
181 name-change or some other means, that your changed version is a modified
182 version of the original. Please read the license text for more detailed
183 information.
184
185 \vfill\vfill\vfill\null
186
187 \newpage
188 \tableofcontents
189
190 \section{The \cs{font} command}
191
192 Traditionally, fonts were selected in \tex like this:
193 |\font\1=|\xarg{tfm name} \xarg{\tex font options}, where the \xarg{\tex
194 font options} included possibilities such as
195 \ ‘| at 10pt|’ \
196 or \ ‘| scaled 1200|’,
197 with evident meaning. This syntax still works, but it has been greatly
198 extended in \xetex.
199
200 The extended syntax looks schematically like this:
201
202 \begin{quote}
203 |\font\1="|\xarg{font identifier}
204 \xarg{font options}%
205 |:|\xarg{font features}%
206 |"|\ \xarg{\tex font options}
207 \end{quote}
208
209 \noindent Each part of this command is discussed in the following, but
210 here is an overview, starting from the end:
211
212 \begin{itemize}
213 \item The \xarg{\tex font options} are unchanged from traditional \tex.
214
215 \item The ASCII double quote character |"| (hex 0x22) surrounds any font
216 definition using the extended syntax.
217
218 \item The \xarg{font features} are an optional list of names,
219 comma or semi-colon separated, preceded by an ASCII colon |:| (0x3a).
220
221 \item The \xarg{font options} are an optional list of specifiers which
222 can only be used with system fonts (see next).
223
224 \item The \xarg{font identifier} is the only mandatory part of the
225 above syntax. If it is given in square brackets, (\eg,
226 |\font\1="[lmroman10-regular]"|), it is taken as a font file name.
227 Without brackets, the name is looked up as both a file name and a system
228 font name.
229
230 \end{itemize}
231
232 This distinction between file name lookups and system font name lookups
233 is crucial to understanding \xetex's behavior and to writing portable
234 documents (in short: don't use system fonts).
235
236 System font name lookups use, except on mac~OS, the
237 |fontconfig| library; running |fc-list| should show you the font names
238 available. \Eg,
239 \begin{quote}\small
240 |\font\1="Liberation Serif"| \hfill \emph{look for OS-installed font}
241 \end{quote}
242
243 Fonts have many internal names, and \xetex\ does the system font lookups
244 in the following order:
245 \vskip1ex
246 \begin{itemize}
247 \item Full Name;
248 \item if the name has a hyphen, it is split into Family-Style pair then matched;
249 \item PostScript Name;
250 \item Family Name, if there is more than one match;
251 \begin{itemize}
252 \item look for font with “regular” bit set in OS/2 table, if no match;
253 \item look for font with style “Regular”, “Plain”, “Normal” or “Roman”, in that order.
254 \end{itemize}
255 \end{itemize}
256 \bigskip
257
258 When using a file name, the |xdvipdfmx| driver must be used (this is the
259 default). The current directory and the |texmf| trees are searched for
260 files matching the name, or the path may be embedded in the font
261 declaration, as usual with |kpathsea|. \Eg,
262 \begin{quote}\small
263 |\font\1="[lmroman10-regular]"| \hfill
264 {\em find |lmroman10-regular.otf| in any tree}
265 |\font\2="[/myfonts/fp9r8a]"| \hfill
266 {\em look for |fp9r8a| only in |/myfonts/|}
267 \end{quote}
268
269 A file with either an |.otf|, |.ttf| or |.pfb| extension (in that order) will be found. The
270 extension can also be specified explicitly.
271
272 \subsection{Font collection files}
273
274 One more special case about the \xarg{font identifier}: if the file is a
275 font collection (\eg, |.ttc| or |.dfont|), the index of the font can be
276 specified using a colon followed by zero-based font index inside the
277 square brackets (in contrast to the font features we'll describe soon,
278 which follow a colon outside any square brackets). \Eg,
279 \begin{quote}\small
280 |\font\2="[myfont.ttc:1]"| \hfill {\em load the second font from |myfont.ttc| file}
281 \end{quote}
282
283
284 \subsection{Font options: For OS-selected fonts only}
285
286 The following \xarg{font options} are only applicable when the font is selected
287 through the operating system (\ie, without square brackets):
288 \begin{optdesc}
289 \item[/B] Use the bold version of the selected font.
290 \item[/I] Use the italic version of the selected font.
291 \item[/BI] Use the bold italic version of the selected font.
292 \item[/IB] Same as \texttt{/BI}.
293 \item[/S=$x$] Use the version of the selected font corresponding to the
294 optical size $x$\,pt.
295 \end{optdesc}
296
297 The following \xarg{font options} control which `renderer' \xetex uses to interface with the font:
298 \begin{optdesc}
299 \item[/AAT] Explicitly use the AAT renderer (Mac~OS~X only).
300 \item[/OT] Explicitly use the OpenType renderer (new in 0.9999).
301 \item[/GR] Explicitly use the Graphite renderer.%
302 \footnote{\raggedright \url{https://scripts.sil.org/cms/scripts/page.php?site_id=projects&item_id=graphite_home}}
303 \item[/ICU] Explicitly use the OpenType renderer (deprecated since 0.9999).
304 \end{optdesc}
305
306
307 \subsection{Font features: For all fonts}
308
309 The \xarg{font features} is a comma or semi-colon separated list
310 activating or deactivating various OpenType, Graphite, or AAT font
311 features; these vary by font. In contrast to font options,
312 features work whether the font is selected by file name or through the
313 operating system.
314
315 The \xetex utility files \path{aat-info.tex} and
316 \path{opentype-info.tex} provide lists of supported features for a given
317 font (see comments at the top of each).
318
319 \subsubsection{Font features specific to OpenType, Graphite, or AAT}
320
321 OpenType font features are usually specified with
322 \hlink{https://www.microsoft.com/typography/otspec/featuretags.htm}{standard
323 tags} in the \cs{font} command. They may be either comma- or
324 semicolon-separated, and prefixed with a |+| to turn them on and a |-|
325 to turn them off, optionally followed by |=| and a 0-based index for
326 selecting alternates from multiple alternates features (ignored for |-|
327 prefixed tags).
328
329 \begin{example}
330 \font\liber="[LinLibertine_RI.otf]/I=5:+smcp" at 12pt
331 \liber This is the OpenType font Linux Libertine in italic with small caps.
332 \end{example}
333
334 OpenType features can be activated by default:
335
336 \begin{example}
337 \font\antt="[AntykwaTorunska-Regular.otf]" at 12pt \antt 0
338 \font\antt="[AntykwaTorunska-Regular.otf]:+aalt=0" at 12pt \antt 0
339 \font\antt="[AntykwaTorunska-Regular.otf]:+aalt=1" at 12pt \antt 0
340 \font\antt="[AntykwaTorunska-Regular.otf]:+aalt=2" at 12pt \antt 0
341 \font\antt="[AntykwaTorunska-Regular.otf]:+aalt=3" at 12pt \antt 0
342 \font\antt="[AntykwaTorunska-Regular.otf]:+aalt=4" at 12pt \antt 0
343 \end{example}
344
345 AAT font features and Graphite font features are specified by strings
346 within each font rather than standardised tags. Therefore, even
347 equivalent features can and do have different names in different fonts.
348
349 \begin{examplenooutput}
350 \font\gra="[CharisSIL-Regular.ttf]/GR:Small Caps=True" at 12pt
351 \gra This is the Graphite font Charis SIL with small caps.
352 \end{examplenooutput}
353
354 \subsubsection{Features for all fonts}
355
356 Some font features may be applied for any font. These are
357 \begin{optdesc}
358
359 \item[color={\slshape RRGGBB}{[{\slshape TT}]}]
360 Triple pair of hex values to specify the colour in RGB space, with an
361 optional value for the transparency.
362
363 \begin{example}
364 \font\9="[lmsans10-regular.otf]:color=0000FF,mapping=tex-text"
365 \9 A sans blue quoted em-dash: ``---''.
366 \end{example}
367
368 \item[embolden=$x$]
369 Increase the envelope of each glyph by the set amount (this makes the
370 letters look ‘more bold’). $x=0$ corresponds to no change; $x=1.5$ is a
371 good default value.
372
373 \item[extend=$x$]
374 Stretch each glyph horizontally by a factor of $x$ (\ie, $x=1$
375 corresponds to no change).
376
377 \item[letterspace=$x$]
378 Adds $x/S$ space between letters in words, where $S$ is the font size.
379
380 \item[mapping=\textsl{<font map>}]
381 Uses the specified font mapping for this font. This uses the TECKit
382 engine to transform Unicode characters in the last-minute processing
383 stage of the source. For example, |mapping=tex-text| will enable the
384 classical mappings from ASCII |``---''| to proper typographical
385 glyphs “—”, and so on.
386
387 \item[slant=$x$]
388 Slant each glyph by the set amount. $x=0$ corresponds to no change;
389 $x=0.2$ is a good default value. The slant is given by $x=R/S$ where $R$
390 is the displacement of the top edge of each glyph and $S$ is the point
391 size.
392
393 \end{optdesc}
394
395 \subsubsection{OpenType script and language support}\seclabel{script}
396
397 OpenType font features (and font behavior) can vary by
398 \hlink{https://www.microsoft.com/typography/otspec/scripttags.htm}{script}
399 (‘alphabet’) and by
400 \hlink{https://www.microsoft.com/typography/otspec/languagetags.htm}{language}.
401 These are selected with four and three letter tags, respectively.
402
403 \begin{optdesc}
404 \item[script=\textsl{<script tag>}] Selects the font script.
405 \item[language=\textsl{<lang tag>}] Selects the font language.
406 \end{optdesc}
407
408 \subsubsection{Multiple Master and Variable Axes AAT font support}
409
410 \begin{optdesc}
411 \item[weight=$x$] Selects the normalised font weight, $x$.
412 \item[width=$x$] Selects the normalised font width, $x$.
413 \item[optical size=$x$] Selects the optical size, $x$\,pt. Note the
414 difference between the \texttt{/S} font option, which selects discrete
415 fonts.
416 \end{optdesc}
417
418 \subsubsection{Vertical typesetting}
419 \begin{optdesc}
420 \item[vertical]
421 Enables glyph rotation in the output so vertical typesetting can be performed.
422 \end{optdesc}
423
424 \section{Font primitives}
425
426 \cmd|\XeTeXtracingfonts|
427 \desc{If nonzero, reports where fonts are found in the log file.}
428 \endcmd
429
430 \cmd|\XeTeXfonttype|
431 \xarg{font}
432 \desc{
433 Expands to a number corresponding to which renderer is used for a
434 \xarg{font}:
435 \begin{optdesc}
436 \item [0] for \tex (a legacy TFM-based font);
437 \item [1] for AAT;
438 \item [2] for OpenType;
439 \item [3] for Graphite.
440 \end{optdesc}
441 }
442 \endcmd
443
444 \begin{example}
445 \newcommand\whattype[1]{%
446 \texttt{\fontname#1} is rendered by
447 \ifcase\XeTeXfonttype#1\TeX\or AAT\or OpenType\or Graphite\fi.\par}
448 \font\1="cmr10"
449 \font\2="[CharisSIL-Regular.ttf]"
450 \font\3="[CharisSIL-Regular.ttf]/OT"
451 \whattype\1 \whattype\2 \whattype\3
452 \end{example}
453
454 \cmd|\XeTeXfirstfontchar|
455 \xarg{font}
456 \desc{Expands to the code of the first character in \xarg{font}.}
457 \endcmd
458
459 \cmd|\XeTeXlastfontchar|
460 \xarg{font}
461 \desc{Expands to the code of the last character in \xarg{font}.}
462 \endcmd
463
464 \begin{example}
465 \font\1="[CharisSIL-Regular.ttf]"\1
466 The first character in Charis SIL is: "\char\XeTeXfirstfontchar\1"
467 and the last character is: "\char\XeTeXlastfontchar\1".
468 \end{example}
469
470 \cmd|\XeTeXglyph|
471 \xarg{glyph slot}
472 \desc{Inserts the glyph in \xarg{glyph slot} of the current font. \strong{Font
473 specific}, so will give different output for different fonts and
474 possibly even different versions of the same font.}
475 \endcmd
476
477 \cmd|\XeTeXcountglyphs|
478 \xarg{font}
479 \desc{The count of the number of glyphs in the specified \xarg{font}.}
480 \endcmd
481
482 \cmd|\XeTeXglyphname|
483 \xarg{font}
484 \xarg{glyph slot}
485 \desc{Expands to the name of the glyph in \xarg{glyph slot} of \xarg{font}.
486 \strong{Font specific}, so will give different output for different fonts and
487 possibly even different versions of the same font.}
488 \endcmd
489
490 \cmd|\XeTeXglyphindex|
491 |"|\xarg{glyph name}|"| \xarg{space} \emph{or} \cs{relax}
492 \desc{Expands to the glyph slot corresponding to the (possibly
493 font specific) \xarg{glyph name} in the currently selected font. Only
494 works for TrueType fonts (or TrueType-based OpenType fonts) at
495 present. Use \texttt{fontforge} or similar to discover glyph names.}
496 \endcmd
497
498 \cmd|\XeTeXcharglyph|
499 \xarg{char code}
500 \desc{Expands to the default glyph number of character \xarg{char code}
501 in the current font, or 0 if the character is not available in the
502 font.}
503 \endcmd
504
505 \begin{example}
506 \font\1="[CharisSIL-Regular.ttf]"\1
507 The glyph slot in Charis SIL for the Yen symbol is:
508 \the\XeTeXglyphindex"yen" . % font-specific glyph name
509 Or: \the\XeTeXcharglyph"00A5. % unicode character slot
510
511 This glyph may be typeset with the font-specific glyph slot:
512 \XeTeXglyph150,
513 or the Unicode character slot:
514 \char"00A5.
515 \end{example}
516
517 \cmd|\XeTeXglyphbounds|
518 \xarg{edge} \xarg{glyph slot}
519 \desc{Expands to a dimension corresponding to one of the bounds of a
520 glyph, where \xarg{edge} is an integer from 1 to~4 indicating the
521 left/top/right/bottom edge respectively, and \xarg{glyph slot} is an
522 integer glyph index in the current font (only valid for non TFM-based
523 fonts).
524
525 The left and right measurements are the glyph sidebearings, measured
526 ‘inwards’ from the origin and advance respectively, so for a glyph that
527 fits completely within its ‘cell’ they will both be positive; for a
528 glyph that ‘overhangs’ to the left or right, they will be negative. The
529 actual width of the glyph’s bounding box, therefore, is the character
530 width (advance) minus both these sidebearings.
531
532 The top and bottom measurements are measured from the baseline, like
533 \tex’s height and depth; the height of the bounding box is the sum of
534 these two dimensions.}
535 \endcmd
536
537 \begin{example}
538 \def\shadebbox#1{%
539 \leavevmode\rlap{%
540 \dimen0=\fontcharwd\font`#1%
541 \edef\gid{\the\XeTeXcharglyph`#1}%
542 \advance\dimen0 by -\XeTeXglyphbounds1 \gid
543 \advance\dimen0 by -\XeTeXglyphbounds3 \gid
544 \kern\XeTeXglyphbounds1 \gid
545 \special{color push rgb 1 1 0.66667}%
546 \vrule width \dimen0
547 height \XeTeXglyphbounds2 \gid
548 depth \XeTeXglyphbounds4 \gid
549 \special{color pop}%
550 \kern\XeTeXglyphbounds3 \gid}%
551 #1}
552
553 \noindent
554 \font\x="[CharisSIL-Italic.ttf]" at 24pt \x
555 \shadebbox{A} \shadebbox{W} \shadebbox{a} \shadebbox{f}
556 \shadebbox{;} \shadebbox{*} \shadebbox{=}
557 \end{example}
558
559 \cmd|\XeTeXuseglyphmetrics|
560 \desc{Counter to specify if the height and depth of characters are taken
561 into account while typesetting ($\ge\mathtt1$). Otherwise ($<\mathtt1$),
562 a single height and depth for the entire alphabet is used. Gives better
563 output but is slower. Activated ($\ge\mathtt1$) by default.}
564 \endcmd
565
566 \begin{example}
567 \XeTeXuseglyphmetrics=0 \fbox{a}\fbox{A}\fbox{j}\fbox{J} vs.
568 \XeTeXuseglyphmetrics=1 \fbox{a}\fbox{A}\fbox{j}\fbox{J}
569 \end{example}
570
571 \cmd|\XeTeXgenerateactualtext|
572 \xarg{integer}
573 \desc{Controls the output of \texttt{/ActualText} entry. Default is 0.
574 When set to 1, the \texttt{/ActualText} entry is added to the output PDF
575 for better copy/paste and search in PDF viewers.}
576 \endcmd
577
578 \subsection{OpenType fonts}
579
580 \cmd|\XeTeXOTcountscripts|
581 \xarg{font}
582 \desc{Expands to the number of scripts in the \xarg{font}.}
583 \endcmd
584
585 \cmd|\XeTeXOTscripttag|
586 \xarg{font}
587 \xarg{integer, $n$}
588 \desc{Expands to the $n$-th script tag of \xarg{font}.}
589 \endcmd
590
591 \cmd|\XeTeXOTcountlanguages|
592 \xarg{font}
593 \xarg{script tag}
594 \desc{Expands to the number of languages in the script of \xarg{font}.}
595 \endcmd
596
597 \cmd|\XeTeXOTlanguagetag|
598 \xarg{font}
599 \xarg{script tag}
600 \xarg{integer, $n$}
601 \desc{Expands to the $n$-th language tag in the script of \xarg{font}.}
602 \endcmd
603
604 \cmd|\XeTeXOTcountfeatures|
605 \xarg{font}
606 \xarg{script tag}
607 \xarg{language tag}
608 \desc{Expands to the number of features in the language of a script of \xarg{font}.}
609 \endcmd
610
611 \cmd|\XeTeXOTfeaturetag|
612 \xarg{font}
613 \xarg{script tag}
614 \xarg{language tag}
615 \xarg{integer, $n$}
616 \desc{Expands to the $n$-th feature tag in the language of a script of \xarg{font}.}
617 \endcmd
618
619
620 \subsection{AAT and Graphite fonts}
621
622 These commands apply to AAT and Graphite fonts; for other kinds of
623 fonts, they produce an error.
624
625 \subsubsection{Features}
626
627 \cmd|\XeTeXcountfeatures|
628 \xarg{font}
629 \desc{Expands to the number of features in the \xarg{font}.}
630 \endcmd
631
632 \cmd|\XeTeXfeaturecode|
633 \xarg{font}
634 \xarg{integer, $n$}
635 \desc{Expands to the feature code for the $n$-th feature in the \xarg{font}.}
636 \endcmd
637
638 \cmd|\XeTeXfeaturename|
639 \xarg{font}
640 \xarg{feature code}
641 \desc{Expands to the name corresponding to the \xarg{feature code} in
642 the \xarg{font}.}
643 \endcmd
644
645 \cmd|\XeTeXisexclusivefeature|
646 \xarg{font}
647 \xarg{feature code}
648 \desc{Expands to a number greater than zero if the feature of a font is
649 exclusive (can only take a single selector).}
650 \endcmd
651
652 \cmd|\XeTeXfindfeaturebyname|
653 \xarg{font}
654 \xarg{feature name}
655 \desc{This command provides a method to query whether a feature name
656 corresponds to a feature contained in the font. It returns an integer
657 corresponding to the feature number used to access the feature
658 numerically. If the feature does not exist, the integer is
659 \texttt{-1}. Also see \cs{XeTeXfindselectorbyname}.}
660 \endcmd
661
662 \begin{examplenooutput}
663 \font\1="[CharisSIL-Regular.ttf]/GR" at 10pt
664 \def\featname{Uppercase Eng alternates}
665 The feature ‘\featname’ has index
666 \the\XeTeXfindfeaturebyname\1 "\featname"\relax
667 \end{examplenooutput}
668
669 \subsubsection{Feature selectors}
670
671 \cmd|\XeTeXcountselectors|
672 \xarg{font}
673 \xarg{feature}
674 \desc{Expands to the number of selectors in a \xarg{feature} of a \xarg{font}.}
675 \endcmd
676
677 \cmd|\XeTeXselectorcode|
678 \xarg{font}
679 \xarg{feature code}
680 \xarg{integer, $n$}
681 \desc{Expands to the selector code for the $n$-th selector in a
682 \xarg{feature} of a \xarg{font}.}
683 \endcmd
684
685 \cmd|\XeTeXselectorname|
686 \xarg{font}
687 \xarg{feature code}
688 \xarg{selector code}
689
690 \desc{Expands to the name corresponding to the \xarg{selector code} of a
691 feature of a \xarg{font}.}
692 \endcmd
693
694 \cmd|\XeTeXisdefaultselector|
695 \xarg{font}
696 \xarg{feature code}
697 \xarg{selector code}
698 \desc{Expands to a number greater than zero if the selector of a feature
699 of a font is on by default.}
700 \endcmd
701
702 \cmd|\XeTeXfindselectorbyname|
703 \xarg{font}
704 \xarg{feature code}
705 \xarg{selector name}
706 \desc{This command provides a method to query whether a feature selector
707 name corresponds to a selector of a specific feature contained in the
708 font. It returns an integer corresponding to the selector number used
709 to access the feature selector numerically. If the feature selector does
710 not exist, the integer is \texttt{-1}.
711
712 The indices given by this command and by \cs{XeTeXfindfeaturebyname} can
713 be used in Graphite fonts to select font features directly (see example
714 below). Alternatively, they can be used as a means of checking whether a
715 feature/selector exists before attempting to use it.}
716 \endcmd
717
718 \begin{examplenooutput}
719 \font\1="[CharisSIL-Regular.ttf]/GR" at 10pt
720 \def\featname{Uppercase Eng alternates}
721 \newcount\featcount
722 \featcount=\XeTeXfindfeaturebyname\1 "\featname"\relax
723
724 \def\selecname{Large eng on baseline}
725 \newcount\seleccount
726 \seleccount=\XeTeXfindselectorbyname\1 \featcount "\selecname"\relax
727 The feature selector ‘\selecname’ has index \the\seleccount
728
729 \font\2="[CharisSIL-Regular.ttf]/GR:\featname=\selecname" at 10pt
730 \font\3="[CharisSIL-Regular.ttf]/GR:\the\featcount=\the\seleccount" at 10pt
731
732 Activating the feature: \1 Ŋ \2 Ŋ \3 Ŋ
733 \end{examplenooutput}
734
735 \subsubsection{Variation axes}
736
737 \cmd|\XeTeXcountvariations|
738 \xarg{font}
739 \desc{Expands to the number of variation axes in the \xarg{font}.}
740 \endcmd
741
742 \cmd|\XeTeXvariation|
743 \xarg{font}
744 \xarg{integer, $n$}
745 \desc{Expands to the variation code for the $n$-th feature in the \xarg{font}.}
746 \endcmd
747
748 \cmd|\XeTeXvariationname|
749 \xarg{font}
750 \xarg{variation code}
751 \desc{Expands to the name corresponding to the \xarg{feature code} in
752 the \xarg{font}.}
753 \endcmd
754
755 \cmd|\XeTeXvariationmin|
756 \xarg{font}
757 \xarg{variation code}
758 \desc{Expands to the minimum value of the variation corresponding to the
759 \xarg{variation code} in the \xarg{font}.}
760 \endcmd
761
762 \cmd|\XeTeXvariationmax|
763 \xarg{font}
764 \xarg{variation code}
765 \desc{Expands to the maximum value of the variation corresponding to the
766 \xarg{variation code} in the \xarg{font}.}
767 \endcmd
768
769 \cmd|\XeTeXvariationdefault|
770 \xarg{font}
771 \xarg{variation code}
772 \desc{Expands to the default value of the variation corresponding to the
773 \xarg{variation code} in the \xarg{font}.}
774 \endcmd
775
776 \cmd|\XeTeXfindvariationbyname|
777 \xarg{font}
778 \xarg{variation name}
779 \desc{An integer corresponding to the internal index corresponding to
780 the \xarg{variation name}. This index cannot be used directly but may be
781 used to error-check that a specified variation name exists before
782 attempting to use it.}
783 \endcmd
784
785 \subsection{Contextual adjustment space handling}
786 \cmd|\XeTeXinterwordspaceshaping|
787 \xarg{integer}
788 \desc{Controls the shaping of space characters in context when using
789 native fonts. Defaults to 0 (disabled). Set to 1 for contextual
790 adjustment of space width only, and 2 for full cross-space shaping
791 (e.g., multi-word ligatures).
792
793 When set to 2, each run of text (words and intervening spaces) in a
794 single font will be re-shaped as a unit as a page is shipped out, so
795 setting this register to 2 affects the whole page, not respecting \TeX\
796 grouping.}
797 \endcmd
798
799 \subsection{Maths fonts}
800
801 The primitives described following are extensions of \tex’s 8-bit primitives.
802
803 In the following commands, \xarg{fam.} is a number (0–255) representing
804 font to use in maths. \xarg{math type} is the 0–7 number corresponding
805 to the type of math symbol; see a \tex reference for details.
806
807 Before version 0.9999.0 the following primitives had |\XeTeX| prefix instead of
808 |\U|, the old names are deprecated and will be removed in the future.
809
810 \cmd|\Umathcode|
811 \xarg{char slot}
812 \opteq
813 \xarg{math type}
814 \xarg{fam.}
815 \xarg{glyph slot}
816 \desc{Defines a maths glyph accessible via an input character. Note that
817 the input takes \emph{three} arguments unlike \tex’s \cs{mathcode}.}
818 \endcmd
819
820 \cmd|\Umathcodenum|
821 \xarg{char slot}
822 \opteq
823 \xarg{math type/fam./glyph slot}
824 \desc{Pure extension of \cs{mathcode} that uses a ‘bit-packed’ single
825 number argument. Can also be used to extract the bit-packed mathcode
826 number of the \xarg{char slot} if no assignment is given.}
827 \endcmd
828
829 \cmd|\Umathchar|
830 \xarg{math type}
831 \xarg{fam.}
832 \xarg{glyph slot}
833 \desc{Typesets the math character in the \xarg{glyph slot} in the family
834 specified.}
835 \endcmd
836
837 \cmd|\Umathcharnum|
838 \xarg{type/fam./glyph slot}
839 \desc{Pure extension of \cs{mathchar} that uses a ‘bit-packed’ single
840 number argument. Can also be used to extract the bit-packed mathcode
841 number of the \xarg{char slot} if no assignment is given.}
842 \endcmd
843
844 \cmd|\Umathchardef|
845 \xarg{control sequence}
846 \opteq
847 \xarg{math type}
848 \xarg{fam.}
849 \xarg{glyph slot}
850 \desc{Defines a maths glyph accessible via a control sequence.}
851 \endcmd
852
853 \cmd|\Umathcharnumdef|
854 \xarg{control sequence}
855 \opteq
856 \xarg{type/fam./glyph slot}
857 \desc{Defines a control sequence for accessing a maths glyph using the
858 ‘bit-packed’ number output by, \eg, \cs{Umathcodenum}. This would
859 be used to replace legacy code such as
860 \cs{mathchardef}\cs{foo}\texttt{=}\cs{mathcode}\texttt{`}\cs{\-}.}
861 \endcmd
862
863 \cmd|\Udelcode|
864 \xarg{char slot}
865 \opteq
866 \xarg{fam.}
867 \xarg{glyph slot}
868 \desc{Defines a delimiter glyph accessible via an input character.}
869 \endcmd
870
871 \cmd|\Udelcodenum|
872 \xarg{char slot}
873 \opteq
874 \xarg{fam./glyph slot}
875 \desc{Pure extension of \cs{delcode} that uses a ‘bit-packed’ single
876 number argument. Can also be used to extract the bit-packed delcode
877 number of the \xarg{char slot} if no assignment is given.}
878 \endcmd
879
880 \cmd|\Udelimiter|
881 \xarg{math type}
882 \xarg{fam.}
883 \xarg{glyph slot}
884 \desc{Typesets the delimiter in the \xarg{glyph slot} in the family
885 specified of either \xarg{math type} 4 (opening) or 5 (closing).}
886 \endcmd
887
888 \cmd|\Umathaccent|
889 \oarg{keyword}
890 \xarg{math type}
891 \xarg{fam.}
892 \xarg{glyph slot}
893 \desc{Typesets the math accent character in the \xarg{glyph slot} in the
894 family specified. Starting from version 0.9998, \cs{Umathaccent} accepts
895 optional keyword:\medskip
896 \begin{optdesc}
897 \item[fixed] Don’t stretch the accent, the default is to stretch it:
898 $\widehat{M}$ vs $\hat{M}$.
899 \item[bottom] Place the accent below its base. Can be followed by the
900 \texttt{fixed} keyword.
901 \end{optdesc}}
902 \endcmd
903
904 \cmd|\Uradical|
905 \xarg{fam.}
906 \xarg{glyph slot}
907 \desc{Typesets the radical in the \xarg{glyph slot} in the family specified.}
908 \endcmd
909
910 \section{Characters}
911
912 \cmd|\char|
913 \xarg{number}
914 \desc{This and related \TeX\ primitives have been extended to take any
915 16-bit number, that is, up to 65536. As usual, hex digits must be
916 specific in uppercase: \cs{char"FF}, not \cs{char"ff}.}
917 \endcmd
918
919 \cmd|\Uchar|
920 \xarg{number}
921 \desc{Expands to a character token with specified slot \xarg{number}
922 (range 0 to 1,114,111) with category code 12. While it looks
923 superficially like the \TeX\ primitive \cs{char}, \cs{Uchar} is an
924 expandable operation.}
925 \endcmd
926
927 \begin{example}
928 \edef\x{\Uchar`\$}
929 \ttfamily\meaning\x\par
930 \expandafter\ifcat\x.[`other']\fi
931 \end{example}
932
933 \cmd|\Ucharcat|
934 \xarg{number}
935 \xarg{catcode}
936 \desc{Expands to a character token with slot \xarg{number} and
937 \xarg{catcode} specified. The values allowed for \xarg{catcode} are:
938 1--4, 6--8 and 10--13.}
939 \endcmd
940
941 \begin{example}
942 \edef\x{\Ucharcat`\# 3}
943 \ttfamily\meaning\x\par
944 \expandafter\ifcat\x$[`mathshift']\fi
945 \end{example}
946
947 \subsection{Character classes}
948
949 The idea behind character classes is to define a boundary where tokens
950 can be added to the input stream without explicit markup. It was
951 originally intended to add glue around punctuation to effect correct
952 Japanese typesetting. This feature can also be used to adjust space
953 around punctuation for European traditions. The general nature of this
954 feature, however, lends it to several other useful applications
955 including automatic font switching when small amounts of another
956 language (in another script) is present in the text.
957
958 \cmd|\XeTeXinterchartokenstate|
959 \desc{Counter. If positive, enables the character classes functionality.}
960 \endcmd
961
962 \cmd|\newXeTeXintercharclass|
963 \xarg{control sequence}
964 \desc{Allocates a new interchar class and assigns it to the
965 \xarg{control sequence} argument.}
966 \endcmd
967
968 \cmd|\XeTeXcharclass|
969 \xarg{char slot}
970 \opteq
971 \xarg{interchar class}
972 \desc{Assigns a class corresponding to \xarg{interchar class} (range
973 0–4095) to a \xarg{char slot}. Most characters are class 0 by
974 default. Class 1 is for CJK ideographs, classes 2 and 3 are CJK
975 punctuation. The boundary of a text string is considered class 4095,
976 wherever there is a boundary between a ‘run’ of characters and something
977 else — glue, kern, math, box, etc. Special case class 4096 is ignored;
978 useful for diacritics so I’m told.}
979 \endcmd
980
981 \cmd|\XeTeXinterchartoks|
982 \xarg{interchar class 1}
983 \xarg{interchar class 2}
984 \opteq
985 |{|\xarg{token list}|}|
986 \desc{Defines tokens to be inserted between
987 \xarg{interchar class 1} and \xarg{interchar class 2} (in that order).}
988 \endcmd
989
990 \begin{example}
991 \XeTeXinterchartokenstate = 1
992 \newXeTeXintercharclass \mycharclassa
993 \newXeTeXintercharclass \mycharclassA
994 \newXeTeXintercharclass \mycharclassB
995 \XeTeXcharclass `\a \mycharclassa
996 \XeTeXcharclass `\A \mycharclassA
997 \XeTeXcharclass `\B \mycharclassB
998
999 % between "a" and "A":
1000 \XeTeXinterchartoks \mycharclassa \mycharclassA = {[\itshape}
1001 \XeTeXinterchartoks \mycharclassA \mycharclassa = {\upshape]}
1002
1003 % between " " and "B":
1004 \XeTeXinterchartoks 4095 \mycharclassB = {\bgroup\color{blue}}
1005 \XeTeXinterchartoks \mycharclassB 4095 = {\egroup}
1006
1007 % between "B" and "B":
1008 \XeTeXinterchartoks \mycharclassB \mycharclassB = {.}
1009
1010 aAa A a B aBa BB
1011 \end{example}
1012
1013 \noindent In the above example the input text is typeset as\par
1014 {\centering
1015 \verb|a[\itshape A\upshape]a A a \bgroup\color{blue}B\egroup aBa B.B|\par}
1016
1017 \newpage
1018 \section{Encodings}
1019
1020 \cmd|\XeTeXinputnormalization|
1021 \xarg{integer}
1022 \desc{Specify whether \xetex is to perform normalisation on the input
1023 text and, if so, what type of normalisation to use. See
1024 \url{https://unicode.org/reports/tr15/} for a description of Unicode
1025 normalisation. The \<integer> value can be:\medskip
1026 \begin{optdesc}
1027 \item[0] (default) do not perform normalisation.
1028 \item[1] normalise to NFC form, using precomposed characters where possible
1029 instead of base characters with combining marks.
1030 \item[2] normalise to NFD form, using base characters with combining marks
1031 instead of precomposed characters.
1032 \end{optdesc}}
1033 \endcmd
1034
1035 \cmd|\XeTeXinputencoding|
1036 \xarg{charset name}
1037
1038 \desc{Defines the input encoding of the following text. The argument is
1039 scanned like a filename, so can be surrounded by ASCII single or double
1040 quote characters, but braces should be avoided. If the name is not
1041 predefined, it is passed to the ICU routine \texttt{ucnv\char`_open}.
1042 Details are described at
1043 \url{https://tex.stackexchange.com/questions/324948/}, or see the source
1044 file \texttt{XeTeX\char`\_ext.c}, function
1045 \texttt{getencodingmodeandinfo}. A simple example:}
1046 \begin{example}
1047 \XeTeXinputencoding ISO-8859-1
1048 \end{example}
1049 \endcmd
1050
1051 \cmd|\XeTeXdefaultencoding|
1052 \xarg{charset name}
1053 \desc{Defines the input encoding of subsequent files to be read. Handled
1054 analogously to the above.}
1055 \endcmd
1056
1057 \section{Line breaking}
1058
1059 \cmd|\XeTeXdashbreakstate|
1060 \xarg{integer}
1061 \desc{Specify whether line breaks after en- and em-dashes are
1062 allowed. Off, 0, by default.}
1063 \endcmd
1064
1065 \cmd|\XeTeXlinebreaklocale|
1066 \xarg{locale-id}
1067 \desc{Defines how to break lines for multilingual text.}
1068 \endcmd
1069
1070 \cmd|\XeTeXlinebreakskip|
1071 \xarg{glue}
1072 \desc{Inter-character linebreak stretch.}
1073 \endcmd
1074
1075 \cmd|\XeTeXlinebreakpenalty|
1076 \xarg{integer}
1077 \desc{Inter-character linebreak penalty.}
1078 \endcmd
1079
1080 \cmd|\XeTeXupwardsmode|
1081 \xarg{integer}
1082 \desc{If greater than zero, successive lines of text (and rules, boxes,
1083 etc.) will be stacked upwards instead of downwards.}
1084 \endcmd
1085
1086
1087 \cmd|\XeTeXhyphenatablelength|
1088 \xarg{integer}
1089 \desc{Sets the maximum hyphenatable word length;
1090 the default is 63, for compatibility with classic \TeX.}
1091 \endcmd
1092
1093 \section{Graphics}
1094
1095 Thanks to Heiko Oberdiek, Paul Isambert, and William Adams for their
1096 help with the documentation in this section.
1097
1098 \cmd|\XeTeXpicfile|
1099 \xarg{filename}
1100 \oarg{ scaled \xarg{int} \|
1101 xscaled \xarg{int} \|
1102 yscaled \xarg{int} \| \\\hspace*{2em}
1103 width \xarg{dimen} \|
1104 height \xarg{dimen} \|
1105 rotated \xarg{decimal} }
1106 \desc{Insert an image. See below for explanation of optional arguments.}
1107 \endcmd
1108
1109 \cmd|\XeTeXpdffile|
1110 \xarg{filename}
1111 \oarg{page \xarg{int}}
1112 \oarg{ crop \| media \| bleed \| trim \| art }\\\hspace*{2em}
1113 \oarg{scaled \xarg{int} \|
1114 xscaled \xarg{int} \|
1115 yscaled \xarg{int} \|
1116 width \xarg{dimen} \|\\\hspace*{2em}~
1117 height \xarg{dimen} \|
1118 rotated \xarg{decimal}}
1119 \desc{Insert (pages of) a PDF. See below for explanation of optional
1120 arguments.}
1121 \endcmd
1122
1123 \noindent In the graphic/PDF commands above, \xarg{filename} is the
1124 usual file name argument of \cs{input}, \cs{openin}, \etc. It must not
1125 terminated by \cs{relax} if options are given. \xarg{int} and
1126 \xarg{dimen} are the usual integer or dimen specifications of regular
1127 \tex.
1128
1129 The rotation is specified in degrees (\ie, an input of ‘|360|’ is full
1130 circle) and the rotation is counterclockwise. The syntax of
1131 \xarg{decimal} require some explanation:
1132 \begin{quote}
1133 \<decimal> $\to$ \<optional signs>\<unsigned decimal>\\
1134 \<unsigned decimal> $\to$ \<normal decimal>
1135 \| \<coerced dimen> \| \<internal dimen>\\
1136 \<normal decimal> $\to$ \<normal integer> \| \<decimal constant>
1137 \end{quote}
1138 A \xarg{coerced dimen} or \xarg{internal dimen} is interpreted as a number
1139 with unit ‘|pt|’. For example, for a rotation specified with a dimension
1140 \cs{testdim},
1141 \begin{itemize}
1142 \item \verb|\testdim=45pt | results in a rotation of 45\textdegree,
1143 \item \verb|\testdim=1in | is 72.27\textdegree, and
1144 \item \verb|\testdim=100sp| is (100/65536)\textdegree.
1145 \end{itemize}
1146 In all cases, the final decimal number for rotation $x$ must be
1147 within the limits $-16384 < x < 16384$.
1148
1149 The \cs{XeTeXpdffile} command takes one more optional argument for
1150 specifying to which ‘box’ the PDF should be cropped before inserting
1151 it (the second optional argument listed in the syntax of
1152 \cs{XeTeXpdffile} above). The PDF standard defines a number of
1153 (rectangular) bounding boxes that may be specified for various
1154 purposes. These are described in the PDF Standard\footnote{Adobe
1155 Systems Incorporated, 2008:\\
1156 \url{https://adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf}} and
1157 summarised below.
1158 \begin{quote}
1159 \begin{description}[style=nextline,leftmargin=1.5cm]
1160 \item [media] the box defining the physical page size.
1161 \item [crop] the box of the page contents for display/printing purposes.
1162 \item [bleed] the box containing the page contents plus whatever extra
1163 space required for printing purposes.
1164 \item [trim] the box of the finished page after trimming the printed
1165 ‘bleed box’.
1166 \item [art] the box containing the ‘meaningful content’ of the
1167 page. This could be the crop box with boilerplate text/logos trimmed
1168 off.
1169 \end{description}
1170 \end{quote}
1171 When not specified in the PDF to be inserted, the crop box defaults
1172 to the media box, and the bleed, trim, and art boxes default to the crop
1173 box.
1174
1175 \cmd|\XeTeXpdfpagecount|
1176 \xarg{filename}
1177 \desc{Expands to the number of pages in a PDF file.}
1178 \endcmd
1179
1180
1181 \section{Character protrusion}
1182
1183 \cmd|\XeTeXprotrudechars|
1184 \xarg{integer}
1185 \desc{Equivalent to \cs{pdfprotrudechars} in \pdftex\ for controlling
1186 character protrusion or ‘margin kerning’. When set to zero (default), character
1187 protrusion is turned off. When set to one, it is activated but will not affect
1188 line-breaking. When set to two, line-breaking decisions will change as a result
1189 of the character protrusion.}
1190 \begin{example}
1191 \XeTeXprotrudechars=2
1192 \font\rm="[texgyrepagella-regular.otf]"\relax
1193 \rm
1194 \rpcode\font\XeTeXcharglyph\hyphenchar\font=250
1195 \hsize=20mm
1196 a a a a a a a a a a abbabbabb aabbabbabb abbabb
1197 \end{example}
1198 See the \pdftex\ documentation for further details.
1199 \endcmd
1200
1201 \cmd|\rpcode| \xarg{font} \xarg{char slot} (integer, $n$)
1202 \desc{Sets the right-side character protrusion value of the \xarg{char slot} in
1203 the specified \xarg{font} to $n/1000$\,em. $n$ is clipped to $\pm1000$.}
1204 \endcmd
1205
1206 \cmd|\lpcode| \xarg{font} \xarg{char slot} (integer, $n$)
1207 \desc{Sets the left-side character protrusion value of the \xarg{char slot} in
1208 the specified \xarg{font} to $n/1000$\,em. $n$ is clipped to $\pm1000$.}
1209 \endcmd
1210
1211 \cmd|\rightmarginkern| \xarg{box number}
1212 \desc{Expands to the width of the margin kerning at the right side of
1213 the horizontal list stored in \cs{box} \xarg{box number}.}
1214 \endcmd
1215
1216 \cmd|\leftmarginkern| \xarg{box number}
1217 \desc{Expands to the width of the margin kerning at the left side of
1218 the horizontal list stored in \cs{box} \xarg{box number}.}
1219 \endcmd
1220
1221
1222 \section{Cross-compatibility with other \TeX\ engines}
1223
1224 The major (non-frozen) \TeX\ engines support most of the
1225 functionality described in this section, in one way or another, so that
1226 macro formats (e.g., \LaTeX) can make use of it. Please see the
1227 \pdftex\ manual for details (in \pdftex, almost all these primitive names
1228 begin with \verb|\pdf...|).
1229
1230 \subsection{Geometry}
1231
1232 \cmd|\pdfpageheight|
1233 \xarg{dimension}
1234 \desc{The height of the PDF page.}
1235 \endcmd
1236
1237 \cmd|\pdfpagewidth|
1238 \xarg{dimension}
1239 \desc{The width of the PDF page.}
1240 \endcmd
1241
1242 \cmd|\pdfsavepos|
1243 \desc{Saves the current location of the page in the typesetting stream.}
1244 \endcmd
1245
1246 \cmd|\pdflastxpos|
1247 \desc{Retrieves the horizontal position saved by \texttt{\char`\\pdfsavepos}.}
1248 \endcmd
1249
1250 \cmd|\pdflastypos|
1251 \desc{Retrieves the vertical position saved by \texttt{\char`\\pdfsavepos}.}
1252 \endcmd
1253
1254 \subsection{Programming}
1255
1256 \cmd|\expanded|
1257 \xarg{general text}
1258 \desc{Carries out full expansion of a token list like \texttt{\char`\\message},
1259 but is itself expandable.}
1260 \endcmd
1261
1262 \cmd|\ifincsname...[\else...]\fi|
1263 \desc{\tex conditional, true if the expansion occurs within
1264 \texttt{\char`\\csname ... \char`\\endcsname}.}
1265 \endcmd
1266
1267 \begin{example}
1268 \def\x{\ifincsname y\else hello\fi}
1269 \def\y{goodbye}
1270 \x/\csname\x\endcsname
1271 \end{example}
1272
1273 \cmd|\ifprimitive| \xarg{control sequence} |...[\else...]\fi|
1274 \desc{\tex conditional to test if a control sequence is a primitive
1275 which still has its primitive meaning, \ie, has not been redefined or
1276 undefined.}
1277 \endcmd
1278
1279 \cmd|\ignoreprimitiveerror|
1280 \xarg{integer}
1281 \desc{If set to 1, the \texttt{Infinite glue shrinkage found in box
1282 being split} error becomes a warning. Other values reserved for future
1283 use. Enabled with the \verb|-etex| option, which is the default
1284 configuration.}
1285 \endcmd
1286
1287 \cmd|\partokencontext|
1288 \xarg{integer}
1289 \desc{Specifies the cases in which \cs{par}, or the given
1290 \cs{partokenname} (see next) is internally emitted. The default is zero,
1291 yielding the standard behavior. See the \pdftex\ manual for more.}
1292 \endcmd
1293
1294 \cmd|\partokenname|
1295 \xarg{control sequence}
1296 \desc{By default, \TeX\ emits a control sequence \cs{par} at blank lines
1297 and other situations. This command changes the name of what is emitted
1298 to the given control sequence. See the \pdftex\ manual for more.}
1299 \endcmd
1300
1301 \cmd|\primitive|
1302 \xarg{control sequence}
1303 \desc{This command executes the primitive meaning of the following control
1304 sequence, regardless of whether the control sequence has been redefined
1305 or made undefined. If the primitive was expandable, \cs{primitive} expands
1306 also. On the other hand, if the control sequence never was a primitive,
1307 nothing happens and no error is raised.}
1308 \endcmd
1309
1310 \cmd|\shellescape|
1311 \desc{Read-only status indicating the level of ‘shell escape’
1312 allowed. That is, whether commands are allowed to be executed through
1313 \texttt{\char`\\write18\char`\{...\char`\}}. Expands to zero for off;
1314 one for on (allowed); two is ‘restricted’ (default in TeX Live 2009 and
1315 greater) in which a subset of commands only are allowed.}
1316 \endcmd
1317
1318 \begin{example}
1319 Shell escape \ifnum\shellescape>0 is \else is not \fi enabled.
1320 \end{example}
1321
1322 \cmd|\showstream|
1323 \xarg{integer}
1324 \desc{If this primitive parameter has a value corresponding to an open output
1325 stream (which has been opened with \cs{openout}), then any
1326 \cs{show}, \cs{showthe}, \cs{showbox} or \cs{showlists}
1327 commands do not write output to the terminal, but instead write to only
1328 the referenced output stream, as if they were written with
1329 \cs{immediate}\cs{write}.}
1330 \endcmd
1331
1332 \cmd|\special shipout |
1333 \xarg{token list}
1334 \desc{With the additional ``keyword'' \texttt{shipout}, expansion of the
1335 \xarg{token listr} is delayed until \cs{shipout}, like
1336 non-\cs{immediate}\cs{write}.}
1337 \endcmd
1338
1339 \cmd|\strcmp|
1340 \xarg{arg one}
1341 \xarg{arg two}
1342 \desc{Compares the full expansion of the two token list
1343 arguments. Expands to zero if they are the same, $-1$ if the
1344 first argument sorts lower (lexicographically) than the second argument,
1345 and~$1$ if vice versa.}
1346 \endcmd
1347
1348 \begin{example}
1349 ‘a’ is less than ‘z’: \strcmp{a}{z}
1350
1351 \def\z{a}
1352 The tokens expand before being compared: \strcmp{a}{\z}
1353
1354 \def\a{z}
1355 Therefore, |\a| is greater than |\z|: \strcmp{\a}{\z}
1356
1357 \edef\b{\string b}
1358 Also note that catcodes are ignored: \strcmp{b}{\b}
1359 \end{example}
1360
1361 \cmd|\tracingstacklevels|
1362 \xarg{integer}
1363 \desc{If this integer parameter is positive, and \cs{tracingmacros}
1364 is also positive, a prefix indicating the macro expansion depth
1365 is output on each relevant log line (e.g., \texttt{\char`\~..}\ at depth~2).
1366 Also, macro logging is truncated at a depth $\ge$ the parameter value.}
1367 \endcmd
1368
1369 \subsection{Randomness}
1370
1371 \cmd|\normaldeviate|
1372 \desc{Generate a normally-distributed random integer with a mean of $0$ and
1373 standard deviation $65\,536$. That is, about $68$\% of the time, the result
1374 will be between $−65\,536$ and $65\,536$ (one standard
1375 deviation away from
1376 the mean). About $95\%$ of results will be within two standard deviations, and
1377 $99.7$\% within three.}
1378 \endcmd
1379
1380 \cmd|\randomseed|
1381 \desc{A read-only integer which allows querying of the random seed.}
1382 \endcmd
1383
1384 \cmd|\setrandomseed|
1385 \xarg{number}
1386 \desc{Set the random seed to a specific value, allowing you to replay
1387 sequences of semi-randoms at a later moment.}
1388 \endcmd
1389
1390 \cmd|\uniformdeviate|
1391 \xarg{number}
1392 \desc{Generate a uniformly-distributed random integer value between $0$
1393 (inclusive) and ⟨number⟩ (exclusive).}
1394 \endcmd
1395
1396 \cmd|SOURCE_DATE_EPOCH|
1397 (environment variable)
1398 \desc{If this environment variable is set, its value is used as the current
1399 time in seconds since the usual Unix ``epoch'': the beginning of
1400 1970-01-01, UTC. Negative or non-integer values cause a fatal error.
1401 Thus, a value of \texttt{32} would result in a \texttt{/CreationDate} and
1402 \texttt{/ModDate} values of \texttt{19700101000032Z}. This is useful for
1403 reproducible builds of documents.}
1404 \endcmd
1405
1406 \cmd|FORCE_SOURCE_DATE|
1407 (environment variable)
1408 \desc{If this is set to~\texttt{1}, \xetex's time-related primitives are also
1409 initialized from the value of \texttt{SOURCE\_DATE\_EPOCH}. These primitives
1410 are \cs{year}, \cs{month}, \cs{day}, and \cs{time}. If
1411 \texttt{SOURCE\_DATE\_EPOCH} is not set, setting \texttt{FORCE\_SOURCE\_DATE}
1412 has no effect. (See the \pdftex\ manual for pathological cases.)}
1413 \endcmd
1414
1415 \subsection{Timing}
1416
1417 \cmd|\elapsedtime|
1418 \desc{Return a number that represents the time elapsed from the moment of
1419 the start of the run or the last point at which the timer was reset.
1420 The elapsed time is returned in `scaled seconds', meaning seconds divided by
1421 $65\,536$. If the time exceeds $32\,767$ seconds, the constant value
1422 $2^{31} − 1$ will be returned.}
1423 \endcmd
1424
1425 \cmd|\resettimer|
1426 \desc{Reset the internal timer to $0$.}
1427 \endcmd
1428
1429 \subsection{File handling}
1430
1431 In general: \xetex\ supports Unicode filenames. Before the 2024 release,
1432 characters in filenames were restricted to be on the Basic Multilingual
1433 Plane (character codes $\le$ U+FFFF).
1434
1435 \cmd|\creationdate|
1436 \desc{Expands to the date string \xetex\ uses in the \texttt{/Info}
1437 dictionary of the output PDF document. This corresponds to the date and
1438 time when \xetex\ engine started, \eg\ \creationdate\ for this file. If
1439 \texttt{SOURCE\_DATE\_EPOCH} is set, its value is used for
1440 \cs{creationdate}.}
1441 \endcmd
1442
1443 \cmd|\filedump|
1444 \texttt{[offset]} \xarg{number}
1445 \texttt{[length]} \xarg{number}
1446 \barg{\xarg{filename}}
1447 \desc{Expands to a hexadecimal dump of the contents of the file, starting
1448 from position zero and extending to the end of the file unless either an
1449 offset or length are given.}
1450 \endcmd
1451
1452 \cmd|\filemoddate|
1453 \barg{\xarg{filename}}
1454 \desc{Expands to the date the file was last modified in the same format
1455 as for \cs{creationdate} as a string. If both \texttt{SOURCE\_DATE\_EPOCH}
1456 and \texttt{FORCE\_SOURCE\_DATE} are set, \cs{filemoddate} returns a value
1457 in UTC, ending in \texttt{Z}, regardless of the values of environment
1458 variables.}
1459 \endcmd
1460
1461 \cmd|\filesize|
1462 \barg{\xarg{filename}}
1463 \desc{Expands to the size of the file in bytes.}
1464 \endcmd
1465
1466 \cmd|\mdfivesum|
1467 \oarg{file}
1468 \barg{\xarg{text}}
1469 \desc{Expands to the MD5 sum of the \xarg{text}, or if the \texttt{file}
1470 keyword is given, the MD5 sum of the contents of the file named \xarg{text}.}
1471 \endcmd
1472
1473 \cmd|\input|
1474 \barg{\xarg{filename}}
1475 \desc{As of \TeX~Live 2020, the \cs{input} primitive in all \TeX\
1476 engines, including \xetex, now also accepts a group-delimited filename
1477 argument, as a system-dependent extension, as in
1478 \cs{input\barg{foo.tex}}. The usage of \cs{input} with a standard
1479 space/token-delimited filename is completely unchanged.
1480
1481 This group-delimited argument was previously implemented in \luatex; now
1482 it is available in all engines. ASCII double quote characters
1483 (\texttt{"}) are removed from the filename, but it is otherwise left
1484 unchanged after tokenization.
1485
1486 We say ``group-delimited'' because, as usual with \TeX\ arguments, the
1487 beginning and ending delimiters are any characters of catcode 1 and 2,
1488 respectively; they don't define a group that affects the semantic
1489 nesting level.
1490
1491 This extension is unlike most others in that it affects a primitive in
1492 standard \TeX\ (\cs{input}), rather than being related to a new
1493 primitive, command line option, etc. This is allowed because additional
1494 methods of recognizing filenames are explicitly mentioned in
1495 \texttt{tex.web} as acceptable system-dependent extensions.
1496
1497 Incidentally, this does not directly affect \LaTeX's \cs{input} command
1498 (which also takes a group-delimited argument), as that is a macro
1499 redefinition of the \cs{input} primitive.}
1500 \endcmd
1501
1502
1503 \subsection{Fonts}
1504
1505 \cmd|\pdfmapfile|
1506 \barg{\xarg{map file}}
1507 \desc{Defined in \texttt{xe(la)tex.ini} to place a whatsit special for
1508 \texttt{xdvipdfmx} to set a font map file. See the \pdftex user manual
1509 for full details.}
1510 \endcmd
1511
1512 \cmd|\pdfmapline|
1513 \barg{\xarg{line from map file}}
1514 \desc{Defined in \texttt{xe(la)texA.ini} to place a whatsit special for
1515 \texttt{xdvipdfmx} to set up a font map. See the \pdftex user manual for
1516 full details.}
1517 \endcmd
1518
1519 \cmd|\tracinglostchars|
1520 \xarg{integer}
1521 \desc{When set to 3 or larger, a character missing from a font provokes
1522 a full error, not just a diagnostic message (perhaps only in the log
1523 file, depending on \texttt{\char`\\tracingonline}. Also, the missing
1524 character code is always reported in hex, two digits for normal \TeX\
1525 fonts or \texttt{U+....} format for system fonts, in addition to its ASCII
1526 character, if printable.}
1527 \endcmd
1528
1529 \cmd|\suppressfontnotfounderror|
1530 \xarg{integer}
1531 \desc{When set to zero (default) if a font is loaded that cannot be
1532 located by \xetex, an error message results and typesetting is
1533 halted. When set to one, this error message is
1534 suppressed and the font control sequence being defined is set to
1535 \cs{nullfont}.}
1536 \begin{example}
1537 \suppressfontnotfounderror=1
1538 \font\x="ImpossibleFont" at 10pt
1539 \ifx\x\nullfont
1540 \font\x="[texgyrepagella-regular.otf]" at 10pt
1541 \fi
1542 \x This would be ‘ImpossibleFont’, if it existed.
1543 \end{example}
1544 \endcmd
1545
1546 \subsection{Output}
1547
1548 \xetex\ outputs an extended DVI format, called XDV. Normally, \xetex\
1549 internally invokes the program \texttt{xdvipdfmx} to generate PDF from
1550 this. This can be overridden with the command line options mentioned
1551 just below.
1552
1553 Thus, the version of PDF format that gets output is controlled by
1554 \texttt{xdvipdfmx}, not \xetex\ directly. This is given in the
1555 configuration file \texttt{dvipdfmx.cfg}. However, \TeX\ documents can
1556 specify the output version with \cs{special} directives. For example, to
1557 generate PDF-1.4 output (the default is newer than this):
1558
1559 \begin{verbatim}
1560 \special{pdf:majorversion:1}
1561 \special{pdf:minorversion:4}
1562 \end{verbatim}
1563
1564 \subsection{Invoking \xetex}
1565
1566 \xetex\ has many command line options and can use many environment
1567 variables and configuration file settings. They are almost all inherited
1568 from the common framework for \TeX\ engines as implemented in Web2C and
1569 Kpathsea. Their documentation is available at
1570 \url{https://tug.org/web2c} and \url{https://tug.org/kpathsea}.
1571
1572 The main \xetex-specific options are \verb|-no-pdf|, which tells \xetex\
1573 to output its XDV (extended DVI) without further processing, and
1574 \verb|-output-driver=|\xarg{cmd}, which processes the XDV output with
1575 \xarg{cmd}; the default is \texttt{xdvipdfmx}.
1576
1577 For a list of all command line options, run \texttt{xetex --help}.
1578 Its current output is give below, for reference:
1579
1580 \begin{footnotesize}
1581 \verbatiminput{helpmsg.txt}
1582 \end{footnotesize}
1583
1584 % qqq doc FONTCONFIG_FILE etc in texmf.cnf
1585
1586 \section{Engine version}
1587
1588 \cmd|\XeTeXversion|
1589 \desc{Expands to a number corresponding to the \xetex version:
1590 \the\XeTeXversion.}
1591 \endcmd
1592
1593 \cmd|\XeTeXrevision|
1594 \desc{Expands to a string corresponding to the \xetex revision number:
1595 \XeTeXrevision.}
1596 \endcmd
1597
1598 \begin{example}
1599 The \xetex version used to typeset this document is:
1600 \the\XeTeXversion\XeTeXrevision
1601 \end{example}
1602
1603 \end{document}