diff options
| -rw-r--r-- | doc/luaotfload-tool.rst | 66 |
1 files changed, 60 insertions, 6 deletions
diff --git a/doc/luaotfload-tool.rst b/doc/luaotfload-tool.rst index 761b0ec..da88b21 100644 --- a/doc/luaotfload-tool.rst +++ b/doc/luaotfload-tool.rst @@ -6,16 +6,16 @@ generate and query the Luaotfload font names database ----------------------------------------------------------------------- -:Date: 2014-01-02 -:Copyright: GPL v2.0 -:Version: 2.5 -:Manual section: 1 -:Manual group: text processing +:Date: 2014-03-30 +:Copyright: GPL v2.0 +:Version: 2.5 +:Manual section: 1 +:Manual group: text processing SYNOPSIS ======================================================================= -**luaotfload-tool** [ -bDfFiIlnpquvVhw ] +**luaotfload-tool** [ -bcDfFiIlLnpqRSuvVhw ] **luaotfload-tool** --update [ --force ] [ --quiet ] [ --verbose ] [ --prefer-texmf ] [ --dry-run ] @@ -32,6 +32,8 @@ SYNOPSIS **luaotfload-tool** --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ] +**luaotfload-tool** --bisect=DIRECTIVE + **luaotfload-tool** --help **luaotfload-tool** --version @@ -187,6 +189,58 @@ font and lookup caches cache; 3) ``show`` -> print stats. +bisection +----------------------------------------------------------------------- +--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. + + *DIRECTIVE* can be one of the following: + + 1) ``run`` -> Make ``luaotfload-tool`` respect + the bisection progress when running. + Combined with ``--update`` and possibly + ``--force`` this will only process the files + from the start up until the pivot and ignore + the rest. + 2) ``start`` -> Start bisection: create a + bisection state file and initialize the low, + high, and pivot indices. + 3) ``stop`` -> Terminate the current bisection + session by deleting the state file. + 4) ``good`` | ``bad`` -> Mark the section + processed last as “good” or “bad”, + respectively. The next bisection step will + continue with the bad section. + 5) ``status`` -> Print status information about + the current bisection session. Hint: Use + with higher verbosity settings for more + output. + + A bisection session is initiated by issuing the + ``start`` directive. This sets the pivot to the + middle of the list of available font files. + Now run *luaotfload-tool* with the ``--update`` + flag set as well as ``--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 ``--bisect=bad``. + The next step of ``--bisect=run`` will continue + bisection with the part of the files below the + pivot. + Likewise, issue ``--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, ``good`` + or ``bad`` will have no effect anymore. ``run`` + will always end up processing the single font + file that was left. + Use ``--bisect=stop`` to clear the bisection + state. + miscellaneous ----------------------------------------------------------------------- --verbose=N, -v Set verbosity level to *n* or the number of |