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