diff options
Diffstat (limited to 'Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex')
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex | 707 |
1 files changed, 707 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex b/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex new file mode 100644 index 00000000000..2ae6e89196d --- /dev/null +++ b/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex @@ -0,0 +1,707 @@ +\documentclass[a4paper]{article} +% generated by Docutils <http://docutils.sourceforge.net/> +% rubber: set program xelatex +\usepackage{fontspec} +% \defaultfontfeatures{Scale=MatchLowercase} +% straight double quotes (defined T1 but missing in TU): +\ifdefined \UnicodeEncodingName + \DeclareTextCommand{\textquotedbl}{\UnicodeEncodingName}{% + {\addfontfeatures{RawFeature=-tlig,Mapping=}\char34}}% +\fi +\usepackage{ifthen} +\usepackage{alltt} +\setcounter{secnumdepth}{0} +\usepackage{longtable,ltcaption,array} +\setlength{\extrarowheight}{2pt} +\newlength{\DUtablewidth} % internal use in tables +\usepackage{tabularx} + +%%% Custom LaTeX preamble +% Linux Libertine (free, wide coverage, not only for Linux) +\setmainfont{Linux Libertine O} +\setsansfont{Linux Biolinum O} +\setmonofont[HyphenChar=None,Scale=MatchLowercase]{DejaVu Sans Mono} + +%%% User specified packages and stylesheets + +%%% Fallback definitions for Docutils-specific commands + +% providelength (provide a length variable and set default, if it is new) +\providecommand*{\DUprovidelength}[2]{ + \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{} +} + +% docinfo (width of docinfo table) +\DUprovidelength{\DUdocinfowidth}{0.9\linewidth} + +% subtitle (in document title) +\providecommand*{\DUdocumentsubtitle}[1]{{\large #1}} +% hyperlinks: +\ifthenelse{\isundefined{\hypersetup}}{ + \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} + \usepackage{bookmark} + \urlstyle{same} % normal text font (alternatives: tt, rm, sf) +}{} +\hypersetup{ + pdftitle={luaotfload.conf}, +} + +\title{luaotfload.conf% + \label{luaotfload-conf}% + \\ % subtitle% + \DUdocumentsubtitle{Luaotfload configuration file}% + \label{luaotfload-configuration-file}} +\author{} +\date{} + +%%% Body +\begin{document} +\maketitle + +% Docinfo +\begin{center} +\begin{tabularx}{\DUdocinfowidth}{lX} +\textbf{Date}: & + 2018-09-21 \\ +\textbf{Copyright}: & + GPL v2.0 \\ +\textbf{Version}: & + 2.9 \\ +\textbf{Manual section}: & +5 +\\ +\textbf{Manual group}: & +text processing +\\ +\end{tabularx} +\end{center} + + +\section{SYNOPSIS% + \label{synopsis}% +} + +\begin{itemize} +\item \textbf{./luaotfload\{.conf,rc\}} + +\item \textbf{XDG\_CONFIG\_HOME/luaotfload/luaotfload\{.conf,rc\}} + +\item \textbf{\textasciitilde{}/.luaotfloadrc} +\end{itemize} + + +\section{DESCRIPTION% + \label{description}% +} + +The file \texttt{luaotfload.conf} contains configuration options for +\emph{Luaotfload}, a font loading and font management component for LuaTeX. + + +\section{EXAMPLE% + \label{example}% +} + +A small Luaotfload configuration file with few customizations could +look as follows: + +\begin{quote} +\begin{alltt} +[db] + formats = afm,ttf + compress = false + +[misc] + termwidth = 60 + +[run] + log-level = 6 +\end{alltt} +\end{quote} + +This will make Luaotfload ignore all font files except for PostScript +binary fonts with a matching AFM file, and Truetype fonts. Also, an +uncompressed index file will be dumped which is going to be much larger +than the default gzip’ed index. The terminal width +is truncated to 60 characters which influences the verbose output +during indexing. Finally, the verbosity is increased greatly: each font +file being processed will be printed to the stdout on a separate line, +along with lots of other information. + +To observe the difference in behavior, save above snippet to +\texttt{./luaotfload.conf} and update the font index: + +\begin{quote} +\begin{alltt} +luaotfload-tool --update --force +\end{alltt} +\end{quote} + +The current configuration can be written to disk using +\textbf{luaotfload-tool}: + +\begin{quote} +\begin{alltt} +luaotfload-tool --dumpconf > luaotfload.conf +\end{alltt} +\end{quote} + +The result can itself be used as a configuration file. + + +\section{SYNTAX% + \label{syntax}% +} + +The configuration file syntax follows the common INI format. For a more +detailed description please refer to the section “CONFIGURATION FILE” +of \textbf{git-config}(1). A brief list of rules is given below: + +\begin{quote} +\begin{itemize} +\item Blank lines and lines starting with a semicolon (\texttt{;}) are ignored. + +\item A configuration file is partitioned into sections that are declared +by specifying the section title in brackets on a separate line: + +\begin{quote} +\begin{alltt} +[some-section] +... section content ... +\end{alltt} +\end{quote} + +\item Sections consist of one or more variable assignments of the form +\texttt{variable-name = value} E. g.: + +\begin{quote} +\begin{alltt} +[foo] + bar = baz + quux = xyzzy + ... +\end{alltt} +\end{quote} + +\item Section and variable names may contain only uppercase and lowercase +letters as well as dashes (\texttt{-}). +\end{itemize} +\end{quote} + + +\section{VARIABLES% + \label{variables}% +} + +Variables in belong into a configuration section and their values must +be of a certain type. Some of them have further constraints. For +example, the “color callback” must be a string of one of the values +\texttt{post\_linebreak\_filter}, \texttt{pre\_linebreak\_filter}, or +\texttt{pre\_output\_filter}, defined in the section \emph{run} of the +configuration file. + +Currently, the configuration is organized into four sections: + +\begin{description} +\item[{db}] \leavevmode +Options relating to the font index. + +\item[{misc}] \leavevmode +Options without a clearly defined category. + +\item[{paths}] \leavevmode +Path and file name settings. + +\item[{run}] \leavevmode +Options controlling runtime behavior of Luaotfload. + +\end{description} + +The list of valid variables, the sections they are part of and their +type is given below. Types represent Lua types that the values must be +convertible to; they are abbreviated as follows: \texttt{s} for the \emph{string} +type, \texttt{n} for \emph{number}, \texttt{b} for \emph{boolean}. A value of \texttt{nil} means +the variable is unset. + + +\subsection{Section \texttt{db}% + \label{section-db}% +} + +\setlength{\DUtablewidth}{\linewidth} +\begin{longtable*}[c]{|p{0.249\DUtablewidth}|p{0.110\DUtablewidth}|p{0.331\DUtablewidth}|} +\hline + +variable + & +type + & +default + \\ +\hline + +compress + & +b + & +\texttt{true} + \\ +\hline + +designsize-dimen + & +b + & +\texttt{bp} + \\ +\hline + +formats + & +s + & +\texttt{\textquotedbl{}otf,ttf,ttc\textquotedbl{}} + \\ +\hline + +max-fonts + & +n + & +\texttt{2\textasciicircum{}51} + \\ +\hline + +scan-local + & +b + & +\texttt{false} + \\ +\hline + +skip-read + & +b + & +\texttt{false} + \\ +\hline + +strip + & +b + & +\texttt{true} + \\ +\hline + +update-live + & +b + & +\texttt{true} + \\ +\hline +\end{longtable*} + +The flag \texttt{compress} determines whether the font index (usually +\texttt{luaotfload-names.lua{[}.gz{]}} will be stored in compressed forms. +If unset it is equivalent of passing \texttt{--no-compress} to +\textbf{luaotfload-tool}. Since the file is only created for convenience +and has no effect on the runtime behavior of Luaotfload, the flag +should remain set. Most editors come with zlib support anyways. + +The setting \texttt{designsize-dimen} applies when looking up fonts from +families with design sizes. In Opentype, these are specified as +“decipoints” where one decipoint equals ten DTP style “big points”. +When indexing fonts these values are converted to \texttt{sp}. In order to +treat the values as though they were specified in TeX points or Didot +points, set \texttt{designsize-dimen} to \texttt{pt} or \texttt{dd}. + +The list of \texttt{formats} must be a comma separated sequence of strings +containing one or more of these elements: + +\begin{itemize} +\item \texttt{otf} (OpenType format), + +\item \texttt{ttf} and \texttt{ttc} (TrueType format), + +\item \texttt{afm} (Adobe Font Metrics), +\end{itemize} + +It corresponds loosely to the \texttt{--formats} option to +\textbf{luaotfload-tool}. Invalid or duplicate members are ignored; if the +list does not contain any useful identifiers, the default list +\texttt{\textquotedbl{}otf,ttf,ttc\textquotedbl{}} will be used. + +The variable \texttt{max-fonts} determines after processing how many font +files the font scanner will terminate the search. This is useful for +debugging issues with the font index and has the same effect as the +option \texttt{--max-fonts} to \textbf{luaotfload-tools}. + +The \texttt{scan-local} flag, if set, will incorporate the current working +directory as a font search location. NB: This will potentially slow +down document processing because a font index with local fonts will not +be saved to disk, so these fonts will have to be re-indexed whenever +the document is built. + +The \texttt{skip-read} flag is only useful for debugging: It makes +Luaotfload skip reading fonts. The font information for rebuilding the +index is taken from the presently existing one. + +Unsetting the \texttt{strip} flag prevents Luaotfload from removing data +from the index that is only useful when processing font files. NB: this +can increase the size of the index files significantly and has no +effect on the runtime behavior. + +If \texttt{update-live} is set, Luaotfload will reload the database if it +cannot find a requested font. Those who prefer to update manually using +\textbf{luaotfload-tool} should unset this flag. This option does not affect +rebuilds due to version mismatch. + + +\subsection{Section \texttt{default-features}% + \label{section-default-features}% +} + +By default Luaotfload enables \texttt{node} mode and picks the default font +features that are prescribed in the OpenType standard. This behavior +may be overridden in the \texttt{default-features} section. Global defaults +that will be applied for all scripts can be set via the \texttt{global} +option, others by the script they are to be applied to. For example, +a setting of + +\begin{quote} +\begin{alltt} +[default-features] + global = mode=base,color=0000FF + dflt = smcp,onum +\end{alltt} +\end{quote} + +would force \emph{base} mode, tint all fonts blue and activate small +capitals and text figures globally. Features are specified as a comma +separated list of variables or variable-value pairs. Variables without +an explicit value are set to \texttt{true}. + + +\subsection{Section \texttt{misc}% + \label{section-misc}% +} + +\setlength{\DUtablewidth}{\linewidth} +\begin{longtable*}[c]{|p{0.191\DUtablewidth}|p{0.110\DUtablewidth}|p{0.307\DUtablewidth}|} +\hline + +variable + & +type + & +default + \\ +\hline + +statistics + & +b + & +\texttt{false} + \\ +\hline + +termwidth + & +n + & +\texttt{nil} + \\ +\hline + +version + & +s + & +<Luaotfload version> + \\ +\hline +\end{longtable*} + +With \texttt{statistics} enabled, extra statistics will be collected during +index creation and appended to the index file. It may then be queried +at the Lua end or inspected by reading the file itself. + +The value of \texttt{termwidth}, if set, overrides the value retrieved by +querying the properties of the terminal in which Luatex runs. This is +useful if the engine runs with \texttt{shell\_escape} disabled and the actual +terminal dimensions cannot be retrieved. + +The value of \texttt{version} is derived from the version string hard-coded +in the Luaotfload source. Override at your own risk. + + +\subsection{Section \texttt{paths}% + \label{section-paths}% +} + +\setlength{\DUtablewidth}{\linewidth} +\begin{longtable*}[c]{|p{0.226\DUtablewidth}|p{0.110\DUtablewidth}|p{0.435\DUtablewidth}|} +\hline + +variable + & +type + & +default + \\ +\hline + +cache-dir + & +s + & +\texttt{\textquotedbl{}fonts\textquotedbl{}} + \\ +\hline + +names-dir + & +s + & +\texttt{\textquotedbl{}names\textquotedbl{}} + \\ +\hline + +index-file + & +s + & +\texttt{\textquotedbl{}luaotfload-names.lua\textquotedbl{}} + \\ +\hline + +lookups-file + & +s + & +\texttt{\textquotedbl{}luaotfload-lookup-cache.lua\textquotedbl{}} + \\ +\hline +\end{longtable*} + +The paths \texttt{cache-dir} and \texttt{names-dir} determine the subdirectory +inside the Luaotfload subtree of the \texttt{luatex-cache} directory where +the font cache and the font index will be stored, respectively. + +Inside the index directory, the names of the index file and the font +lookup cache will be derived from the respective values of +\texttt{index-file} and \texttt{lookups-file}. This is the filename base for the +bytecode compiled version as well as -- for the index -- the gzipped +version. + + +\subsection{Section \texttt{run}% + \label{section-run}% +} + +\setlength{\DUtablewidth}{\linewidth} +\begin{longtable*}[c]{|p{0.226\DUtablewidth}|p{0.110\DUtablewidth}|p{0.365\DUtablewidth}|} +\hline + +variable + & +type + & +default + \\ +\hline + +anon-sequence + & +s + & +\texttt{\textquotedbl{}tex,path,name\textquotedbl{}} + \\ +\hline + +color-callback + & +s + & +\texttt{\textquotedbl{}post\_linebreak\_filter\textquotedbl{}} + \\ +\hline + +definer + & +s + & +\texttt{\textquotedbl{}patch\textquotedbl{}} + \\ +\hline + +log-level + & +n + & +\texttt{0} + \\ +\hline + +resolver + & +s + & +\texttt{\textquotedbl{}cached\textquotedbl{}} + \\ +\hline + +fontloader + & +s + & +\texttt{\textquotedbl{}default\textquotedbl{}} + \\ +\hline +\end{longtable*} + +Unqualified font lookups are treated with the flexible “anonymous” +mechanism. This involves a chain of lookups applied successively until +the first one yields a match. By default, the lookup will first search +for TFM fonts using the Kpathsea library. If this wasn’t successful, an +attempt is made at interpreting the request as an absolute path (like +the \texttt{{[}/path/to/font/foo.ttf{]}} syntax) or a file name +(\texttt{file:foo.ttf}). Finally, the request is interpreted as a font name +and retrieved from the index (\texttt{name:Foo Regular}). This behavior can +be configured by specifying a list as the value to \texttt{anon-sequence}. +Available items are \texttt{tex}, \texttt{path}, \texttt{name} -- representing the +lookups described above, respectively --, and \texttt{file} for searching a +filename but not an absolute path. Also, \texttt{my} lookups are valid +values but they should only be used from within TeX documents, because +there is no means of customizing a \texttt{my} lookups on the command line. + +The \texttt{color-callback} option determines the stage at which fonts that +defined with a \texttt{color=xxyyzz} feature will be colorized. By default +this happens in a \texttt{post\_linebreak\_filter} but alternatively the +\texttt{pre\_linebreak\_filter} or \texttt{pre\_output\_filter} may be chosen, which +is faster but might produce inconsistent output. The +\texttt{pre\_output\_filter} used to be the default in the 1.x series of +Luaotfload, whilst later versions up to and including 2.5 hooked into +the \texttt{pre\_linebreak\_filter} which naturally didn’t affect any glyphs +inserting during hyphenation. Both are kept around as options to +restore the previous behavior if necessary. + +The \texttt{definer} allows for switching the \texttt{define\_font} callback. +Apart from the default \texttt{patch} one may also choose the \texttt{generic} +one that comes with the vanilla fontloader. Beware that this might +break tools like Fontspec that rely on the \texttt{patch\_font} callback +provided by Luaotfload to perform important corrections on font data. + +The fontloader backend can be selected by setting the value of +\texttt{fontloader}. The most important choices are \texttt{default}, which will +load the dedicated Luaotfload fontloader, and \texttt{reference}, the +upstream package as shipped with Luaotfload. Other than those, a file +name accessible via kpathsea can be specified. + +Alternatively, the individual files that constitute the fontloader can +be loaded directly. While less efficient, this greatly aids debugging +since error messages will reference the actual line numbers of the +source files and explanatory comments are not stripped. Currently, +three distinct loading strategies are available: \texttt{unpackaged} will +load the batch that is part of Luaotfload. These contain the identical +source code that the reference fontloader has been compiled from. +Another option, \texttt{context} will attempt to load the same files by +their names in the Context format from the search path. Consequently +this option allows to use the version of Context that comes with the +TeX distribution. Distros tend to prefer the stable version (“current” +in Context jargon) of those files so certain bugs encountered in the +more bleeding edge Luaotfload can be avoided this way. A third option +is to use \texttt{context} with a colon to specify a directory prefix where +the \emph{TEXMF} is located that the files should be loaded from, e. g. +\texttt{context:\textasciitilde{}/context/tex/texmf-context}. This can be used when +referencing another distribution like the Context minimals that is +installed under a different path not indexed by kpathsea. + +The value of \texttt{log-level} sets the default verbosity of messages +printed by Luaotfload. Only messages defined with a verbosity of less +than or equal to the supplied value will be output on the terminal. +At a log level of five Luaotfload can be very noisy. Also, printing too +many messages will slow down the interpreter due to line buffering +being disabled (see \textbf{setbuf}(3)). + +The \texttt{resolver} setting allows choosing the font name resolution +function: With the default value \texttt{cached} Luaotfload saves the result +of a successful font name request to a cache file to speed up +subsequent lookups. The alternative, \texttt{normal} circumvents the cache +and resolves every request individually. (Since to the restructuring of +the font name index in Luaotfload 2.4 the performance difference +between the cached and uncached lookups should be marginal.) + + +\section{FILES% + \label{files}% +} + +Luaotfload only processes the first configuration file it encounters at +one of the search locations. The file name may be either +\texttt{luaotfload.conf} or \texttt{luaotfloadrc}, except for the dotfile in the +user’s home directory which is expected at \texttt{\textasciitilde{}/.luaotfloadrc}. + +Configuration files are located following a series of steps. The search +terminates as soon as a suitable file is encountered. The sequence of +locations that Luaotfload looks at is + +\begin{enumerate} +\renewcommand{\labelenumi}{\roman{enumi}.} +\item The current working directory of the LuaTeX process. + +\item The subdirectory \texttt{luaotfload/} inside the XDG configuration +tree, e. g. \texttt{/home/oenothea/config/luaotfload/}. + +\item The dotfile. + +\item The \emph{TEXMF} (using kpathsea). +\end{enumerate} + + +\section{SEE ALSO% + \label{see-also}% +} + +\textbf{luaotfload-tool}(1), \textbf{luatex}(1), \textbf{lua}(1) + +\begin{itemize} +\item \texttt{texdoc luaotfload} to display the PDF manual for the \emph{Luaotfload} +package + +\item Luaotfload development \url{https://github.com/u-fischer/luaotfload} + +\item LuaLaTeX mailing list \url{http://tug.org/pipermail/lualatex-dev/} + +\item LuaTeX \url{http://luatex.org/} + +\item Luaotfload on CTAN \url{http://ctan.org/pkg/luaotfload} +\end{itemize} + + +\section{REFERENCES% + \label{references}% +} + +\begin{itemize} +\item The XDG base specification +\url{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}. +\end{itemize} + + +\section{AUTHORS% + \label{authors}% +} + +\emph{Luaotfload} was developed by the LuaLaTeX dev team +(\url{https://github.com/lualatex/}). It is currently maintained by Ulrike Fischer +and Marcel Krüger at \url{https://github.com/u-fischer/luaotfload} + +This manual page was written by Philipp Gesang <\href{mailto:phg@phi-gamma.net}{phg@phi-gamma.net}>. + +\end{document} |