Merge pull request #228 from phi-gamma/master

merge version 2.5 (texlive2014) into master

1 files changed, 325 insertions, 0 deletions

diff --git a/doc/luaotfload-tool.rst b/doc/luaotfload-tool.rst
new file mode 100644
index 0000000..4b1a934
--- /dev/null
+++ b/doc/luaotfload-tool.rst
@@ -0,0 +1,325 @@
+=======================================================================
+                            luaotfload-tool
+=======================================================================
+
+-----------------------------------------------------------------------
+         generate and query the Luaotfload font names database
+-----------------------------------------------------------------------
+
+:Date:                  2014-03-30
+:Copyright:             GPL v2.0
+:Version:               2.5
+:Manual section:        1
+:Manual group:          text processing
+
+SYNOPSIS
+=======================================================================
+
+**luaotfload-tool** [ -bcDfFiIlLnpqRSuvVhw ]
+
+**luaotfload-tool** --update [ --force ] [ --quiet ] [ --verbose ]
+                             [ --prefer-texmf ] [ --dry-run ]
+                             [ --formats=[+|-]EXTENSIONS ]
+                             [ --no-compress ] [ --no-strip ]
+                             [ --local ] [ --max-fonts=N ]
+
+**luaotfload-tool** --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ]
+                                    [ --no-reload ]
+
+**luaotfload-tool** --flush-lookups
+
+**luaotfload-tool** --cache=DIRECTIVE
+
+**luaotfload-tool** --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ]
+
+**luaotfload-tool** --bisect=DIRECTIVE
+
+**luaotfload-tool** --help
+
+**luaotfload-tool** --version
+
+**luaotfload-tool** --show-blacklist
+
+**luaotfload-tool** --diagnose=CHECK
+
+DESCRIPTION
+=======================================================================
+
+luaotfload-tool accesses the font names database that is required by
+the *Luaotfload* package. There are two general modes: **update** and
+**query**.
+
++ **update**:  update the database or rebuild it entirely;
++ **query**:   resolve a font name or display close matches.
+
+OPTIONS
+=======================================================================
+
+update mode
+-----------------------------------------------------------------------
+--update, -u            Update the database; indexes new fonts.
+--force, -f             Force rebuilding of the database; re-indexes
+                        all fonts.
+--local, -L             Include font files in ``$PWD``. 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 ``luaotfload-tool``.
+--no-reload, -n         Suppress auto-updates to the database (e.g.
+                        when ``--find`` is passed an unknown name).
+--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.
+
+--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.
+--formats=EXTENSIONS    Extensions of the font files to index.
+                        Where *EXTENSIONS* is a comma-separated list of
+                        supported file extensions (otf, ttf, ttc,
+                        dfont, pfa, and pfb).  If the list is prefixed
+                        with a ``+`` sign, the given list is added to
+                        the currently active one; ``-`` subtracts.
+                        Default: *otf,ttf,ttc,dfont*.
+                        Examples:
+
+                        1) ``--formats=-ttc,ttf`` would skip
+                           TrueType fonts and font collections;
+                        2) ``--formats=otf`` would scan only OpenType
+                           files;
+                        3) ``--formats=+pfb`` includes binary
+                           Postscript files. **Warning**: with a
+                           standard TeX Live installation this will
+                           grow the database considerably and slow down
+                           font indexing.
+
+query mode
+-----------------------------------------------------------------------
+--find=NAME             Resolve a font name; this looks up <name> in
+                        the database and prints the file name it is
+                        mapped to.
+                        ``--find`` also understands request syntax,
+                        i.e. ``--find=file:foo.otf`` checks whether
+                        ``foo.otf`` is indexed.
+--fuzzy, -F             Show approximate matches to the file name if
+                        the lookup was unsuccessful (requires
+                        ``--find``).
+
+--info, -i              Display basic information to a resolved font
+                        file (requires ``--find``).
+--inspect, -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 ``--find``).
+--warnings, -w          Print the warnings generated by the fontloader
+                        library (assumes ``-I``). Automatically enabled
+                        if the verbosity level exceeds 2.
+
+--list=CRITERION        Show entries, where *CRITERION* is one of the
+                        following:
+
+                        1) the character ``*``, selecting all entries;
+                        2) a field of a database entry, for instance
+                           *version* or *format**, according to which
+                           the output will be sorted.
+                           Information in an unstripped database (see
+                           the option ``--no-strip`` above) is nested:
+                           Subfields of a record can be addressed using
+                           the ``->`` separator, e. g.
+                           ``file->location``, ``style->units_per_em``,
+                           or
+                           ``names->sanitized->english->prefmodifiers``.
+                           NB: shell syntax requires that arguments
+                           containing ``->`` be properly quoted!
+                        3) an expression of the form ``field:value`` to
+                           limit the output to entries whose ``field``
+                           matches ``value``.
+
+                        For example, in order to output file names and
+                        corresponding versions, sorted by the font
+                        format::
+
+                            ./luaotfload-tool.lua --list="format" --fields="file->base,version"
+
+                        This prints::
+
+                            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
+                            ...
+
+--fields=FIELDS         Comma-separated list of fields that should be
+                        printed.
+                        Information in an unstripped database (see the
+                        option ``--no-strip`` above) is nested:
+                        Subfields of a record can be addressed using
+                        the ``->`` separator, e. g.
+                        ``file->location``, ``style->units_per_em``,
+                        or ``names->sanitized->english->subfamily``.
+                        The default is plainname,version*.
+                        (Only meaningful with ``--list``.)
+
+font and lookup caches
+-----------------------------------------------------------------------
+--flush-lookups         Clear font name lookup cache (experimental).
+
+--cache=DIRECTIVE       Cache control, where *DIRECTIVE* is one of the
+                        following:
+
+                        1) ``purge`` -> delete Lua files from cache;
+                        2) ``erase`` -> delete Lua and Luc files from
+                           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
+                        repetitions of ``-v``.
+--quiet                 No verbose output (log level set to zero).
+--log=CHANNEL           Redirect log output (for database
+                        troubleshooting), where *CHANNEL* can be
+
+                        1) ``stdout`` -> all output will be
+                           dumped to the terminal (default); or
+                        2) ``file`` -> write to a file to the temporary
+                           directory (the name will be chosen
+                           automatically.
+
+--version, -V           Show version numbers of components as well as
+                        some basic information and exit.
+--help, -h              Show help message and exit.
+
+--diagnose=CHECK        Run the diagnostic procedure *CHECK*. Available
+                        procedures are:
+
+                        1) ``files`` -> check *Luaotfload* files for
+                           modifications;
+                        2) ``permissions`` -> check permissions of
+                           cache directories and files;
+                        3) ``environment`` -> print relevant
+                            environment and kpse variables;
+                        4) ``repository`` -> check the git repository
+                           for new releases,
+                        5) ``index`` -> check database, display
+                           information about it.
+
+                        Procedures can be chained by concatenating with
+                        commas, e.g. ``--diagnose=files,permissions``.
+                        Specify ``thorough`` to run all checks.
+
+FILES
+=======================================================================
+
+The font name database is usually located in the directory
+``texmf-var/luatex-cache/generic/names/`` (``$TEXMFCACHE`` as set in
+``texmf.cnf``) of your *TeX Live* distribution as a zlib-compressed
+file ``luaotfload-names.lua.gz``.
+The experimental lookup cache will be created as
+``luaotfload-lookup-cache.lua`` 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 ``.luc`` 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 *LuaTeX*.
+
+SEE ALSO
+=======================================================================
+
+**luatex** (1), **lua** (1)
+
+* ``texdoc luaotfload`` to display the manual for the *Luaotfload*
+  package
+* Luaotfload development `<https://github.com/lualatex/luaotfload>`_
+* LuaLaTeX mailing list  `<http://tug.org/pipermail/lualatex-dev/>`_
+* LuaTeX                 `<http://luatex.org/>`_
+* ConTeXt                `<http://wiki.contextgarden.net>`_
+* Luaotfload on CTAN     `<http://ctan.org/pkg/luaotfload>`_
+
+BUGS
+=======================================================================
+
+Tons, probably.
+
+AUTHORS
+=======================================================================
+
+*Luaotfload* is maintained by the LuaLaTeX dev team
+(`<https://github.com/lualatex/>`__).
+The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt
+NL (`<http://pragma-ade.com/>`__).
+
+This manual page was written by Philipp Gesang
+<philipp.gesang@alumni.uni-heidelberg.de>.
+