diff options
Diffstat (limited to 'doc/luaotfload-main.tex')
| -rw-r--r-- | doc/luaotfload-main.tex | 282 |
1 files changed, 197 insertions, 85 deletions
diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index c01beba..5ea70d8 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -32,7 +32,7 @@ \beginfrontmatter \setdocumenttitle {The \identifier{luaotfload} package} - \setdocumentdate {2015/03/29 v2.6} + \setdocumentdate {2015/11/05 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. @@ -664,7 +669,7 @@ obviously, \inlinecode{random}. 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 +678,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 +691,7 @@ obviously, \inlinecode{random}. user. \endaltitem -\ifcontextmkiv +\iffalse \startbuffer [printvectors] \directlua{inspect(fonts.protrusions.setups.default) inspect(fonts.expansions.setups.default)} @@ -706,7 +711,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)} @@ -763,7 +768,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 +910,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 +1061,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 +1093,23 @@ 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} +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 +1117,46 @@ 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. - -\begindefinitions - \beginnormalitem - \emphasis{\LUA utility libraries}, a subset - of what is provided by the \identifier{lualibs} - package. +% +This file constitutes the “reference fontloader” and is part of the +\identifier{luaotfload} package as \fileent{fontloader-reference.lua}. +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}. + +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. +} - \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 +1164,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 +1201,17 @@ 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. +% +Thus if you prefer running bleeding edge code from the \CONTEXT beta, +all you have to do is to choose the \inlinecode {context} fontloader +via the configuration file (see section \ref{sec:conf} below). % -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. +This will make \identifier {Luaotfload} locate the \CONTEXT source via +\identifier{kpathsea} lookups and use those instead of the fontloader +%% TODO allow choosing the context path 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 +1219,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 +1235,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 +1251,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 +1271,93 @@ 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} + +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} or the name of a file +somewhere in the search path of \LUATEX. + +\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 +1366,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 +1387,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 +1479,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 +1489,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 +1528,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 +1639,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 +1649,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: |