% 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{}] 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{