diff options
Diffstat (limited to 'macros/luatex/generic/luaotfload/luaotfload-tool.1')
-rw-r--r-- | macros/luatex/generic/luaotfload/luaotfload-tool.1 | 442 |
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. +. |