From 4540a7d25d8a2dbbc3c773f2f27f2f1d7604b2ea Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Thu, 5 Nov 2015 23:29:15 +0100 Subject: [doc] fix manual build MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ``\luafunction`` appears to now have some fragile semantics that we’d rather avoid. Also the Latex folks finally got rid of the ``\luatex…`` namespace for primitives. --- doc/luaotfload-main.tex | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index c01beba..8f548fa 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}} @@ -233,7 +233,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 +664,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 +673,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 @@ -1254,7 +1254,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 +1275,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 +1367,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 +1377,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 +1416,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 +1527,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 +1537,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: -- cgit v1.2.3 From 6a7d1e67bb6e6fd073450a104ebe3ca934eaf14c Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Fri, 6 Nov 2015 00:02:56 +0100 Subject: [doc] update manual wrt files --- doc/luaotfload-main.tex | 104 ++++++++++++++++++++++++++++-------------------- 1 file changed, 61 insertions(+), 43 deletions(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index 8f548fa..a5ed940 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -1056,23 +1056,21 @@ An example with explicit paths: \endsection %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\beginsection {Files from \CONTEXT and \LUATEX-Fonts} +\beginsection {The Fontloader Package} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\identifier{luaotfload} relies on code originally written by Hans -Hagen for the \hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net} +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 @@ -1093,13 +1091,13 @@ Below is a commented list of the files distributed with 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 +1105,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. +% +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} that are already provided +by \identifier{lualibs} package are not part of the \identifier{luaotfload} +fontloader.\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. +} +\beginnarrower + \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 +\endnarrower -\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 +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 +1152,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 @@ -1209,7 +1221,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 +1237,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 -- cgit v1.2.3 From 8860ba7e4cb6009ac4abca9abd37cf276c786a45 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Fri, 6 Nov 2015 00:10:40 +0100 Subject: [doc] adapt to state of the art; stub section for configuration --- doc/luaotfload-main.tex | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index a5ed940..46f66b5 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -1072,9 +1072,10 @@ The original \LUA source files have been combined using the 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 @@ -1194,11 +1195,12 @@ merged file, it will load the individual \LUA libraries instead. % 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. +\inlinecode {luaotfload}-prefix) since the initialization mirrors +the sequence in \LUATEX-Fonts. +%% FIXME this is a config option nowadays! +%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. Also, the merged file at some point loads the Adobe Glyph List from a \LUA table that is contained in \fileent{luaotfload-glyphlist.lua}, @@ -1206,8 +1208,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. @@ -1259,6 +1262,13 @@ files not contained in the merge. Some of these have no equivalent in \endsection +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\beginsection {Configuration Files} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\emphasis{Caution}: For the authoritative documentation, consult the +manpage for \fileent{luaotfload.conf(5)}. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \beginsection {Auxiliary Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -- cgit v1.2.3 From 28dc7605d7875058227c5690a8f6354e1979d1b5 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Fri, 6 Nov 2015 00:17:32 +0100 Subject: [doc] remove redundant namespace prefixing for primitives --- doc/luaotfload-main.tex | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index 46f66b5..7badffd 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -1116,31 +1116,31 @@ 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} that are already provided -by \identifier{lualibs} package are not part of the \identifier{luaotfload} -fontloader.\footnote{% +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. + duplication with the pervasive \identifier{lualibs} package. This conceptual glitch has since been amended by tightening the coupling with the excellent \CONTEXT\ toolchain. } -\beginnarrower - \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 -\endnarrower + +\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: -- cgit v1.2.3 From 65c8b21ab3bf907357b203a7b5c6fb5b0a971cea Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Sat, 7 Nov 2015 00:42:06 +0100 Subject: [doc] expand documentation of config files --- doc/luaotfload-main.tex | 73 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 66 insertions(+), 7 deletions(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index 7badffd..4b5e2e8 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -686,7 +686,7 @@ obviously, \inlinecode{random}. user. \endaltitem -\ifcontextmkiv +\iffalse \startbuffer [printvectors] \directlua{inspect(fonts.protrusions.setups.default) inspect(fonts.expansions.setups.default)} @@ -706,7 +706,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 +763,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 +905,7 @@ directories. \tablefloat {table-searchpaths} {List of paths searched for each supported operating system.} {% - \unless \ifcontextmkiv + \unless \iffalse \begincentered \begintabulate [lp{.5\textwidth}] \beginrow @@ -1262,18 +1262,77 @@ files not contained in the merge. Some of these have no equivalent in \endsection +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\beginsection {Packaging a Fontloader} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +TODO % it’s simple, though + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \beginsection {Configuration Files} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\emphasis{Caution}: For the authoritative documentation, consult the -manpage for \fileent{luaotfload.conf(5)}. +\beginnarrower + \emphasis{Caution}: For the authoritative documentation, consult the + manpage for \fileent{luaotfload.conf(5)}. +\endnarrower + +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 +% 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). % -- cgit v1.2.3 From 54e6a5293dbff1e3775c2c3478b80c244608a4a5 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Sat, 7 Nov 2015 08:26:48 +0100 Subject: [doc] briefly describe config file syntax --- doc/luaotfload-main.tex | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index 4b5e2e8..112572f 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -1303,8 +1303,14 @@ locations: \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: -- cgit v1.2.3 From 55945326011925fa81cca8cf2b5b9376025451a5 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Sat, 7 Nov 2015 08:44:55 +0100 Subject: [doc] introduce fontloader switching --- doc/luaotfload-main.tex | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index 112572f..cc242e8 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -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 @@ -1056,9 +1061,11 @@ An example with explicit paths: \endsection %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\beginsection {The Fontloader Package} +\beginsection {The Fontloader} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\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} @@ -1086,6 +1093,10 @@ 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. % @@ -1260,14 +1271,23 @@ files not contained in the merge. Some of these have no equivalent in {Schematic of the files in \identifier{Luaotfload}} {filegraph.pdf} -\endsection +\endsubsection -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\beginsection {Packaging a Fontloader} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\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. TODO % it’s simple, though +\endsubsection +\endsection + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \beginsection {Configuration Files} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1277,6 +1297,7 @@ TODO % it’s simple, though 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 -- cgit v1.2.3 From 952d2c9b24c1b2e6f0f48df28981c1f2674137f4 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Tue, 10 Nov 2015 08:17:38 +0100 Subject: [doc] add directions for loading Context libs --- doc/luaotfload-main.tex | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) (limited to 'doc/luaotfload-main.tex') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index cc242e8..5ea70d8 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -1201,17 +1201,17 @@ grouped twofold as below: \endnormalitem \enddefinitions -Note that if \identifier{luaotfload} cannot locate the -merged file, it will load the individual \LUA libraries -instead. -% -Their names remain the same as in \CONTEXT (without the -\inlinecode {luaotfload}-prefix) since the initialization mirrors -the sequence in \LUATEX-Fonts. -%% FIXME this is a config option nowadays! -%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. +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). +% +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}, @@ -1283,8 +1283,6 @@ To specify the fontloader you wish to use, the configuration file \inlinecode{default} or \inlinecode{reference} or the name of a file somewhere in the search path of \LUATEX. -TODO % it’s simple, though - \endsubsection \endsection -- cgit v1.2.3