diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/fontspec/fontspec-doc-intro.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/fontspec/fontspec-doc-intro.tex | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/fontspec/fontspec-doc-intro.tex b/Master/texmf-dist/source/latex/fontspec/fontspec-doc-intro.tex new file mode 100644 index 00000000000..560a68e003b --- /dev/null +++ b/Master/texmf-dist/source/latex/fontspec/fontspec-doc-intro.tex @@ -0,0 +1,202 @@ + +\part{Getting started} + +\section{History} + +This package began life as a \LaTeX\ interface to select system-installed +\MacOSX\ fonts in \name{Jonathan Kew}'s \XeTeX, the first widely-used +Unicode extension to \TeX. Over time, \XeTeX\ was extended to support OpenType +fonts and then was ported into a cross-platform program to run also on Windows +and Linux. + +More recently, \LuaTeX\ is fast becoming the \TeX\ engine of the day; it +supports Unicode encodings and OpenType fonts and opens up the internals of +\TeX\ via the Lua programming language. Hans Hagen's Con\TeX t Mk.\,IV is a +re-write of his powerful typesetting system, taking full advantage of +\LuaTeX's features including font support; a kernel of his work in this area +has been extracted to be useful for other \TeX\ macro systems as well, and +this has enabled \pkg{fontspec} to be adapted for \LaTeX\ when run with the +\LuaTeX\ engine. + + + +\section{Introduction} + +The \pkg{fontspec} package allows users of either \XeTeX\ or \LuaTeX\ to +load OpenType fonts in a \LaTeX\ document. No font installation is necessary, +and font features can be selected and used as desired throughout the document. + +Without \pkg{fontspec}, it is necessary to write cumbersome font definition +files for \LaTeX, since \LaTeX's font selection scheme (known as the +`\textsc{nfss}') has a lot going on behind the scenes to allow easy +commands like \cmd\emph\ or \cmd\bfseries. With an uncountable number of +fonts now available for use, however, it becomes less desirable to have to +write these font definition (|.fd|) files for every font one wishes to use. + +Because \pkg{fontspec} is designed to work in a variety of modes, this +user documentation is split into separate sections that are designed to be +relatively independent. Nonetheless, the basic functionality all behaves in +the same way, so previous users of \pkg{fontspec} under \XeTeX\ should have +little or no difficulty switching over to \LuaTeX. + +This manual can get rather in-depth, as there are a lot of details +to cover. See the documents \path{fontspec-example.tex} for a complete minimal example +to get started quickly. + + +\subsection{Acknowledgements} + +This package could not have been possible without the early and continued support +the author of \XeTeX, Jonathan Kew. When I started this package, he steered +me many times in the right direction. + +I've had great +feedback over the years on feature requests, documentation queries, bug reports, font suggestions, and so on from lots of people all around the world. +Many thanks to you all. + +Thanks to David Perry and Markus B\"ohning for numerous documentation +improvements and David Perry again for contributing the text for one of the +sections of this manual. + +Special thanks to Khaled Hosny, who was the driving force behind the support for \LuaLaTeX, ultimately leading to version 2.0 of the package. + + + +\section{Package loading and options} + +For basic use, no package options are required: +\begin{Verbatim} + \usepackage{fontspec} +\end{Verbatim} +Package options will be introduced below; some preliminary details are discussed first. + + +\subsection{Font encodings} +The 2016 release of \pkg{fontspec} initiated some changes for font encodings and the loading of \pkg{xunicode}. +The 2017 release rolls out those changes as default. + +The now-default \texttt{tuenc} package option switches the \textsc{nfss} font encoding to \texttt{TU}. +\texttt{TU} is a new Unicode font encoding, intended for both \XeTeX\ and \LuaTeX\ engines, and automatically contains support for symbols covered by \LaTeX's traditional \texttt{T1} and \texttt{TS1} font encodings (for example, |\%|, |\textbullet|, |\"u|, and so on). +As a result, with this package option, Ross Moore's \pkg{xunicode} package is \textbf{not} loaded. +Some new, experimental, features are now provided to customise some encoding details; see Part~\vref{part:enc} for further details. + +Pre-2017 behaviour can be achieved with the \texttt{euenc} package option. +This selects the \texttt{EU1} or \texttt{EU2} encoding (\XeTeX/\LuaTeX, resp.) and loads the \pkg{xunicode} package. +Package authors and users who have referred explicitly to the encoding names \texttt{EU1} or \texttt{EU2} should update their code or documents. +(See internal variable names described in \vref{sec:api} for how to do this properly.) + + +\subsection{Maths fonts adjustments} +By default, \pkg{fontspec} adjusts \LaTeX's default maths setup in order to maintain the correct Computer Modern symbols when the roman font changes. +However, it will attempt to avoid doing this if another maths font package is loaded (such as \pkg{mathpazo} or the \pkg{unicode-math} package). + +If you find that \pkg{fontspec} is incorrectly changing the maths font when it shouldn't be, apply the |no-math| package option to manually suppress its behaviour here. + + +\subsection{Configuration} +\label{sec:config} + +If you wish to customise any part of the +\pkg{fontspec} interface, this should be done by creating your own +\texttt{fontspec.cfg} file, +which will be automatically loaded if it is found by \XeTeX\ or \LuaTeX. +A |fontspec.cfg| file is distributed with \pkg{fontspec} with a small number of defaults set up within it. + +To customise \pkg{fontspec} to your liking, use the standard |.cfg| file as a starting point or write your own from scratch, then either place it in the same folder as the main document for isolated cases, or in a location +that \XeTeX\ or \LuaTeX\ searches by default; \eg\ in Mac\TeX: \path{~/Library/texmf/tex/latex/}. + +The package option |no-config| will suppress the loading of the |fontspec.cfg| file under all circumstances. + + +\subsection{Warnings} +\label{sec:quiet-warnings} + +This package can give some warnings that can be harmless if you know what +you're doing. Use the |quiet| package option to write these warnings to the +transcript (\texttt{.log}) file instead. + +Use the |silent| package option to completely suppress these warnings if you +don't even want the |.log| file cluttered up. + + + +\section{Interaction with \LaTeXe\ and other packages} + +This section documents some areas of adjustment that \pkg{fontspec} makes +to improve default behaviour with \LaTeXe\ and third-party packages. + + +\subsection{Verbatim} +\label{sec:verb} + +Many verbatim mechanisms assume the existence of a `visible space' character that exists in the \textsc{ascii} space slot of the typewriter font. This character is known in Unicode as \unichar{2423}{box open}, which looks like this: `\verb*| |'. + +When a Unicode typewriter font is used, \LaTeX\ no longer prints visible spaces for the |verbatim*| environment and |\verb*| command. +This problem is fixed by using the correct Unicode glyph, and the following packages are patched to do the same: +\pkg{listings}, \pkg{fancyvrb}, \pkg{moreverb}, and \pkg{verbatim}. + +In the case that the typewriter font does not contain `\verb*| |', the Latin Modern Mono font is used as a fallback. + + +\subsection{Discretionary hyphenation: \cmd\-} +\label{sec:hyphen} + +\DescribeMacro{\-} +\LaTeX\ defines the macro \cmd\-\ to insert discretionary hyphenation points. +However, it is hard-coded in \LaTeX\ to use the hyphen |-| character. +Since \pkg{fontspec} provides features to change the hyphenation character on +a per font basis, the definition of \cmd\-\ is changed to adapt accordingly. + + +\subsection{Commands for old-style and lining numbers} + +\DescribeMacro{\oldstylenums} +\DescribeMacro{\liningnums} +\LaTeX's definition of \cs{oldstylenums} relies on strange font encodings. +We provide a \pkg{fontspec}-compatible alternative and while we're at it +also throw in the reverse option as well. Use \cs{oldstylenums}\marg{text} +to explicitly use old-style (or lowercase) numbers in \meta{text}, and +the reverse for \cs{liningnums}\marg{text}. + + +\subsection{Italic small caps} + +\DescribeMacro{\itshape} +\DescribeMacro{\slshape} +\DescribeMacro{\scshape} +Note that this package redefines the \cs{itshape}, \cs{slshape}, and \cs{scshape} commands in order to allow them to select italic small caps in conjunction. +With these changes, writing |\itshape\scshape| will lead to italic small caps, and |\upshape| subsequently then moves back to small caps only. |\upshape| again returns from small caps to upright regular. +(And similarly for for |\slshape|. In addition, once italic small caps are selected then |\slshape| will switch to slanted small caps, and vice versa.) + + +\subsection{Emphasis and nested emphasis} + +\DescribeMacro{\eminnershape} +\LaTeXe\ allows you to specify the behaviour of \cs{emph} nested within \cs{emph} by setting the \cs{eminnershape} command. +For example, +\begin{Verbatim} + \renewcommand\eminnershape{\upshape\scshape} +\end{Verbatim} +will produce small caps within |\emph{\emph{...}}|. + +\DescribeMacro{\emfontdeclare} +The \pkg{fontspec} package takes this idea one step further to allow arbitrary font changes (e.g., boldness) and arbitrary levels of nesting within emphasis. +This is performed using the |\emfontdeclare| command, which takes a comma-separated list of font switches corresponding to increasing levels of emphasis. +Two examples: +\begin{enumerate} +\item |\emfontdeclare{\itshape,\upshape\scshape,\itshape}| will lead to `italics', `small caps', then `italic small caps' as the level of emphasis increases, as long as italic small caps are defined for the font. + Note that |\upshape| is required because the font changes are cascading. +\item |\emfontdeclare{\bfseries,\fontseries{h}\selectfont,\fontseries{x}\selectfont}| could lead to (if fonts are set up correctly) `bold', `heavy', and `extra bold'. +\end{enumerate} +The implementation of these feature tries to be `smart' and guess what level of emphasis to use in the case of manual font changing. +This is reliable only if you use series- and/or shape- changing commands in \cs{emfontdeclare}. +For example: +\begin{Verbatim} + \emfontdeclare{\itshape,\upshape\scshape,\itshape} + ... + \scshape small caps \emph{hello} +\end{Verbatim} +Here, the emphasised text `hello' will be printed in italic small caps since |\emph| can detect that the current font shape is already in the second `mode' of emphasis. + +\DescribeMacro{\emreset} +Finally, if you have so much nested emphasis that |\emfontdeclare| runs out of options, it will insert |\emreset| (by default just |\upshape|) and start again from the beginning. |