diff options
Diffstat (limited to 'Master/texmf-dist/doc/xetex/XeTeX-reference.ltx')
-rw-r--r-- | Master/texmf-dist/doc/xetex/XeTeX-reference.ltx | 468 |
1 files changed, 468 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/xetex/XeTeX-reference.ltx b/Master/texmf-dist/doc/xetex/XeTeX-reference.ltx new file mode 100644 index 00000000000..e8309427efa --- /dev/null +++ b/Master/texmf-dist/doc/xetex/XeTeX-reference.ltx @@ -0,0 +1,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}
\ No newline at end of file |