diff options
Diffstat (limited to 'Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex')
-rw-r--r-- | Master/texmf-dist/doc/luatex/luaotfload/luaotfload-tool.tex | 517 |
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} |