Merge pull request #211 from phi-gamma/texlive2014

update documentation

3 files changed, 90 insertions, 37 deletions

diff --git a/doc/luaotfload-latex.tex b/doc/luaotfload-latex.tex
index 409adcf..c886462 100644
--- a/doc/luaotfload-latex.tex
+++ b/doc/luaotfload-latex.tex
@@ -208,12 +208,10 @@
 \usepackage {listings}
 \lstset {
   basicstyle=\ttfamily,
-  escapechar=Ö,
 }
 
-\def \inlinecode #1{%
-  \lstinline {#1}%
-}
+%\let \inlinecode \lstinline
+\protected \def \inlinecode {\lstinline}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% codelistings; this sucks hard since we lack access to buffers
diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 5b033c0..a0df7f0 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -754,15 +754,25 @@ Currently (2014) there are three of them:
   \endaltitem
 
   \beginaltitem {tlig}
-          Applies legacy \TEX ligatures:
+          Applies legacy \TEX ligatures\footnote{%
+            These contain the feature set \inlinecode {trep} of earlier
+            versions of \identifier{luaotfload}.
+
+            Note to \XETEX users: this is the equivalent of the
+            assignment \inlinecode {mapping=text-tex} using \XETEX's input
+            remapping feature.
+          }:
 
           \unless \ifcontextmkiv
+            %% Using braced arg syntax with inline code appears to be
+            %% impossible within Latex tables -- just ignore the weird
+            %% exclamation points below.
             \begintabulate [rlrl]
-              \beginrow ``  \newcell  \inlinecode {``}  \newcell  ''  \newcell  \inlinecode {''}  \endrow
-              \beginrow `   \newcell  \inlinecode {`}   \newcell  '   \newcell  \inlinecode {'}   \endrow
-              \beginrow "   \newcell  \inlinecode {"}   \newcell  --  \newcell  \inlinecode {--}  \endrow
-              \beginrow --- \newcell  \inlinecode {---} \newcell  !`  \newcell  \inlinecode {!`}  \endrow
-              \beginrow ?`  \newcell  \inlinecode {?`}  \newcell      \newcell                    \endrow
+              \beginrow ``  \newcell  {\inlinecode !``! } \newcell  ''  \newcell  {\inlinecode !''!} \endrow
+              \beginrow `   \newcell  {\inlinecode !`!  } \newcell  '   \newcell  {\inlinecode !'! } \endrow
+              \beginrow "   \newcell  {\inlinecode !"!  } \newcell  --  \newcell  {\inlinecode !--!} \endrow
+              \beginrow --- \newcell  {\inlinecode !---!} \newcell  !`  \newcell  {\inlinecode ?!`?} \endrow
+              \beginrow ?`  \newcell  {\inlinecode !?`! } \newcell      \newcell                     \endrow
             \endtabulate
           \else
             %% XXX find a way to wrap these in the tabulate environment
@@ -778,15 +788,6 @@ Currently (2014) there are three of them:
               \stopframed
             \stopframed
           \fi
-
-          \footnote{%
-            These contain the feature set \inlinecode {trep} of earlier
-            versions of \identifier{luaotfload}.
-
-            Note to \XETEX users: this is the equivalent of the
-            assignment \inlinecode {mapping=text-tex} using \XETEX's input
-            remapping feature.
-          }
   \endaltitem
 
   \beginaltitem {itlc}
@@ -911,7 +912,7 @@ directories.
       \begincentered
         \begintabulate [lp{.5\textwidth}]
           \beginrow
-            Windows   \newcell \inlinecode {\% WINDIR\%\\ Fonts}
+            Windows   \newcell \inlinecode !\% WINDIR\%\\ Fonts!
           \endrow
           \beginrow
             Linux     \newcell \fileent{/usr/local/etc/fonts/fonts.conf} and\hfill\break
diff --git a/doc/luaotfload-tool.rst b/doc/luaotfload-tool.rst
index 761b0ec..4b1a934 100644
--- a/doc/luaotfload-tool.rst
+++ b/doc/luaotfload-tool.rst
@@ -6,22 +6,22 @@
          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 ]
                              [ --formats=[+|-]EXTENSIONS ]
                              [ --no-compress ] [ --no-strip ]
-                             [ --local ]
+                             [ --local ] [ --max-fonts=N ]
 
 **luaotfload-tool** --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ]
                                     [ --no-reload ]
@@ -32,6 +32,8 @@ SYNOPSIS
 
 **luaotfload-tool** --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ]
 
+**luaotfload-tool** --bisect=DIRECTIVE
+
 **luaotfload-tool** --help
 
 **luaotfload-tool** --version
@@ -67,10 +69,6 @@ update mode
                         with every invocation of ``luaotfload-tool``.
 --no-reload, -n         Suppress auto-updates to the database (e.g.
                         when ``--find`` is passed an unknown name).
---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.
 --no-compress, -c       Do not filter the plain text version of the
                         font index through gzip. Useful for debugging
                         if your editor is built without zlib.
@@ -78,8 +76,6 @@ update mode
 --prefer-texmf, -p      Organize the file name database in a way so
                         that it prefer fonts in the *TEXMF* tree over
                         system fonts if they are installed in both.
---max-fonts=N           Process at most *N* font files, including fonts
-                        already indexed in the count.
 --formats=EXTENSIONS    Extensions of the font files to index.
                         Where *EXTENSIONS* is a comma-separated list of
                         supported file extensions (otf, ttf, ttc,
@@ -99,9 +95,6 @@ update mode
                            grow the database considerably and slow down
                            font indexing.
 
---dry-run, -D           Don’t load fonts, scan directories only.
-                        (For debugging file system related issues.)
-
 query mode
 -----------------------------------------------------------------------
 --find=NAME             Resolve a font name; this looks up <name> in
@@ -125,7 +118,6 @@ query mode
                         library (assumes ``-I``). Automatically enabled
                         if the verbosity level exceeds 2.
 
---show-blacklist, -b    Show blacklisted files (not directories).
 --list=CRITERION        Show entries, where *CRITERION* is one of the
                         following:
 
@@ -187,6 +179,68 @@ font and lookup caches
                            cache;
                         3) ``show``  -> print stats.
 
+debugging methods
+-----------------------------------------------------------------------
+--show-blacklist, -b    Show blacklisted files (not directories).
+--dry-run, -D           Don’t load fonts when updating the database;
+                        scan directories only.
+                        (For debugging file system related issues.)
+--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.
+--max-fonts=N           Process at most *N* font files, including fonts
+                        already indexed in the count.
+--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