[doc] document new “anon-sequence” option

2 files changed, 25 insertions, 5 deletions

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 90738de..05c3670 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -32,7 +32,7 @@
 \beginfrontmatter
 
   \setdocumenttitle  {The \identifier{luaotfload} package}
-  \setdocumentdate   {2016/04/21 v2.7}
+  \setdocumentdate   {2016/04/28 v2.7}
   \setdocumentauthor {Elie Roux · Khaled Hosny · Philipp Gesang\\
                       Home:    \hyperlink {https://github.com/lualatex/luaotfload}\\
                       Support: \email     {lualatex-dev@tug.org}}
@@ -363,9 +363,14 @@ However, they have a broader spectrum of possible interpretations:
 before anything else, \identifier{luaotfload} attempts to load a
 traditional \TEX Font Metric (\abbrev{tfm} or \abbrev{ofm}).
 %
-If this fails, it performs a \inlinecode {name:} lookup, which itself will
-fall back to a \inlinecode {file:} lookup if no database entry matches
-\meta{font name}.
+If this fails, it performs a \inlinecode {path:} lookup, which itself will
+fall back to a \inlinecode {file:} lookup.
+%
+Lastly, if none of the above succeeded, attempt to resolve the request as a
+\inlinecode {name:} lookup by searching the font index for \meta{font name}.
+%
+The behavior of this “anonymous” lookup is configurable, see the configuation
+manpage for details.
 
 Furthermore, \identifier{luaotfload} supports the slashed (shorthand)
 font style notation from \XETEX.
diff --git a/doc/luaotfload.conf.rst b/doc/luaotfload.conf.rst
index e7cbccb..3568909 100644
--- a/doc/luaotfload.conf.rst
+++ b/doc/luaotfload.conf.rst
@@ -6,7 +6,7 @@
                      Luaotfload configuration file
 -----------------------------------------------------------------------
 
-:Date:                  2016-04-21
+:Date:                  2016-04-28
 :Copyright:             GPL v2.0
 :Version:               2.7
 :Manual section:        5
@@ -271,6 +271,8 @@ Section ``run``
 +------------------+--------+------------------------------+
 |  variable        |  type  |  default                     |
 +------------------+--------+------------------------------+
+|  anon-sequence   |   s    |  ``"tex,path,name"``         |
++------------------+--------+------------------------------+
 |  color-callback  |   s    |  ``"post_linebreak_filter"`` |
 +------------------+--------+------------------------------+
 |  definer         |   s    |  ``"patch"``                 |
@@ -282,6 +284,19 @@ Section ``run``
 |  fontloader      |   s    |  ``"default"``               |
 +------------------+--------+------------------------------+
 
+Unqualified font lookups are treated with the flexible “anonymous”
+mechanism. This involves a chain of lookups applied successively until
+the first one yields a match. By default, the lookup will first search
+for TFM fonts using the Kpathsea library. If this wasn’t successful, an
+attempt is made at interpreting the request as an absolute path (like
+the ``[/path/to/font/foo.ttf]`` syntax) or a file name
+(``file:foo.ttf``). Finally, the request is interpreted as a font name
+and retrieved from the index (``name:Foo Regular``). This behavior can
+be configured by specifying a list as the value to ``anon-sequence``.
+Available items are ``tex``, ``path``, ``name`` -- representing the
+lookups described above, respectively --, and ``file`` for searching a
+filename but not an absolute path.
+
 The ``color-callback`` option determines the stage at which fonts that
 defined with a ``color=xxyyzz`` feature will be colorized. By default
 this happens in a ``post_linebreak_filter`` but alternatively the