diff options
Diffstat (limited to 'macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex')
-rw-r--r-- | macros/unicodetex/latex/fontspec/fontspec-doc-xetex.tex | 294 |
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/>. +% ------------------------------------------------ +% ©/ |