diff options
Diffstat (limited to 'Master/texmf-dist/source/luatex/luaotfload/luaotfload-main.tex')
-rw-r--r-- | Master/texmf-dist/source/luatex/luaotfload/luaotfload-main.tex | 364 |
1 files changed, 273 insertions, 91 deletions
diff --git a/Master/texmf-dist/source/luatex/luaotfload/luaotfload-main.tex b/Master/texmf-dist/source/luatex/luaotfload/luaotfload-main.tex index 2e89ff000e8..967f5a2b346 100644 --- a/Master/texmf-dist/source/luatex/luaotfload/luaotfload-main.tex +++ b/Master/texmf-dist/source/luatex/luaotfload/luaotfload-main.tex @@ -1,4 +1,4 @@ -%% Copyright (C) 2009-2014 +%% Copyright (C) 2009-2015 %% %% by Elie Roux <elie.roux@telecom-bretagne.eu> %% and Khaled Hosny <khaledhosny@eglug.org> @@ -32,7 +32,7 @@ \beginfrontmatter \setdocumenttitle {The \identifier{luaotfload} package} - \setdocumentdate {2014/07/13 v2.5} + \setdocumentdate {2015/12/09 v2.6} \setdocumentauthor {Elie Roux · Khaled Hosny · Philipp Gesang\\ Home: \hyperlink {https://github.com/lualatex/luaotfload}\\ Support: \email {lualatex-dev@tug.org}} @@ -43,6 +43,11 @@ 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. + + After discussion of the font loading API, this manual gives an + overview of the core components of \identifier{Luaotfload}: The + packaged font loader code, the names database, configuration, and + helper functions on the \LUA\ end. \endabstractcontent \endfrontmatter @@ -233,7 +238,7 @@ where \meta{prefix} is either \inlinecode{file:} or \inlinecode {name:}.\footnot needed, for instance when supplying a customized tex distribution. The \inlinecode {my} lookup takes this a step further: it lets you define - a custom resolver function and hook it into the \luafunction{resolve_font} + a custom resolver function and hook it into the \luaident{resolve_font} callback. % This ensures full control over how a file is located. @@ -606,7 +611,9 @@ obviously, \inlinecode{random}. the file \inlinecode{tkrn.fea} that is part of \identifier{luaotfload}. It can be read and applied as follows: - \inlinecode{\\font \\test = Latin Modern Roman:featurefile=tkrn.fea;+tkrn} + \beginlisting + \font \test = Latin Modern Roman:featurefile=tkrn.fea;+tkrn + \endlisting \endaltitem \beginaltitem {color} @@ -619,7 +626,7 @@ obviously, \inlinecode{random}. For example, in order to set text in semitransparent red: \beginlisting -\font \test = "Latin Modern Roman:color=FF0000BB" + \font \test = "Latin Modern Roman:color=FF0000BB" \endlisting \endaltitem @@ -658,13 +665,13 @@ obviously, \inlinecode{random}. letterspacing width: \beginlisting -\font \iwonakernedA = "file:Iwona-Regular.otf:kernfactor=0.125" -\font \iwonakernedB = "file:Iwona-Regular.otf:letterspace=12.5" + \font \iwonakernedA = "file:Iwona-Regular.otf:kernfactor=0.125" + \font \iwonakernedB = "file:Iwona-Regular.otf:letterspace=12.5" \endlisting Specific pairs of letters and ligatures may be exempt from letterspacing by defining the \LUA functions - \luafunction{keeptogether} and \luafunction{keepligature}, + \luaident{keeptogether} and \luaident{keepligature}, respectively, inside the namespace \inlinecode {luaotfload.letterspace}. % Both functions are called whenever the letterspacing callback @@ -673,10 +680,10 @@ obviously, \inlinecode{random}. If they return a true-ish value, no extra kern is inserted at the current position. % - \luafunction{keeptogether} receives a pair of consecutive + \luaident{keeptogether} receives a pair of consecutive glyph nodes in order of their appearance in the node list. % - \luafunction{keepligature} receives a single node which can be + \luaident{keepligature} receives a single node which can be analyzed into components. % (For details refer to the \emphasis{glyph nodes} section in the @@ -686,7 +693,7 @@ obviously, \inlinecode{random}. user. \endaltitem -\ifcontextmkiv +\iffalse \startbuffer [printvectors] \directlua{inspect(fonts.protrusions.setups.default) inspect(fonts.expansions.setups.default)} @@ -706,7 +713,7 @@ obviously, \inlinecode{random}. % Alternatively and with loss of information, you can dump those tables into your terminal by issuing - \unless \ifcontextmkiv + \unless \iffalse \beginlisting \directlua{inspect(fonts.protrusions.setups.default) inspect(fonts.expansions.setups.default)} @@ -731,7 +738,7 @@ obviously, \inlinecode{random}. }: \beginlisting -\font \test = LatinModernRoman:protrusion=default + \font \test = LatinModernRoman:protrusion=default \endlisting \endaltitem \enddescriptions @@ -763,7 +770,7 @@ Currently (2014) there are three of them: remapping feature. }: - \unless \ifcontextmkiv + \unless \iffalse %% Using braced arg syntax with inline code appears to be %% impossible within Latex tables -- just ignore the weird %% exclamation points below. @@ -905,7 +912,7 @@ directories. \tablefloat {table-searchpaths} {List of paths searched for each supported operating system.} {% - \unless \ifcontextmkiv + \unless \iffalse \begincentered \begintabulate [lp{.5\textwidth}] \beginrow @@ -1056,27 +1063,28 @@ An example with explicit paths: \endsection %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\beginsection {Files from \CONTEXT and \LUATEX-Fonts} +\beginsection {The Fontloader} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\identifier{luaotfload} relies on code originally written by Hans -Hagen for the \hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net} +\beginsubsection {Overview} + +To a large extent, \identifier{luaotfload} relies on code originally +written by Hans Hagen for the +\hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net} format. % -It integrates the font loader as distributed in -the \identifier{\LUATEX-Fonts} package. +It integrates the font loader, written entirely in \LUA, as distributed +in the \identifier{\LUATEX-Fonts} package. % The original \LUA source files have been combined using the -\fileent{mtx-package} script into a single, self-contained blob. -In this form the font loader has no further dependencies\footnote{% - It covers, however, to some extent the functionality of the - \identifier{lualibs} package. -} -and requires only minor adaptions to integrate into +\fileent{mtx-package} script into a single, self-contained blob. In +this form the font loader depends only on the \identifier{lualibs} +package and requires only minor adaptions to integrate into \identifier{luaotfload}. -% -The guiding principle is to let \CONTEXT/\LUATEX-Fonts take care of -the implementation, and update the imported code from time to time. + +The guiding principle is to let \CONTEXT/\LUATEX-Fonts take care of the +implementation, and update the imported code as frequently as +necessary. % As maintainers, we aim at importing files from upstream essentially \emphasis{unmodified}, except for renaming them to prevent name @@ -1087,19 +1095,24 @@ This job has been greatly alleviated since the advent of manually spotted and extracted from the \CONTEXT source code in a complicated and error-prone fashion. +\endsubsection + +\beginsubsection {Contents and Dependencies} + Below is a commented list of the files distributed with \identifier{luaotfload} in one way or the other. % See figure \ref{file-graph} on page \pageref{file-graph} for a graphical representation of the dependencies. % -From \LUATEX-Fonts, only the file \fileent{luatex-fonts-merged.lua} -has been imported as \fileent{luaotfload-fontloader.lua}. -% -It is generated by \fileent{mtx-package}, a \LUA source code merging -too developed by Hans Hagen.\footnote{% - \fileent{mtx-package} is - \hyperlink [part of \CONTEXT]{http://repo.or.cz/w/context.git/blob_plain/refs/heads/origin:/scripts/context/lua/mtx-package.lua} +\label{package}% +Through the script \fileent{luaotfload-package.lua} the \CONTEXT +utility \fileent{mtx-package} is invoked to create the +\identifier{luaotfload} fontloader as a merged (amalgamated) source +file.\footnote{% + \fileent{mtx-package}, a \LUA source code merging tool developed by + Hans Hagen, is + \hyperlink [part of \CONTEXT]{https://bitbucket.org/phg/context-mirror/src/726a663be481042003566d4614266b940b5a0c91/scripts/context/lua/mtx-package.lua?at=beta} and requires \fileent{mtxrun}. Run \inlinecode {mtxrun --script package --help} @@ -1107,31 +1120,56 @@ too developed by Hans Hagen.\footnote{% For the actual merging code see the file \fileent{util-mrg.lua} that is part of \CONTEXT. } -It houses several \LUA files that can be classed in three -categories. +% +This file constitutes the “default fontloader” and is part of the +\identifier{luaotfload} package as \fileent{fontloader-YY-MM-DD.lua}, +where the uppercase letters are placeholders for the build date. +% +A companion to it, \fileent{luatex-basics-gen.lua} must be loaded +beforehand to set up parts of the environment required by the \CONTEXT +libraries. +% +During a \TEX\ run, the fontloader initialization and injection happens +in the module \fileent{luaotfload-init.lua}. +% +Additionally, the “reference fontloader” as imported from \LUATEX-Fonts +is provided as the file \fileent{fontloader-reference.lua}. +% +This file is self-contained in that it packages all the auxiliary \LUA +libraries too, as Luaotfload did up to the 2.5 series; since that job +has been offloaded to the \identifier{Lualibs} package, loading this +fontloader introduces a certain code duplication. + +A number of \emphasis{\LUA utility libraries} are not part of the +\identifier{luaotfload} fontloader, contrary to its equivalent in +\LUATEX-Fonts. These are already provided by the \identifier{lualibs} +and have thus been omitted from the merge.\footnote{% + Faithful listeners will remember the pre-2.6 era when the fontloader + used to be integrated as-is which caused all kinds of code + duplication with the pervasive \identifier{lualibs} package. + This conceptual glitch has since been amended by tightening the + coupling with the excellent \CONTEXT\ toolchain. +} -\begindefinitions - \beginnormalitem - \emphasis{\LUA utility libraries}, a subset - of what is provided by the \identifier{lualibs} - package. - - \begindoublecolumns - \begindefinitions - \beginaltitem {l-lua.lua} \endaltitem - \beginaltitem {l-lpeg.lua} \endaltitem - \beginaltitem {l-function.lua} \endaltitem - \beginaltitem {l-string.lua} \endaltitem - \beginaltitem {l-table.lua} \endaltitem - \beginaltitem {l-io.lua} \endaltitem - \beginaltitem {l-file.lua} \endaltitem - \beginaltitem {l-boolean.lua} \endaltitem - \beginaltitem {l-math.lua} \endaltitem - \beginaltitem {util-str.lua} \endaltitem - \enddefinitions - \enddoublecolumns - \endnormalitem +\begindoublecolumns + \begindefinitions + \beginaltitem {l-lua.lua} \endaltitem + \beginaltitem {l-lpeg.lua} \endaltitem + \beginaltitem {l-function.lua} \endaltitem + \beginaltitem {l-string.lua} \endaltitem + \beginaltitem {l-table.lua} \endaltitem + \beginaltitem {l-io.lua} \endaltitem + \beginaltitem {l-file.lua} \endaltitem + \beginaltitem {l-boolean.lua} \endaltitem + \beginaltitem {l-math.lua} \endaltitem + \beginaltitem {util-str.lua} \endaltitem + \enddefinitions +\enddoublecolumns + +The reference fontloader is home to several \LUA files that can be +grouped twofold as below: +\begindefinitions \beginnormalitem The \emphasis{font loader} itself. These files have been written for @@ -1139,7 +1177,6 @@ categories. with \identifier{luaotfload}. \begindoublecolumns \begindefinitions - \beginaltitem{luatex-basics-gen.lua} \endaltitem \beginaltitem{luatex-basics-nod.lua} \endaltitem \beginaltitem{luatex-fonts-enc.lua} \endaltitem \beginaltitem{luatex-fonts-syn.lua} \endaltitem @@ -1177,16 +1214,13 @@ categories. \endnormalitem \enddefinitions -Note that if \identifier{luaotfload} cannot locate the -merged file, it will load the individual \LUA libraries -instead. +As an alternative to the merged file, \identifier {Luaotfload} may load +individual unpackaged \LUA libraries that come with the source, or even +use the files from Context directly. % -Their names remain the same as in \CONTEXT (without the -\inlinecode {otfl}-prefix) since we imported the relevant section of -\fileent{luatex-fonts.lua} unmodified into \fileent{luaotfload-main.lua}. -Thus if you prefer running bleeding edge code from the -\CONTEXT beta, all you have to do is remove -\fileent{luaotfload-merged.lua} from the search path. +Thus if you prefer running bleeding edge code from the \CONTEXT beta, +choose the \inlinecode {context} fontloader via the configuration file +(see sections \ref{sec:conf} and \ref{sec:pkg} below). Also, the merged file at some point loads the Adobe Glyph List from a \LUA table that is contained in \fileent{luaotfload-glyphlist.lua}, @@ -1194,8 +1228,9 @@ which is automatically generated by the script \fileent{mkglyphlist}.\footnote{% See \fileent{luaotfload-font-enc.lua}. The hard-coded file name is why we have to replace the procedure - that loads the file in \fileent{luaotfload-override.lua}. + that loads the file in \fileent{luaotfload-init.lua}. } +% There is a make target \identifier{glyphs} that will create a fresh glyph list so we don’t need to import it from \CONTEXT any longer. @@ -1209,7 +1244,10 @@ files not contained in the merge. Some of these have no equivalent in font feature handling; incorporates some of the code from \fileent{font-otc} from \CONTEXT; \endaltitem - \beginaltitem {luaotfload-override.lua} + \beginaltitem {luaotfload-configuration.lua} + handling of \fileent{luaotfload.conf(5)}. + \endaltitem + \beginaltitem {luaotfload-log.lua} overrides the \CONTEXT logging functionality. \endaltitem \beginaltitem {luaotfload-loaders.lua} @@ -1222,6 +1260,9 @@ files not contained in the merge. Some of these have no equivalent in \beginaltitem {luaotfload-database.lua} font names database. \endaltitem + \beginaltitem {luaotfload-resolvers.lua} + file name resolvers. + \endaltitem \beginaltitem {luaotfload-colors.lua} color handling. \endaltitem @@ -1239,13 +1280,154 @@ files not contained in the merge. Some of these have no equivalent in {Schematic of the files in \identifier{Luaotfload}} {filegraph.pdf} +\endsubsection + +\beginsubsection {Packaging} + +\label{sec:pkg}% +The fontloader code is integrated as an isolated component that can be +switched out on demand. +% +To specify the fontloader you wish to use, the configuration file +(described in section \ref{sec:conf}) provides the option +\inlinecode{fontloader}. +% +Its value can be one of the identifiers \inlinecode{default} or +\inlinecode{reference} (see above, section \ref{package}) or the name +of a file somewhere in the search path of \LUATEX. +% +This will make \identifier {Luaotfload} locate the \CONTEXT source by +means of \identifier{kpathsea} lookups and use those instead of the +merged package. +% +The parameter may be extended with a path to the \CONTEXT +\fileent{texmf}, separated with a colon: + +\beginlisting +[run] + fontloader = context:~/context/tex/texmf-context +\endlisting + +\noindent This setting allows accessing an installation -- e. g. the +standalone distribution or a source repository -- outside the current +\TEX distribution. + +Like the \identifier{Lualibs} package, the fontloader is deployed as a +\emphasis{merged package} containing a series of \LUA files joined +together in their expected order and stripped of non-significant parts. +% +The \fileent{mkimport} utility assists in pulling the files from a +\CONTEXT tree and packaging them for use with \identifier{Luaotfload}.% +% +The state of the files currently in \identifier{Luaotfload}’s +repository can be queried: +\beginlisting +./scripts/mkimport news +\endlisting +% +The subcommand for importing takes the prefix of the desired \CONTEXT +\identifier{texmf} as an optional argument: +\beginlisting +./scripts/mkimport import ~/context/tex/texmf-context +\endlisting +% +Whereas the command for packaging requires a path to the +\emphasis{package description file} and the output name to be passed. +\beginlisting +./scripts/mkimport package ./src/fontloader/luaotfload-package.lua fontloader-custom.lua +\endlisting + +From the toplevel makefile, the targets \inlinecode{import} and +\inlinecode{package} provide easy access to the commands as invoked during +the \identifier{Luaotfload} build process.\footnote{% + \emphasis{Hint for those interested in the packaging process}: issue + \inlinecode{make show} for a list of available build routines. +} +These will call \inlinecode{mkimport} script with the correct +parameters to generate a datestamped package. +% +Whether files have been updated in the upstream distribution can be +queried by \inlinecode{./scripts/mkimport news}. +% +This will compare the imported files with their counterparts in the +\CONTEXT distribution and report changes. + +\endsubsection + \endsection %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\beginsection {Configuration Files} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\beginnarrower + \emphasis{Caution}: For the authoritative documentation, consult the + manpage for \fileent{luaotfload.conf(5)}. +\endnarrower + +\label{sec:conf} +The runtime behavior of \identifier{Luaotfload} can be customized by +means of a configuration file. +% location +At startup, it attempts to locate a file called \fileent +{luaotfload.conf} or \fileent {luaotfloadrc} at a number of candidate +locations: + +\begincentered + \begindefinitions + \beginnormalitem \fileent{./luaotfload.conf} \endnormalitem + \beginnormalitem \fileent{./luaotfloadrc} \endnormalitem + \beginnormalitem \fileent{\$XDG_CONFIG_HOME/luaotfload/luaotfload.conf} \endnormalitem + \beginnormalitem \fileent{\$XDG_CONFIG_HOME/luaotfload/luaotfload.rc} \endnormalitem + \beginnormalitem \fileent{~/.luaotfloadrc} \endnormalitem + \enddefinitions +\endcentered + +\beginnarrower + \emphasis{Caution}: The configuration potentially modifies the final + document. A project-local file belongs under version control along + with the rest of the document. This is to ensure that everybody who + builds the project also receives the same customizations as the + author. +\endnarrower + +% syntax +The syntax is fairly close to the format used by +\fileent{git-config(1)} which in turn was derived from the popular +\identifier{.INI} format: Lines of key-value pairs are grouped under +different configuration “sections”.\footnote{% + The configuration parser in \fileent {luoatfload-parsers.lua} might + be employed by other packages for similar purposes. +} +% example settings +An example for customization via \fileent {luaotfload.conf} might look +as below: + +\beginlisting +; Example luaotfload.conf containing a rudimentary configuration +[db] + update-live = false +[run] + color-callback = pre_linebreak_filter + definer = info_patch + log-level = 5 +[default-features] + global = mode=base +\endlisting + +This specifies that for the given project, \identifier{Luaotfload} +shall not attempt to automatically scan for fonts if it can’t resolve a +request. The font-based colorization will happen during \LUATEX’s +pre-linebreak filter. The fontloader will output verbose information +about the fonts at definition time along with globally increased +verbosity. Lastly, the fontloader defaults to the less expensive +\luaident{base} mode like it does in \CONTEXT. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \beginsection {Auxiliary Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -With release version 2.2, \identifier{luaotfload} received +With release version 2.2, \identifier{Luaotfload} received additional functions for package authors to call from outside (see the file \fileent{luaotfload-auxiliary.lua} for details). % @@ -1254,7 +1436,7 @@ The purpose of this addition twofold. Firstly, \identifier{luaotfload} failed to provide a stable interface to internals in the past which resulted in an unmanageable situation of different packages abusing the raw access to font objects by means -of the \luafunction{patch_font} callback. +of the \luaident{patch_font} callback. % When the structure of the font object changed due to an update, all of these imploded and several packages had to be fixed while @@ -1275,7 +1457,7 @@ additions. \beginsubsection {Callback Functions} -The \luafunction{patch_font} callback is inserted in the wrapper +The \luaident{patch_font} callback is inserted in the wrapper \identifier{luaotfload} provides for the font definition callback. % At this place it allows manipulating the font object immediately after @@ -1367,8 +1549,8 @@ are defined for which scripts. \beginfunctionlist \beginaltitem {aux.font_has_glyph (id : int, index : int)} - Predicate that returns true if the font \luafunction{id} - has glyph \luafunction{index}. + Predicate that returns true if the font \luaident{id} + has glyph \luaident{index}. \endaltitem \beginaltitem {aux.slot_of_name(name : string)} @@ -1377,33 +1559,33 @@ are defined for which scripts. \endaltitem \beginaltitem {aux.name_of_slot(slot : int)} - The inverse of \luafunction{slot_of_name}; note that this + The inverse of \luaident{slot_of_name}; note that this might be incomplete as multiple glyph names may map to the same codepoint, only one of which is returned by - \luafunction{name_of_slot}. + \luaident{name_of_slot}. \endaltitem \beginaltitem {aux.provides_script(id : int, script : string)} - Test if a font supports \luafunction{script}. + Test if a font supports \luaident{script}. \endaltitem \beginaltitem {aux.provides_language(id : int, script : string, language : string)} - Test if a font defines \luafunction{language} for a given - \luafunction{script}. + Test if a font defines \luaident{language} for a given + \luaident{script}. \endaltitem \beginaltitem {aux.provides_feature(id : int, script : string, language : string, feature : string)} - Test if a font defines \luafunction{feature} for - \luafunction{language} for a given \luafunction{script}. + Test if a font defines \luaident{feature} for + \luaident{language} for a given \luaident{script}. \endaltitem \beginaltitem {aux.get_math_dimension(id : int, dimension : string)} - Get the dimension \luafunction{dimension} of font \luafunction{id}. + Get the dimension \luaident{dimension} of font \luaident{id}. \endaltitem \beginaltitem {aux.sprint_math_dimension(id : int, dimension : string)} - Same as \luafunction{get_math_dimension()}, but output the value + Same as \luaident{get_math_dimension()}, but output the value in scaled points at the \TEX end. \endaltitem @@ -1416,7 +1598,7 @@ are defined for which scripts. %% not implemented, may come back later \beginfunctionlist % \beginaltitem {aux.scan_external_dir(dir : string)} -% Include fonts in directory \luafunction{dir} in font lookups without +% Include fonts in directory \luaident{dir} in font lookups without % adding them to the database. % \beginaltitem {aux.read_font_index (void)} @@ -1527,9 +1709,9 @@ Another strategy that helps avoiding problems is to not access raw Some of them, even though they are dangerous to access, have not been overridden or disabled. % -Thus, whenever possible prefer the functions in the \luafunction{aux} +Thus, whenever possible prefer the functions in the \luaident{aux} namespace over direct manipulation of font objects. For example, raw -access to the \luafunction{font.fonts} table like: +access to the \luaident{font.fonts} table like: \beginlisting local somefont = font.fonts[2] @@ -1537,16 +1719,16 @@ access to the \luafunction{font.fonts} table like: \noindent can render already defined fonts unusable. % -Instead, the function \luafunction{font.getfont()} should be used +Instead, the function \luaident{font.getfont()} should be used because it has been replaced by a safe variant. -However, \luafunction{font.getfont()} only covers fonts handled by the +However, \luaident{font.getfont()} only covers fonts handled by the font loader, e.~g. \identifier{OpenType} and \identifier{TrueType} fonts, but not \abbrev{tfm} or \abbrev{ofm}. % Should you absolutely require access to all fonts known to \LUATEX, including the virtual and autogenerated ones, then you need to query -both \luafunction{font.getfont()} and \luafunction{font.fonts}. +both \luaident{font.getfont()} and \luaident{font.fonts}. % In this case, best define you own accessor: |