summaryrefslogtreecommitdiff
path: root/macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex')
-rw-r--r--macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex294
1 files changed, 294 insertions, 0 deletions
diff --git a/macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex b/macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex
new file mode 100644
index 0000000000..5c1e3e3e7d
--- /dev/null
+++ b/macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex
@@ -0,0 +1,294 @@
+%%^^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/>.
+% ------------------------------------------------
+% ©/