summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/luatex/luaotfload/luaotfload.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/luatex/luaotfload/luaotfload.dtx')
-rw-r--r--Master/texmf-dist/source/luatex/luaotfload/luaotfload.dtx282
1 files changed, 222 insertions, 60 deletions
diff --git a/Master/texmf-dist/source/luatex/luaotfload/luaotfload.dtx b/Master/texmf-dist/source/luatex/luaotfload/luaotfload.dtx
index 3892bd86ab1..adbdf26f122 100644
--- a/Master/texmf-dist/source/luatex/luaotfload/luaotfload.dtx
+++ b/Master/texmf-dist/source/luatex/luaotfload/luaotfload.dtx
@@ -40,7 +40,7 @@
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
-\Msg{* Package: luaotfload v2.3b OpenType layout system}
+\Msg{* Package: luaotfload v2.4 OpenType layout system}
\Msg{************************************************************************}
\keepsilent
@@ -111,7 +111,7 @@ and the derived files
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{luaotfload.drv}%
- [2013/07/23 v2.3b OpenType layout system]%
+ [2013/12/28 v2.4 OpenType layout system]%
\documentclass{ltxdoc}
\usepackage{metalogo,multicol,mdwlist,fancyvrb,xspace}
\usepackage[x11names]{xcolor}
@@ -231,7 +231,7 @@ and the derived files
% \GetFileInfo{luaotfload.drv}
%
% \title{The \identifier{luaotfload} package}
-% \date{2013/07/23 v2.3b}
+% \date{2013/12/28 v2.4}
% \author{Elie Roux · Khaled Hosny · Philipp Gesang\\
% Home: \url{https://github.com/lualatex/luaotfload}\\
% Support: \email{lualatex-dev@tug.org}}
@@ -755,10 +755,64 @@ and the derived files
%
% \begin{quote}
% \begin{verbatim}
-% \font\test={Latin Modern Roman}:color=FF0000BB
+% \font\test={Latin Modern Roman}:color=FF0000BB
% \end{verbatim}
% \end{quote}
%
+% \item [kernfactor \& letterspace] \hfill \\
+% Define a font with letterspacing (tracking) enabled.
+% In \identifier{luaotfload}, letterspacing is implemented by
+% inserting additional kerning between glyphs.
+%
+% This approach is derived from and still quite similar to the
+% \emphasis{character kerning} (\texmacro{setcharacterkerning} /
+% \texmacro{definecharacterkerning} \& al.) functionality of
+% Context, see the file \fileent{typo-krn.lua} there.
+% The main difference is that \identifier{luaotfload} does not
+% use \LUATEX attributes to assign letterspacing to regions,
+% but defines virtual letterspaced versions of a font.
+%
+% The option \identifier{kernfactor} accepts a numeric value that
+% determines the letterspacing factor to be applied to the font
+% size.
+% E.~g. a kern factor of $0.42$ applied to a $10$ pt font
+% results in $4.2$ pt of additional kerning applied to each
+% pair of glyphs.
+% Ligatures are split into their component glyphs unless
+% explicitly ignored (see below).
+%
+% For compatibility with \XETEX an alternative
+% \identifier{letterspace} option is supplied that interprets the
+% supplied value as a \emphasis{percentage} of the font size but
+% is otherwise identical to \identifier{kernfactor}.
+% Consequently, both definitions in below snippet yield the same
+% letterspacing width:
+%
+% \begin{quote}
+% \begin{verbatim}
+% \font\iwonakernedA="file:Iwona-Regular.otf:kernfactor=0.125"
+% \font\iwonakernedB="file:Iwona-Regular.otf:letterspace=12.5"
+% \end{verbatim}
+% \end{quote}
+%
+% Specific pairs of letters and ligatures may be exempt from
+% letterspacing by defining the \LUA functions
+% \luafunction{keeptogether} and \luafunction{keepligature},
+% respectively, inside the namespace \verb|luaotfload.letterspace|.
+% Both functions are called whenever the letterspacing callback
+% encounters an appropriate node or set of nodes.
+% If they return a true-ish value, no extra kern is inserted at
+% the current position.
+% \luafunction{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
+% analyzed into components.
+% (For details refer to the \emphasis{glyph nodes} section in the
+% \LUATEX reference manual.)
+% The implementation of both functions is left entirely to the
+% user.
+%
+%
% \item [protrusion \& expansion] \hfill \\
% These keys control microtypographic features of the font,
% namely \emphasis{character protrusion} and \emphasis{font
@@ -771,14 +825,15 @@ and the derived files
% Alternatively and with loss of information, you can dump
% those tables into your terminal by issuing
% \begin{verbatim}
-% \directlua{inspect(fonts.protrusions.setups.default)
-% inspect(fonts.expansions.setups.default)}
+% \directlua{inspect(fonts.protrusions.setups.default)
+% inspect(fonts.expansions.setups.default)}
% \end{verbatim}
% at some point after loading \fileent{luaotfload.sty}.
% }
% For both, only the set \identifier{default} is predefined.
%
-% For example, to enable default protrusion\footnote{%
+% For example, to define a font with the default
+% protrusion vector applied\footnote{%
% You also need to set
% \verb|pdfprotrudechars=2| and
% \verb|pdfadjustspacing=2|
@@ -791,7 +846,7 @@ and the derived files
%
% \begin{quote}
% \begin{verbatim}
-% \font\test=LatinModernRoman:protrusion=default
+% \font\test=LatinModernRoman:protrusion=default
% \end{verbatim}
% \end{quote}
% \end{description}
@@ -1005,6 +1060,14 @@ and the derived files
% In \TEX Live: \fileent{texmf-dist/doc/luatex/base/luatexref-t.pdf}.
% }
%
+% For a much more detailed report about a given font try the \verb|-I| option
+% instead (\verb|--inspect|).
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool -I --find="Iwona Light Italic"
+% \end{verbatim}
+% \end{quote}
+%
% \verb|luaotfload-tool --help| will list the available command line
% switches, including some not discussed in detail here.
% For a full documentation of \identifier{luaotfload-tool} and its
@@ -1087,7 +1150,7 @@ and the derived files
% 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-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
@@ -1170,7 +1233,7 @@ and the derived files
%
% Also, the merged file at some point
% loads the Adobe Glyph List from a \LUA table that is contained in
-% \fileent{luaotfload-glyphlist.lua}, which is automatically generated by the %
+% \fileent{luaotfload-glyphlist.lua}, 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
@@ -1191,20 +1254,21 @@ and the derived files
% \normalitem{\fileent{#1}}%
% \space--\hskip1em
% }
-% \ouritem {luaotfload-features.lua} font feature handling;
-% incorporates some of the code from
-% \fileent{font-otc} from \CONTEXT;
-% \ouritem {luaotfload-override.lua} overrides the \CONTEXT logging
-% functionality.
-% \ouritem {luaotfload-loaders.lua} registers the \OpenType
-% font reader as handler for
-% Postscript fonts
-% (\abbrev{pfa}, \abbrev{pfb}).
-% \ouritem {luaotfload-database.lua} font names database.
-% \ouritem {luaotfload-colors.lua} color handling.
-% \ouritem {luaotfload-auxiliary.lua} access to internal functionality
-% for package authors
-% (proposals for additions welcome).
+% \ouritem {luaotfload-features.lua} font feature handling;
+% incorporates some of the code from
+% \fileent{font-otc} from \CONTEXT;
+% \ouritem {luaotfload-override.lua} overrides the \CONTEXT logging
+% functionality.
+% \ouritem {luaotfload-loaders.lua} registers the \OpenType
+% font reader as handler for
+% Postscript fonts
+% (\abbrev{pfa}, \abbrev{pfb}).
+% \ouritem {luaotfload-database.lua} font names database.
+% \ouritem {luaotfload-colors.lua} color handling.
+% \ouritem {luaotfload-auxiliary.lua} access to internal functionality
+% for package authors
+% (proposals for additions welcome).
+% \ouritem {luaotfload-letterspace.lua} font-based letterspacing.
% \end{itemize}
%
% \begin{figure}[b]
@@ -1383,6 +1447,7 @@ and the derived files
%
% \section{Troubleshooting}
%
+% \subsection {Database Generation}
% If you encounter problems with some fonts, please first update to the latest
% version of this package before reporting a bug, as
% \identifier{luaotfload} is under active development and still a
@@ -1392,18 +1457,42 @@ and the derived files
% tracker for submitting bug reports, feature requests and the likes
% requests and the likes.
%
-% Errors during database generation can be traced by increasing
-% verbosity levels and redirecting log output to \fileent{stdout}:
+% Bug reports are more likely to be addressed if they contain the output of
%
-% \begin{verbatim}
-% luaotfload-tool -fuvvv --log=stdout
-% \end{verbatim}
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool --diagnose=environment,files,permissions
+% \end{verbatim}
+% \end{quote}
+%
+% \noindent Consult the man page for a description of these options.
%
-% If this fails, the font last printed to the terminal is likely to be
-% the culprit.
+% Errors during database generation can be traced by increasing the
+% verbosity level and redirecting log output to \fileent{stdout}:
+%
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool -fuvvv --log=stdout
+% \end{verbatim}
+% \end{quote}
+%
+% \noindent or to a file in \fileent{/tmp}:
+%
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool -fuvvv --log=file
+% \end{verbatim}
+% \end{quote}
+%
+% \noindent In the latter case, invoke the \verb|tail(1)| utility on the file
+% for live monitoring of the progress.
+%
+% If database generation fails, the font last printed to the terminal or log
+% file is likely to be the culprit.
% Please specify it when reporting a bug, and blacklist it for the time
% being (see above, page \pageref{font-blacklist}).
%
+% \subsection {Font Features}
% A common problem is the lack of features for some
% \OpenType fonts even when specified.
% This can be related to the fact that some fonts do not provide
@@ -1414,10 +1503,22 @@ and the derived files
% fix it.
% For example with \verb|latn|:
%
-% \begin{verbatim}
-% \font\test=file:MyFont.otf:script=latn;+liga;
-% \end{verbatim}
+% \begin{quote}
+% \begin{verbatim}
+% \font\test=file:MyFont.otf:script=latn;+liga;
+% \end{verbatim}
+% \end{quote}
+%
+% You can get a list of features that a font defines for scripts and languages
+% by querying it in \fileent{luaotfload-tool}:
%
+% \begin{quote}
+% \begin{verbatim}
+% luaotfload-tool --find="Iwona" --inspect
+% \end{verbatim}
+% \end{quote}
+%
+% \subsection {\LUATEX Programming}
% Another strategy that helps avoiding problems is to not access raw \LUATEX
% internals directly.
% Some of them, even though they are dangerous to access, have not been
@@ -1426,14 +1527,39 @@ and the derived files
% \luafunction{aux} namespace over direct manipulation of font objects.
% For example, raw access to the \luafunction{font.fonts} table like:
%
-% \begin{verbatim}
-% local somefont = font.fonts[2]
-% \end{verbatim}
+% \begin{quote}
+% \begin{verbatim}
+% local somefont = font.fonts[2]
+% \end{verbatim}
+% \end{quote}
%
-% can render already defined fonts unusable.
+% \noindent can render already defined fonts unusable.
% Instead, the function \luafunction{font.getfont()} should be used because
% it has been replaced by a safe variant.
%
+% However, \luafunction{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}.
+% In this case, best define you own accessor:
+%
+% \begin{quote}
+% \begin{verbatim}
+% local unsafe_getfont = function (id)
+% local tfmdata = font.getfont (id)
+% if not tfmdata then
+% tfmdata = font.fonts[id]
+% end
+% return tfmdata
+% end
+%
+% --- use like getfont()
+% local somefont = unsafe_getfont (2)
+% \end{verbatim}
+% \end{quote}
+%
% \part{Implementation}
%
% \section{\fileent{luaotfload.lua}}
@@ -1475,11 +1601,15 @@ config.luaotfload.prioritize = config.luaotfload.prioritize or "sys"
config.luaotfload.names_dir = config.luaotfload.names_dir or "names"
config.luaotfload.cache_dir = config.luaotfload.cache_dir or "fonts"
config.luaotfload.index_file = config.luaotfload.index_file or "luaotfload-names.lua"
+config.luaotfload.formats = config.luaotfload.formats or "otf,ttf,ttc,dfont"
+if not config.luaotfload.strip then
+ config.luaotfload.strip = true
+end
luaotfload.module = {
name = "luaotfload",
- version = 2.3002,
- date = "2013/07/23",
+ version = 2.40003,
+ date = "2013/12/28",
description = "OpenType layout system.",
author = "Elie Roux & Hans Hagen",
copyright = "Elie Roux",
@@ -1706,7 +1836,7 @@ tex.attribute[0] = 0
%
% \begin{macrocode}
-loadmodule"merged.lua"
+loadmodule"fontloader.lua"
---loadmodule"font-odv.lua" --- <= Devanagari support from Context
if fonts then
@@ -1829,10 +1959,15 @@ loadmodule"colors.lua" --- “font-clr”
%
% \begin{macrocode}
+local filesuffix = file.suffix
+local fileremovesuffix = file.removesuffix
local request_resolvers = fonts.definers.resolvers
-local formats = fonts.formats -- nice table; does lowercasing ...
+local formats = fonts.formats
+local names = fonts.names
formats.ofm = "type1"
+fonts.encodings.known = fonts.encodings.known or { }
+
% \end{macrocode}
% \identifier{luaotfload} promises easy access to system fonts.
% Without additional precautions, this cannot be achieved by
@@ -1847,24 +1982,28 @@ formats.ofm = "type1"
% With the release version 2.2 the file names are indexed in the database
% as well and we are ready to resolve \verb|file:| lookups this way.
% Thus we no longer need to call the \identifier{kpathsea} library in
-% most cases when looking up font files, only when generating the database.
+% most cases when looking up font files, only when generating the database,
+% and when verifying the existence of a file in the \fileent{texmf} tree.
%
% \begin{macrocode}
-local resolvefile = fonts.names.crude_file_lookup
---local resolvefile = fonts.names.crude_file_lookup_verbose
+local resolve_file = names.crude_file_lookup
+--local resolve_file = names.crude_file_lookup_verbose
+local resolve_name = names.resolve_name
-request_resolvers.file = function (specification)
- local name = resolvefile(specification.name)
- local suffix = file.suffix(name)
+local file_resolver = function (specification)
+ local name = resolve_file (specification.name)
+ local suffix = filesuffix(name)
if formats[suffix] then
- specification.forced = suffix
- specification.name = file.removesuffix(name)
+ specification.forced = suffix
+ specification.forcedname = file.removesuffix(name)
else
specification.name = name
end
end
+request_resolvers.file = file_resolver
+
% \end{macrocode}
% We classify as \verb|anon:| those requests that have neither a
% prefix nor brackets. According to Khaled\footnote{%
@@ -1899,7 +2038,8 @@ request_resolvers.anon = function (specification)
for i=1, #type1_formats do
local format = type1_formats[i]
if resolvers.findfile(name, format) then
- specification.name = file.addsuffix(name, format)
+ specification.forcedname = file.addsuffix(name, format)
+ specification.forced = format
return
end
end
@@ -1936,9 +2076,9 @@ request_resolvers.path = function (specification)
logs.names_report("log", 1, "load",
"path lookup of %q unsuccessful, falling back to file:",
name)
- request_resolvers.file(specification)
+ file_resolver (specification)
else
- local suffix = file.suffix(name)
+ local suffix = filesuffix (name)
if formats[suffix] then
specification.forced = suffix
specification.name = file.removesuffix(name)
@@ -1957,12 +2097,12 @@ end
request_resolvers.kpse = function (specification)
local name = specification.name
- local suffix = file.suffix(name)
+ local suffix = filesuffix(name)
if suffix and formats[suffix] then
name = file.removesuffix(name)
if resolvers.findfile(name, suffix) then
- specification.forced = suffix
- specification.name = name
+ specification.forced = suffix
+ specification.forcedname = name
return
end
end
@@ -1976,6 +2116,28 @@ request_resolvers.kpse = function (specification)
end
% \end{macrocode}
+% The \verb|name:| resolver wraps the database function
+% \luafunction{resolve_name}.
+%
+% \begin{macrocode}
+
+--- fonts.names.resolvers.name -- Customized version of the
+--- generic name resolver.
+
+request_resolvers.name = function (specification)
+ local resolved, subfont = resolve_name (specification)
+ if resolved then
+ specification.resolved = resolved
+ specification.sub = subfont
+ specification.forced = filesuffix (resolved)
+ specification.forcedname = resolved
+ specification.name = fileremovesuffix (resolved)
+ else
+ file_resolver (specification)
+ end
+end
+
+% \end{macrocode}
% Also {\bfseries EXPERIMENTAL}:
% custom file resolvers via callback.
%
@@ -2039,9 +2201,9 @@ elseif font_definer == "patch" then
1)
end
-loadmodule"features.lua" --- contains what was “font-ltx” and “font-otc”
-loadmodule"extralibs.lua" --- load additional Context libraries
-loadmodule"auxiliary.lua" --- additionaly high-level functionality (new)
+loadmodule"features.lua" --- contains what was “font-ltx” and “font-otc”
+loadmodule"letterspace.lua" --- extra character kerning
+loadmodule"auxiliary.lua" --- additionaly high-level functionality (new)
luaotfload.aux.start_rewrite_fontname () --- to be migrated to fontspec
@@ -2070,7 +2232,7 @@ luaotfload.aux.start_rewrite_fontname () --- to be migrated to fontspec
\else
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{luaotfload}%
- [2013/07/23 v2.3b OpenType layout system]
+ [2013/12/28 v2.4 OpenType layout system]
\RequirePackage{luatexbase}
\fi
\ifnum\luatexversion<76