diff options
Diffstat (limited to 'luaotfload.dtx')
-rw-r--r-- | luaotfload.dtx | 406 |
1 files changed, 333 insertions, 73 deletions
diff --git a/luaotfload.dtx b/luaotfload.dtx index 18e01d8..5b454bc 100644 --- a/luaotfload.dtx +++ b/luaotfload.dtx @@ -130,6 +130,8 @@ and the derived files \setsansfont[Ligatures=TeX,Scale=MatchLowercase]{Iwona Medium} %setmathfont{XITS Math} +\usepackage{hologo} + \newcommand\TEX {\TeX\xspace} \newcommand\LUA {Lua\xspace} \newcommand\PDFTEX {pdf\TeX\xspace} @@ -160,6 +162,8 @@ and the derived files \renewcommand\partname{Part}%% gets rid of the stupid “file” heading +\usepackage{syntax}%% bnf for font request syntax + \VerbatimFootnotes \begin{document} \DocInput{luaotfload.dtx}% @@ -244,56 +248,177 @@ and the derived files % % \section{Loading Fonts} % -% \identifier{luaotfload} supports an extended font loading syntax: +% \identifier{luaotfload} supports an extended font request syntax: % -% \begin{center} +% \begin{quote} % |\font\foo={|% % \meta{prefix}|:|% % \meta{font name}|:|% % \meta{font features}|}|% % \meta{\TEX font features} -% \end{center} +% \end{quote} % % \noindent % The curly brackets are optional and escape the spaces in the enclosed -% font name (alternatively, double quotes serve the same purpose). -% The individual parts of the syntax are: -% -% \paragraph{Prefix} -% -% The \meta{prefix} is either |file:| or |name:|. -% It determines whether the font loader should interpret the request as a -% file name or font name, respectively, which again influences how it -% will attempt to locate the font. -% The prefix can be omitted, in which case |name:| is assumed. -% -%% \iffalse%% how am i supposed to friggin comment stuff in a dtx??? -%% TODO -%% it would appear that the next paragraph is incorrect; I get -%% name: lookups regardless unless the font file is actually -%% in CWD -%% \fi -%% For compatibility with \XETEX, surrounding the \meta{font name} with -%% square brackets is synonymous to using the |file:| prefix. +% font name. +% Alternatively, double quotes serve the same purpose. +% A selection of individual parts of the syntax are discussed below; +% for a more formal description see figure \ref{font-syntax}. % +% \begin{figure}[b] +% \setlength\grammarparsep{12pt plus 2pt minus 2pt} +% \setlength\grammarindent{5cm} +% \begingroup +% \small +% \begin{grammar} +% <definition> ::= `\\font', {\sc csname}, `=', <font request>, [ <size> ] ; +% +% <size> ::= `at', {\sc dimension} ; +% +% <font request> ::= `"', <unquoted font request> `"' +% \alt `{', <unquoted font request> `}' +% \alt <unquoted font request> ; +% +% <unquoted font request> ::= <specification>, [`:', <feature list> ] +% \alt `[', <path lookup> `]', [ [`:'], <feature list> ] ; +% +% <specification> ::= <prefixed spec>, [ <subfont no> ], \{ <modifier> \} +% \alt <anon lookup>, \{ <modifier> \} ; +% +% <prefixed spec> ::= `file:', <file lookup> +% \alt `name:', <name lookup> ; +% +% <file lookup> ::= \{ <name character> \} ; +% +% <name lookup> ::= \{ <name character> \} ; +% +% <anon lookup> ::= {\sc tfmname} | <name lookup> ; +% +% <path lookup> ::= \{ {\sc all_characters} - `]' \} ; +% +% <modifier> ::= `/', (`i' | `b' | `bi' | `ib') ; +% +% <subfont no> ::= `(', \{ {\sc digit} \}, `)' ; +% +% <feature list> ::= <feature expr>, \{ `;', <feature expr> \} ; +% +% <feature expr> ::= {\sc feature_id}, `=', {\sc feature_value} +% \alt <feature switch>, {\sc feature_id} ; +% +% <feature switch> ::= `+' | `-' ; +% +% <name character> ::= {\sc all_characters} - ( `(' | `/' | `:' ) ; +% \end{grammar} +% \endgroup +% \caption{Font request syntax. +% Braces or double quotes around the +% \emphasis{specification} rule will +% preserve whitespace in file names. +% 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}. +% The special terminals are: +% {\sc feature\textunderscore id} for a valid font +% feature name and +% {\sc 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.} +% \label{font-syntax} +% \end{figure} +% +% \subsection{Prefix -- the \identifier{luaotfload}{ }Way} +% +% In \identifier{luaotfload}, the canonical syntax for font requests +% requires a \emphasis{prefix}: +% \begin{quote} +% |\font\fontname=|\meta{prefix}|:|\meta{fontname}\dots +% \end{quote} +% where \meta{prefix} is either \verb|file:| or \verb|name:|. +% It determines whether the font loader should interpret the request as +% a \emphasis{file name} or +% \emphasis{font name}, respectively, +% which again influences how it will attempt to locate the font. +% Examples for font names are +% “Latin Modern Italic”, +% “GFS Bodoni Rg”, and +% “PT Serif Caption” +% -- they are the human readable identifiers +% usually listed in drop-down menus and the like. % In order for fonts installed both in system locations and in your % \fileent{texmf} to be accessible by font name, \identifier{luaotfload} must % first collect the metadata included in the files. -% Please refer to section ~\ref{sec:fontdb} below for instructions on how to +% Please refer to section~\ref{sec:fontdb} below for instructions on how to % create the database. % -% \paragraph{Font name} +% File names are whatever your file system allows them to be, except +% that that they may not contain the characters +% \verb|(|, +% \verb|:|, and +% \verb|/|. +% As obvious from the last exception, the \verb|file:| lookup will +% not process paths to the font location -- only those +% files found when generating the database are addressable this way. +% Continue below in the \XETEX section if you need to load your fonts +% by path. +% The file names corresponding to the example font names above are +% \fileent{lmroman12-italic.otf}, +% \fileent{GFSBodoni.otf}, and +% \fileent{PTZ56F.ttf}. +% +% \subsection{\hologo{XeTeX} Compatibility Layer} +% +% In addition to the regular prefixed requests, \identifier{luaotfload} +% accepts loading fonts the \XETEX way. +% There are again two modes: bracketed and unbracketed. +% A bracketed request looks as follows. % -% The \meta{font name} can be either a font filename or actual font -% name based on the \meta{prefix} as mentioned above. +% \begin{quote} +% |\font\fontname=[|\meta{path to file}|]| +% \end{quote} +% +% \noindent +% Inside the square brackets, every character except for a closing +% bracket is permitted, allowing for specifying paths to a font file. +% Naturally, path-less file names are equally valid and processed the +% same way as an ordinary \verb|file:| lookup. % -% A filename request may optionally include the absolute path to the font file, -% allowing for fonts outside the standard locations to be loaded as well. -% If no path is specified, then \identifier{kpathsea} is used to locate the -% font (which will typically be in the \fileent{texmf} tree or the -% current directory). +% \begin{quote} +% |\font\fontname=|\meta{font name} \dots +% \end{quote} % -% \subparagraph{Examples for loading by file name} +% Unbracketed (or, for lack of a better word: \emphasis{anonymous}) +% font requests resemble the conventional \TEX syntax. +% However, they have a broader spectrum of possible interpretations: +% before anything else, \identifier{luaotfload} attempts to load a +% traditional \TEX Font Metric (\abbrev{tfm} or \abbrev{ofm}). +% If this fails, it performs a \verb|name:| lookup, which itself will +% fall back to a \verb|file:| lookup if no database entry matches +% \meta{font name}. +% +% Furthermore, \identifier{luaotfload} supports the slashed (shorthand) +% font style notation from \XETEX. +% +% \begin{quote} +% |\font\fontname=|\meta{font name}|/|\meta{modifier}\dots +% \end{quote} +% +% \noindent +% Currently, four style modifiers are supported: +% \verb|i| for italic shape, +% \verb|b| for bold weight, +% \verb|bi| or \verb|ib| for the combination of both. +% Other “slashed” modifiers are too specific to the \XETEX engine and +% have no meaning in \LUATEX. +% +% \subsection{Examples} +% +% \subsubsection{Loading by File Name} % % For example, conventional \abbrev{type1} font can be loaded with a \verb|file:| % request like so: @@ -305,8 +430,11 @@ and the derived files % \end{quote} % % The \OpenType version of Janusz Nowacki’s font \emphasis{Antykwa -% Półtawskiego} (in \TEX Live) in its condensed variant can be loaded as -% follows: +% Półtawskiego}\footnote{% +% \url{http://jmn.pl/antykwa-poltawskiego/}, also available in +% in \TEX Live. +% } +% in its condensed variant can be loaded as follows: % % \begin{quote} % \begin{verbatim} @@ -324,7 +452,7 @@ and the derived files % \end{verbatim} % \end{quote} % -% \subparagraph{Examples for loading by font name} +% \subsubsection{Loading by Font Name} % % The \verb|name:| lookup does not depend on cryptic filenames: % @@ -360,9 +488,62 @@ and the derived files % \end{verbatim} % \end{quote} % -% \paragraph{Font features} +% \subsubsection{Modifiers} +% +% If the entire \emphasis{Iwona} family\footnote{% +% \url{http://jmn.pl/kurier-i-iwona/}, +% also in \TEX Live. +% } +% is installed in some location accessible by \identifier{luaotfload}, +% the regular shape can be loaded as follows: +% +% \begin{quote} +% \begin{verbatim} +% \font\iwona=Iwona at 20pt +% \end{verbatim} +% \end{quote} +% +% \noindent +% To load the most common of the other styles, the slash notation can +% be employed as shorthand: % -% \meta{font features} is semicolon-separated list of feature +% \begin{quote} +% \begin{verbatim} +% \font\iwonaitalic =Iwona/i at 20pt +% \font\iwonabold =Iwona/b at 20pt +% \font\iwonabolditalic=Iwona/bi at 20pt +% \end{verbatim} +% \end{quote} +% +% \noindent +% which is equivalent to these full names: +% +% \begin{quote} +% \begin{verbatim} +% \font\iwonaitalic ="Iwona Italic" at 20pt +% \font\iwonabold ="Iwona Bold" at 20pt +% \font\iwonabolditalic="Iwona BoldItalic" at 20pt +% \end{verbatim} +% \end{quote} +% +% \section{Font features} +% +% \emphasis{Font features} are the second to last component in the +% general scheme for font requests: +% +% \begin{quote} +% |\font\foo={|% +% \meta{prefix}|:|% +% \meta{font name}|:|% +% \meta{font features}|}|% +% \meta{\TEX font features} +% \end{quote} +% +% \noindent +% If style modifiers are present (\XETEX style), they must precede +% \meta{font features}. +% +% The element \meta{font features} is a semicolon-separated list of feature % tags\footnote{% % Cf. \url{http://www.microsoft.com/typography/otspec/featurelist.htm}. % } @@ -587,8 +768,8 @@ and the derived files % This is particularly noticeable if it occurs during a typesetting run. % In any case, subsequent updates to the database will be quite fast. % -% \subsection[fontdbutil / mkluatexfontdb.lua]% -% {\fileent{fontdbutil} / +% \subsection[luaotfload-tool / mkluatexfontdb.lua]% +% {\fileent{luaotfload-tool} / % \fileent{mkluatexfontdb.lua}\footnote{% % The script may be named just \fileent{mkluatexfontdb} in your % distribution. @@ -597,7 +778,7 @@ and the derived files % It can still be desirable at times to do some of these steps % manually, and without having to compile a document. % To this end, \identifier{luaotfload} comes with the utility -% \fileent{fontdbutil} that offers an interface to the database +% \fileent{luaotfload-tool} that offers an interface to the database % functionality. % Being a \LUA script, there are two ways to run it: % either make it executable (\verb|chmod +x| on unixoid systems) or @@ -612,15 +793,15 @@ and the derived files % \emphasis{Note}: % On \abbrev{MS} \identifier{Windows} systems, the script can be run % either by calling the wrapper application -% \fileent{fontdbutil.exe} or as -% \verb|texlua.exe fontdbutil|. +% \fileent{luaotfload-tool.exe} or as +% \verb|texlua.exe luaotfload-tool.lua|. % } % Invoked with the argument \verb|--update| it will perform a database % update, scanning for fonts not indexed. % % \begin{quote} % \begin{verbatim} -% fontdbutil --update +% luaotfload-tool --update % \end{verbatim} % \end{quote} % @@ -629,11 +810,11 @@ and the derived files % % \begin{quote} % \begin{verbatim} -% fontdbutil --update --force +% luaotfload-tool --update --force % \end{verbatim} % \end{quote} % -% For sake of backwards compatibility, \fileent{fontdbutil} may be +% For sake of backwards compatibility, \fileent{luaotfload-tool} may be % renamed or symlinked to \fileent{mkluatexfontdb}. % Whenever it is run under this name, it will update the database % first, mimicking the behavior of earlier versions of @@ -681,7 +862,7 @@ and the derived files % % \subsection{Querying from Outside} % -% \fileent{fontdbutil} also provides rudimentary means of +% \fileent{luaotfload-tool} also provides rudimentary means of % accessing the information collected in the font database. % If the option \verb|--find=|\emphasis{name} is given, the script will % try and search the fonts indexed by \identifier{luaotfload} for a @@ -690,7 +871,7 @@ and the derived files % % \begin{quote} % \begin{verbatim} -% fontdbutil --find="Iwona Regular" +% luaotfload-tool --find="Iwona Regular" % \end{verbatim} % \end{quote} % @@ -707,7 +888,7 @@ and the derived files % % \begin{quote} % \begin{verbatim} -% fontdbutil -F --find="Iwona Bright" +% luaotfload-tool -F --find="Iwona Bright" % \end{verbatim} % \end{quote} % @@ -718,7 +899,7 @@ and the derived files % using the \verb|-i| option (\verb|--info|). % \begin{quote} % \begin{verbatim} -% fontdbutil -F --find="Iwona Light Italic" +% luaotfload-tool -F --find="Iwona Light Italic" % \end{verbatim} % \end{quote} % \noindent @@ -727,7 +908,7 @@ and the derived files % In \TEX Live: \fileent{texmf-dist/doc/luatex/base/luatexref-t.pdf}. % } % -% \verb|fontdbutil --help| will list the available command line +% \verb|luaotfload-tool --help| will list the available command line % switches, including some not discussed in detail here. % % \subsection{Blacklisting Fonts} @@ -736,7 +917,7 @@ and the derived files % Some fonts are problematic in general, or just in \LUATEX. % If you find that compiling your document takes far too long or eats % away all your system’s memory, you can track down the culprit by -% running \verb|fontdbutil -v| to increase verbosity. +% running \verb|luaotfload-tool -v| to increase verbosity. % Take a note of the \emphasis{filename} of the font that database % creation fails with and append it to the file % \fileent{luaotfload-blacklist.cnf}. @@ -945,7 +1126,7 @@ and the derived files % verbosity levels and redirecting log output to \fileent{stdout}: % % \begin{verbatim} -% fontdbutil -fuvvv --log=stdout +% luaotfload-tool -fuvvv --log=stdout % \end{verbatim} % % If this fails, the font last printed to the terminal is likely to be @@ -998,12 +1179,13 @@ local luaotfload = luaotfload config = config or { } config.luaotfload = config.luaotfload or { } -luaotfload.prefer_merge = config.luaotfload.prefer_merge or true +config.luaotfload.resolver = config.luaotfload.resolver or "normal" +--luaotfload.prefer_merge = config.luaotfload.prefer_merge or true luaotfload.module = { name = "luaotfload", version = 2.2, - date = "2013/04/15", + date = "2013/04/29", description = "OpenType layout system.", author = "Elie Roux & Hans Hagen", copyright = "Elie Roux", @@ -1014,11 +1196,12 @@ local luatexbase = luatexbase local type, next = type, next local setmetatable = setmetatable +local find_file = kpse.find_file +local lfsisfile = lfs.isfile local stringfind = string.find -local stringsub = string.sub -local stringmatch = string.match local stringformat = string.format -local find_file = kpse.find_file +local stringmatch = string.match +local stringsub = string.sub local add_to_callback, create_callback = luatexbase.add_to_callback, luatexbase.create_callback @@ -1328,7 +1511,7 @@ add_to_callback("find_vf_file", loadmodule"lib-dir.lua" --- required by luaofload-database.lua loadmodule"override.lua" --- “luat-ovr” -logs.set_loglevel(0) +logs.set_loglevel(config.luaotfload.loglevel or 2) % \end{macrocode} % \CONTEXT does not support ofm, these lines were added in order to make it @@ -1350,23 +1533,101 @@ loadmodule"database.lua" --- “font-nms” loadmodule"colors.lua" --- “font-clr” % \end{macrocode} -% This hack makes fonts called with file method found by fonts.names.resolve -% instead of just trying to find them with \identifier{kpse}. -% It is necessary in cases when font files are not reachable by -% \identifier{kpse} but present in the database, a quite common case -% under Linux. -% -% As of 2013-04-24 we have a workaround in the resolver that handles -% \verb|file:| lookups diverted this way. -% It requires some overhead due to additional extra data saved in the -% names database, and might vanish entirely once the font request syntax -% is understood. -% Until then it is considered a kludge, like the hack below. +% Relying on the \verb|name:| resolver for everything has been the source +% of permanent trouble with the database. +% With the introduction of the new syntax parser we now have enough +% granularity to distinguish between the \XETEX emulation layer and the +% genuine \verb|name:| and \verb|file:| lookups of \LUATEX-Fonts. +% Another benefit is that we can now easily plug in or replace new lookup +% behaviors if necessary. +% +% The name resolver remains untouched, but it calls +% \luafunction{fonts.names.resolve()} internally anyways (see +% \fileent{luaotfload-database.lua}). +% +% \begin{macrocode} + +local request_resolvers = fonts.definers.resolvers +local formats = fonts.formats +formats.ofm = "type1" + +% \end{macrocode} +% \identifier{luaotfload} promises easy access to system fonts. +% Without additional precautions, this cannot be achieved by +% \identifier{kpathsea} alone, because it searches only the +% \fileent{texmf} directories by default. +% Although it is possible for \identifier{kpathsea} to include extra +% paths by adding them to the \verb|OSFONTDIR| environment variable, +% this is still short of the goal »\emphasis{it just works!}«. +% When building the font database \identifier{luaotfload} scans +% system font directories anyways, so we already have all the +% information for looking sytem fonts. +% 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. +% +% \begin{macrocode} +request_resolvers.file = function (specification) + --local found = fonts.names.crude_file_lookup(specification.name) + local found = fonts.names.crude_file_lookup_verbose(specification.name) + specification.name = found[1] + --if format then specification.forced = format end +end + +% \end{macrocode} +% We classify as \verb|anon:| those requests that have neither a +% prefix nor brackets. According to Khaled\footnote{% +% \url{https://github.com/phi-gamma/luaotfload/issues/4#issuecomment-17090553}. +% } +% they are the \XETEX equivalent of a \verb|name:| request, so we will be +% treating them as such. +% +% \begin{macrocode} + +--request_resolvers.anon = request_resolvers.name + +% \end{macrocode} +% There is one drawback, though. +% This syntax is also used for requesting fonts in \identifier{Type1} +% (\abbrev{tfm}, \abbrev{ofm}) format. +% These are essentially \verb|file:| lookups and must be caught before +% the \verb|name:| resolver kicks in, lest they cause the database to +% update. +% Even if we were to require the \verb|file:| prefix for all +% \identifier{Type1} requests, tests have shown that certain fonts still +% include further fonts (e.~g. \fileent{omlgcb.ofm} will ask for +% \fileent{omsecob.tfm}) \emphasis{using the old syntax}. +% For this reason, we introduce an extra check with an early return. % % \begin{macrocode} +local type1_formats = { "tfm", "ofm", } + +request_resolvers.anon = function (specification) + local name = specification.name + for i=1, #type1_formats do + local format = type1_formats[i] + if resolvers.findfile(name, format) then + specification.name = file.addsuffix(name, format) + return + end + end + request_resolvers.name(specification) +end -fonts.definers.resolvers.file = function (specification) - specification.name = fonts.names.resolve('', '', specification) +% \end{macrocode} +% Prior to version 2.2, \identifier{luaotfload} did not distinguish +% \verb|file:| and \verb|path:| lookups, causing complications with the +% resolver. +% Now we test if the requested name is an absolute path in the file +% system, otherwise we fall back to the \verb|file:| lookup. +% +% \begin{macrocode} +request_resolvers.path = function (specification) + local exists, _ = lfsisfile(specification.name) + if not exists then -- resort to file: lookup + request_resolvers.file(specification) + end end % \end{macrocode} @@ -1442,7 +1703,6 @@ local patch_defined_font = function (specification, size, id) if type(tfmdata) == "table" then call_callback("luaotfload.patch_font", tfmdata) end - -- inspect(table.keys(tfmdata)) return tfmdata end |