From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- info/xetexref/README.txt | 34 + info/xetexref/xetex-reference.pdf | Bin 0 -> 149713 bytes info/xetexref/xetex-reference.tex | 1352 +++++++++++++++++++++++++++++++++++++ 3 files changed, 1386 insertions(+) create mode 100644 info/xetexref/README.txt create mode 100644 info/xetexref/xetex-reference.pdf create mode 100644 info/xetexref/xetex-reference.tex (limited to 'info/xetexref') diff --git a/info/xetexref/README.txt b/info/xetexref/README.txt new file mode 100644 index 0000000000..4c67c8708e --- /dev/null +++ b/info/xetexref/README.txt @@ -0,0 +1,34 @@ +# The XETEXREF documentation + +This package consists of a semi-official reference document for XeTeX. +It is not a user manual; it simply attempts to list XeTeX’s extended features and interfaces. + +Developed at: +Released at: + +## Compilation + +A standard TeX distribution that includes XeTeX is needed to compile the `xetex-reference.tex` document. The following (freely available) fonts are required to be installed in your texmf tree: + +* Linux Libertine O +* Antykwa Torunska +* Charis SIL + +## Legalities + +Copyright 2007-2019 Will Robertson +Copyright 2018 Joseph Wright +Copyright 2011-2017 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 Will Robertson. diff --git a/info/xetexref/xetex-reference.pdf b/info/xetexref/xetex-reference.pdf new file mode 100644 index 0000000000..d2e2ddc92a Binary files /dev/null and b/info/xetexref/xetex-reference.pdf differ diff --git a/info/xetexref/xetex-reference.tex b/info/xetexref/xetex-reference.tex new file mode 100644 index 0000000000..ea7e45707c --- /dev/null +++ b/info/xetexref/xetex-reference.tex @@ -0,0 +1,1352 @@ +% Copyright 2007-2017 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 Will Robertson. +% +% This work consists of the files xetex-reference.tex, +% README.txt, and the derived file xetex-reference.pdf. + +\documentclass[12pt]{article} + +\title{The \xetex reference guide\\\url{https://ctan.org/pkg/xetexref}} +\author{Will Robertson \and Khaled Hosny \and Karl Berry} +\date{2019-03-05} + +\suppressfontnotfounderror=1 + +\makeatletter +\def\@dotsep{999} + +\usepackage{fontspec,unicode-math} +\setmainfont{texgyrepagella}[ + Extension = .otf , + UprightFont = *-regular , + ItalicFont = *-italic , + BoldFont = *-bold , + BoldItalicFont = *-bolditalic , + Scale=MatchLowercase + ] +\setsansfont{texgyreheros}[ + Extension = .otf , + UprightFont = *-regular , + ItalicFont = *-italic , + BoldFont = *-bold , + BoldItalicFont = *-bolditalic , + Scale=MatchLowercase + ] +\setmonofont{inconsolata}[ + Scale=MatchLowercase, + StylisticSet=3, % <- straight quotes + AutoFakeSlant=.2] +\setmathfont{texgyrepagella-math.otf} + +\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 \& Karl Berry}, + 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$} +\let\meta\xarg +\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\relax % let existing font continue +\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} +\maketitle + +\vfill + +\section*{Introduction} + +This document serves to summarise additional features of \xetex without +being so much as a ‘users’ guide. 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 rather +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 + +\section{The \cs{font} command} + +Traditionally, fonts were selected in \tex like this: +|\font\1=|\xarg{tfm name} \xarg{\tex font options}, where the \xarg{\tex +font options} included possibilities such as +\ ‘| at 10pt|’ \ +or \ ‘| scaled 1200|’, +with evident meaning. This syntax still works, but it has been greatly +extended in \xetex. + +The extended syntax looks schematically like this: + +\begin{quote} + |\font\1="|\xarg{font identifier} + \xarg{font options}% + |:|\xarg{font features}% + |"|\ \xarg{\tex font options} +\end{quote} + +\noindent Each part of this command is discussed in the following, but +here is an overview, starting from the end: + +\begin{itemize} +\item The \xarg{\tex font options} are unchanged from traditional \tex. + +\item The ASCII double quote character |"| (hex 0x22) surrounds any font +definition using the extended syntax. + +\item The \xarg{font features} are an optional list of names, +comma or semi-colon separated, preceded by an ASCII colon |:| (0x3a). + +\item The \xarg{font options} are an optional list of specifiers which +can only be used with system fonts (see next). + +\item The \xarg{font identifier} is the only mandatory part of the +above syntax. If it is given in square brackets, (\eg, +|\font\1="[lmroman10-regular]"|), it is taken as a font file name. +Without brackets, the name is looked up as both a file name and a system +font name. + +\end{itemize} + +This distinction between file name lookups and system font name lookups +is crucial to understanding \xetex's behavior and to writing portable +documents (in short: don't use system fonts). + +System font name lookups use (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 does the system font lookups +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\1="[lmroman10-regular]"| \hfill + {\em find |lmroman10-regular.otf| in any tree} +|\font\2="[/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. + +\subsection{Font collection files} + +One more special case about the \xarg{font identifier}: if the file is a +font collection (\eg, |.ttc| or |.dfont|), the index of the font can be +specified using a colon followed by zero-based font index inside the +square brackets (in contrast to the font features we'll describe soon, +which follow a colon outside any square brackets). \Eg, +\begin{quote}\small +|\font\2="[myfont.ttc:1]"| \hfill {\em load the second font from |myfont.ttc| file} +\end{quote} + + +\subsection{Font options: For OS-selected fonts only} + +The following \xarg{font options} are only applicable when the font is selected +through the operating system (\ie, without square brackets): +\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. +\end{optdesc} + +The following \xarg{font options} control which `renderer' \xetex uses to interface with the font: +\begin{optdesc} +\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: For all fonts} + +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 utility files \path{aat-info.tex} and +\path{opentype-info.tex} provide lists of supported features for a given +font (see comments at the top of each). + +\subsubsection{Font features specific to OpenType, Graphite, or AAT} + +OpenType font features are usually 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="[LinLibertine_RI.otf]/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, may be activated by default. + +\begin{example} +\font\antt="[AntykwaTorunska-Regular.otf]" at 12pt \antt 0 +\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=0" at 12pt \antt 0 +\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=1" at 12pt \antt 0 +\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=2" at 12pt \antt 0 +\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=3" at 12pt \antt 0 +\font\antt="[AntykwaTorunska-Regular.otf]:+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="[CharisSIL-R.ttf]/GR:Small Caps=True" at 12pt +\gra This is the Graphite font Charis SIL with small caps. +\end{example} + +\subsubsection{Features for all fonts} + +Some font features may be applied for any font. These are +\begin{optdesc} + +\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. + +\begin{example} +\font\9="[lmsans10-regular]:color=0000FF,mapping=tex-text" +\9 A sans blue quoted em-dash: ``---''. +\end{example} + +\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$ (\ie, $x=1$ +corresponds to no change). + +\item[letterspace=$x$] +Adds $x/S$ space between letters in words, where $S$ is the font size. + +\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 ASCII |``---''| to proper typographical +glyphs “—”, and so on. + +\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{