summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex')
-rw-r--r--Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex1143
1 files changed, 1143 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
new file mode 100644
index 00000000000..feae3759ebf
--- /dev/null
+++ b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
@@ -0,0 +1,1143 @@
+% Copyright 2007-2011 Will Robertson
+% Copyright 2011 Karl Berry
+% Copyright 2013 Khaled Hosny
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Khaled Hosny.
+%
+% This work consists of the files xetex-reference.tex,
+% README.txt, and the derived file xetex-reference.pdf.
+
+\documentclass[12pt]{article}
+
+\suppressfontnotfounderror=1
+
+\makeatletter
+\def\@dotsep{999}
+
+\usepackage{fontspec,unicode-math}
+\setmainfont[Scale=MatchLowercase]{TeX Gyre Pagella}
+\setsansfont[Scale=MatchLowercase]{TeX Gyre Heros}
+\setmonofont[Scale=MatchLowercase, AutoFakeSlant=.2]{Inconsolata}
+\setmathfont{TeX Gyre Pagella Math}
+
+\usepackage{calc,fancyvrb,hyperref,refstyle,varioref,xcolor,hologo,xspace}
+\usepackage{geometry}
+%\geometry{screen,margin=3cm}
+
+\newcommand\tex {\hologo{TeX}\xspace}
+\newcommand\xetex {\hologo{XeTeX}\xspace}
+\newcommand\pdftex {\hologo{pdfTeX}\xspace}
+\newcommand\luatex {\hologo{LuaTeX}\xspace}
+\newcommand\latex {\hologo{LaTeX}\xspace}
+\newcommand\context{\hologo{ConTeXt}\xspace}
+
+\hypersetup{
+ colorlinks,
+ linkcolor=black,
+ urlcolor=black,
+ pdfsubject={The XeTeX reference guide},
+ pdfauthor={Will Robertson \& Khaled Hosny},
+ pdfkeywords={xetex, tex, typesetting, unicode, math, opentype, graphite, aat}
+}
+
+\usepackage[it]{titlesec}
+\usepackage{enumitem}
+\setlist{nolistsep}
+
+\newenvironment{optdesc}
+ {\begin{description}[font=\ttfamily,style=nextline,leftmargin=1.5cm]}
+ {\end{description}}
+
+\newcommand\cmd{%
+ \noindent
+ \begin{trivlist}\item[]
+ \SaveVerb[%
+ aftersave={%
+ \begin{minipage}{\linewidth}
+ \parindent=2em\relax\noindent
+ \UseVerb{CMD}}]{CMD}}
+\edef\|{|}
+\DefineShortVerb{\|}
+\newcommand\xarg[1]{$\langle\hbox{\rmfamily\itshape #1}\rangle$}
+\def\<#1>{\xarg{#1}}
+\newcommand\oarg[1]{\texttt{[\,#1\,]}}
+\newcommand\desc[1]{\par\noindent\ignorespaces#1\par}
+\def\endcmd{%
+ \end{minipage}
+ \end{trivlist}}
+
+\def\cs#1{\texttt{\textbackslash#1}}
+
+\newsavebox\verbatimbox
+\edef\examplefilename{\jobname.example}
+\newlength\exampleindent
+\setlength\exampleindent{1em}
+
+\newenvironment{example}
+ {\VerbatimEnvironment
+ \begin{VerbatimOut}{\examplefilename}}
+ {\end{VerbatimOut}
+ \typesetexample}
+
+\newcommand\typesetexample{%
+ \begin{trivlist}\item[]
+ \vrule
+ \hspace{\exampleindent}
+ \begin{minipage}{\linewidth-\exampleindent-\exampleindent}
+ \textit{Example:}\par
+ \vspace{0.4\baselineskip}
+ \BVerbatimInput[fontsize=\small]{\examplefilename}\par
+ \vspace{0.4\baselineskip}
+ \color[rgb]{0.7,0,0}\input\examplefilename\relax
+ \end{minipage}\par
+ \end{trivlist}}
+
+\let\strong\textbf
+\newcommand\hlink[2]{\href{#1}{#2}\footnote{\url{#1}}}
+
+\let\latin\textit
+\def\eg{\latin{e.g.}}
+\def\ie{\latin{i.e.}}
+\def\Eg{\latin{E.g.}}
+\def\Ie{\latin{I.e.}}
+\def\etc{\@ifnextchar.{\latin{etc}}{\latin{etc.}\@}}
+
+\def\opteq{\unskip\,\textcolor{gray}{[\textcolor{black}{=}]}\,}
+
+\setlength\parskip{0pt}
+\setlength\parindent{2em}
+\raggedbottom
+
+\begin{document}
+\title{The \xetex reference guide}
+\author{Will Robertson \and Khaled Hosny}
+\maketitle
+
+\vfill
+
+\section*{Introduction}
+
+This document serves to summarise additional features of \xetex without
+being so much as a ‘users’ guide. Note that much of the functionality
+addressed here is provided in abstracted form in various \latex
+packages and \context modules.
+
+The descriptions here should be a fairly exhaustive list of the new
+primitives and features of \xetex. Descriptions are still a little
+aenemic, however.
+
+\section*{License}
+
+This work, is distributed under the terms of the LaTeX Project Public License
+(\url{http://www.latex-project.org/lppl.txt}).
+
+This basically means you are free to re-distribute this file as you
+wish; you may also make changes to this file or use its contents for
+another purpose, in which case you should make it clear, by way of a
+name-change or some other means, that your changed version is a modified
+version of the original. Please read the license text for more detailed
+information.
+
+\vfill\vfill\vfill\null
+
+\newpage
+\tableofcontents
+
+\part{\xetex specifics}
+
+\section{The \cs{font} command}
+
+Traditionally, fonts were selected in \tex like this:
+|\font\1=|\xarg{tfm name} with various options possibly appended
+% harder to read without the extra space
+such as \ ‘| at 10pt|’ \ or \ ‘| scaled 1.2|’, with obvious meaning. This syntax
+still works, but it has been greatly extended in \xetex.
+
+The extended syntax looks schematically like this:
+
+{\centering
+ |\font\1="|\xarg{font identifier}\xarg{font options}|:|\xarg{font features}|"|
+ \xarg{\tex font options}\par}
+
+\noindent The \xarg{font identifier} is the only mandatory part of the
+above syntax. If it is given in square brackets, (e.g.,
+|[lmroman10-regular]|), it is taken as a font file name.
+Without brackets, the name is looked up both as a file name and a system
+font name.
+When using a font name, the font is looked up through the operating
+system, using (except on Mac~OS~X) the |fontconfig| library. Running
+|fc-list| should show you the font names available. \Eg,
+\begin{quote}\small
+|\font\1="Liberation Serif"| \hfill \emph{look for OS-installed font}
+\end{quote}
+
+Fonts have many internal names, and XeTeX matches them in the following order:
+\vskip1ex
+\begin{itemize}
+ \item Full Name;
+ \item if the name has a hyphen, it is split into Family-Style pair then matched;
+ \item PostScript Name;
+ \item Family Name, if there is more than one match;
+ \begin{itemize}
+ \item look for font with “regular” bit set in OS/2 table, if no match;
+ \item look for font with style “Regular”, “Plain”, “Normal” or “Roman”, in that order.
+ \end{itemize}
+\end{itemize}
+\bigskip
+
+When using a file name, the |xdvipdfmx| driver must be used (this is the
+default). The current directory and the |texmf| trees are searched for
+files matching the name, or the path may be embedded in the font
+declaration, as usual with |kpathsea|. \Eg,
+\begin{quote}\small
+|\font\2="[lmroman10-regular]"| \hfill
+ {\em find |lmroman10-regular.otf| in any tree}
+|\font\3="[/myfonts/fp9r8a]"| \hfill
+ {\em look for |fp9r8a| only in |/myfonts/|}
+\end{quote}
+
+A file with either an |.otf|, |.ttf| or |.pfb| extension (in that order) will be found. The
+extension can also be specified explicitly.
+If the file is a font collection (e.g., |.ttc| or |.dfont|), the index of the
+font can be specified using a colon followed by zero-based font index inside
+the square brackets. \Eg,
+\begin{quote}\small
+|\font\4="[myfont.ttc:1]"| \hfill {\em load the second font from |myfont.ttc| file}
+\end{quote}
+
+
+\subsection{Font options}
+
+\xarg{Font options} are only applicable when the font is selected
+through the operating system (\ie, without square brackets). They may
+be any concatenation of the following:
+
+\begin{optdesc}
+\item[/B] Use the bold version of the selected font.
+\item[/I] Use the italic version of the selected font.
+\item[/BI] Use the bold italic version of the selected font.
+\item[/IB] Same as \texttt{/BI}.
+\item[/S=$x$] Use the version of the selected font corresponding to the
+optical size $x$\,pt.
+\item[/AAT] Explicitly use the AAT renderer (Mac~OS~X only).
+\item[/OT] Explicitly use the OpenType renderer (new in 0.9999).
+\item[/GR] Explicitly use the Graphite renderer.%
+ \footnote{\url{http://scripts.sil.org/cms/scripts/page.php?site_id=projects&item_id=graphite_home}}
+\item[/ICU] Explicitly use the OpenType renderer (deprecated since 0.9999).
+\end{optdesc}
+
+
+\subsection{Font features}
+
+The \xarg{font features} is a comma or semi-colon separated list
+activating or deactivating various OpenType, Graphite, or AAT font
+features, which will vary by font. In contrast to font options,
+features work whether the font is selected by file name or through the
+operating system.
+
+The \xetex documentation files \path{aat-info.tex} and
+\path{opentype-info.tex} provide per-font lists of supported features.
+
+\subsubsection{Arbitrary OpenType, Graphite, or AAT features}
+
+OpenType font features are chosen with
+\hlink{http://www.microsoft.com/typography/otspec/featuretags.htm}{standard
+tags}. They may be either comma- or semicolon-separated, and prefixed
+with a |+| to turn them on and a |-| to turn them off, optionally followed
+by |=| and a 0-based index for selecting alternates from multiple
+alternates features (ignored for |-| prefixed tags).
+
+\begin{example}
+\font\liber="Linux Libertine O/I=5:+smcp" at 12pt
+\liber This is the OpenType font Linux Libertine in italic with small caps.
+\end{example}
+
+Varying depending on the language and script in use (see
+\secref[vref]{script}), a small number of OpenType features, if they
+exist, will be activated by default.
+
+\begin{example}
+\font\antt="Antykwa Torunska" at 12pt \antt 0
+\font\antt="Antykwa Torunska:+aalt=0" at 12pt \antt 0
+\font\antt="Antykwa Torunska:+aalt=1" at 12pt \antt 0
+\font\antt="Antykwa Torunska:+aalt=2" at 12pt \antt 0
+\font\antt="Antykwa Torunska:+aalt=3" at 12pt \antt 0
+\font\antt="Antykwa Torunska:+aalt=4" at 12pt \antt 0
+\end{example}
+
+AAT font features and Graphite font features are specified by strings
+within each font rather than standardised tags. Therefore, even
+equivalent features between different fonts can have different names.
+
+\begin{example}
+\font\gra="Charis SIL/GR:Small Caps=True" at 12pt
+\gra This is the Graphite font Charis SIL with small caps.
+\end{example}
+
+\subsubsection{Options for all fonts}
+
+Some font features may be applied for any font. These are
+\begin{optdesc}
+\item[mapping=\textsl{<font map>}]
+Uses the specified font mapping for this font. This uses the TECKit
+engine to transform unicode characters in the last-minute processing
+stage of the source. For example, |mapping=tex-text| will enable the
+classical mappings from ugly ascii |``---''| to proper typographical
+glyphs “—”, and so on.
+
+\item[color={\slshape RRGGBB}{[{\slshape TT}]}]
+Triple pair of hex values to specify the colour in RGB space, with an
+optional value for the transparency.
+
+\item[letterspace=$x$]
+Adds $x/S$ space between letters in words, where $S$ is the font size.
+
+\item[embolden=$x$]
+Increase the envelope of each glyph by the set amount (this makes the
+letters look ‘more bold’). $x=0$ corresponds to no change; $x=1.5$ is a
+good default value.
+
+\item[extend=$x$]
+Stretch each glyph horizontally by a factor of $x$ (i.e., $x=1$
+corresponds to no change).
+
+\item[slant=$x$]
+Slant each glyph by the set amount. $x=0$ corresponds to no change;
+$x=0.2$ is a good default value. The slant is given by $x=R/S$ where $R$
+is the displacement of the top edge of each glyph and $S$ is the point
+size.
+
+\end{optdesc}
+
+\subsubsection{OpenType script and language support}\seclabel{script}
+
+OpenType font features (and font behaviour) can vary by
+\hlink{http://www.microsoft.com/typography/otspec/scripttags.htm}{script}
+(‘alphabet’) and by
+\hlink{http://www.microsoft.com/typography/otspec/languagetags.htm}{language}.
+These are selected with four and three letter tags, respectively.
+
+\begin{optdesc}
+\item[script=\textsl{<script tag>}] Selects the font script.
+\item[language=\textsl{<lang tag>}] Selects the font language.
+\end{optdesc}
+
+\subsubsection{Multiple Master and Variable Axes AAT font support}
+
+\begin{optdesc}
+\item[weight=$x$] Selects the normalised font weight, $x$.
+\item[width=$x$] Selects the normalised font width, $x$.
+\item[optical size=$x$] Selects the optical size, $x$\,pt. Note the
+difference between the \texttt{/S} font option, which selects discrete
+fonts.
+\end{optdesc}
+
+\subsubsection{Vertical typesetting}
+\begin{optdesc}
+\item[vertical]
+Enables glyph rotation in the output so vertical typesetting can be performed.
+\end{optdesc}
+
+\part{New commands}
+
+\section{Font primitives}
+
+\cmd|\XeTeXtracingfonts|
+\desc{If nonzero, reports where fonts are found in the log file.}
+\endcmd
+
+\cmd|\XeTeXfonttype|
+\xarg{font}
+\desc{
+ Expands to a number corresponding to which renderer is used for a
+ \xarg{font}:
+ \begin{optdesc}
+ \item [0] for \tex (a legacy TFM-based font);
+ \item [1] for AAT;
+ \item [2] for OpenType;
+ \item [3] for Graphite.
+ \end{optdesc}
+}
+\endcmd
+
+\begin{example}
+\newcommand\whattype[1]{%
+ \texttt{\fontname#1} is rendered by
+ \ifcase\XeTeXfonttype#1\TeX\or AAT\or OpenType\or Graphite\fi.\par}
+\font\1="cmr10"
+\font\2="Charis SIL"
+\font\3="Charis SIL/OT"
+\whattype\1 \whattype\2 \whattype\3
+\end{example}
+
+\cmd|\XeTeXfirstfontchar|
+\xarg{font}
+\desc{Expands to the code of the first character in \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXlastfontchar|
+\xarg{font}
+\desc{Expands to the code of the last character in \xarg{font}.}
+\endcmd
+
+\begin{example}
+\font\1="Charis SIL"\1
+The first character in Charis SIL is: "\char\XeTeXfirstfontchar\1"
+and the last character is: "\char\XeTeXlastfontchar\1".
+\end{example}
+
+\cmd|\XeTeXglyph|
+\xarg{glyph slot}
+\desc{Inserts the glyph in \xarg{glyph slot} of the current font. \strong{Font
+specific}, so will give different output for different fonts and
+possibly even different versions of the same font.}
+\endcmd
+
+\cmd|\XeTeXcountglyphs|
+\xarg{font}
+\desc{The count of the number of glyphs in the specified \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXglyphname|
+\xarg{font}
+\xarg{glyph slot}
+\desc{Expands to the name of the glyph in \xarg{glyph slot} of \xarg{font}.
+\strong{Font specific}, so will give different output for different fonts and
+possibly even different versions of the same font.}
+\endcmd
+
+\cmd|\XeTeXglyphindex|
+|"|\xarg{glyph name}|"| \xarg{space} \emph{or} \cs{relax}
+\desc{Expands to the glyph slot corresponding to the (possibly
+font specific) \xarg{glyph name} in the currently selected font. Only
+works for TrueType fonts (or TrueType-based OpenType fonts) at
+present. Use \texttt{fontforge} or similar to discover glyph names.}
+\endcmd
+
+\cmd|\XeTeXcharglyph|
+\xarg{char code}
+\desc{Expands to the default glyph number of character \xarg{char code}
+in the current font, or 0 if the character is not available in the
+font.}
+\endcmd
+
+\begin{example}
+\font\1="Charis SIL"\1
+The glyph slot in Charis SIL for the Yen symbol is:
+ \the\XeTeXglyphindex"yen" . % the font-specific glyph name
+Or: \the\XeTeXcharglyph"00A5. % the unicode character slot
+
+This glyph may be typeset with the font-specific glyph slot:
+\XeTeXglyph150,
+or the unicode character slot:
+\char"00A5.
+\end{example}
+
+\cmd|\XeTeXglyphbounds|
+\xarg{edge} \xarg{glyph slot}
+\desc{Expands to a dimension corresponding to one of the bounds of a
+glyph, where \xarg{edge} is an integer from 1 to~4 indicating the
+left/top/right/bottom edge respectively, and \xarg{glyph slot} is an
+integer glyph index in the current font (only valid for non TFM-based
+fonts).
+
+The left and right measurements are the glyph sidebearings, measured
+‘inwards’ from the origin and advance respectively, so for a glyph that
+fits completely within its ‘cell’ they will both be positive; for a
+glyph that ‘overhangs’ to the left or right, they will be negative. The
+actual width of the glyph’s bounding box, therefore, is the character
+width (advance) minus both these sidebearings.
+
+The top and bottom measurements are measured from the baseline, like
+\tex’s height and depth; the height of the bounding box is the sum of
+these two dimensions.}
+\endcmd
+
+\begin{example}
+\def\shadebbox#1{%
+\leavevmode\rlap{%
+ \dimen0=\fontcharwd\font`#1%
+ \edef\gid{\the\XeTeXcharglyph`#1}%
+ \advance\dimen0 by -\XeTeXglyphbounds1 \gid
+ \advance\dimen0 by -\XeTeXglyphbounds3 \gid
+ \kern\XeTeXglyphbounds1 \gid
+ \special{color push rgb 1 1 0.66667}%
+ \vrule width \dimen0
+ height \XeTeXglyphbounds2 \gid
+ depth \XeTeXglyphbounds4 \gid
+ \special{color pop}%
+ \kern\XeTeXglyphbounds3 \gid}%
+ #1}
+
+\noindent
+\font\x="Charis SIL/I" at 24pt \x
+\shadebbox{A} \shadebbox{W} \shadebbox{a} \shadebbox{f}
+\shadebbox{;} \shadebbox{*} \shadebbox{=}
+\end{example}
+
+\cmd|\XeTeXuseglyphmetrics|
+\desc{Counter to specify if the height and depth of characters are taken
+into account while typesetting ($\ge\mathtt1$). Otherwise ($<\mathtt1$),
+a single height and depth for the entire alphabet is used. Gives better
+output but is slower. Activated ($\ge\mathtt1$) by default.}
+\endcmd
+
+\begin{example}
+\XeTeXuseglyphmetrics=0 \fbox{a}\fbox{A}\fbox{j}\fbox{J} vs.
+\XeTeXuseglyphmetrics=1 \fbox{a}\fbox{A}\fbox{j}\fbox{J}
+\end{example}
+
+\subsection{OpenType fonts}
+
+\cmd|\XeTeXOTcountscripts|
+\xarg{font}
+\desc{Expands to the number of scripts in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXOTscripttag|
+\xarg{font}
+\xarg{integer, $n$}
+\desc{Expands to the $n$-th script tag of \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXOTcountlanguages|
+\xarg{font}
+\xarg{script tag}
+\desc{Expands to the number of languages in the script of \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXOTlanguagetag|
+\xarg{font}
+\xarg{script tag}
+\xarg{integer, $n$}
+\desc{Expands to the $n$-th language tag in the script of \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXOTcountfeatures|
+\xarg{font}
+\xarg{script tag}
+\xarg{language tag}
+\desc{Expands to the number of features in the language of a script of \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXOTfeaturetag|
+\xarg{font}
+\xarg{script tag}
+\xarg{language tag}
+\xarg{integer, $n$}
+\desc{Expands to the $n$-th feature tag in the language of a script of \xarg{font}.}
+\endcmd
+
+
+\subsection{AAT and Graphite fonts}
+
+\subsubsection{Features}
+
+\cmd|\XeTeXcountfeatures|
+\xarg{font}
+\desc{Expands to the number of features in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXfeaturecode|
+\xarg{font}
+\xarg{integer, $n$}
+\desc{Expands to the feature code for the $n$-th feature in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXfeaturename|
+\xarg{font}
+\xarg{feature code}
+\desc{Expands to the name corresponding to the \xarg{feature code} in
+the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXisexclusivefeature|
+\xarg{font}
+\xarg{feature code}
+\desc{Expands to a number greater than zero if the feature of a font is
+exclusive (can only take a single selector).}
+\endcmd
+
+\cmd|\XeTeXfindfeaturebyname|
+\xarg{font}
+\xarg{feature name}
+\desc{This command provides a method to query whether a feature name
+corresponds to a feature contained in the font. It represents an integer
+corresponding to the feature number used to access the feature
+numerically. If the feature does not exist, the integer is
+\texttt{-1}. Also see \cs{XeTeXfindselectorbyname}.}
+\endcmd
+
+\begin{example}
+\font\1="Charis SIL/GR" at 10pt
+\def\featname{Uppercase Eng alternates}
+The feature ‘\featname’ has index
+\the\XeTeXfindfeaturebyname\1 "\featname"\relax
+\end{example}
+
+\subsubsection{Feature selectors}
+
+\cmd|\XeTeXcountselectors|
+\xarg{font}
+\xarg{feature}
+\desc{Expands to the number of selectors in a \xarg{feature} of a \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXselectorcode|
+\xarg{font}
+\xarg{feature code}
+\xarg{integer, $n$}
+\desc{Expands to the selector code for the $n$-th selector in a
+\xarg{feature} of a \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXselectorname|
+\xarg{font}
+\xarg{feature code}
+\xarg{selector code}
+
+\desc{Expands to the name corresponding to the \xarg{selector code} of a
+feature of a \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXisdefaultselector|
+\xarg{font}
+\xarg{feature code}
+\xarg{selector code}
+\desc{Expands to a number greater than zero if the selector of a feature
+of a font is on by default.}
+\endcmd
+
+
+\cmd|\XeTeXfindselectorbyname|
+\xarg{font}
+\xarg{feature name}
+\xarg{selector name}
+\desc{This command provides a method to query whether a feature selector
+name corresponds to a selector of a specific feature contained in the
+font. It represents an integer corresponding to the selector number used
+to access the feature selector numerically. If the feature selector does
+not exist, the integer is \texttt{-1}.
+
+The indices given by this command and by \cs{XeTeXfindfeaturebyname} can
+be used in Graphite fonts to select font features directly (see example
+below). Alternatively, they can be used as a means of checking whether a
+feature/selector exists before attempting to use it.}
+\endcmd
+
+\begin{example}
+\font\1="Charis SIL/GR" at 10pt
+\def\featname{Uppercase Eng alternates}
+\newcount\featcount
+\featcount=\XeTeXfindfeaturebyname\1 "\featname"\relax
+
+\def\selecname{Large eng on baseline}
+\newcount\seleccount
+\seleccount=\XeTeXfindselectorbyname\1 \featcount "\selecname"\relax
+The feature selector ‘\selecname’ has index \the\seleccount
+
+\font\2="Charis SIL/GR:\featname=\selecname" at 10pt
+\font\3="Charis SIL/GR:\the\featcount=\the\seleccount" at 10pt
+
+Activating the feature: \1 Ŋ \2 Ŋ \3 Ŋ
+\end{example}
+
+\subsubsection{Variation axes}
+
+\cmd|\XeTeXcountvariations|
+\xarg{font}
+\desc{Expands to the number of variation axes in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXvariation|
+\xarg{font}
+\xarg{integer, $n$}
+\desc{Expands to the variation code for the $n$-th feature in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXvariationname|
+\xarg{font}
+\xarg{variation code}
+\desc{Expands to the name corresponding to the \xarg{feature code} in
+the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXvariationmin|
+\xarg{font}
+\xarg{variation code}
+\desc{Expands to the minimum value of the variation corresponding to the
+\xarg{variation code} in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXvariationmax|
+\xarg{font}
+\xarg{variation code}
+\desc{Expands to the maximum value of the variation corresponding to the
+\xarg{variation code} in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXvariationdefault|
+\xarg{font}
+\xarg{variation code}
+\desc{Expands to the default value of the variation corresponding to the
+\xarg{variation code} in the \xarg{font}.}
+\endcmd
+
+\cmd|\XeTeXfindvariationbyname|
+\xarg{font}
+\xarg{variation name}
+\desc{An integer corresponding to the internal index corresponding to
+the \xarg{variation name}. This index cannot be used directly but may be
+used to error-check that a specified variation name exists before
+attempting to use it.}
+\endcmd
+
+\subsection{Maths fonts}
+
+The primitives described following are extensions of \tex’s 8-bit primitives.
+
+In the following commands, \xarg{fam.} is a number (0–255) representing
+font to use in maths. \xarg{math type} is the 0–7 number corresponding
+to the type of math symbol; see a \tex reference for details.
+
+Before version 0.9999.0 the following primitives had |\XeTeX| prefix instead of
+|\U|, the old names are deprecated and will be removed in the future.
+
+\cmd|\Umathcode|
+\xarg{char slot}
+\opteq
+\xarg{math type}
+\xarg{fam.}
+\xarg{glyph slot}
+\desc{Defines a maths glyph accessible via an input character. Note that
+the input takes \emph{three} arguments unlike \tex’s \cs{mathcode}.}
+\endcmd
+
+\cmd|\Umathcodenum|
+\xarg{char slot}
+\opteq
+\xarg{math type/fam./glyph slot}
+\desc{Pure extension of \cs{mathcode} that uses a ‘bit-packed’ single
+number argument. Can also be used to extract the bit-packed mathcode
+number of the \xarg{char slot} if no assignment is given.}
+\endcmd
+
+\cmd|\Umathchar|
+\xarg{math type}
+\xarg{fam.}
+\xarg{glyph slot}
+\desc{Typesets the math character in the \xarg{glyph slot} in the family
+specified.}
+\endcmd
+
+\cmd|\Umathcharnum|
+\xarg{type/fam./glyph slot}
+\desc{Pure extension of \cs{mathchar} that uses a ‘bit-packed’ single
+number argument. Can also be used to extract the bit-packed mathcode
+number of the \xarg{char slot} if no assignment is given.}
+\endcmd
+
+\cmd|\Umathchardef|
+\xarg{control sequence}
+\opteq
+\xarg{math type}
+\xarg{fam.}
+\xarg{glyph slot}
+\desc{Defines a maths glyph accessible via a control sequence.}
+\endcmd
+
+\cmd|\Umathcharnumdef|
+\xarg{control sequence}
+\opteq
+\xarg{type/fam./glyph slot}
+\desc{Defines a control sequence for accessing a maths glyph using the
+‘bit-packed’ number output by, e.g., \cs{Umathcodenum}. This would
+be used to replace legacy code such as
+\cs{mathchardef}\cs{foo}\texttt{=}\cs{mathcode}\texttt{`}\cs{\-}.}
+\endcmd
+
+\cmd|\Udelcode|
+\xarg{char slot}
+\opteq
+\xarg{fam.}
+\xarg{glyph slot}
+\desc{Defines a delimiter glyph accessible via an input character.}
+\endcmd
+
+\cmd|\Udelcodenum|
+\xarg{char slot}
+\opteq
+\xarg{fam./glyph slot}
+\desc{Pure extension of \cs{delcode} that uses a ‘bit-packed’ single
+number argument. Can also be used to extract the bit-packed delcode
+number of the \xarg{char slot} if no assignment is given.}
+\endcmd
+
+\cmd|\Udelimiter|
+\xarg{math type}
+\xarg{fam.}
+\xarg{glyph slot}
+\desc{Typesets the delimiter in the \xarg{glyph slot} in the family
+specified of either \xarg{math type} 4 (opening) or 5 (closing).}
+\endcmd
+
+\cmd|\Umathaccent|
+\oarg{keyword}
+\xarg{math type}
+\xarg{fam.}
+\xarg{glyph slot}
+\desc{Typesets the math accent character in the \xarg{glyph slot} in the
+family specified. Starting from version 0.9998, \cs{Umathaccent} accepts
+optional keyword:\medskip
+\begin{optdesc}
+\item[fixed] Don’t stretch the accent, the default is to stretch it:
+ $\widehat{M}$ vs $\hat{M}$.
+\item[bottom] Place the accent below its base. Can be followed by the
+ \texttt{fixed} keyword.
+\end{optdesc}}
+\endcmd
+
+\cmd|\Uradical|
+\xarg{fam.}
+\xarg{glyph slot}
+\desc{Typesets the radical in the \xarg{glyph slot} in the family specified.}
+\endcmd
+
+\section{Character classes}
+
+The idea behind character classes is to define a boundary where tokens
+can be added to the input stream without explicit markup. It was
+originally intended to add glue around punctuation to effect correct
+Japanese typesetting. This feature can also be used to adjust space
+around punctuation for European traditions. The general nature of this
+feature, however, lends it to several other useful applications
+including automatic font switching when small amounts of another
+language (in another script) is present in the text.
+
+\cmd|\XeTeXinterchartokenstate|
+\desc{Counter. If positive, enables the character classes functionality.}
+\endcmd
+
+\cmd|\newXeTeXintercharclass|
+\xarg{control sequence}
+\desc{Allocates a new interchar class and assigns it to the
+\xarg{control sequence} argument.}
+\endcmd
+
+\cmd|\XeTeXcharclass|
+\xarg{char slot}
+\opteq
+\xarg{interchar class}
+\desc{Assigns a class corresponding to \xarg{interchar class} (range
+0–255) to a \xarg{char slot}. Most characters are class 0 by
+default. Class 1 is for CJK ideographs, classes 2 and 3 are CJK
+punctuation. The boundary of a text string is considered class 255,
+wherever there is a boundary between a ‘run’ of characters and something
+else — glue, kern, math, box, etc. Special case class 256 is ignored;
+useful for diacritics so I’m told.}
+\endcmd
+
+\cmd|\XeTeXinterchartoks|
+\xarg{interchar class 1}
+\xarg{interchar class 2}
+\opteq
+|{|\xarg{token list}|}|
+\desc{Defines tokens to be inserted between
+\xarg{interchar class 1} and \xarg{interchar class 2} (in that order).}
+\endcmd
+
+\begin{example}
+\XeTeXinterchartokenstate = 1
+\newXeTeXintercharclass \mycharclassa
+\newXeTeXintercharclass \mycharclassA
+\newXeTeXintercharclass \mycharclassB
+\XeTeXcharclass `\a \mycharclassa
+\XeTeXcharclass `\A \mycharclassA
+\XeTeXcharclass `\B \mycharclassB
+
+% between "a" and "A":
+\XeTeXinterchartoks \mycharclassa \mycharclassA = {[\itshape}
+\XeTeXinterchartoks \mycharclassA \mycharclassa = {\upshape]}
+
+% between " " and "B":
+\XeTeXinterchartoks 255 \mycharclassB = {\bgroup\color{blue}}
+\XeTeXinterchartoks \mycharclassB 255 = {\egroup}
+
+% between "B" and "B":
+\XeTeXinterchartoks \mycharclassB \mycharclassB = {.}
+
+aAa A a B aBa BB
+\end{example}
+
+\noindent In the above example the input text is typeset as\par
+{\centering
+ \verb|a[\itshape A\upshape]a A a \bgroup\color{blue}B\egroup aBa B.B|\par}
+
+\newpage
+\section{Encodings}
+
+\cmd|\XeTeXinputnormalization|
+\xarg{Integer}
+\desc{Specify whether \xetex is to perform normalisation on the input
+text and, if so, what type of normalisation to use. See
+\url{http://unicode.org/reports/tr15/} for a description of Unicode
+normalisation. The \<Integer> value can be:\medskip
+\begin{optdesc}
+\item[0] (default) do not perform normalisation.
+\item[1] normalise to NFC form, using precomposed characters where possible
+ instead base characters with combining marks.
+\item[2] normalise to NFD form, using base characters with combining marks
+ instead of precomposed characters.
+\end{optdesc}}
+\endcmd
+
+\cmd|\XeTeXinputencoding|
+\xarg{Charset name}
+\desc{Defines the input encoding of the following text.}
+\endcmd
+
+\cmd|\XeTeXdefaultencoding|
+\xarg{Charset name}
+\desc{Defines the input encoding of subsequent files to be read.}
+\endcmd
+
+\section{Line breaking}
+
+\cmd|\XeTeXdashbreakstate|
+\xarg{Integer}
+\desc{Specify whether line breaks after en- and em-dashes are
+allowed. Off, 0, by default.}
+\endcmd
+
+\cmd|\XeTeXlinebreaklocale|
+\xarg{Locale ID}
+\desc{Defines how to break lines for multilingual text.}
+\endcmd
+
+\cmd|\XeTeXlinebreakskip|
+\xarg{Glue}
+\desc{Inter-character linebreak stretch}
+\endcmd
+
+\cmd|\XeTeXlinebreakpenalty|
+\xarg{Integer}
+\desc{Inter-character linebreak penalty}
+\endcmd
+
+\cmd|\XeTeXupwardsmode|
+\xarg{Integer}
+\desc{If greater than zero, successive lines of text (and rules, boxes,
+etc.) will be stacked upwards instead of downwards.}
+\endcmd
+
+\section{Graphics}
+
+Thanks to Heiko Oberdiek, Paul Isambert, and William Adams for their
+help with the documentation in this section.
+
+\cmd|\XeTeXpicfile|
+\xarg{filename}
+\oarg{ scaled \xarg{int} \|
+ xscaled \xarg{int} \|
+ yscaled \xarg{int} \| \\\hspace*{2em}
+ width \xarg{dimen} \|
+ height \xarg{dimen} \|
+ rotated \xarg{decimal} }
+\desc{Insert an image. See below for explanation of optional arguments.}
+\endcmd
+
+\cmd|\XeTeXpdffile|
+\xarg{filename}
+\oarg{page \xarg{int}}
+\oarg{ crop \| media \| bleed \| trim \| art }\\\hspace*{2em}
+\oarg{scaled \xarg{int} \|
+ xscaled \xarg{int} \|
+ yscaled \xarg{int} \|
+ width \xarg{dimen} \|\\\hspace*{2em}~
+ height \xarg{dimen} \|
+ rotated \xarg{decimal}}
+\desc{Insert (pages of) a PDF. See below for explanation of optional
+arguments.}
+\endcmd
+
+\noindent In the graphic/PDF commands above, \xarg{filename} is the
+usual file name argument of \cs{input}, \cs{openin}, \etc. It must not
+terminated by \cs{relax} if options are given. \xarg{int} and
+\xarg{dimen} are the usual integer or dimen specifications of regular
+\tex.
+
+The rotation is specified in degrees (\ie, an input of ‘|360|’ is full
+circle) and the rotation is counterclockwise. The syntax of
+\xarg{decimal} require some explanation:
+\begin{quote}
+\<decimal> $\to$ \<optional signs>\<unsigned decimal>\\
+\<unsigned decimal> $\to$ \<normal decimal>
+ \| \<coerced dimen> \| \<internal dimen>\\
+\<normal decimal> $\to$ \<normal integer> \| \<decimal constant>
+\end{quote}
+A \xarg{coerced dimen} or \xarg{internal dimen} is interpreted as number
+with unit ‘|pt|’. For example, for a rotation specified with a dimension
+\cs{testdim},
+\begin{itemize}
+\item \verb|\testdim=45pt | results in a rotation of 45\textdegree,
+\item \verb|\testdim=1in | is 72.27\textdegree, and
+\item \verb|\testdim=100sp| is (100/65536)\textdegree.
+\end{itemize}
+In all cases the resulting decimal number for rotation $x$ must be
+within the limits $-16384 < x < 16384$.
+
+The \cs{XeTeXpdffile} command takes one more optional argument for
+specifying to which ‘box’ the PDF should be cropped before inserting
+it (the second optional argument listed in thes syntax of
+\cs{XeTeXpdffile} above). The PDF standard defines a number of
+(rectangular) bounding boxes that may be specified for various
+purposes. These are described in the PDF Standard\footnote{Adobe
+Systems Incorporated, 2008:\\
+\url{http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf}} and
+summarised below.
+\begin{quote}
+\begin{description}[style=nextline,leftmargin=1.5cm]
+\item [media] the box defining the physical page size.
+\item [crop] the box of the page contents for display/printing purposes.
+\item [bleed] the box containing the page contents plus whatever extra
+space required for printing purposes.
+\item [trim] the box of the finished page after trimming the printed
+‘bleed box’.
+\item [art] the box containing the ‘meaningful content’ of the
+page. This could be the crop box with boilerplate text/logos trimmed
+off.
+\end{description}
+\end{quote}
+When not specified in the PDF to be inserted, the crop box defaults
+to the media box, and the bleed, trim, and art boxes default to the crop
+box.
+
+\cmd|\XeTeXpdfpagecount|
+\xarg{filename}
+\desc{Expands to the number of pages in a PDF file.}
+\endcmd
+
+\section{Cross-compatibility with \pdftex and/or \luatex}
+
+\cmd|\pdfpageheight|
+\xarg{dimension}
+\desc{The height of the PDF page.}
+\endcmd
+
+\cmd|\pdfpagewidth|
+\xarg{dimension}
+\desc{The width of the PDF page.}
+\endcmd
+
+\cmd|\pdfsavepos|
+\desc{Saves the current location of the page in the typesetting stream.}
+\endcmd
+
+\cmd|\pdflastxpos|
+\desc{Retrieves the horizontal position saved by \texttt{\char`\\pdfsavepos}.}
+\endcmd
+
+\cmd|\pdflastypos|
+\desc{Retrieves the vertical position saved by \texttt{\char`\\pdfsavepos}.}
+\endcmd
+
+\cmd|\ifincsname...(\else...)\fi|
+\desc{\tex conditional to branch true if the expansion occurs within
+\texttt{\char`\\csname ... \char`\\endcsname}.}
+\endcmd
+
+\begin{example}
+\def\x{\ifincsname y\else hello\fi}
+\def\y{goodbye}
+\x/\csname\x\endcsname
+\end{example}
+
+\cmd|\ifprimitive| \xarg{control sequence} |...(\else...)\fi|
+\desc{\tex conditional to test if a control sequence is a primitive and
+that it has not been redefined.}
+\endcmd
+
+\cmd|\primitive|
+\xarg{control sequence}
+\desc{If the control sequence is a primitive that’s been redefined, this
+command causes it to expand with its original (i.e., primitive)
+definition.}
+\endcmd
+
+\cmd|\shellescape|
+\desc{Read-only status indicating the level of ‘shell escape’
+allowed. That is, whether commands are allowed to be executed through
+\texttt{\char`\\write18\char`\{...\char`\}}. Expands to zero for off;
+one for on (allowed); two is ‘restricted’ (default in TeX Live 2009 and
+greater) in which a subset of commands only are allowed.}
+\endcmd
+
+\begin{example}
+Shell escape \ifnum\shellescape>0 is \else is not \fi enabled.
+\end{example}
+
+\cmd|\strcmp|
+\xarg{arg one}
+\xarg{arg two}
+\desc{Compares the full expansion of the two token list
+arguments. Expands to zero if they are the same, less than one if the
+first argument sorts lower (lexicographically) than the second argument,
+and greater than one if vice versa.}
+\endcmd
+
+\begin{example}
+‘a’ is less than ‘z’: \strcmp{a}{z}
+
+\def\z{a}
+The tokens expand before being compared: \strcmp{a}{\z}
+
+\def\a{z}
+Therefore, |\a| is greater than |\z|: \strcmp{\a}{\z}
+
+\edef\b{\string b}
+Also note that catcodes are ignored: \strcmp{b}{\b}
+\end{example}
+
+\cmd|\suppressfontnotfounderror|
+\xarg{integer}
+\desc{When set to zero (default) if a font is loaded that cannot be
+located by \xetex, an error message results and typesetting is
+halted. When set to one, this error message is
+suppressed and the font control sequence being defined is set to
+\cs{nullfont}.}
+\begin{example}
+\suppressfontnotfounderror=1
+\font\x="ImpossibleFont" at 10pt
+\ifx\x\nullfont
+ \font\x="Georgia" at 10pt
+\fi
+\x This would be ‘ImpossibleFont’, if it existed.
+\end{example}
+\endcmd
+
+\section{Misc.}
+
+\cmd|\XeTeXversion|
+\desc{Expands to a number corresponding to the \xetex version.}
+\endcmd
+
+\cmd|\XeTeXrevision|
+\desc{Expands to a string corresponding to the \xetex revision number.}
+\endcmd
+
+\begin{example}
+The \xetex version used to typeset this document is:
+\the\XeTeXversion\XeTeXrevision
+\end{example}
+
+\end{document}