diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 4 | ||||
| -rw-r--r-- | doc/filegraph.dot | 175 | ||||
| -rw-r--r-- | doc/luaotfload-context.tex | 485 | ||||
| -rw-r--r-- | doc/luaotfload-latex.tex | 93 | ||||
| -rw-r--r-- | doc/luaotfload-main.tex | 249 |
5 files changed, 360 insertions, 646 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 – 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..4b5e2e8 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 @@ -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 @@ -1056,27 +1056,26 @@ 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 -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 @@ -1093,13 +1092,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 +1106,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} are not part of the +\identifier{luaotfload} fontloader, contrary to its equivalent in +\LUATEX-Fonts. These are already provided by the \identifier{lualibs} +and have thus been omitted from the merge.\footnote{% + Faithful listeners will remember the pre-2.6 era when the fontloader + used to be integrated as-is which caused all kinds of code + duplication with the pervasive \identifier{lualibs} package. + This conceptual glitch has since been amended by tightening the + coupling with the excellent \CONTEXT\ toolchain. +} -\begindefinitions - \beginnormalitem - \emphasis{\LUA utility libraries}, a subset - of what is provided by the \identifier{lualibs} - package. - - \begindoublecolumns - \begindefinitions - \beginaltitem {l-lua.lua} \endaltitem - \beginaltitem {l-lpeg.lua} \endaltitem - \beginaltitem {l-function.lua} \endaltitem - \beginaltitem {l-string.lua} \endaltitem - \beginaltitem {l-table.lua} \endaltitem - \beginaltitem {l-io.lua} \endaltitem - \beginaltitem {l-file.lua} \endaltitem - \beginaltitem {l-boolean.lua} \endaltitem - \beginaltitem {l-math.lua} \endaltitem - \beginaltitem {util-str.lua} \endaltitem - \enddefinitions - \enddoublecolumns - \endnormalitem +\begindoublecolumns + \begindefinitions + \beginaltitem {l-lua.lua} \endaltitem + \beginaltitem {l-lpeg.lua} \endaltitem + \beginaltitem {l-function.lua} \endaltitem + \beginaltitem {l-string.lua} \endaltitem + \beginaltitem {l-table.lua} \endaltitem + \beginaltitem {l-io.lua} \endaltitem + \beginaltitem {l-file.lua} \endaltitem + \beginaltitem {l-boolean.lua} \endaltitem + \beginaltitem {l-math.lua} \endaltitem + \beginaltitem {util-str.lua} \endaltitem + \enddefinitions +\enddoublecolumns + +The reference fontloader is home to several \LUA files that can be +grouped twofold as below: +\begindefinitions \beginnormalitem The \emphasis{font loader} itself. These files have been written for @@ -1139,7 +1153,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 @@ -1182,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}, @@ -1194,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. @@ -1209,7 +1224,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 +1240,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 @@ -1242,10 +1263,76 @@ 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} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\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). % @@ -1254,7 +1341,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 +1362,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 +1454,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 +1464,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 +1503,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 +1614,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 +1624,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: |