summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/luaotfload/luaotfload-tool.1
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/luaotfload/luaotfload-tool.1')
-rw-r--r--macros/luatex/generic/luaotfload/luaotfload-tool.1442
1 files changed, 442 insertions, 0 deletions
diff --git a/macros/luatex/generic/luaotfload/luaotfload-tool.1 b/macros/luatex/generic/luaotfload/luaotfload-tool.1
new file mode 100644
index 0000000000..81b5c22d6d
--- /dev/null
+++ b/macros/luatex/generic/luaotfload/luaotfload-tool.1
@@ -0,0 +1,442 @@
+.\" Man page generated from reStructuredText.
+.
+.TH LUAOTFLOAD-TOOL 1 "2019-08-11" "2.991" "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\&.
+.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\fP,\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.
+.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/lualatex/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 Ulrike Fischer
+and Marcel Krüger at \fI\%https://github.com/u\-fischer/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.
+.