diff options
| -rw-r--r-- | luaotfload.dtx | 228 |
1 files changed, 162 insertions, 66 deletions
diff --git a/luaotfload.dtx b/luaotfload.dtx index 818dbd9..3121512 100644 --- a/luaotfload.dtx +++ b/luaotfload.dtx @@ -130,13 +130,14 @@ and the derived files \setsansfont[Ligatures=TeX,Scale=MatchLowercase]{Iwona Medium} %setmathfont{XITS Math} -\newcommand\TEX {\TeX\xspace} -\newcommand\LUA {Lua\xspace} -\newcommand\PDFTEX {pdf\TeX\xspace} -\newcommand\LUATEX {Lua\TeX\xspace} -\newcommand\XETEX {\XeTeX\xspace} -\newcommand\LATEX {\LaTeX\xspace} -\newcommand\CONTEXT{Con\TeX t\xspace} +\newcommand\TEX {\TeX\xspace} +\newcommand\LUA {Lua\xspace} +\newcommand\PDFTEX {pdf\TeX\xspace} +\newcommand\LUATEX {Lua\TeX\xspace} +\newcommand\XETEX {\XeTeX\xspace} +\newcommand\LATEX {\LaTeX\xspace} +\newcommand\CONTEXT {Con\TeX t\xspace} +\newcommand\OpenType{\identifier{Open\kern-.25ex Type}\xspace} \def\definehighlight[#1][#2]% {\ifcsname #1\endcsname\else @@ -192,9 +193,9 @@ and the derived files % \maketitle % % \begin{abstract} -% This package is an adaptation of the \CONTEXT font loading system, providing -% the ability to load \identifier{OpenType} fonts with extended font loading syntax -% supporting a large selection of \identifier{OpenType} font features. +% This package is an adaptation of the \CONTEXT font loading system. +% It allows for loading \OpenType fonts with an extended syntax and adds +% support for a variety of font features. % \end{abstract} % % \tableofcontents @@ -203,13 +204,13 @@ and the derived files % % Font management and installation has always been painful with \TEX. A lot of % files are needed for one font (\abbrev{tfm}, \abbrev{pfb}, \abbrev{map}, -% \abbrev{fd}, \abbrev{vf}), and as \TEX is 8-bit each font is limited to 256 -% characters. +% \abbrev{fd}, \abbrev{vf}), and due to the 8-Bit encoding each font is limited +% to 256 characters. % But the font world has evolved since the original % \TEX, and new typographic systems have appeared, most notably the so -% called \emphasis{smart font} technologies like \identifier{OpenType} -% (\abbrev{otf}) fonts. -% These fonts can contain a lot of characters and additional +% called \emphasis{smart font} technologies like \OpenType +% fonts (\abbrev{otf}). +% These fonts can contain many more characters than \TEX fonts, as well as additional % functionality like ligatures, old-style numbers, small capitals, % etc., and support more complex writing systems like Arabic and % Indic\footnote{% @@ -219,7 +220,7 @@ and the derived files % appreciated. % } % scripts. -% \identifier{OpenType} fonts are widely deployed and available for all +% \OpenType fonts are widely deployed and available for all % modern operating systems. % As of 2013 they have become the de facto standard for advanced text % layout. @@ -227,10 +228,15 @@ and the derived files % world was with the \XETEX engine. % % Unlike \XETEX, \LUATEX has no built-in support for -% \identifier{OpenType} or other technologies. -% Instead, it provides hooks for executing Lua during the \TEX run +% \OpenType or technologies other than the original \TEX fonts. +% Instead, it provides hooks for executing \Lua code during the \TEX run % that allow implementing extensions for loading fonts and manipulating % how input text is processed without modifying the underlying engine. +% This is where \identifier{luaotfload} comes into play: +% Based on code from \CONTEXT, it extends \LUATEX with functionality necessary +% for handling \OpenType fonts. +% Additionally, it provides means for accessing fonts known to the operating +% system conveniently by indexing the metadata. % % \section{Loading fonts} % @@ -252,7 +258,7 @@ and the derived files % \paragraph{Prefix} % % The \meta{prefix} is either |file:| or |name:|. -% It determines whether font loader should interpret the request as a +% It determines whether the font loader should interpret the request as a % file name or font name, respectively, which again influences how it % will attempt to locate the font. % The prefix can be omitted, in which case |name:| is assumed. @@ -266,30 +272,89 @@ and the derived files %% For compatibility with \XETEX, surrounding the \meta{font name} with %% square brackets is synonymous to using the |file:| prefix. % -% Accessing fonts by fontname allows loading system installed fonts as -% well as \fileent{texmf} ones, and requires a font names database; see -% Section~\ref{sec:fontdb} for more information. +% In order for fonts installed both in system locations and in your +% \fileent{texmf} to be accessible by font name, \identifier{luaotfload} must +% first collect the metadata included in the files. +% Please refer to section ~\ref{sec:fontdb} below for instructions on how to +% create the database. % % \paragraph{Font name} % % The \meta{font name} can be either a font filename or actual font % name based on the \meta{prefix} as mentioned above. % -% Fonts loaded by filename may either include their absolute path in -% the filesystem or consist of just the filename without a path. If no -% path is specified, then \identifier{kpathsea} is used to locate the +% A filename request may optionally include the absolute path to the font file, +% allowing for fonts outside the standard locations to be loaded as well. +% If no path is specified, then \identifier{kpathsea} is used to locate the % font (which will typically be in the \fileent{texmf} tree or the % current directory). % -% For example, +% \subparagraph{Examples for loading by file name} +% +% For example, conventional \abbrev{type1} font can be loaded with a \verb|file:| +% request like so: +% % \begin{quote} -% \begin{verbatim} -% \font\1={file:ec-lmr10} at 10pt -% \font\2={/Users/Shared/Fonts/aldus.otf} at 11pt -% \font\3={name:TeX Gyre Pagella} at 9pt -% \end{verbatim} +% \begin{verbatim} +% \font\lmromanten={file:ec-lmr10} at 10pt +% \end{verbatim} +% \end{quote} +% +% The \OpenType version of Janusz Nowacki’s font \emphasis{Antykwa +% Półtawskiego} (in \TEX Live) in its condensed variant can be loaded as +% follows: +% +% \begin{quote} +% \begin{verbatim} +% \font\apcregular=file:antpoltltcond-regular.otf at 42pt +% \end{verbatim} +% \end{quote} +% +% The next example shows how to load the \emphasis{Porson} font digitized by +% the Greek Font Society using \XETEX-style syntax and an absolute path from a +% non-standard directory: +% +% \begin{quote} +% \begin{verbatim} +% \font\gfsporson="[/tmp/GFSPorson.otf]" at 12pt +% \end{verbatim} +% \end{quote} +% +% \subparagraph{Examples for loading by font name} +% +% The \verb|name:| lookup does not depend on cryptic filenames: +% +% \begin{quote} +% \begin{verbatim} +% \font\pagellaregular={name:TeX Gyre Pagella} at 9pt +% \end{verbatim} +% \end{quote} +% +% A bit more specific but essentially the same lookup would be: +% +% \begin{quote} +% \begin{verbatim} +% \font\pagellaregular={name:TeX Gyre Pagella Regular} at 9pt +% \end{verbatim} % \end{quote} % +% Which fits nicely with the whole set: +% +% \begin{quote} +% \begin{verbatim} +% \font\pagellaregular ={name:TeX Gyre Pagella Regular} at 9pt +% \font\pagellaitalic ={name:TeX Gyre Pagella Italic} at 9pt +% \font\pagellabold ={name:TeX Gyre Pagella Bold} at 9pt +% \font\pagellabolditalic={name:TeX Gyre Pagella Bolditalic} at 9pt +% +% {\pagellaregular foo bar baz\endgraf} +% {\pagellaitalic foo bar baz\endgraf} +% {\pagellabold foo bar baz\endgraf} +% {\pagellabolditalic foo bar baz\endgraf} +% +% ... +% \end{verbatim} +% \end{quote} % % \paragraph{Font features} % @@ -298,10 +363,14 @@ and the derived files % Cf. \url{http://www.microsoft.com/typography/otspec/featurelist.htm}. % } % and font options. -% Prepending a font feature with a |+|-sign enables it, while -% a |-| disables it. For instance, the request +% Prepending a font feature with a |+| (plus sign) enables it, whereas +% a |-| (minus) disables it. For instance, the request % -% |\font\test=Latin Modern Roman:+clig;-kern| +% \begin{quote} +% \begin{verbatim} +% \font\test=LatinModernRoman:+clig;-kern +% \end{verbatim} +% \end{quote} % % \noindent activates contextual ligatures (|clig|) and disables % kerning (|kern|). @@ -309,35 +378,45 @@ and the derived files % the feature in a key/value expression. % The following request has the same meaning as the last one: % -% |\font\test=Latin Modern Roman:clig=true;kern=false| +% \begin{quote} +% \begin{verbatim} +% \font\test=LatinModernRoman:clig=true;kern=false +% \end{verbatim} +% \end{quote} % % \noindent -% Furthermore, this second syntax is required if a font feature -% accepts options besides its activation state. -% For example, \emphasis{stylistic alternates} (|salt|) provide a set -% of variants to given glyphs. -% These can be selected either explicitly by supplying the variant -% index (starting from 1), or randomly by setting the value to, -% obviously, |random|: -% -% |\font\test=Latin Modern Roman:salt=1| +% Furthermore, this second syntax is required should a font feature +% accept other options besides a true/false switch. +% For example, \emphasis{stylistic alternates} (|salt|) are variants of given +% glyphs. +% They can be selected either explicitly by supplying the variant +% index (starting from one), or randomly by setting the value to, +% obviously, |random|. +% +% \iffalse TODO verify that this actually works with a font that supports +% the salt feature!\false +% \begin{quote} +% \begin{verbatim} +% \font\librmsaltfirst=LatinModernRoman:salt=1 +% \end{verbatim} +% \end{quote} % % \noindent Other font options include: % % \begin{description} % % \item [mode] \hfill \\ -% \identifier{luaotfload} has two \identifier{OpenType} processing +% \identifier{luaotfload} has two \OpenType processing % \emphasis{modes}: % \identifier{base} and \identifier{node}. % -% \identifier{base} mode works by mapping \identifier{OpenType} -% features to traditional \TEX ligature and kerning mechanisms, -% thus supporting only non-contextual substitutions and kerning -% pairs, but is the slightly faster variant. -% \identifier{node} mode works by processing \TEX’s internal +% \identifier{base} mode works by mapping \OpenType +% features to traditional \TEX ligature and kerning mechanisms. +% Supporting only non-contextual substitutions and kerning +% pairs, it is the slightly faster, albeit somewhat limited, variant. +% \identifier{node} mode works by processing \TeX’s internal % node list directly at the \LUA end and supports -% a wider range of \identifier{OpenType} features. +% a wider range of \OpenType features. % The downside is that the intricate operations required for % \identifier{node} mode may slow down typesetting especially % with complex fonts and it does not work in math mode. @@ -346,19 +425,20 @@ and the derived files % mode, and \identifier{base} mode has to be requested where needed, % e.~g. for math fonts. % -% \item [script] \ref{script-tag} \hfill \\ -% An \identifier{OpenType} script tag;\footnote{% +% \item [script] \label{script-tag} \hfill \\ +% An \OpenType script tag;\footnote{% % See \url{http://www.microsoft.com/typography/otspec/scripttags.htm} % for a list of valid values. % For scripts derived from the Latin alphabet the value % |latn| is good choice. % } % the default value is |dlft|. -% Some fonts do not assign features to the |dflt| script, in +% Some fonts, including very popular ones by foundries like Adobe, +% do not assign features to the |dflt| script, in % which case the script needs to be set explicitly. % % \item [language] \hfill \\ -% An \identifier{OpenType} language system identifier,\footnote{% +% An \OpenType language system identifier,\footnote{% % Cf. \url{http://www.microsoft.com/typography/otspec/languagetags.htm}. % } % defaulting to |dflt|. @@ -367,13 +447,13 @@ and the derived files % A comma-separated list of feature files to be applied to the % font. % Feature files contain a textual representation of -% \identifier{OpenType} tables and extend the features of a font +% \OpenType tables and extend the features of a font % on fly. % After they are applied to a font, features defined in a % feature file can be enabled or disabled just like any % other font feature. % The syntax is documented in \identifier{Adobe}’s -% \identifier{OpenType} Feature File Specification.\footnote{% +% \OpenType Feature File Specification.\footnote{% % Cf. \url{http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html}. % } % @@ -391,13 +471,17 @@ and the derived files % % For example, in order to set text in semitransparent red: % -% |\font\test=Latin Modern Roman:color=FF0000BB| +% \begin{quote} +% \begin{verbatim} +% \font\test={Latin Modern Roman}:color=FF0000BB +% \end{verbatim} +% \end{verbatim} % % \item [protrusion \& expansion] \hfill \\ -% These keys both control microtypographic features of the font, +% These keys control microtypographic features of the font, % namely \emphasis{character protrusion} and \emphasis{font % expansion}. -% They accept names of predefined \LUA tables that contain +% Their arguments are names of \LUA tables that contain % values for the respective features.\footnote{% % For examples of the table layout please refer to the % section of the file \fileent{otfl-fonts-ext.lua} where the @@ -423,12 +507,16 @@ and the derived files % for details. % }: % -% |\font\test=Latin Modern Roman:protrusion=default| +% \begin{quote} +% \begin{verbatim} +% \font\test=LatinModernRoman:protrusion=default +% \end{verbatim} +% \end{verbatim} % \end{description} % % \paragraph{Non-standard font features} -% \identifier{luaotfload} add a number of features that are not defined -% in the original \identifier{OpenType} specification, most of them +% \identifier{luaotfload} adds a number of features that are not defined +% in the original \OpenType specification, most of them % aiming at emulating the behavior familiar from other \TEX engines. % Currently (2013) there are three of them: % @@ -441,7 +529,15 @@ and the derived files % % \item [tlig] % Applies legacy \TEX ligatures: -% |``|, |''|, |`|, |'|, |"|, |--|, |---|, |!`| and |?`|.% +% +% \begin{tabular}{rl|rl} +% `` & \verb|``| & '' & \verb|''| \\ +% ` & \verb|`| & ' & \verb|'| \\ +% " & \verb|"| & -- & \verb|--| \\ +% --- & \verb|---| & !` & \verb|!`| \\ +% ?` & \verb|?`| & & \\ +% \end{tabular} + % \footnote{% % These contain the feature set \verb|trep| of earlier % versions of \identifier{luaotfload}. @@ -768,7 +864,7 @@ and the derived files % by \fileent{otfl-font-nms.lua}. % \ouritem {otfl-luat-ovr.lua} overrides for the \CONTEXT logging % functionality. -% \ouritem {otfl-font-pfb.lua} registers the \identifier{OpenType} +% \ouritem {otfl-font-pfb.lua} registers the \OpenType % font reader as handler for % Postscript fonts. % \ouritem {otfl-font-nms.lua} font database. @@ -803,7 +899,7 @@ and the derived files % being (see above, page \pageref{font-blacklist}). % % A common problem is the lack of features for some -% \identifier{OpenType} fonts even when specified. +% \OpenType fonts even when specified. % This can be related to the fact that some fonts do not provide % features for the |dflt| script (see above on page % \pageref{script-tag}), |