summaryrefslogtreecommitdiff
path: root/doc/luaotfload-main.tex
diff options
context:
space:
mode:
Diffstat (limited to 'doc/luaotfload-main.tex')
-rw-r--r--doc/luaotfload-main.tex329
1 files changed, 190 insertions, 139 deletions
diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 0e74aa9..5b033c0 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -1,16 +1,3 @@
-%\beginsection {foo}
- %bar baz
-%\endsection
-
-%\begindescriptions
-
- %\beginaltitem {mode} foo
- %%\identifier{luaotfload} has two \OpenType processing
- %%\emphasis{modes}:
-%\enddescriptions
-
-%\endinput
-
%% Copyright (C) 2009-2014
%%
%% by Elie Roux <elie.roux@telecom-bretagne.eu>
@@ -42,21 +29,25 @@
%% ----------------------------------------------------------------------------
%%
-\setdocumenttitle {The \identifier{luaotfload} package}
-\setdocumentdate {2014/**/** v2.5}
-\setdocumentauthor {Elie Roux · Khaled Hosny · Philipp Gesang\\
- Home: \hyperlink {https://github.com/lualatex/luaotfload}\\
- Support: \email {lualatex-dev@tug.org}}
+\beginfrontmatter
-\typesetdocumenttitle
+ \setdocumenttitle {The \identifier{luaotfload} package}
+ \setdocumentdate {2014/**/** v2.5}
+ \setdocumentauthor {Elie Roux · Khaled Hosny · Philipp Gesang\\
+ Home: \hyperlink {https://github.com/lualatex/luaotfload}\\
+ Support: \email {lualatex-dev@tug.org}}
-\beginabstractcontent
- 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.
-\endabstractcontent
+ \typesetdocumenttitle
-\tableofcontents
+ \beginabstractcontent
+ 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.
+ \endabstractcontent
+
+\endfrontmatter
+
+\typesetcontent
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\beginsection {Introduction}
@@ -140,10 +131,10 @@ in the task and willingness to respond to our suggestions.
\identifier{luaotfload} supports an extended font request syntax:
\beginnarrower
- \inlinecode{\\font\\foo=\{}%
- \meta{prefix}\inlinecode{:}%
- \meta{font name}\inlinecode{:}%
- \meta{font features}\inlinecode{\}}%
+ \nonproportional{\string\font\string\foo\space= \string{}%
+ \meta{prefix}\nonproportional{:}%
+ \meta{font name}\nonproportional{:}%
+ \meta{font features}\nonproportional{\string}}%
\meta{\TEX font features}
\endnarrower
@@ -165,18 +156,18 @@ for a more formal description see figure \ref{font-syntax}.
In addition to the font style modifiers
(\emphasis{slash-notation}) given above, there
are others that are recognized but will be silently
- ignored: {\ttfamily aat},
- {\ttfamily icu}, and
- {\ttfamily gr}.
+ ignored: \nonproportional{aat},
+ \nonproportional{icu}, and
+ \nonproportional{gr}.
The special terminals are:
- {\sc feature\textunderscore id} for a valid font
+ \smallcaps {feature\textunderscore id} for a valid font
feature name and
- {\sc feature\textunderscore value} for the corresponding
+ \smallcaps {feature\textunderscore value} for the corresponding
value.
- {\sc tfmname} is the name of a \abbrev{tfm} file.
- {\sc digit} again refers to bytes 48--57, and
- {\sc all\textunderscore characters} to all byte values.
- {\sc csname} and {\sc dimension} are the \TEX concepts.}
+ \smallcaps {tfmname} is the name of a \abbrev{tfm} file.
+ \smallcaps {digit} again refers to bytes 48--57, and
+ \smallcaps {all\textunderscore characters} to all byte values.
+ \smallcaps {csname} and \smallcaps {dimension} are the \TEX concepts.}
%
<definition> ::= `\\font', {\sc csname}, `=', <font request>, [ <size> ] ;
@@ -223,7 +214,11 @@ In \identifier{luaotfload}, the canonical syntax for font requests
requires a \emphasis{prefix}:
%
\beginnarrower
- \inlinecode{\\font\\fontname=}\meta{prefix}\inlinecode{:}\meta{fontname}\dots
+ \nonproportional{\string\font\string\fontname\space= }%
+ \meta{prefix}%
+ \nonproportional{:}%
+ \meta{fontname}%
+ \dots
\endnarrower
%
where \meta{prefix} is either \inlinecode{file:} or \inlinecode {name:}.\footnote{%
@@ -318,7 +313,9 @@ There are again two modes: bracketed and unbracketed.
A bracketed request looks as follows.
\beginnarrower
- \inlinecode{\\font\\fontname=[}\meta{path to file}\inlinecode{]}
+ \nonproportional{\string\font\string\fontname\space = [}%
+ \meta{/path/to/file}%
+ \nonproportional{]}
\endnarrower
\noindent
@@ -329,7 +326,9 @@ Naturally, path-less file names are equally valid and processed the
same way as an ordinary \inlinecode {file:} lookup.
\beginnarrower
- \inlinecode{\\font\\fontname=}\meta{font name} \dots
+ \nonproportional{\string\font\string\fontname\space= }%
+ \meta{font name}
+ \dots
\endnarrower
Unbracketed (or, for lack of a better word: \emphasis{anonymous})
@@ -347,7 +346,11 @@ Furthermore, \identifier{luaotfload} supports the slashed (shorthand)
font style notation from \XETEX.
\beginnarrower
- \inlinecode{\\font\\fontname=}\meta{font name}\inlinecode{/}\meta{modifier}\dots
+ \nonproportional{\string\font\string\fontname\space= }%
+ \meta{font name}%
+ \nonproportional{/}%
+ \meta{modifier}
+ \dots
\endnarrower
\noindent
@@ -470,11 +473,14 @@ which is equivalent to these full names:
general scheme for font requests:
\beginnarrower
- \inlinecode{\\font\\foo=\{}%
- \meta{prefix}\inlinecode{:}%
- \meta{font name}\inlinecode{:}%
- \meta{font features}\inlinecode{\}}%
- \meta{\TEX font features}
+ \nonproportional{\string\font\string\foo\space= "}%
+ \meta{prefix}%
+ \nonproportional{:}%
+ \meta{font name}%
+ \nonproportional{:}%
+ \meta{font features}%
+ \meta{\TEX font features}%
+ \nonproportional{"}
\endnarrower
\noindent
@@ -680,6 +686,12 @@ obviously, \inlinecode{random}.
user.
\endaltitem
+\ifcontextmkiv
+ \startbuffer [printvectors]
+ \directlua{inspect(fonts.protrusions.setups.default)
+ inspect(fonts.expansions.setups.default)}
+ \stopbuffer
+\fi
\beginaltitem {protrusion \& expansion}
These keys control microtypographic features of the font,
@@ -694,10 +706,14 @@ obviously, \inlinecode{random}.
%
Alternatively and with loss of information, you can dump
those tables into your terminal by issuing
- \beginlisting
-\directlua{inspect(fonts.protrusions.setups.default)
- inspect(fonts.expansions.setups.default)}
- \endlisting
+ \unless \ifcontextmkiv
+ \beginlisting
+ \directlua{inspect(fonts.protrusions.setups.default)
+ inspect(fonts.expansions.setups.default)}
+ \endlisting
+ \else
+ \typebuffer [printvectors]
+ \fi
at some point after loading \fileent{luaotfload.sty}.
}
%
@@ -740,13 +756,28 @@ Currently (2014) there are three of them:
\beginaltitem {tlig}
Applies legacy \TEX ligatures:
- \begintabulate [rlrl]
- \beginrow `` \newcell \inlinecode {``} \newcell '' \newcell \inlinecode {''} \endrow
- \beginrow ` \newcell \inlinecode {`} \newcell ' \newcell \inlinecode {'} \endrow
- \beginrow " \newcell \inlinecode {"} \newcell -- \newcell \inlinecode {--} \endrow
- \beginrow --- \newcell \inlinecode {---} \newcell !` \newcell \inlinecode {!`} \endrow
- \beginrow ?` \newcell \inlinecode {?`} \newcell \newcell \endrow
- \endtabulate
+ \unless \ifcontextmkiv
+ \begintabulate [rlrl]
+ \beginrow `` \newcell \inlinecode {``} \newcell '' \newcell \inlinecode {''} \endrow
+ \beginrow ` \newcell \inlinecode {`} \newcell ' \newcell \inlinecode {'} \endrow
+ \beginrow " \newcell \inlinecode {"} \newcell -- \newcell \inlinecode {--} \endrow
+ \beginrow --- \newcell \inlinecode {---} \newcell !` \newcell \inlinecode {!`} \endrow
+ \beginrow ?` \newcell \inlinecode {?`} \newcell \newcell \endrow
+ \endtabulate
+ \else
+ %% XXX find a way to wrap these in the tabulate environment
+ \startframed [frame=off,width=broad,align=middle]
+ \startframed [frame=off,width=\dimexpr(\textwidth/2)]
+ \startxtable [align=middle]
+ \startxrow \startxcell `` \stopxcell \startxcell \inlinecode {``} \stopxcell \startxcell '' \stopxcell \startxcell \inlinecode {''} \stopxcell \stopxrow
+ \startxrow \startxcell ` \stopxcell \startxcell \inlinecode {`} \stopxcell \startxcell ' \stopxcell \startxcell \inlinecode {'} \stopxcell \stopxrow
+ \startxrow \startxcell " \stopxcell \startxcell \inlinecode {"} \stopxcell \startxcell -- \stopxcell \startxcell \inlinecode {--} \stopxcell \stopxrow
+ \startxrow \startxcell --- \stopxcell \startxcell \inlinecode {---} \stopxcell \startxcell !` \stopxcell \startxcell \inlinecode {!`} \stopxcell \stopxrow
+ \startxrow \startxcell ?` \stopxcell \startxcell \inlinecode {?`} \stopxcell \startxcell \stopxcell \startxcell \stopxcell \stopxrow
+ \stopxtable
+ \stopframed
+ \stopframed
+ \fi
\footnote{%
These contain the feature set \inlinecode {trep} of earlier
@@ -873,26 +904,41 @@ Other paths can be specified by setting the environment variable
If it is non-empty, then search will be extended to the included
directories.
-\begintablefloat {table-searchpaths}
+\tablefloat {table-searchpaths}
{List of paths searched for each supported operating system.}
- \begincentered
- \begintabulate [lp{.5\textwidth}]
- \beginrow
- Windows \newcell \inlinecode {\% WINDIR\%\\ Fonts}
- \endrow
- \beginrow
- Linux \newcell \fileent{/usr/local/etc/fonts/fonts.conf} and\hfill\break
- \fileent{/etc/fonts/fonts.conf}
- \endrow
- \beginrow
- Mac \newcell \fileent{\textasciitilde/Library/Fonts},\break
- \fileent{/Library/Fonts},\break
- \fileent{/System/Library/Fonts}, and\hfill\break
- \fileent{/Network/Library/Fonts}
- \endrow
- \endtabulate
- \endcentered
-\endtablefloat
+ {%
+ \unless \ifcontextmkiv
+ \begincentered
+ \begintabulate [lp{.5\textwidth}]
+ \beginrow
+ Windows \newcell \inlinecode {\% WINDIR\%\\ Fonts}
+ \endrow
+ \beginrow
+ Linux \newcell \fileent{/usr/local/etc/fonts/fonts.conf} and\hfill\break
+ \fileent{/etc/fonts/fonts.conf}
+ \endrow
+ \beginrow
+ Mac \newcell \fileent{\textasciitilde/Library/Fonts},\break
+ \fileent{/Library/Fonts},\break
+ \fileent{/System/Library/Fonts}, and\hfill\break
+ \fileent{/Network/Library/Fonts}
+ \endrow
+ \endtabulate
+ \endcentered
+ \else
+ \setuplocalinterlinespace [14pt]
+ \starttabulate [|l|p(.5\textwidth)|]
+ \NC Windows \NC \inlinecode {\% WINDIR\%\\ Fonts} \NC \NR
+ \NC Linux \NC \fileent{/usr/local/etc/fonts/fonts.conf} and\crlf
+ \fileent{/etc/fonts/fonts.conf} \NC \NR
+ \NC
+ Mac \NC \fileent{\textasciitilde/Library/Fonts},\crlf
+ \fileent{/Library/Fonts},\break
+ \fileent{/System/Library/Fonts}, and\crlf
+ \fileent{/Network/Library/Fonts} \NC \NR
+ \stoptabulate
+ \fi%
+ }
\endsubsection
@@ -1016,7 +1062,7 @@ An example with explicit paths:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\identifier{luaotfload} relies on code originally written by Hans
-Hagen for the \hyperlink[\identifier\CONTEXT]{http://wiki.contextgarden.net}
+Hagen for the \hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net}
format.
%
It integrates the font loader as distributed in
@@ -1067,64 +1113,70 @@ It houses several \LUA files that can be classed in three
categories.
\begindefinitions
- \normalitem \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
-
- \normalitem The \emphasis{font loader} itself.
- These files have been written for
- \LUATEX-Fonts and they are distributed along
- 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
- \beginaltitem{luatex-fonts-tfm.lua} \endaltitem
- \beginaltitem{luatex-fonts-chr.lua} \endaltitem
- \beginaltitem{luatex-fonts-lua.lua} \endaltitem
- \beginaltitem{luatex-fonts-inj.lua} \endaltitem
- \beginaltitem{luatex-fonts-otn.lua} \endaltitem
- \beginaltitem{luatex-fonts-def.lua} \endaltitem
- \beginaltitem{luatex-fonts-ext.lua} \endaltitem
- \beginaltitem{luatex-fonts-cbk.lua} \endaltitem
- \enddefinitions
- \enddoublecolumns
-
- \normalitem Code related to \emphasis{font handling and
- node processing}, taken directly from
- \CONTEXT.
- \begindoublecolumns
- \begindefinitions
- \beginaltitem{data-con.lua} \endaltitem
- \beginaltitem{font-ini.lua} \endaltitem
- \beginaltitem{font-con.lua} \endaltitem
- \beginaltitem{font-cid.lua} \endaltitem
- \beginaltitem{font-map.lua} \endaltitem
- \beginaltitem{font-oti.lua} \endaltitem
- \beginaltitem{font-otf.lua} \endaltitem
- \beginaltitem{font-otb.lua} \endaltitem
- \beginaltitem{font-ota.lua} \endaltitem
- \beginaltitem{font-def.lua} \endaltitem
- \beginaltitem{font-otp.lua} \endaltitem
- \enddefinitions
- \enddoublecolumns
+ \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
+
+ \beginnormalitem
+ The \emphasis{font loader} itself.
+ These files have been written for
+ \LUATEX-Fonts and they are distributed along
+ 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
+ \beginaltitem{luatex-fonts-tfm.lua} \endaltitem
+ \beginaltitem{luatex-fonts-chr.lua} \endaltitem
+ \beginaltitem{luatex-fonts-lua.lua} \endaltitem
+ \beginaltitem{luatex-fonts-inj.lua} \endaltitem
+ \beginaltitem{luatex-fonts-otn.lua} \endaltitem
+ \beginaltitem{luatex-fonts-def.lua} \endaltitem
+ \beginaltitem{luatex-fonts-ext.lua} \endaltitem
+ \beginaltitem{luatex-fonts-cbk.lua} \endaltitem
+ \enddefinitions
+ \enddoublecolumns
+ \endnormalitem
+
+ \beginnormalitem
+ Code related to \emphasis{font handling and
+ node processing}, taken directly from
+ \CONTEXT.
+ \begindoublecolumns
+ \begindefinitions
+ \beginaltitem{data-con.lua} \endaltitem
+ \beginaltitem{font-ini.lua} \endaltitem
+ \beginaltitem{font-con.lua} \endaltitem
+ \beginaltitem{font-cid.lua} \endaltitem
+ \beginaltitem{font-map.lua} \endaltitem
+ \beginaltitem{font-oti.lua} \endaltitem
+ \beginaltitem{font-otf.lua} \endaltitem
+ \beginaltitem{font-otb.lua} \endaltitem
+ \beginaltitem{font-ota.lua} \endaltitem
+ \beginaltitem{font-def.lua} \endaltitem
+ \beginaltitem{font-otp.lua} \endaltitem
+ \enddefinitions
+ \enddoublecolumns
+ \endnormalitem
\enddefinitions
Note that if \identifier{luaotfload} cannot locate the
@@ -1184,11 +1236,10 @@ files not contained in the merge. Some of these have no equivalent in
\endaltitem
\endfilelist
-\beginfigurefloat
+\figurefloat
{file-graph}
{Schematic of the files in \identifier{Luaotfload}}
- \includegraphics[width=\textwidth]{filegraph.pdf}
-\endfigurefloat
+ {filegraph.pdf}
\endsection