From 56188a1cc038c94defb8102bfd4926482b25ffb7 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg42.2a@gmail.com>
Date: Sun, 21 Apr 2013 01:12:08 +0200
Subject: document behavior modes of fontdbutil

---
 luaotfload.dtx | 44 ++++++++++++++++++++++++++++++--------------
 1 file changed, 30 insertions(+), 14 deletions(-)

(limited to 'luaotfload.dtx')

diff --git a/luaotfload.dtx b/luaotfload.dtx
index 45436a8..06541f6 100644
--- a/luaotfload.dtx
+++ b/luaotfload.dtx
@@ -585,8 +585,9 @@ and the derived files
 % This is particularly noticeable if it occurs during a typesetting run.
 % In any case, subsequent updates to the database will be quite fast.
 %
-% \subsection[mkluatexfontdb.lua]%
-%            {\fileent{mkluatexfontdb.lua}\footnote{%
+% \subsection[fontdbutil / mkluatexfontdb.lua]%
+%            {\fileent{fontdbutil} /
+%             \fileent{mkluatexfontdb.lua}\footnote{%
 %   The script may be named just \fileent{mkluatexfontdb} in your
 %   distribution.
 % }}
@@ -594,7 +595,7 @@ and the derived files
 % It can still be desirable at times to do some of these steps
 % manually, and without having to compile a document.
 % To this end, \identifier{luaotfload} comes with the utility
-% \fileent{mkluatexfontdb} that offers an interface to the database
+% \fileent{fontdbutil} that offers an interface to the database
 % functionality.
 % Being a \LUA script, there are two ways to run it:
 % either make it executable (\verb|chmod +x| on unixoid systems) or
@@ -609,18 +610,33 @@ and the derived files
 %   \emphasis{Note}:
 %   On \abbrev{MS} \identifier{Windows} systems, the script can be run
 %   either by calling the wrapper application
-%   \fileent{mkluatexfontdb.exe} or as
-%   \verb|texlua.exe mkluatexfontdb.lua|.
+%   \fileent{fontdbutil.exe} or as
+%   \verb|texlua.exe fontdbutil|.
 % }
-% Invoke it from the command line with the \verb|--force| switch to
-% initiate a complete rebuild of the database.
+% Invoked with the argument \verb|--update| it will perform a database
+% update, scanning for fonts not indexed.
 %
 % \begin{quote}
 %   \begin{verbatim}
-%     mkluatexfontdb --force
+%     fontdbutil --update
 %   \end{verbatim}
 % \end{quote}
 %
+% Adding the \verb|--force| switch will initiate a complete
+% rebuild of the database.
+%
+% \begin{quote}
+%   \begin{verbatim}
+%     fontdbutil --update --force
+%   \end{verbatim}
+% \end{quote}
+%
+% For sake of backwards compatibility, \fileent{fontdbutil} may be
+% renamed or symlinked to \fileent{mkluatexfontdb}.
+% Whenever it is run under this name, it will update the database
+% first, mimicking the behavior of earlier versions of
+% \identifier{luaotfload}.
+%
 % \subsection{Search Paths}
 %
 % \identifier{luaotfload} scans those directories where fonts are
@@ -663,7 +679,7 @@ and the derived files
 %
 % \subsection{Querying from Outside}
 %
-% \fileent{mkluatexfontdb.lua} also provides rudimentary means of
+% \fileent{fontdbutil} also provides rudimentary means of
 % accessing the information collected in the font database.
 % If the option \verb|--find=|\emphasis{name} is given, the script will
 % try and search the fonts indexed by \identifier{luaotfload} for a
@@ -672,7 +688,7 @@ and the derived files
 %
 % \begin{quote}
 %   \begin{verbatim}
-%     mkluatexfontdb.lua  --find="Iwona Regular"
+%     fontdbutil  --find="Iwona Regular"
 %   \end{verbatim}
 % \end{quote}
 %
@@ -688,14 +704,14 @@ and the derived files
 %
 % \begin{quote}
 %   \begin{verbatim}
-%     mkluatexfontdb.lua  -F --find="Iwona Bright"
+%     fontdbutil  -F --find="Iwona Bright"
 %   \end{verbatim}
 % \end{quote}
 %
 % \noindent
 % will tell you that indeed the latter name is correct.
 %
-% \verb|mkluatexfontdb.lua --help| will list the available command line
+% \verb|fontdbutil --help| will list the available command line
 % switches, including some not discussed in detail here.
 %
 % \subsection{Blacklisting Fonts}
@@ -704,7 +720,7 @@ and the derived files
 % Some fonts are problematic in general, or just in \LUATEX.
 % If you find that compiling your document takes far too long or eats
 % away all your system’s memory, you can track down the culprit by
-% running \verb|mkluatexfontdb -v| to increase verbosity.
+% running \verb|fontdbutil -v| to increase verbosity.
 % Take a note of the \emphasis{filename} of the font that database
 % creation fails with and append it to the file
 % \fileent{otfl-blacklist.cnf}.
@@ -901,7 +917,7 @@ and the derived files
 % verbosity levels and redirecting log output to \fileent{stdout}:
 %
 % \begin{verbatim}
-%   mkluatexfontdb.lua -F -vvv --log=stdout
+%   fontdbutil -F -vvv --log=stdout
 % \end{verbatim}
 %
 % If this fails, the font last printed to the terminal is likely to be
-- 
cgit v1.2.3