summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/luaotfload-tool.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/luaotfload-tool.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/luaotfload-tool.1122
1 files changed, 96 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/man/man1/luaotfload-tool.1 b/Master/texmf-dist/doc/man/man1/luaotfload-tool.1
index d368e35f84a..dd8abe2999f 100644
--- a/Master/texmf-dist/doc/man/man1/luaotfload-tool.1
+++ b/Master/texmf-dist/doc/man/man1/luaotfload-tool.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH LUAOTFLOAD-TOOL 1 "2014-05-18" "2.4-4" "text processing"
+.TH LUAOTFLOAD-TOOL 1 "2014-03-30" "2.5" "text processing"
.SH NAME
luaotfload-tool \- generate and query the Luaotfload font names database
.
@@ -32,13 +32,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
-\fBluaotfload\-tool\fP [ \-bDfFiIlnpquvVhw ]
+\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 ]
@@ -50,6 +51,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.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
@@ -68,10 +71,6 @@ the \fILuaotfload\fP package. There are two general modes: \fBupdate\fP and
.IP \(bu 2
\fBquery\fP: resolve a font name or display close matches.
.UNINDENT
-.sp
-Note that if the script is named \fBmkluatexfontdb\fP it will behave like
-earlier versions (<=1.3) and always update the database first. Also,
-the verbosity level will be set to 2.
.SH OPTIONS
.SS update mode
.INDENT 0.0
@@ -83,16 +82,19 @@ Update the database; indexes new fonts.
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\-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
.B \-\-no\-compress\fP,\fB \-c
Do not filter the plain text version of the
font index through gzip. Useful for debugging
@@ -103,10 +105,6 @@ 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 \-\-max\-fonts\fB= N
-Process at most \fIN\fP font files, including fonts
-already indexed in the count.
-.TP
.BI \-\-formats\fB= EXTENSIONS
Extensions of the font files to index.
Where \fIEXTENSIONS\fP is a comma\-separated list of
@@ -130,10 +128,6 @@ standard TeX Live installation this will
grow the database considerably and slow down
font indexing.
.UNINDENT
-.TP
-.B \-\-dry\-run\fP,\fB \-D
-Don’t load fonts, scan directories only.
-(For debugging file system related issues.)
.UNINDENT
.SS query mode
.INDENT 0.0
@@ -167,9 +161,6 @@ Print the warnings generated by the fontloader
library (assumes \fB\-I\fP). Automatically enabled
if the verbosity level exceeds 2.
.TP
-.B \-\-show\-blacklist\fP,\fB \-b
-Show blacklisted files (not directories).
-.TP
.BI \-\-list\fB= CRITERION
Show entries, where \fICRITERION\fP is one of the
following:
@@ -260,6 +251,84 @@ cache;
\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
@@ -276,15 +345,16 @@ troubleshooting), where \fICHANNEL\fP can be
.INDENT 7.0
.IP 1. 3
\fBstdout\fP \-> all output will be
-dumped to the terminal; or
+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 (\fBexperimental!\fP).
+automatically.
.UNINDENT
.TP
.B \-\-version\fP,\fB \-V
-Show version info of components and exit.
+Show version numbers of components as well as
+some basic information and exit.
.TP
.B \-\-help\fP,\fB \-h
Show help message and exit.