summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex')
-rw-r--r--Master/texmf-dist/doc/luatex/luaotfload/luaotfload-conf.tex707
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}