%%^^A%% fontspec-doc-intro.tex -- part of FONTSPEC \documentclass[a4paper]{l3doc} \usepackage{fontspec-doc-style} \showexamplesfalse \begin{document} \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. Package options are setup with the in-built \LaTeX{} keyval options handler. This means that the package can be loaded more than once with different options without triggering an option clash error. \DescribeOption{config} \DescribeOption{no-config} The \texttt{config} and \texttt{no-config} option must be used in the first loading and are ignored later. \subsection{Font encodings} The package 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). Some additional features are provided by \pkg{fontspec} to customise some encoding details; see Part~\vref{part:enc} for further details. \DescribeOption{euenc} \DescribeOption{tuenc} Pre-2017 behaviour is now obsolete. The \texttt{euenc} and \texttt{tuenc} package options are ignored. 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 \DescribeOption{no-math} |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/}. \DescribeOption{no-config} The package option |no-config| will suppress the loading of the |fontspec.cfg| file under all circumstances. Both options must be used the first time \pkg{fontspec} is loaded and are ignored in later calls. \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 \DescribeOption{quiet} |quiet| package option to write these warnings to the transcript (\texttt{.log}) file instead. \DescribeOption{silent} Use the |silent| package option to completely suppress these warnings if you don't even want the |.log| file cluttered up. Both options can also be used with \cs{Setkeys} in the document. Use the \DescribeOption{verbose} |verbose| option to get activate the warnings again. \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{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} Support now provided by \LaTeXe\ in 2020. \subsection{Emphasis and nested emphasis} Support now provided by \LaTeXe\ in 2020. \subsection{Strong emphasis} \DescribeMacro{\strong} \DescribeMacro{\strongenv} The \cs{strong} macro is used analogously to \cs{emph} but produces variations in weight. If you need it in environment form, use |\begin{strongenv}...\end{strongenv}|. As with emphasis, this font-switching command is intended to move through a range of font weights. For example, if the fonts are set up correctly it allows usage such as |\strong{...\strong{...}}| in which each nested \cs{strong} macro increases the weight of the font. \DescribeMacro{\strongfontdeclare} Currently this feature set is somewhat experimental and there is no syntactic sugar to easily define a range of font weights using \pkg{fontspec} commands. Use, say, the following to define first bold and then black (|k|) font faces for \cs{strong}: \begin{Verbatim} \strongfontdeclare{\bfseries,\fontseries{k}\selectfont} \end{Verbatim} \DescribeMacro{\strongreset} If too many levels of \cs{strong} are reached, \cs{strongreset} is inserted. By default this is a no-op and the font will simply remain the same. Use \cs{renewcommand}\cs{strongreset}|{\mdseries}| to start again from the beginning if desired. An example for setting up a font family for use with \cs{strong} is discussed in \vref{sec:strong-example}. \end{document} % /© % ------------------------------------------------ % The FONTSPEC package % ------------------------------------------------ % Copyright 2022-2024 The LaTeX project, LPPL "maintainer" % Copyright 2004-2022 Will Robertson % 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): . % ------------------------------------------------ % ©/