summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex')
-rw-r--r--Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex517
1 files changed, 517 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex b/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex
new file mode 100644
index 00000000000..eab3b38b1de
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex
@@ -0,0 +1,517 @@
+\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{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}}
+
+% optionlist environment
+\providecommand*{\DUoptionlistlabel}[1]{\bf #1 \hfill}
+\DUprovidelength{\DUoptionlistindent}{3cm}
+\ifthenelse{\isundefined{\DUoptionlist}}{
+ \newenvironment{DUoptionlist}{%
+ \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
+ \setlength{\rightmargin}{1cm}
+ \setlength{\leftmargin}{\rightmargin}
+ \addtolength{\leftmargin}{\labelwidth}
+ \addtolength{\leftmargin}{\labelsep}
+ \renewcommand{\makelabel}{\DUoptionlistlabel}}
+ }
+ {\endlist}
+}{}
+% 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-tool},
+}
+
+\title{luaotfload-tool%
+ \label{luaotfload-tool}%
+ \\ % subtitle%
+ \DUdocumentsubtitle{generate and query the Luaotfload font names database}%
+ \label{generate-and-query-the-luaotfload-font-names-database}}
+\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}: &
+1
+\\
+\textbf{Manual group}: &
+text processing
+\\
+\end{tabularx}
+\end{center}
+
+
+\section{SYNOPSIS%
+ \label{synopsis}%
+}
+
+\textbf{luaotfload-tool} {[} -bcDfFiIlLnpqRSuvVhw {]}
+
+\begin{description}
+\item[{\textbf{luaotfload-tool} --update {[} --force {]} {[} --quiet {]} {[} --verbose {]}}] \leavevmode
+{[} --prefer-texmf {]} {[} --dry-run {]}
+{[} --formats={[}+|-{]}EXTENSIONS {]}
+{[} --no-compress {]} {[} --no-strip {]}
+{[} --local {]} {[} --max-fonts=N {]}
+
+\item[{\textbf{luaotfload-tool} --find=FONTNAME {[} --fuzzy {]} {[} --info {]} {[} --inspect {]}}] \leavevmode
+{[} --no-reload {]}
+
+\end{description}
+
+\textbf{luaotfload-tool} --flush-lookups
+
+\textbf{luaotfload-tool} --cache=DIRECTIVE
+
+\textbf{luaotfload-tool} --list=CRITERION{[}:VALUE{]} {[} --fields=F1,F2,...,Fn {]}
+
+\textbf{luaotfload-tool} --bisect=DIRECTIVE
+
+\textbf{luaotfload-tool} --help
+
+\textbf{luaotfload-tool} --version
+
+\textbf{luaotfload-tool} --show-blacklist
+
+\textbf{luaotfload-tool} --diagnose=CHECK
+
+\textbf{luaotfload-tool} --conf=FILE --dumpconf
+
+
+\section{DESCRIPTION%
+ \label{description}%
+}
+
+luaotfload-tool accesses the font names database that is required by
+the \emph{Luaotfload} package. There are two general modes: \textbf{update} and
+\textbf{query}.
+
+\begin{itemize}
+\item \textbf{update}: update the database or rebuild it entirely;
+
+\item \textbf{query}: resolve a font name or display close matches.
+\end{itemize}
+
+
+\section{OPTIONS%
+ \label{options}%
+}
+
+
+\subsection{update mode%
+ \label{update-mode}%
+}
+
+\begin{DUoptionlist}
+\item[--update, -u] Update the database; indexes new fonts.
+
+\item[--force, -f] Force rebuilding of the database; re-indexes
+all fonts.
+
+\item[--local, -L] Include font files in \texttt{\$PWD}. This option
+will cause large parts of the database to be
+rebuilt. Thus it is quite inefficient.
+Additionally, if local font files are found,
+the database is prevented from being saved
+to disk, so the local fonts need to be parsed
+with every invocation of \texttt{luaotfload-tool}.
+
+\item[--no-reload, -n] Suppress auto-updates to the database (e.g.
+when \texttt{--find} is passed an unknown name).
+
+\item[--no-compress, -c] Do not filter the plain text version of the
+font index through gzip. Useful for debugging
+if your editor is built without zlib.
+
+\item[--prefer-texmf, -p] Organize the file name database in a way so
+that it prefer fonts in the \emph{TEXMF} tree over
+system fonts if they are installed in both.
+
+\item[--formats=EXTENSIONS] Extensions of the font files to index.
+Where \emph{EXTENSIONS} is a comma-separated list of
+supported file extensions (otf, ttf, ttc).
+If the list is prefixed
+with a \texttt{+} sign, the given list is added to
+the currently active one; \texttt{-} subtracts.
+Default: \emph{otf,ttf,ttc}.
+Examples:
+
+\begin{enumerate}
+\renewcommand{\labelenumi}{\arabic{enumi})}
+\item \texttt{--formats=-ttc,ttf} would skip
+TrueType fonts and font collections;
+
+\item \texttt{--formats=otf} would scan only OpenType
+files;
+
+\item \texttt{--formats=+afm} includes binary
+Postscript files accompanied by an AFM file.
+\end{enumerate}
+\end{DUoptionlist}
+
+
+\subsection{query mode%
+ \label{query-mode}%
+}
+
+\begin{DUoptionlist}
+\item[--find=NAME] Resolve a font name; this looks up <name> in
+the database and prints the file name it is
+mapped to.
+\texttt{--find} also understands request syntax,
+i.e. \texttt{--find=file:foo.otf} checks whether
+\texttt{foo.otf} is indexed.
+
+\item[--fuzzy, -F] Show approximate matches to the file name if
+the lookup was unsuccessful (requires
+\texttt{--find}).
+
+\item[--info, -i] Display basic information to a resolved font
+file (requires \texttt{--find}).
+
+\item[--inspect, -I] Display detailed information by loading the
+font and analyzing the font table; very slow!
+For the meaning of the returned fields see
+the LuaTeX documentation.
+(requires \texttt{--find}).
+
+\item[--list=CRITERION] Show entries, where \emph{CRITERION} is one of the
+following:
+
+\begin{enumerate}
+\renewcommand{\labelenumi}{\arabic{enumi})}
+\item the character \texttt{*}, selecting all entries;
+
+\item a field of a database entry, for instance
+\emph{version} or \emph{format*}, according to which
+the output will be sorted.
+Information in an unstripped database (see
+the option \texttt{--no-strip} above) is nested:
+Subfields of a record can be addressed using
+the \texttt{->} separator, e. g.
+\texttt{file->location}, \texttt{style->units\_per\_em},
+or
+\texttt{names->sanitized->english->prefmodifiers}.
+NB: shell syntax requires that arguments
+containing \texttt{->} be properly quoted!
+
+\item an expression of the form \texttt{field:value} to
+limit the output to entries whose \texttt{field}
+matches \texttt{value}.
+\end{enumerate}
+
+For example, in order to output file names and
+corresponding versions, sorted by the font
+format:
+
+\begin{quote}
+\begin{alltt}
+./luaotfload-tool.lua --list="format" --fields="file->base,version"
+\end{alltt}
+\end{quote}
+
+This prints:
+
+\begin{quote}
+\begin{alltt}
+otf latinmodern-math.otf Version 1.958
+otf lmromancaps10-oblique.otf 2.004
+otf lmmono8-regular.otf 2.004
+otf lmmonoproplt10-bold.otf 2.004
+otf lmsans10-oblique.otf 2.004
+otf lmromanslant8-regular.otf 2.004
+otf lmroman12-italic.otf 2.004
+otf lmsansdemicond10-oblique.otf 2.004
+...
+\end{alltt}
+\end{quote}
+
+\item[--fields=FIELDS] Comma-separated list of fields that should be
+printed.
+Information in an unstripped database (see the
+option \texttt{--no-strip} above) is nested:
+Subfields of a record can be addressed using
+the \texttt{->} separator, e. g.
+\texttt{file->location}, \texttt{style->units\_per\_em},
+or \texttt{names->sanitized->english->subfamily}.
+The default is plainname,version*.
+(Only meaningful with \texttt{--list}.)
+\end{DUoptionlist}
+
+
+\subsection{font and lookup caches%
+ \label{font-and-lookup-caches}%
+}
+
+\begin{DUoptionlist}
+\item[--flush-lookups] Clear font name lookup cache (experimental).
+
+\item[--cache=DIRECTIVE] Cache control, where \emph{DIRECTIVE} is one of the
+following:
+
+\begin{enumerate}
+\renewcommand{\labelenumi}{\arabic{enumi})}
+\item \texttt{purge} -> delete Lua files from cache;
+
+\item \texttt{erase} -> delete Lua and Luc files from
+cache;
+
+\item \texttt{show} -> print stats.
+\end{enumerate}
+\end{DUoptionlist}
+
+
+\subsection{debugging methods%
+ \label{debugging-methods}%
+}
+
+\begin{DUoptionlist}
+\item[--show-blacklist, -b] Show blacklisted files (not directories).
+
+\item[--dry-run, -D] Don’t load fonts when updating the database;
+scan directories only.
+(For debugging file system related issues.)
+
+\item[--no-strip] Do not strip redundant information after
+building the database. Warning: this will
+inflate the index to about two to three times
+the normal size.
+
+\item[--max-fonts=N] Process at most \emph{N} font files, including fonts
+already indexed in the count.
+
+\item[--bisect=DIRECTIVE] Bisection of the font database.
+This mode is intended as assistance in
+debugging the Luatex engine, especially when
+tracking memleaks or buggy fonts.
+
+\emph{DIRECTIVE} can be one of the following:
+
+\begin{enumerate}
+\renewcommand{\labelenumi}{\arabic{enumi})}
+\item \texttt{run} -> Make \texttt{luaotfload-tool} respect
+the bisection progress when running.
+Combined with \texttt{--update} and possibly
+\texttt{--force} this will only process the files
+from the start up until the pivot and ignore
+the rest.
+
+\item \texttt{start} -> Start bisection: create a
+bisection state file and initialize the low,
+high, and pivot indices.
+
+\item \texttt{stop} -> Terminate the current bisection
+session by deleting the state file.
+
+\item \texttt{good} | \texttt{bad} -> Mark the section
+processed last as “good” or “bad”,
+respectively. The next bisection step will
+continue with the bad section.
+
+\item \texttt{status} -> Print status information about
+the current bisection session. Hint: Use
+with higher verbosity settings for more
+output.
+\end{enumerate}
+
+A bisection session is initiated by issuing the
+\texttt{start} directive. This sets the pivot to the
+middle of the list of available font files.
+Now run \emph{luaotfload-tool} with the \texttt{--update}
+flag set as well as \texttt{--bisect=run}: only the
+fonts up to the pivot will be considered. If
+that task exhibited the issue you are tracking,
+then tell Luaotfload using \texttt{--bisect=bad}.
+The next step of \texttt{--bisect=run} will continue
+bisection with the part of the files below the
+pivot.
+Likewise, issue \texttt{--bisect=good} in order to
+continue with the fonts above the pivot,
+assuming the tested part of the list did not
+trigger the bug.
+
+Once the culprit font is tracked down, \texttt{good}
+or \texttt{bad} will have no effect anymore. \texttt{run}
+will always end up processing the single font
+file that was left.
+Use \texttt{--bisect=stop} to clear the bisection
+state.
+\end{DUoptionlist}
+
+
+\subsection{miscellaneous%
+ \label{miscellaneous}%
+}
+
+\begin{DUoptionlist}
+\item[--verbose=N, -v] Set verbosity level to \emph{n} or the number of
+repetitions of \texttt{-v}.
+
+\item[--quiet] No verbose output (log level set to zero).
+
+\item[--log=CHANNEL] Redirect log output (for database
+troubleshooting), where \emph{CHANNEL} can be
+
+\begin{enumerate}
+\renewcommand{\labelenumi}{\arabic{enumi})}
+\item \texttt{stdout} -> all output will be
+dumped to the terminal (default); or
+
+\item \texttt{file} -> write to a file to the temporary
+directory (the name will be chosen
+automatically.
+\end{enumerate}
+
+\item[--version, -V] Show version numbers of components as well as
+some basic information and exit.
+
+\item[--help, -h] Show help message and exit.
+
+\item[--diagnose=CHECK] Run the diagnostic procedure \emph{CHECK}. Available
+procedures are:
+
+\begin{enumerate}
+\renewcommand{\labelenumi}{\arabic{enumi})}
+\item \texttt{files} -> check \emph{Luaotfload} files for
+modifications;
+
+\item \texttt{permissions} -> check permissions of
+cache directories and files;
+
+\item
+\begin{description}
+\item[{\texttt{environment} -> print relevant}] \leavevmode
+environment and kpse variables;
+
+\end{description}
+
+\item \texttt{repository} -> check the git repository
+for new releases,
+
+\item \texttt{index} -> check database, display
+information about it.
+\end{enumerate}
+
+Procedures can be chained by concatenating with
+commas, e.g. \texttt{--diagnose=files,permissions}.
+Specify \texttt{thorough} to run all checks.
+
+\item[--conf=FILE] Read the configuration from \emph{FILE}. See
+\textbf{luaotfload.conf}(\%) for documentation
+concerning the format and available options.
+
+\item[--dumpconf] Print the currently active configuration; the
+output can be saved to a file and used for
+bootstrapping a custom configuration files.
+\end{DUoptionlist}
+
+
+\section{FILES%
+ \label{files}%
+}
+
+The font name database is usually located in the directory
+\texttt{texmf-var/luatex-cache/generic/names/} (\texttt{\$TEXMFCACHE} as set in
+\texttt{texmf.cnf}) of your \emph{TeX Live} distribution as a zlib-compressed
+file \texttt{luaotfload-names.lua.gz}.
+The experimental lookup cache will be created as
+\texttt{luaotfload-lookup-cache.lua} in the same directory.
+These Lua tables are not used directly by Luaotfload, though.
+Instead, they are compiled to Lua bytecode which is written to
+corresponding files with the extension \texttt{.luc} in the same directory.
+When modifying the files by hand keep in mind that only if the bytecode
+files are missing will Luaotfload use the plain version instead.
+Both kinds of files are safe to delete, at the cost of regenerating
+them with the next run of \emph{LuaTeX}.
+
+
+\section{SEE ALSO%
+ \label{see-also}%
+}
+
+\textbf{luaotfload.conf}(5), \textbf{luatex}(1), \textbf{lua}(1)
+
+\begin{itemize}
+\item \texttt{texdoc luaotfload} to display the manual for the \emph{Luaotfload}
+package
+
+\item Luaotfload development \url{https://github.com/lualatex/luaotfload}
+
+\item LuaLaTeX mailing list \url{http://tug.org/pipermail/lualatex-dev/}
+
+\item LuaTeX \url{http://luatex.org/}
+
+\item ConTeXt \url{http://wiki.contextgarden.net}
+
+\item Luaotfload on CTAN \url{http://ctan.org/pkg/luaotfload}
+\end{itemize}
+
+
+\section{BUGS%
+ \label{bugs}%
+}
+
+Tons, probably.
+
+
+\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}
+The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt
+NL (\url{http://pragma-ade.com/}).
+
+This manual page was written by Philipp Gesang <\href{mailto:phg@phi-gamma.net}{phg@phi-gamma.net}>.
+
+\end{document}