.\" Man page generated from reStructuredText.
.
.TH LUAOTFLOAD-TOOL 1 "2022-10-03" "3.23" "text processing"
.SH NAME
luaotfload-tool \- generate and query the Luaotfload font names database
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBluaotfload\-tool\fP [ \-bcDfFiIlLnpqRSuvVhw ]
.INDENT 0.0
.TP
.B \fBluaotfload\-tool\fP \-\-update [ \-\-force ] [ \-\-quiet ] [ \-\-verbose ]
[ \-\-prefer\-texmf ] [ \-\-dry\-run ]
[ \-\-formats=[+|\-]EXTENSIONS ]
[ \-\-no\-compress ] [ \-\-no\-strip ]
[ \-\-local ] [ \-\-max\-fonts=N ]
.TP
.B \fBluaotfload\-tool\fP \-\-find=FONTNAME [ \-\-fuzzy ] [ \-\-info ] [ \-\-inspect ]
[ \-\-no\-reload ]
.UNINDENT
.sp
\fBluaotfload\-tool\fP \-\-flush\-lookups
.sp
\fBluaotfload\-tool\fP \-\-cache=DIRECTIVE
.sp
\fBluaotfload\-tool\fP \-\-list=CRITERION[:VALUE] [ \-\-fields=F1,F2,...,Fn ]
.sp
\fBluaotfload\-tool\fP \-\-bisect=DIRECTIVE
.sp
\fBluaotfload\-tool\fP \-\-help
.sp
\fBluaotfload\-tool\fP \-\-version
.sp
\fBluaotfload\-tool\fP \-\-show\-blacklist
.sp
\fBluaotfload\-tool\fP \-\-diagnose=CHECK
.sp
\fBluaotfload\-tool\fP \-\-conf=FILE \-\-dumpconf
.SH DESCRIPTION
.sp
luaotfload\-tool accesses the font names database that is required by
the \fILuaotfload\fP package. There are two general modes: \fBupdate\fP and
\fBquery\fP\&.
.INDENT 0.0
.IP \(bu 2
\fBupdate\fP:  update the database or rebuild it entirely;
.IP \(bu 2
\fBquery\fP:   resolve a font name or display close matches.
.UNINDENT
.SH OPTIONS
.SS update mode
.INDENT 0.0
.TP
.B \-\-update\fP,\fB  \-u
Update the database; indexes new fonts.
.TP
.B \-\-force\fP,\fB  \-f
Force rebuilding of the database; re\-indexes
all fonts.
.TP
.B \-\-local\fP,\fB  \-L
Include font files in \fB$PWD\fP\&. 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 \fBluaotfload\-tool\fP\&.
.TP
.B \-\-no\-reload\fP,\fB  \-n
Suppress auto\-updates to the database (e.g.
when \fB\-\-find\fP is passed an unknown name).
.TP
.B \-\-no\-compress\fP,\fB  \-c
Do not filter the plain text version of the
font index through gzip. Useful for debugging
if your editor is built without zlib.
.TP
.B \-\-prefer\-texmf\fP,\fB  \-p
Organize the file name database in a way so
that it prefer fonts in the \fITEXMF\fP tree over
system fonts if they are installed in both.
.TP
.BI \-\-formats\fB= EXTENSIONS
Extensions of the font files to index.
Where \fIEXTENSIONS\fP is a comma\-separated list of
supported file extensions (otf, ttf, ttc).
If the list is prefixed
with a \fB+\fP sign, the given list is added to
the currently active one; \fB\-\fP subtracts.
Default: \fIotf,ttf,ttc\fP\&.
Examples:
.INDENT 7.0
.IP 1. 3
\fB\-\-formats=\-ttc,ttf\fP would skip
TrueType fonts and font collections;
.IP 2. 3
\fB\-\-formats=otf\fP would scan only OpenType
files;
.IP 3. 3
\fB\-\-formats=+afm\fP includes binary
Postscript files accompanied by an AFM file.
.UNINDENT
.UNINDENT
.SS query mode
.INDENT 0.0
.TP
.BI \-\-find\fB= NAME
Resolve a font name; this looks up <name> in
the database and prints the file name it is
mapped to.
\fB\-\-find\fP also understands request syntax,
i.e. \fB\-\-find=file:foo.otf\fP checks whether
\fBfoo.otf\fP is indexed.
.TP
.B \-\-fuzzy\fP,\fB  \-F
Show approximate matches to the file name if
the lookup was unsuccessful (requires
\fB\-\-find\fP).
.TP
.B \-\-info\fP,\fB  \-i
Display basic information to a resolved font
file (requires \fB\-\-find\fP).
.TP
.B \-\-inspect\fP,\fB  \-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 \fB\-\-find\fP).
.TP
.BI \-\-list\fB= CRITERION
Show entries, where \fICRITERION\fP is one of the
following:
.INDENT 7.0
.IP 1. 3
the character \fB*\fP, selecting all entries;
.IP 2. 3
a field of a database entry, for instance
\fIversion\fP or \fIformat*\fP, according to which
the output will be sorted.
Information in an unstripped database (see
the option \fB\-\-no\-strip\fP above) is nested:
Subfields of a record can be addressed using
the \fB\->\fP separator, e. g.
\fBfile\->location\fP, \fBstyle\->units_per_em\fP,
or
\fBnames\->sanitized\->english\->prefmodifiers\fP\&.
NB: shell syntax requires that arguments
containing \fB\->\fP be properly quoted!
.IP 3. 3
an expression of the form \fBfield:value\fP to
limit the output to entries whose \fBfield\fP
matches \fBvalue\fP\&. The \fBvalue\fP can contain
\fB*\fP to match an arbitrary number of characters.
.UNINDENT
.sp
For example, in order to output file names and
corresponding versions, sorted by the font
format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\&./luaotfload\-tool.lua \-\-list="format" \-\-fields="file\->base,version"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This prints:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
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
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.BI \-\-fields\fB= FIELDS
Comma\-separated list of fields that should be
printed.
Information in an unstripped database (see the
option \fB\-\-no\-strip\fP above) is nested:
Subfields of a record can be addressed using
the \fB\->\fP separator, e. g.
\fBfile\->location\fP, \fBstyle\->units_per_em\fP,
or \fBnames\->sanitized\->english\->subfamily\fP\&.
The default is plainname,version*.
(Only meaningful with \fB\-\-list\fP\&.)
.UNINDENT
.SS font and lookup caches
.INDENT 0.0
.TP
.B \-\-flush\-lookups
Clear font name lookup cache (experimental).
.TP
.BI \-\-cache\fB= DIRECTIVE
Cache control, where \fIDIRECTIVE\fP is one of the
following:
.INDENT 7.0
.IP 1. 3
\fBpurge\fP \-> delete Lua files from cache;
.IP 2. 3
\fBerase\fP \-> delete Lua and Luc files from
cache;
.IP 3. 3
\fBshow\fP  \-> print stats.
.UNINDENT
.UNINDENT
.SS debugging methods
.INDENT 0.0
.TP
.B \-\-show\-blacklist\fP,\fB  \-b
Show blacklisted files (not directories).
.TP
.B \-\-dry\-run\fP,\fB  \-D
Don’t load fonts when updating the database;
scan directories only.
(For debugging file system related issues.)
.TP
.B \-\-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.
.TP
.BI \-\-max\-fonts\fB= N
Process at most \fIN\fP font files, including fonts
already indexed in the count.
.TP
.BI \-\-bisect\fB= DIRECTIVE
Bisection of the font database.
This mode is intended as assistance in
debugging the Luatex engine, especially when
tracking memleaks or buggy fonts.
.sp
\fIDIRECTIVE\fP can be one of the following:
.INDENT 7.0
.IP 1. 3
\fBrun\fP \-> Make \fBluaotfload\-tool\fP respect
the bisection progress when running.
Combined with \fB\-\-update\fP and possibly
\fB\-\-force\fP this will only process the files
from the start up until the pivot and ignore
the rest.
.IP 2. 3
\fBstart\fP \-> Start bisection: create a
bisection state file and initialize the low,
high, and pivot indices.
.IP 3. 3
\fBstop\fP \-> Terminate the current bisection
session by deleting the state file.
.IP 4. 3
\fBgood\fP | \fBbad\fP \-> Mark the section
processed last as “good” or “bad”,
respectively. The next bisection step will
continue with the bad section.
.IP 5. 3
\fBstatus\fP \-> Print status information about
the current bisection session. Hint: Use
with higher verbosity settings for more
output.
.UNINDENT
.sp
A bisection session is initiated by issuing the
\fBstart\fP directive. This sets the pivot to the
middle of the list of available font files.
Now run \fIluaotfload\-tool\fP with the \fB\-\-update\fP
flag set as well as \fB\-\-bisect=run\fP: only the
fonts up to the pivot will be considered. If
that task exhibited the issue you are tracking,
then tell Luaotfload using \fB\-\-bisect=bad\fP\&.
The next step of \fB\-\-bisect=run\fP will continue
bisection with the part of the files below the
pivot.
Likewise, issue \fB\-\-bisect=good\fP in order to
continue with the fonts above the pivot,
assuming the tested part of the list did not
trigger the bug.
.sp
Once the culprit font is tracked down, \fBgood\fP
or \fBbad\fP will have no effect anymore. \fBrun\fP
will always end up processing the single font
file that was left.
Use \fB\-\-bisect=stop\fP to clear the bisection
state.
.UNINDENT
.SS miscellaneous
.INDENT 0.0
.TP
.BI \-\-verbose\fB= N\fR,\fB \ \-v
Set verbosity level to \fIn\fP or the number of
repetitions of \fB\-v\fP\&.
.TP
.B \-\-quiet
No verbose output (log level set to zero).
.TP
.BI \-\-log\fB= CHANNEL
Redirect log output (for database
troubleshooting), where \fICHANNEL\fP can be
.INDENT 7.0
.IP 1. 3
\fBstdout\fP \-> all output will be
dumped to the terminal (default); or
.IP 2. 3
\fBfile\fP \-> write to a file to the temporary
directory (the name will be chosen
automatically.
.UNINDENT
.TP
.B \-\-version\fP,\fB  \-V
Show version numbers of components as well as
some basic information and exit.
.TP
.B \-\-help\fP,\fB  \-h
Show help message and exit.
.TP
.BI \-\-diagnose\fB= CHECK
Run the diagnostic procedure \fICHECK\fP\&. Available
procedures are:
.INDENT 7.0
.IP 1. 3
\fBfiles\fP \-> check \fILuaotfload\fP files for
modifications;
.IP 2. 3
\fBpermissions\fP \-> check permissions of
cache directories and files;
.IP 3. 3
.INDENT 3.0
.TP
.B \fBenvironment\fP \-> print relevant
environment and kpse variables;
.UNINDENT
.IP 4. 3
\fBrepository\fP \-> check the git repository
for new releases,
.IP 5. 3
\fBindex\fP \-> check database, display
information about it.
.UNINDENT
.sp
Procedures can be chained by concatenating with
commas, e.g. \fB\-\-diagnose=files,permissions\fP\&.
Specify \fBthorough\fP to run all checks.
.TP
.BI \-\-conf\fB= FILE
Read the configuration from \fIFILE\fP\&. See
\fBluaotfload.conf\fP(%) for documentation
concerning the format and available options.
.TP
.B \-\-dumpconf
Print the currently active configuration; the
output can be saved to a file and used for
bootstrapping a custom configuration files.
.TP
.B \-\-aliases
Dump the font name database as a kpathsea
aliases file. This option is experimental and
might go away.
.UNINDENT
.SH FILES
.sp
The font name database is usually located in the directory
\fBtexmf\-var/luatex\-cache/generic/names/\fP (\fB$TEXMFCACHE\fP as set in
\fBtexmf.cnf\fP) of your \fITeX Live\fP distribution as a zlib\-compressed
file \fBluaotfload\-names.lua.gz\fP\&.
The experimental lookup cache will be created as
\fBluaotfload\-lookup\-cache.lua\fP 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 \fB\&.luc\fP 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 \fILuaTeX\fP\&.
.SH SEE ALSO
.sp
\fBluaotfload.conf\fP(5), \fBluatex\fP(1), \fBlua\fP(1)
.INDENT 0.0
.IP \(bu 2
\fBtexdoc luaotfload\fP to display the manual for the \fILuaotfload\fP
package
.IP \(bu 2
Luaotfload development \fI\%https://github.com/latex3/luaotfload\fP
.IP \(bu 2
LuaLaTeX mailing list  \fI\%http://tug.org/pipermail/lualatex\-dev/\fP
.IP \(bu 2
LuaTeX                 \fI\%http://luatex.org/\fP
.IP \(bu 2
ConTeXt                \fI\%http://wiki.contextgarden.net\fP
.IP \(bu 2
Luaotfload on CTAN     \fI\%http://ctan.org/pkg/luaotfload\fP
.UNINDENT
.SH BUGS
.sp
Tons, probably.
.SH AUTHORS
.sp
\fILuaotfload\fP was developed by the LuaLaTeX dev team
(\fI\%https://github.com/lualatex/\fP). It is currently maintained by the LaTeX
Project Team at \fI\%https://github.com/latex3/luaotfload\fP
The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt
NL (\fI\%http://pragma\-ade.com/\fP).
.sp
This manual page was written by Philipp Gesang <\fI\%phg@phi\-gamma.net\fP>.
.SH COPYRIGHT
GPL v2.0
.\" Generated by docutils manpage writer.
.