summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/xetex/XeTeX-reference.ltx
blob: e8309427efa392a2c74246e238abface3de1c657 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
%!TEX TS-program = XeLaTeX=xdvipdfmx

\documentclass[12pt]{article}

\makeatletter
\def\@dotsep{999}

\usepackage{fontspec,xltxtra,xunicode}
\usepackage{lmodern}
\defaultfontfeatures{Mapping=tex-text, Scale=MatchLowercase}
\setromanfont[Numbers=Lowercase]{FPL Neu}
%\setsansfont{Lucida Sans}
%\setmonofont{Lucida Sans Typewriter}

\usepackage{calc,fancyvrb,hyperref}
\usepackage{geometry}
%\geometry{screen,margin=3cm}

\usepackage[nofancy]{svninfo}
\svnInfo $Id: XeTeX-reference.ltx 7 2006-10-25 12:06:06Z will $ 

\usepackage[medium,rm]{titlesec}
\usepackage{enumitem}
\setlist{nolistsep}

\newenvironment{optdesc}
  {\begin{description}[font=\ttfamily,style=nextline,leftmargin=1.5cm]}
  {\end{description}}

\newcommand\cmd{%
  \vspace{2ex plus 5pt minus 5pt}
  \noindent
  \SaveVerb[%
    aftersave={%
      \begin{minipage}{\linewidth}
        \UseVerb{CMD}}]{CMD}}
\DefineShortVerb{\|}
\newcommand\xarg[1]{‹\textit{#1}›}
\newcommand\desc[1]{\par#1}
\def\endcmd{\end{minipage}}

\newsavebox\verbatimbox
\edef\examplefilename{\jobname.example}
\newlength\exampleindent
\setlength\exampleindent{1em}

\newenvironment{example}
  {\VerbatimEnvironment
   \begin{VerbatimOut}{\examplefilename}}
  {\end{VerbatimOut}
   \typesetexample}
   
\newcommand\typesetexample{%
  \vspace{2ex plus 5pt minus 5pt}
  \vrule
  \hspace{\exampleindent}
  \begin{minipage}{\linewidth-\exampleindent}
    \textit{Example:}\par
    \vspace{0.4\baselineskip}
    \BVerbatimInput[fontsize=\small]{\examplefilename}\par
    \vspace{0.4\baselineskip}
    \input\examplefilename\relax
  \end{minipage}
  \vspace{2ex plus 5pt minus 5pt}}

\let\strong\textbf
\providecommand\pdfTeX{pdf\/\TeX}
\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.}\@}}

\setlength\parskip{0pt}
\setlength\parindent{2em}
\raggedbottom

\begin{document}
\title{The \XeTeX\ reference guide}
\author{Will Robertson}
\date{\svnInfoLongDate}
\maketitle
\tableofcontents

\section{Introduction}
This document serves to summarise \XeTeX's additional features 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 Con\TeX{}t modules.

\part{\XeTeX\ specifics}

\section{The {\ttfamily\char`\\font} command}
The |\font| command has seen significant addition in \XeTeX\ to facilitate rich font feature selection. Under \TeX, fonts were selected like so: |\font\1="|\xarg{font name}|"| with various options appended such as `|at 10pt|' or `|scaled 1.2|'. This syntax has been extended in \XeTeX\ by passing additions options through the \xarg{font name}.

This syntax looks something like\par
{\centering|\font\1="|\xarg{font name}\xarg{font options}|:|\xarg{font features}|"| \xarg{\TeX\ font features}\par}\noindent
The \xarg{font name} is the actual name of the font; e.g., `|Charis SIL|'. 

When using the |xdvipdfmx| driver (not yet the default in Mac~OS~X), it is possible to use fonts
that aren't installed in the operating system by surrounding their name with square brackets. The current directory and the |texmf| trees are searched for files named in this way, or the path may be embedded in the
font declaration. \Eg,
\begin{quote}\small
|\font\1="[fp9r8a]"| \hfill \emph{Selects `FPL Neu' in the current directory}
|\font\1="[/myfonts/fp9r8a]"| \hfill \emph{Selects `FPL Neu' somewhere else}
|\font\1="[lmroman10-regular]"| \hfill \emph{Selects a Latin Modern font in the \emph{TDS}}
\end{quote}

The other arguments are optional and described subsequently.

\subsection{Font options}

\xarg{Font options} may be an 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 ATSUI renderer (Mac OS X only).
\item[/ICU] Explicitly use the ICU OpenType renderer (only useful on Mac OS X).
\end{optdesc}
Font options aren't applicable when the font is selected locally (\ie, with square brackets).

\subsection{Font features}

The \xarg{font features} is a comma or semi-colon separated list activating or deactivating various AAT or OpenType font features, which will vary by font. 
The \XeTeX\ documentation files \path{aat-info.tex} and \path{opentype-info.tex} provide per-font lists of supported features.

\subsubsection{Arbitrary AAT or OpenType features.}
OpenType font features are chosen with standard tags, registered with Adobe or Microsoft: see 
\hlink{http://www.microsoft.com/typography/otspec/featuretags.htm}{this link}.

\begin{example}
\font\warnock="Warnock Pro/I/S=5:+smcp" at 12pt
\warnock This is the OpenType font Warnock Pro in italic 
         with small caps at a small optical size.
\end{example}

AAT font features are specified by strings within each font. Therefore, even equivalent features between different fonts can have different names.
\begin{example}
\font\hoefler="Hoefler Text/B:Letter Case=Small Caps" at 12pt
\hoefler This is the AAT font Hoefler Text in bold with small caps.
\end{example}

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.
\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.
\end{optdesc}

\subsubsection{OpenType script and language support}
OpenType font features can vary by script (`alphabet') and by language.
\begin{optdesc}
\item[script=\textsl{<script tag>}] See \hlink{http://www.microsoft.com/typography/otspec/scripttags.htm}{this link}.
\item[language=\textsl{<lang tag>}] See \hlink{http://www.microsoft.com/typography/otspec/languagetags.htm}{this link}.
\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$. Note the difference between the \texttt{/S} font option, which selects discrete fonts.
\end{optdesc}

\section{\XeTeX's {\ttfamily\char`\\special}s}

\textit{To be addressed. Hopefully not by me.}

\part{New commands}

\section{Font primitives}

\cmd|\XeTeXuseglyphmetrics|
\xarg{Integer}
\desc{Boolean to specify if the height and depth of characters are taken into account ($\ge\mathtt1$). Otherwise ($<\mathtt1$), a single height and depth for the entire alphabet is used. When activated, by default, gives better output but is slower.}
\endcmd

\begin{example}
\XeTeXuseglyphmetrics=0 \fbox{a}\fbox{A}\fbox{j}\fbox{J} vs.
\XeTeXuseglyphmetrics=1 \fbox{a}\fbox{A}\fbox{j}\fbox{J}
\end{example}

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

\cmd|\XeTeXglyphindex|
\xarg{Glyph name}
\desc{Returns the \xarg{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{Returns 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:
\XeTeXglyph1458, 
or the unicode character slot:
\char"00A5.
\end{example}

\cmd|\XeTeXfonttype|
\xarg{font}
\desc{
  Returns what renderer is used for a \xarg{font}:
  \begin{optdesc}
    \item [0] for \TeX\ (a legacy TFM-based font);
    \item [1] for ATSUI (usually an AAT font);
    \item [2] for ICU (an OpenType font).
  \end{optdesc}
}
\endcmd

\begin{example}
\newcommand\whattype[1]{%
  \texttt{\fontname#1} is rendered by
  \ifcase\XeTeXfonttype#1\TeX\or ATSUI\or ICU\fi.\par}
\font\1="cmr10"
\font\2="Hoefler Text"
\font\3="Charis SIL"
\font\4="Charis SIL/AAT" 
\whattype\1\whattype\2\whattype\3\whattype\4
\end{example}

\subsection{OpenType fonts}

\cmd|\XeTeXOTcountscripts|
\xarg{Font}
\desc{Returns the number of scripts in a font.}
\endcmd

\cmd|\XeTeXOTscripttag|
\xarg{Font}
\xarg{Integer, $n$}
\desc{Returns the $n$-th script tag of a font.}
\endcmd

\cmd|\XeTeXOTcountlanguages|
\xarg{Font}
\xarg{Script tag}
\desc{Returns the number of languages in the script of a font.}
\endcmd

\cmd|\XeTeXOTlanguagetag|
\xarg{Font}
\xarg{Script tag}
\xarg{Integer, $n$}
\desc{Returns the $n$-th language tag in the script of a font.}
\endcmd

\cmd|\XeTeXOTcountfeatures|
\xarg{Font}
\xarg{Script tag}
\xarg{Language tag}
\desc{Returns the number of features in the language of a script of a font.}
\endcmd

\cmd|\XeTeXOTfeaturetag|
\xarg{Font}
\xarg{Script tag}
\xarg{Language tag}
\xarg{Integer, $n$}
\desc{Returns the $n$-th feature tag in the language of a script of a font.}
\endcmd


\subsection{AAT fonts}

\subsubsection{Features}

\cmd|\XeTeXcountfeatures|
\xarg{font}
\desc{Returns the number of features in the \xarg{font}.}
\endcmd

\cmd|\XeTeXfeaturecode|
\xarg{font}
\xarg{integer, $n$}
\desc{Returns the feature code for the $n$-th feature in the \xarg{font}.}
\endcmd

\cmd|\XeTeXfeaturename|
\xarg{font}
\xarg{feature code}
\desc{Returns the name corresponding to the \xarg{feature code} in the \xarg{font}.}
\endcmd

\cmd|\XeTeXisexclusivefeature|
\xarg{font}
\xarg{feature code}
\desc{Returns greater than zero if the feature of a font is exclusive (can only take a single selector).}
\endcmd

\subsubsection{Feature selectors}

\cmd|\XeTeXcountselectors|
\xarg{font}
\xarg{feature}
\desc{Returns the number of selectors in a \xarg{feature} of a \xarg{font}.}
\endcmd

\cmd|\XeTeXselectorcode|
\xarg{font}
\xarg{feature code}
\xarg{integer, $n$}
\desc{Returns 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{Returns 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{Returns greater than zero if the selector of a feature of a font is on by default.}
\endcmd

\subsubsection{Variation axes}

\cmd|\XeTeXcountvariations|
\xarg{font}
\desc{Returns the number of variation axes in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariation|
\xarg{font}
\xarg{integer, $n$}
\desc{Returns the variation code for the $n$-th feature in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariationname|
\xarg{font}
\xarg{variation code}
\desc{Returns the name corresponding to the \xarg{feature code} in the \xarg{font}.}
\endcmd

\cmd|\XeTeXvariationmin|
\xarg{font}
\xarg{variation code}
\desc{Returns 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{Returns 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{Returns the default value of the variation corresponding to the \xarg{variation code} in the \xarg{font}.}
\endcmd

\subsection{Maths fonts}

To be addressed. Still incomplete in \XeTeX.

\section{Encodings}

\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. On, 1, 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 positive, successive lines of text (and rules, boxes, etc.) will be stacked upwards instead of downwards.}
\endcmd

\section{Graphics}

\cmd|\XeTeXpicfile|
\xarg{filename}
\xarg{optional options}
\desc{Insert an image.}
\endcmd

\cmd|\XeTeXpdffile|
\xarg{filename}
\xarg{optional options}
\desc{Insert (pages of) a PDF.}
\endcmd

\subsection{Parity with \pdfTeX}

\cmd|\pdfpageheight|
\xarg{Number}
\desc{The height of the PDF page.}
\endcmd

\cmd|\pdfpagewidth|
\xarg{Number}
\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 the above.}
\endcmd

\cmd|\pdflastypos|
\desc{Retrieves the vertical position saved by the above.}
\endcmd

\section{Misc.}

\cmd|\XeTeXversion|
\desc{A number corresponding to the \XeTeX\ version.}
\endcmd

\cmd|\XeTeXrevision|
\desc{A string corresponding to the \XeTeX\ revision number.}
\endcmd

\begin{example}
The \XeTeX\ version is: \the\XeTeXversion\XeTeXrevision
\end{example}



\end{document}