summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDavid Carlisle <d.p.carlisle@gmail.com>2015-11-21 21:45:03 +0000
committerDavid Carlisle <d.p.carlisle@gmail.com>2015-11-21 21:45:03 +0000
commitb46f13e0949e310b46e97e791fd4e9e38635a491 (patch)
tree415c893c82e7f55ed630a10033885f1b5781ab56 /doc
parenta472b6fd5461318ec1e5d2899af2ef57f0fb14e8 (diff)
parent6c3d70e21b100c6c7ffa11e1c6d9260b32ccc781 (diff)
downloadluaotfload-b46f13e0949e310b46e97e791fd4e9e38635a491.tar.gz
for 2.6
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile4
-rw-r--r--doc/filegraph.dot175
-rw-r--r--doc/luaotfload-context.tex485
-rw-r--r--doc/luaotfload-latex.tex93
-rw-r--r--doc/luaotfload-main.tex282
-rw-r--r--doc/luaotfload.conf.rst25
6 files changed, 414 insertions, 650 deletions
diff --git a/doc/Makefile b/doc/Makefile
index ed340a4..0355a0e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,6 +1,6 @@
NAME = luaotfload
DOCPDF = $(NAME).pdf
-DOCSRC = $(NAME)-latex.tex
+DOCSRC = $(NAME)-latex.tex $(NAME)-main.tex
SCRIPTNAME = luaotfload-tool
TOOLMANSRC = $(SCRIPTNAME).rst
@@ -47,7 +47,7 @@ $(DOTPDF): $(DOT)
@echo "creating file graph ($(DOTPDF))"
$(DO_GRAPHVIZ)
-.PHONY: clean mrproper
+.PHONY: clean mrproper graph doc all manuals
clean:
@$(RM) -- *.log *.aux *.toc *.idx *.ind *.ilg *.out
diff --git a/doc/filegraph.dot b/doc/filegraph.dot
index e1a9937..af3c8ad 100644
--- a/doc/filegraph.dot
+++ b/doc/filegraph.dot
@@ -10,8 +10,8 @@ strict digraph luaotfload_files { //looks weird with circo ...
size = "21cm";
rankdir = LR;
- ranksep = 0.618;
- nodesep = 1.618;
+ ranksep = 0.618;
+ nodesep = 1.618;
edge [
arrowhead = onormal,
@@ -30,37 +30,38 @@ strict digraph luaotfload_files { //looks weird with circo ...
fontdbutil -> font_names [label="--update",
style=dashed]
- luaotfload -> otfl_fonts_merged [label="merged"]
- luaotfload -> merged_lua_libs [label="unmerged", style=solid]
- luaotfload -> merged_luatex_fonts [label="unmerged", style=solid]
- luaotfload -> merged_context_libs [label="unmerged", style=solid]
+ luaotfload -> merged_lua_libs [style=solid]
+ luaotfload -> luaotfload_init [label="main()", style=solid]
+ luaotfload -> luaotfload_libs [label="main()", style=solid]
- luaotfload -> luaotfload_libs
- luaotfload -> otfl_blacklist_cnf
-
- otfl_fonts_merged -> merged_lua_libs [label="merged",
- style=dotted,
- lhead=cluster_merged]
- otfl_fonts_merged -> merged_luatex_fonts [label="merged",
+ fontloader -> merged_luatex_fonts [label="merged",
style=dotted,
lhead=cluster_merged]
- otfl_fonts_merged -> merged_context_libs [label="merged",
+ fontloader -> merged_context_libs [label="merged",
style=dotted,
lhead=cluster_merged]
+ luaotfload_init -> luaotfload_log [label="init_early()", style=solid]
+ luaotfload_init -> luaotfload_basics_gen [label="init_early()", style=solid]
+ luaotfload_init -> fontloader [label="init_main()", style=solid]
+
+ luaotfload_init -> merged_luatex_fonts [label="unmerged", style=solid]
+ luaotfload_init -> merged_context_libs [label="unmerged", style=solid]
+
merged_luatex_fonts -> font_age [label="luatex-fonts-enc.lua",
ltail=cluster_merged]
fontdbutil -> fontdbutil_diagnostics [label="--diagnose"]
-
fontdbutil -> status [label="version information"]
- fontdbutil_diagnostics -> status [constraint=no, label="hash files"]
+ luaotfload_package -> fontloader [label="merges", style=dashed]
merged_luatex_fonts -> characters [label="luaotfload-auxiliary.lua",
ltail=cluster_merged]
- luaotfload_libs -> font_names [label="luaotfload-database.lua"]
+ luaotfload_libs -> font_names [label="luaotfload-database.lua"]
+ luaotfload_libs -> otfl_blacklist_cnf [label="luaotfload-database.lua"]
+
mkstatus -> status [label="generates from distribution files",
style=dashed]
@@ -71,13 +72,30 @@ strict digraph luaotfload_files { //looks weird with circo ...
mkcharacters -> characters [label="generates from Context’s char-def.lua",
style=dashed]
+ fontdbutil_diagnostics -> status [label="hash files"]
+
+ mkimport -> merged_luatex_fonts [label="pulls", style=dashed, constraint=no];
+ mkimport -> merged_context_libs [label="pulls", style=dashed, constraint=no];
+
subgraph { rank = same;
- mkcharacters;
- mkglyphlist;
- mkstatus;
fontdbutil;
luaotfload }
+ subgraph cluster_scripts {
+ node [style=filled, color=white];
+ style = "filled,rounded";
+ color = "#44000011:#CCCCCC77";
+ //nodesep = "3.0";
+ rank = same;
+ label = "Standalone scripts";
+ gradientangle=90;
+ mkcharacters;
+ mkglyphlist;
+ mkimport;
+ mktest;
+ mkstatus;
+ }
+
/* ····································································
* main files
* ································································· */
@@ -90,6 +108,14 @@ strict digraph luaotfload_files { //looks weird with circo ...
style = "filled,rounded",
penwidth=2]
+ luaotfload_package [label = "luaotfload-package.lua",
+ shape = rect,
+ width = "3.2cm",
+ height = "1.2cm",
+ color = "#01012222",
+ style = "filled,rounded",
+ penwidth=2]
+
fontdbutil_diagnostics [label = "luaotfload-diagnostics.lua",
shape = rect,
width = "3.2cm",
@@ -98,27 +124,43 @@ strict digraph luaotfload_files { //looks weird with circo ...
style = "filled,rounded",
penwidth=2]
+ mktest [label = "mktest",
+ shape = rect,
+ width = "3.2cm",
+ height = "0.618cm",
+ color = "#FFFFFF66",
+ style = "filled,rounded",
+ penwidth=2]
+
+ mkimport [label = "mkimport",
+ shape = rect,
+ width = "3.2cm",
+ height = "0.618cm",
+ color = "#FFFFFF66",
+ style = "filled,rounded",
+ penwidth=2]
+
mkstatus [label = "mkstatus",
shape = rect,
width = "3.2cm",
- height = "1.2cm",
- color = "#01012222",
+ height = "0.618cm",
+ color = "#FFFFFF66",
style = "filled,rounded",
penwidth=2]
mkglyphlist [label = "mkglyphlist",
shape = rect,
width = "3.2cm",
- height = "1.2cm",
- color = "#01012222",
+ height = "0.618cm",
+ color = "#FFFFFF66",
style = "filled,rounded",
penwidth=2]
mkcharacters [label = "mkcharacters",
shape = rect,
width = "3.2cm",
- height = "1.2cm",
- color = "#01012222",
+ height = "0.618cm",
+ color = "#FFFFFF66",
style = "filled,rounded",
penwidth=2]
@@ -138,13 +180,37 @@ strict digraph luaotfload_files { //looks weird with circo ...
* style = "filled,rounded",
* penwidth=2]
*/
- otfl_fonts_merged [label = "luaotfload-fontloader.lua",
- shape = rect,
- width = "3.2cm",
- height = "1.2cm",
- color = "#01012222",
- style = "filled,rounded",
- penwidth=2]
+ luaotfload_init [label = "luaotfload-init.lua",
+ shape = rect,
+ width = "3.2cm",
+ height = "1.2cm",
+ color = "#44440122",
+ style = "filled,rounded",
+ penwidth=2]
+
+ luaotfload_log [label = "luaotfload-log.lua",
+ shape = rect,
+ width = "3.2cm",
+ height = "1.2cm",
+ color = "#44440122",
+ style = "filled,rounded",
+ penwidth=2]
+
+ luaotfload_basics_gen [label = "fontloader-basics-gen.lua",
+ shape = rect,
+ width = "3.2cm",
+ height = "1.2cm",
+ color = "#FFFFFF66",
+ style = "filled,rounded",
+ penwidth=2]
+
+ fontloader [label = "fontloader-reference.lua",
+ shape = rect,
+ width = "3.2cm",
+ height = "1.2cm",
+ color = "#FFFFFF66",
+ style = "filled,rounded",
+ penwidth=2]
/* ····································································
* luaotfload files
@@ -193,15 +259,16 @@ strict digraph luaotfload_files { //looks weird with circo ...
luaotfload_libs [
shape = box,
style = "filled,rounded",
- color = "grey90:goldenrod4",
+ color = "grey90",
fontsize = 10,
label = <
<table cellborder="0" bgcolor="#FFFFFFAA">
<th> <td colspan="2"> <font point-size="12" face="Iwona Italic">Luaotfload Libraries</font> </td> </th>
- <tr> <td>luaotfload-auxiliary.lua</td> <td>luaotfload-features.lua</td> </tr>
- <tr> <td>luaotfload-loaders.lua</td> <td>luaotfload-color.lua</td> </tr>
- <tr> <td>luaotfload-log.lua</td> <td>luaotfload-letterspace.lua</td> </tr>
- <tr> <td>luaotfload-parsers.lua</td> <td>luaotfload-database.lua</td> </tr>
+ <tr> <td>luaotfload-auxiliary.lua</td> <td>luaotfload-features.lua</td> </tr>
+ <tr> <td>luaotfload-loaders.lua</td> <td>luaotfload-colors.lua</td> </tr>
+ <tr> <td>luaotfload-resolvers.lua</td> <td>luaotfload-letterspace.lua</td> </tr>
+ <tr> <td>luaotfload-parsers.lua</td> <td>luaotfload-database.lua</td> </tr>
+ <tr> <td>luaotfload-configuration.lua</td><td></td> </tr>
</table>
>,
]
@@ -213,28 +280,40 @@ strict digraph luaotfload_files { //looks weird with circo ...
subgraph cluster_merged {
node [style=filled, color=white];
style = "filled,rounded";
- color = "grey90:dodgerblue4";
+ color = "#912CEE33";
//nodesep = "3.0";
rank = same;
label = "Merged Libraries";
gradientangle=0;
- merged_lua_libs;
merged_luatex_fonts;
merged_context_libs;
}
- otfl_fonts_merged -> merged_lua_libs
- otfl_fonts_merged -> merged_luatex_fonts
- otfl_fonts_merged -> merged_context_libs
+ fontloader -> merged_luatex_fonts
+ fontloader -> merged_context_libs
+
+ subgraph cluster_fontloader {
+ node [style=filled, color=white];
+ style = "filled,rounded";
+ color = "bisque";
+ //nodesep = "3.0";
+ rank = same;
+ label = "Fontloader";
+ gradientangle=0;
+ luaotfload_basics_gen;
+ fontloader;
+ }
merged_lua_libs [
shape = box,
style = "filled,rounded",
- color = "#FFFFFFAA",
+ color = "#CCCC1166",
+ fontsize = 10,
fontsize = 10,
label = <
<table border="0">
- <th> <td colspan="3"> <font point-size="12" face="Iwona Italic">Lua Libraries from Context</font> </td> </th>
+ <th> <td colspan="3"> <font point-size="12" face="Iwona Italic">
+ Lualibs &ndash; Lua Libraries from Context</font> </td> </th>
<tr> <td>l-lua.lua</td> <td>l-lpeg.lua</td> <td>l-function.lua</td> </tr>
<tr> <td>l-string.lua</td> <td>l-table.lua</td> <td>l-io.lua</td> </tr>
<tr> <td>l-file.lua</td> <td>l-boolean.lua</td> <td>l-math.lua</td> </tr>
@@ -251,17 +330,13 @@ strict digraph luaotfload_files { //looks weird with circo ...
label = <
<table border="0">
<th> <td colspan="2"> <font point-size="12" face="Iwona Italic">Font Loader (LuaTeX-Fonts)</font> </td> </th>
- <tr> <td>luatex-basics-gen.lua</td> <td>luatex-basics-nod.lua</td> </tr>
+ <tr> <td>luatex-fonts-cbk.lua</td> <td>luatex-basics-nod.lua</td> </tr>
<tr> <td>luatex-fonts-enc.lua</td> <td>luatex-fonts-syn.lua</td> </tr>
<tr> <td>luatex-font-tfm.lua</td> <td>luatex-font-afm.lua</td> </tr>
<tr> <td>luatex-font-afk.lua</td> <td>luatex-fonts-tfm.lua</td> </tr>
<tr> <td>luatex-fonts-chr.lua</td> <td>luatex-fonts-lua.lua</td> </tr>
<tr> <td>luatex-fonts-inj.lua</td> <td>luatex-fonts-otn.lua</td> </tr>
<tr> <td>luatex-fonts-def.lua</td> <td>luatex-fonts-ext.lua</td> </tr>
- <tr> <td>luatex-fonts-cbk.lua</td> </tr>
-
-
-
</table>
>,
]
diff --git a/doc/luaotfload-context.tex b/doc/luaotfload-context.tex
deleted file mode 100644
index 6c8d4b2..0000000
--- a/doc/luaotfload-context.tex
+++ /dev/null
@@ -1,485 +0,0 @@
-% macros=mkvi
-%% Copyright (C) 2009-2014
-%%
-%% by Elie Roux <elie.roux@telecom-bretagne.eu>
-%% and Khaled Hosny <khaledhosny@eglug.org>
-%% and Philipp Gesang <philipp.gesang@alumni.uni-heidelberg.de>
-%%
-%% This file is part of Luaotfload.
-%%
-%% Home: https://github.com/lualatex/luaotfload
-%% Support: <lualatex-dev@tug.org>.
-%%
-%% Luaotfload is under the GPL v2.0 (exactly) license.
-%%
-%% ----------------------------------------------------------------------------
-%%
-%% Luaotfload is free software; you can redistribute it and/or
-%% modify it under the terms of the GNU General Public License
-%% as published by the Free Software Foundation; version 2
-%% of the License.
-%%
-%% Luaotfload is distributed in the hope that it will be useful,
-%% but WITHOUT ANY WARRANTY; without even the implied warranty of
-%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-%% GNU General Public License for more details.
-%%
-%% You should have received a copy of the GNU General Public License
-%% along with Luaotfload; if not, see <http://www.gnu.org/licenses/>.
-%%
-%% ----------------------------------------------------------------------------
-%%
-
-\unprotect
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% layout and paper
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setuppapersize [A5] [A5] %% 148×210
-
-\definelayout [mainlayout] [
- backspace=15mm, %% 133
- textwidth=103mm,
- topspace=15mm,
-]
-
-\setuplayout [mainlayout]
-
-\setuppagenumbering [location=,alternative=doublesided]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% colors
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\usecolors [x11]
-\definecolor [primarycolor] [dodgerblue4]
-\definecolor [secondarycolor] [goldenrod4]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% interaction
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupinteraction [
- state=start,
- page=no,
- click=yes,
- style=italic,
- color=primarycolor,
- contrastcolor=secondarycolor,
- title={The Luaotfload package},
- subtitle={OpenType layout system for Plain TeX and LaTeX},
- author={Elie Roux & Khaled Hosny & Philipp Gesang},
- keywords={luatex, lualatex, unicode, opentype},
-]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% fonts
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\usemodule [simplefonts]
-
-\definefontfeature [default] [default] [mode=base,liga=yes,dlig=yes,tlig=yes,onum=yes]
-\definefontfeature [monospace] [liga=no,tlig=no,onum=no]
-
-\definefontfamily [mainface] [serif] [Linux Libertine O] [features=default]
-%definefontfamily [mainface] [serif] [Liberation Serif] [feature=default]
-%definefontfamily [mainface] [sans] [Iwona] [feature=default]
-\definefontfamily [mainface] [sans] [Iwona Medium] [
- feature=default,
- it=file:IwonaMedium-Italic.otf,
- tf=file:IwonaMedium-Regular.otf,
- bf=file:Iwona-Bold.otf,
- bi=file:Iwona-BoldItalic.otf,
-]
-%definefontfamily [mainface] [sans] [DejaVu Sans] [feature=default]
-\definefontfamily [mainface] [mono] [Liberation Mono] [scale=0.85,features=monospace]
-
-\setupbodyfont [mainface,10pt]
-
-\def \LUA {Lua}
-\def \LUALATEX {Lua\LATEX}
-\def \OpenType {\identifier{Open\kern-.25ex Type}}
-
-\definealternativestyle [emphasis:texmacro] [\ss \it \letterbackslash] [\ss \it \letterbackslash]
-\definealternativestyle [emphasis:identifier] [\ss] [\ss]
-\definealternativestyle [emphasis:normal] [\sl] [\sl]
-\definealternativestyle [emphasis:abbrev] [{\feature [+][smallcaps]}] [{\feature [+][smallcaps]}]
-\definealternativestyle [emphasis:Largefont] [{\switchtobodyfont[14pt]}] [{\switchtobodyfont[14pt]}]
-\definealternativestyle [emphasis:smallcaps] [{\feature [+][smallcaps]}] [{\feature [+][smallcaps]}]
-%definealternativestyle [emphasis:nonproportional] [\mono] [\mono]
-\definealternativestyle [emphasis:nonproportional] [\tt] [\tt]
-\definealternativestyle [head:section] [{\roman\feature[+][smallcaps]}] [{\roman\feature[+][smallcaps]}]
-\definealternativestyle [head:subsection] [{\roman\feature[+][smallcaps]}] [{\roman\feature[+][smallcaps]}]
-\definealternativestyle [head:subsubsection] [{\roman\feature[+][smallcaps]}] [{\roman\feature[+][smallcaps]}]
-\definealternativestyle [typing:luafunction] [\italic] [\italic]
-\definealternativestyle [typing:fileent] [\tt] [\tt]
-
-\definehighlight [texmacro] [style=emphasis:texmacro] %% cs
-\definehighlight [identifier] [style=emphasis:identifier] %% names
-\definehighlight [abbrev] [style=emphasis:abbrev] %% acronyms
-\definehighlight [emphasis] [style=emphasis:normal] %% level 1 emph
-
-\definehighlight [Largefont] [style=emphasis:Largefont] %% font size
-\definehighlight [smallcaps] [style=emphasis:smallcaps] %% font feature
-\definehighlight [nonproportional] [style=emphasis:nonproportional] %% font switch
-
-\definetype [fileent] [style=typing:fileent]
-\definetype [luafunction] [style=typing:luafunction]
-\setuptyping [style=ttx]
-
-\definebodyfontenvironment [8pt]
-\definebodyfontenvironment [10pt]
-\definebodyfontenvironment [12pt]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% headings
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setuphead [section] [style=head:section, alternative=inmargin]
-\setuphead [subsection] [style=head:subsection, alternative=inmargin]
-\setuphead [subsubsection] [style=head:subsubsection,alternative=inmargin]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% running headers
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupheadertexts
- [{\tfx \getmarking[section]}] [pagenumber]
- [pagenumber] [{\tfx \fileent{Luaotfload} Manual}]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% structurals
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-%% section
-\def \beginsection {\dosingleempty \section_begin_indeed}
-
-\def \section_begin_indeed [#ref]#title{%
- \iffirstargument
- \startsection [reference=#ref,title=#title]%
- \else
- \startsection [title=#title]%
- \fi
-}
-
-\let \endsection \stopsection
-
-%% subsection
-\def \beginsubsection {\dosingleempty \section_begin_indeed}
-
-\def \subsection_begin_indeed [#ref]#title{%
- \iffirstargument
- \startsubsection [reference=#ref,title=#title]%
- \else
- \startsubsection [title=#title]%
- \fi
-}
-
-\let \endsubsection \stopsection
-
-%% subsubsection
-\def \beginsubsubsection {\dosingleempty \section_begin_indeed}
-
-\def \subsubsection_begin_indeed [#ref]#title{%
- \iffirstargument
- \startsubsubsection [reference=#ref,title=#title]%
- \else
- \startsubsubsection [title=#title]%
- \fi
-}
-
-\let \endsubsubsection \stopsection
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% inline verbatim
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-%% Context offers both \type{…} and \type<<…>>, but not an unbalanced
-%% one that we could map directly onto Latex’s \verb|…|.
-
-\definetype [inlinecode_indeed] [style=emphasis:nonproportional]
-
-%% The listings macros don’t seem to handle backslashes and braces
-%% well. We emulate this behavior by handling the escaping in Lua.
-
-\startluacode
- local lpeg = require "lpeg"
- local Cs, P, S = lpeg.Cs, lpeg.P, lpeg.S
- local lpegmatch = lpeg.match
- local unescape_char = S[[\letterbackslash\letterleftbrace\letterrightbrace]]
- local backslash = P[[\letterbackslash]]
- local unescape = Cs (((backslash / "" * unescape_char) + 1)^0)
- commands.unescape_things = function (str)
- context.type (lpegmatch (unescape, str))
- end
-\stopluacode
-
-\unexpanded \def \inlinecode #content{%
- \ctxcommand {unescape_things \!!bs \detokenize {#content}\!!es}%
-}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% codelistings
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Now *that’s* what I call easy.
-
-\unexpanded \def \beginlisting {%
- \grabbufferdatadirect{listing}{beginlisting}{endlisting}%
-}
-
-\unexpanded \def \endlisting {\typebuffer [listing]}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% enumerations and lists
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\definedescription [descriptionitem] [
- align=right,
- alternative=hanging,
- width=2em,
-]
-
-\def \begindescriptions {%
- \begingroup
- \def \beginnormalitem ##1\endnormalitem{%
- \startitem##1\stopitem
- }
- \let \endnormalitem \relax
- \let \beginaltitem \startdescriptionitem
- \let \endaltitem \stopdescriptionitem
-}
-
-\let \enddescriptions \endgroup
-
-
-\definedescription [definitionitem] [
- align=right,
- alternative=hanging,
-]
-
-\def \begindefinitions {%
- \begingroup
- \def \beginnormalitem ##1\endnormalitem{%
- \startitem##1\stopitem
- }
- \let \endnormalitem \relax
- \let \beginaltitem \startdefinitionitem
- \let \endaltitem \stopdefinitionitem
-}
-
-\let \enddefinitions \endgroup
-
-
-\definedescription [filelistitem] [
- align=normal,
- alternative=hanging,
- headstyle=typing:fileent,
- width=4cm,
-]
-
-\def \beginfilelist {%
- \begingroup
- \def \beginnormalitem ##1\endnormalitem{%
- \startitem##1\stopitem
- }
- \let \endnormalitem \relax
- \let \beginaltitem \startfilelistitem
- \let \endaltitem \stopfilelistitem
-}
-
-\let \endfilelist \endgroup
-
-\definedescription [functionlistitem] [
- align=normal,
- alternative=hanging,
- headstyle=typing:luafunction,
- width=4cm,
-]
-
-\def \beginfunctionlist {%
- \begingroup
- \def \beginnormalitem ##1\endnormalitem{%
- \startitem##1\stopitem
- }
- \let \endnormalitem \relax
- \let \beginaltitem \startfunctionlistitem
- \let \endaltitem \stopfunctionlistitem
-}
-
-\let \endfunctionlist \endgroup
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% columns
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\def \begindoublecolumns {\startcolumns [2]}
-\let \enddoublecolumns \stopcolumns
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% alignment
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupnarrower [before={\blank[line]},after={\blank[line]}]
-\let \beginnarrower \startnarrower
-\let \endnarrower \stopnarrower
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% special elements
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\definefont [lmromantenregular] [file:lmroman10-regular.otf*default]
-
-\def \meta #1{%
- {\lmromantenregular<}%
- {\italic #1}%
- {\lmromantenregular>}%
-}
-
-\def \beginabstractcontent {%
- \grabbufferdatadirect{abstractcontent}{beginabstractcontent}{endabstractcontent}%
-}
-
-\let \endabstractcontent \relax
-
-\def \setdocumenttitle #1{\setvalue {document_title}{#1}}
-\def \setdocumentdate #1{\setvalue {document_date}{#1}}
-\def \setdocumentauthor #1{\setvalue {document_author}{#1}}
-
-\let \typesetdocumenttitle \relax
-\let \beginfrontmatter \relax
-
-\def \endfrontmatter {
- \startstandardmakeup
- \vfill
- \strut \hfill
- \startframed [frame=off,align=middle,width=.5\textwidth]
- \Largefont{\getvalue {document_title}}
- \stopframed
- \hfill \strut \par
-
- \blank [2*big]
-
- \strut \hfill
- \startframed [frame=off,align=middle,width=.65\textwidth]
- \setuplocalinterlinespace [18pt]
- \getvalue {document_author}
- \stopframed
- \hfill \strut \par
-
- \vfill
- \strut \hfill \getvalue {document_date} \hfill \strut
- \blank [2*big]
-
- \strut \hfill
- \startframed [width=.7\textwidth,align=normal,style=tfx,frame=off]%
- \getbuffer [abstractcontent]
- \stopframed
- \hfill \strut
- \stopstandardmakeup
-}
-
-\let \typesetcontent \completecontent
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% floats
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% XXX we can improve on this part later
-
-\usemodule [vim]
-\definevimtyping [bnf] [syntax=bnf]
-\definefloat [syntax] [figure]
-
-\def \beginsyntaxfloat #reference#caption{%
- \begingroup
- \edef \currentreference {#reference}%
- \edef \currentcaption {#caption}%
- \grabbufferdatadirect{rawsyntaxdata}{beginsyntaxfloat}{endsyntaxfloat}%
-}
-
-\def \endsyntaxfloat {%
- \savebuffer [rawsyntaxdata] [rawsyntaxdata]
- \startplacesyntax [
- reference=\currentreference,
- title={\currentcaption},
- ]
- %% there’s no \typebnfbuffer in t-vim :(
- \typebnffile {\jobname-rawsyntaxdata.tmp}
- \stopplacesyntax
- \endgroup%
-}
-
-\def \figurefloat #reference#caption#file{%
- \startplacefigure [
- reference=#reference,
- title={#caption},
- ]
- \externalfigure [#file] [width=\textwidth]
- \stopplacefigure
-}
-
-
-\def \tablefloat #reference#caption#content{%
- \startplacetable [
- reference=#reference,
- title={#caption},
- ]
- #content
- \stopplacetable
-}
-
-
-%% tables
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% tables
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupxtable [frame=off,option=stretch,textwidth=\dimexpr(\textwidth/2)]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% hyperlinks and references
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\unexpanded \def \hyperlink{%
- \dosingleempty \hyperlink_indeed%
-}
-
-\def \hyperlink_indeed [#text]#url{%
- \iffirstargument
- \useURL [temporary_url] [#url] [] [#text]%
- \else
- \useURL [temporary_url] [#url]%
- \fi%
- \from [temporary_url]%
-}
-
-
-\def \email #1{\goto{#1}[url(mailto:#1)]}
-
-\def \label #tag{\reference [#tag]\empty}
-\def \pageref #tag{\at{page}{#tag}}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% escaped characters
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\let \charpercent \letterpercent
-\let \charbackslash \letterbackslash
-\let \chartilde \lettertilde
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% main
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\protect
-
-\newif \ifcontextmkiv \contextmkivtrue
-
-\starttext
- \input luaotfload-main.tex
-\stoptext
-
diff --git a/doc/luaotfload-latex.tex b/doc/luaotfload-latex.tex
index 34c494d..e3541c5 100644
--- a/doc/luaotfload-latex.tex
+++ b/doc/luaotfload-latex.tex
@@ -1,4 +1,4 @@
-\luatexsuppresslongerror1%% sigh ...
+\suppresslongerror1%% sigh ...
%% Copyright (C) 2009-2014
%%
%% by Elie Roux <elie.roux@telecom-bretagne.eu>
@@ -129,7 +129,7 @@
\definehighlight [fileent][\ttfamily\restoreunderscore] %% files, dirs
\definehighlight [texmacro][\sffamily\itshape\textbackslash] %% cs
-\definehighlight [luafunction][\sffamily\itshape\restoreunderscore] %% lua identifiers
+\definehighlight [luaident][\sffamily\itshape\restoreunderscore] %% lua identifiers
\definehighlight [identifier][\sffamily] %% names
\definehighlight [abbrev][\rmfamily\scshape] %% acronyms
\definehighlight [emphasis][\rmfamily\slshape] %% level 1 emph
@@ -220,9 +220,9 @@
\newcount \othercatcode \othercatcode 12
\newcount \activecatcode \othercatcode 13
-\newluatexcatcodetable \vrbcatcodes
-\setluatexcatcodetable \vrbcatcodes {%
- \luatexcatcodetable \CatcodeTableIniTeX
+\newcatcodetable \vrbcatcodes
+\setcatcodetable \vrbcatcodes {%
+ \catcodetable \CatcodeTableIniTeX
\catcode 9 \othercatcode %% \tabasciicode
\catcode 13 \othercatcode %% \endoflineasciicode
\catcode 12 \othercatcode %% \formfeedasciicode
@@ -230,48 +230,85 @@
\catcode 32 \othercatcode %% \spaceasciicode
}
-\newluatexcatcodetable \literalcatcodes
-\setluatexcatcodetable \literalcatcodes {%
- \luatexcatcodetable \CatcodeTableString
+\directlua {
+ document = document or { }
+ document.vrbcatcodesidx = tonumber (\the \vrbcatcodes)
+}
+
+\newcatcodetable \literalcatcodes
+\setcatcodetable \literalcatcodes {%
+ \catcodetable \CatcodeTableString
\catcode 32 \activecatcode %% \spaceasciicode
}
+\def \listingsurroundskip {\vskip \baselineskip}
+
\def \beginlisting {%
+ \noindent
\begingroup
- \luatexcatcodetable \vrbcatcodes
+ \catcodetable \vrbcatcodes
\beginlistingindeed%
}
\directlua {
- local texprint = tex.print
- local stringsub = string.sub
- local backslash = string.byte (0x5c)
- document = document or { }
+ local texsprint = tex.sprint
+ local stringis_empty = string.is_empty
+ local stringsub = string.sub
+ local stringgsub = string.gsub
+ %local backslash = unicode.utf8.char (0x200c)
+ local backslash = unicode.utf8.char (0x5c)
+ local escaped = [[\string\string\string\]]
document.printlines = function (buffer)
- for _, line in next, string.explode (buffer, "\noexpand\n") do
- if stringsub (line, 1, 1) == " " then
- line = backslash .. line
+ local lines = string.explode (buffer, "\noexpand\n")
+ print ""
+ for i, line in next, lines do
+ local line = stringgsub (line, backslash, escaped)
+ if stringis_empty (line) then
+ print (i, "listing: <empty line />")
+ texsprint [[\string\listingpar]]
+ else
+ local line = [[\string\beginlistingline]]
+ .. line
+ .. [[\string\endlistingline]]
+ .. [[\string\listingpar]]
+ print (i, "listing: «" .. line .. "»")
+ texsprint (document.vrbcatcodesidx, line)
end
- texprint (-1, line)
- texprint (-1, "")
end
end
}
+\def \listingpar {\endgraf}
+
+\let \endlistingline \relax
+\let \endlisting \relax
+
+\protected \def \beginlistingline{%
+ \leavevmode
+ \begingroup
+ \beginlistinglineindeed%
+}
+
+\def \beginlistinglineindeed #1\endlistingline{%
+ \endgroup
+ \hbox{%
+ \addfontfeature {RawFeature=-tlig;-liga}%% So one can’t just turn them all off at once using the ``Ligatures`` key?
+ \obeyspaces
+ #1}%
+}
+
\def \beginlistingindeed#1\endlisting{%
\endgroup
\begingroup
+ \endgraf
+ \listingsurroundskip
\ttfamily
\small
- \begin {quote}
- \bgroup
- \addfontfeature {RawFeature=-tlig;-liga}%% So one can’t just turn them all off at once using the ``Ligatures`` key?
- \luatexcatcodetable \literalcatcodes
- \obeyspaces
- \obeylines
- \directlua{document.printlines ([==[\detokenize {#1}]==])}
- \egroup
- \end {quote}
+ \parindent = 0em
+ \leftskip = 2em
+ \hangindent = 2em
+ \directlua{document.printlines ([==[\detokenize {#1}]==])}%
+ \listingsurroundskip
\endgroup
}
@@ -301,7 +338,7 @@
\definelist [descriptions]{\normalitem {\textbf \first}\hfill\break}
\definelist [definitions]{\normalitem {\fileent {\first}}}
\definelist [filelist]{\normalitem {\fileent {\first}}\space--\hskip 1em}
-\definelist [functionlist]{\normalitem {\luafunction {\first}}\hfill\break}
+\definelist [functionlist]{\normalitem {\luaident {\first}}\hfill\break}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% columns
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:
diff --git a/doc/luaotfload.conf.rst b/doc/luaotfload.conf.rst
index 2a339ce..12dd887 100644
--- a/doc/luaotfload.conf.rst
+++ b/doc/luaotfload.conf.rst
@@ -276,6 +276,8 @@ Section ``run``
+------------------+--------+------------------------------+
| resolver | s | ``"cached"`` |
+------------------+--------+------------------------------+
+| fontloader | s | ``"default"`` |
++------------------+--------+------------------------------+
The ``color-callback`` option determines the stage at which fonts that
defined with a ``color=xxyyzz`` feature will be colorized. By default
@@ -294,6 +296,29 @@ one that comes with the vanilla fontloader. Beware that this might
break tools like Fontspect that rely on the ``patch_font`` callback
provided by Luaotfload to perform important corrections on font data.
+The fontloader backend can be selected by setting the value of
+``fontloader``. Other than the default, which selects the packaged
+``reference`` loader as shipped with Luaotfload, a file name accessible
+by kpathsea can be specified. Alternatively, the individual files that
+constitute the fontloader can be loaded directly. While less efficient,
+this greatly aids debugging since error messages will reference the
+actual line numbers of the source files and explanatory comments are
+not stripped. Currently, three distinct loading strategies are
+available: ``unpackaged`` will load the batch that is part of
+Luaotfload. These contain the identical source code that the reference
+fontloader has been compiled from. Another option, ``context`` will
+attempt to load the same files by their names in the Context format
+from the search path. Consequently this option allows to use the
+version of Context that comes with the TeX distribution. Distros tend
+to prefer the stable version (“current” in Context jargon) of those
+files so certain bugs encountered in the more bleeding edge Luaotfload
+can be avoided this way. A third option is to use ``context`` with a
+colon to specify a directory prefix where the *TEXMF* is located that
+the files should be loaded from, e. g. ``context:~/context/tex/texmf-context``.
+This can be used when referencing another distribution like the Context
+minimals that is installed under a different path not indexed by
+kpathsea.
+
The value of ``log-level`` sets the default verbosity of messages
printed by Luaotfload. Only messages defined with a verbosity of less
than or equal to the supplied value will be output on the terminal.