path: root/macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex

%%^^A%%  fontspec-doc-xetex.tex -- part of FONTSPEC <wspr.io/fontspec>

\documentclass[a4paper]{l3doc}
\usepackage{fontspec-doc-style}
\showexamplesfalse
\begin{document}

\part{Fonts and features with \XeTeX}
\label{sec:xetex-features}

\section{\XeTeX-only font features}

The features described here are available for any font
selected by \pkg{fontspec}.

\subsection{Mapping}
\label{sec:mapping}

The \feat{Mapping} feature enables a \XeTeX\ text-mapping scheme, with an example shown in \exref{mapping}.

\begin{Xexample}{mapping}{\XeTeX's \feat{Mapping} feature.}
  \fontspec{texgyrepagella-regular.otf}[Mapping=tex-text]
  ``!`A small amount of---text!''
\end{Xexample}

Only one mapping can be active at a time and a second call to \feat{Mapping}
will override the first.
Using the |tex-text| mapping is also equivalent to writing |Ligatures=TeX|.
The use of the latter syntax is recommended for better compatibility with
\LuaTeX\ documents.


\subsection{Different font technologies: \AAT, OpenType, and Graphite}\label{sec:renderer-xetex}

\textbf{Note that from 2020 it appears that \XeTeX\ can no longer support \AAT\ fonts in \MacOSX.}

\XeTeX\ supports three rendering technologies for typesetting, selected with
the \feat{Renderer} font feature. The first, \opt{AAT}, is
that provided only by \MacOSX.
The second, \opt{OpenType}, is an open source OpenType interpreter.
It provides greater support for OpenType features, notably contextual arrangement, over \opt{AAT}.
The third is \opt{Graphite}, which is an alternative to OpenType with particular features for less-common languages and the capability for more powerful font options.
Features for \opt{OpenType} have already been discussed in \vref{sec:opentype-features};
\opt{Graphite} and \opt{AAT} features are discussed later in \vref{sec:graphite-features} and \vref{sec:aat-features}.

Unless you have a particular need, the \feat{Renderer} feature is rarely explicitly required: for OpenType
fonts, the \opt{OpenType} renderer is used automatically, and for \AAT\ fonts,
\opt{AAT} is chosen by default. Some fonts, however, will contain font tables
for multiple rendering technologies, such as the Hiragino Japanese fonts
distributed with \MacOSX, and in these cases one over the other may be preferred.

Among some other font features only available through a specific renderer,
\opt{OpenType} provides for the \feat{Script} and \feat{Language} features, which allow
different font behaviour for different alphabets and languages; see \vref{sec:ot}
for the description of these features. {\em Because these font features can
change which features are able to be selected for the font instance, they are selected
by \pkg{fontspec} before all others and will automatically and without warning
select the \opt{OpenType} renderer.}


\subsection{Optical font sizes} \label{sec:aat-opticalsize}

Multiple Master fonts are parameterised over
orthogonal font axes, allowing continuous selection along such
features as weight, width, and optical size.
Whereas an OpenType font will have only a few separate
optical sizes, a Multiple Master font's optical size can be
specified over a continuous range. Unfortunately, this flexibility makes
it harder to create an automatic interface through \LaTeX, and the
optical size for a Multiple Master font must always be specified
explicitly.
\begin{Verbatim}
  \fontspec{Minion MM Roman}[OpticalSize=11]
   MM optical size test                    \\
  \fontspec{Minion MM Roman}[OpticalSize=47]
   MM optical size test                    \\
  \fontspec{Minion MM Roman}[OpticalSize=71]
   MM optical size test                    \\
\end{Verbatim}


\subsection{Vertical typesetting}

\XeTeX\ provides for vertical typesetting simply with the ability to rotate
the individual glyphs as a font is used for typesetting, as shown in
\exref{vert}.

\begin{Xexample}[firstline=2]{vert}{Vertical typesetting.}
  \def\verttext{共産主義者は}
  \fontspec{Hiragino Mincho Pro}
  \verttext

  \fontspec{Hiragino Mincho Pro}[Renderer=AAT,Vertical=RotatedGlyphs]
  \rotatebox{-90}{\verttext}% requires the graphicx package
\end{Xexample}

No actual provision is made for typesetting top-to-bottom
languages; for an example of how to do this, see the vertical Chinese
example provided in the \XeTeX\ documentation.


\section{The Graphite renderer}
\label{sec:graphite-features}

Since the Graphite renderer is designed for less common scripts and languages, usually with
specific or unique requirements, Graphite features are not standard across fonts.

Currently \pkg{fontspec} does not support a convenient interface to select Graphite font
features and all selection must be done via `raw' font feature selection.

Here's an example:
\begin{Verbatim}
  \fontspec{Charis SIL}[
    Renderer=Graphite,
    RawFeature={Uppercase Eng alternates=Large eng on baseline}]
  Ŋ
\end{Verbatim}

Here's another:
\begin{Verbatim}
\fontspec{AwamiNastaliq-Regular.ttf}[Renderer=Graphite] ^^^^06b5
\addfontfeature{RawFeature={Lam with V=V over bowl}}    ^^^^06b5
\end{Verbatim}



\section{\MacOSX's \AAT\ fonts}
\label{sec:aat-features}

\begin{quote}\itshape
\textbf{Warning!}
\XeTeX's implementation on \MacOSX\ is currently in a state of flux and the information contained below may well be wrong from 2013 onwards.
There is a good chance that the features described in this section will not be available any more as \XeTeX's completes its transition to a cross-platform--only application.
All examples in this section have now been removed.
\end{quote}

\MacOSX's font technology began life before the ubiquitous-OpenType era
and revolved around the Apple-invented `\AAT' font format. This format
had some advantages (and other disadvantages) but it never became widely
popular in the font world.

Nonetheless, this is the font format that was first supported by \XeTeX\
(due to its pedigree on \MacOSX\ in the first place) and was the first
font format supported by \pkg{fontspec}. A number of fonts distributed with
\MacOSX\ are still in the \AAT\ format, such as `Skia'.

\subsection{Ligatures}

\feat{Ligatures} refer to the replacement of two separate characters
with a specially drawn glyph for functional or \ae sthetic reasons.
For \AAT\ fonts, you may choose from any combination of \opt{Required},
\opt{Common}, \opt{Rare} (or \opt{Discretionary}), \opt{Logos}, \opt{Rebus},
\opt{Diphthong}, \opt{Squared}, \opt{AbbrevSquared}, and \opt{Icelandic}.

Some other Apple \AAT\ fonts have those `Rare' ligatures contained in
the \opt{Icelandic} feature. Notice also that the old \TeX\ trick of
splitting up a ligature with an empty brace pair does not work in
\XeTeX; you must use a 0\,pt kern or \cs{hbox} (\eg, \cs{null}) to
split the characters up if you do not want a ligature to be performed (the usual examples for when this might be desired are words like `shelf\null full').

\subsection{Letters} \label{sec:aat-letters}
The \opt{Letters} feature specifies how the letters in the current font
will look. For \AAT\ fonts, you may choose from \opt{Normal},
\opt{Uppercase}, \opt{Lowercase}, \opt{SmallCaps}, and
\opt{InitialCaps}.


\subsection{Numbers}
The \feat{Numbers} feature defines how numbers will look in the
selected font. For \AAT\ fonts, they may be a
combination of \opt{Lining} or \opt{OldStyle} and \opt{Proportional} or
\opt{Monospaced} (the latter is good for tabular material). The synonyms
\opt{Uppercase} and \opt{Lowercase} are equivalent to \opt{Lining} and
\opt{OldStyle}, respectively. The differences have been shown previously
in \vref{sec:addfontfeatures}.

\subsection{Contextuals} \label{sec:contextuals}
This feature refers to glyph substitution that vary by their position;
things like contextual swashes are implemented here.
The options for \AAT\ fonts are
\opt{WordInitial}, \opt{WordFinal} (\exref{wordcx}), \opt{LineInitial},
\opt{LineFinal}, and \opt{Inner} (\exref{longsaat}, also called `non-final' sometimes). As
non-exclusive selectors, like the ligatures, you can turn them off
by prefixing their name with \opt{No}.

\subsection{Vertical position}
The \feat{VerticalPosition} feature is used to access things like
subscript (\opt{Inferior}) and superscript (\opt{Superior}) numbers and
letters (and a small amount of punctuation, sometimes).
The \opt{Ordinal} option is (supposed to be)
contextually sensitive to only raise characters that appear directly
after a number.

The \pkg{realscripts} package redefines the \cmd\textsubscript\ and
\cmd\textsuperscript\ commands to use the above font features,
including for use in footnote labels.

\subsection{Fractions}
Many fonts come with the capability to typeset various forms of
fractional material. This is accessed in \pkg{fontspec} with the
\feat{Fractions} feature, which may be turned \opt{On} or \opt{Off}
in both \AAT\ and OpenType fonts.

In \AAT\ fonts, the `fraction slash' or solidus character, is
to be used to create fractions. When \feat{Fractions} are turned
\opt{On}, then only pre-drawn fractions will be used.

Using the \opt{Diagonal} option (\AAT\ only), the font will attempt
to create the fraction from superscript and subscript
characters.

Some (Asian fonts predominantly) also provide for the
\opt{Alternate} feature.

\subsection{Variants}
The \feat{Variant} feature takes a single numerical input for
choosing different alphabetic shapes.
See \vref{sec:newfeatures} for a way to assign names to variants,
which should be done on a per-font basis.

\subsection{Alternates}
Selection of \feat{Alternate}s again must be done numerically.
See \vref{sec:newfeatures} for a way to assign names to alternates,
which should be done on a per-font basis.


\subsection{Style}
The options of the \feat{Style} feature
are defined in \AAT\ as one of the following: \opt{Display},
\opt{Engraved}, \opt{IlluminatedCaps}, \opt{Italic},
\opt{Ruby},\footnotemark\ \opt{TallCaps}, or \opt{Titling}.
\footnotetext{`Ruby' refers to a small optical size, used in
Japanese typography for annotations.}

Typical examples for these features are shown in \ref{sec:ot-feat-style}.

\subsection{CJK shape}
There have been many standards for how CJK ideographic
glyphs are `supposed' to look. Some fonts will contain many alternate
glyphs in order to be able to display these gylphs
correctly in whichever form is appropriate. Both \AAT\ and OpenType
fonts support the following \feat{CJKShape} options:
\opt{Traditional}, \opt{Simplified}, \opt{JIS1978}, \opt{JIS1983},
\opt{JIS1990}, and \opt{Expert}. OpenType also supports the \opt{NLC} option.

\subsection{Character width}
See \vref{sec:CharacterWidth} for relevant examples; the features are
the same between OpenType and \AAT\ fonts.
\AAT\ also allows \feat{CharacterWidth}|=|\opt{Default} to return to
the original font settings.

\subsection{Diacritics}
Diacritics are marks, such as the acute accent or the tilde, applied to letters; they usually indicate a change in pronunciation.
In Arabic scripts, diacritics are used to indicate vowels.
You may either choose
to \opt{Show}, \opt{Hide} or \opt{Decompose} them in \AAT\ fonts.
The \opt{Hide} option is for scripts such as Arabic which may be
displayed either with or without vowel markings. E.g.,
\verb|\fontspec[Diacritics=Hide]{...}|

Some older fonts distributed with \MacOSX\ included `|O/|' \etc\ as shorthand for writing `\O' under the label of the \feat{Diacritics} feature. If you come across such fonts, you'll
want to turn this feature off (imagine typing |hello/goodbye| and
getting `hell\o goodbye' instead!) by decomposing the two characters
in the diacritic into the ones you actually
want. I recommend using
the proper \LaTeX\ input conventions for obtaining such characters
instead.


\subsection{Annotation}
Various Asian fonts are equipped with a more extensive range of
numbers and numerals in different forms. These are accessed through
the \feat{Annotation} feature with the following
options: \opt{Off},
\opt{Box}, \opt{RoundedBox}, \opt{Circle}, \opt{BlackCircle},
\opt{Parenthesis}, \opt{Period}, \opt{RomanNumerals}, \opt{Diamond},
\opt{BlackSquare}, \opt{BlackRoundSquare}, and \opt{DoubleCircle}.

\end{document}

% /©
% ------------------------------------------------
% The FONTSPEC package  <wspr.io/fontspec>
% ------------------------------------------------
% Copyright  2004-2020  Will Robertson, LPPL "maintainer"
% Copyright  2009-2015  Khaled Hosny
% Copyright  2013       Philipp Gesang
% Copyright  2013-2016  Joseph Wright
% ------------------------------------------------
% This package is free software and may be redistributed and/or modified under
% the conditions of the LaTeX Project Public License, version 1.3c or higher
% (your choice): <http://www.latex-project.org/lppl/>.
% ------------------------------------------------
% ©/