From ad480924393fffa2896156e1a32c22f5c61120dd Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Sat, 11 Feb 2017 00:21:52 +0100
Subject: [PATCH] [doc] extend documentation of path lookups

---
 doc/luaotfload-main.tex | 49 ++++++++++++++++++++++++++++++++---------
 1 file changed, 38 insertions(+), 11 deletions(-)

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index b82c8d9b..21e001b2 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -240,6 +240,7 @@
       <name character>   ::= {\sc all_characters} - ( `(' | `/' | `:' ) ;
 \endsyntaxfloat
 
+%% Below guarded space gets borked in index; why‽
 \beginsubsection{Prefix -- the \identifier{luaotfload}{ }Way}
 
 In \identifier{luaotfload}, the canonical syntax for font requests
@@ -335,13 +336,12 @@
 
 \endsubsection
 
-\beginsubsection {Compatibility Layer}
-
-In addition to the regular prefixed requests, \identifier{luaotfload}
-accepts loading fonts the \XETEX way.
+\beginsubsection {Bracketed Lookups}
+\label{sec:conf}
+Bracketed lookups allow for arbitrary character content to be used in a
+definition.
 %
-There are again two modes: bracketed and unbracketed.
-A bracketed request looks as follows.
+A simple bracketed request looks follows the scheme
 
 \beginnarrower
   \nonproportional{\string\font\string\fontname\space = [}%
@@ -350,21 +350,41 @@
 \endnarrower
 
 \noindent
-Inside the square brackets, every character except for a closing
-bracket is permitted, allowing for specifying paths to a font file.
+Inside the square brackets, every character except for a closing bracket is
+permitted, allowing for  arbitrary paths to a font file -- including Windows
+style paths with UNC or drive letter prepended -- to be specified.
 %
+The \identifier{Luaotfload} syntax differs from \XETEX in that the subfont
+selector goes \emphasis{after} the closing bracket:
+
+\beginnarrower
+  \nonproportional{\string\font\string\fontname\space = [}%
+  \meta{/path/to/file}%
+  \nonproportional{]}
+  \nonproportional{(}n\nonproportional{)}
+\endnarrower
+
 Naturally, path-less file names are equally valid and processed the
 same way as an ordinary \inlinecode {file:} lookup.
 
+\beginsubsection {Compatibility}
+
+In addition to the regular prefixed requests, \identifier{luaotfload}
+accepts loading fonts the \XETEX way.
+%
+There are again two modes: bracketed and unbracketed.
+For the bracketed variety, see above, \ref{sec:conf}.
+
+Unbracketed (or, for lack of a better word: \emphasis{anonymous})
+font requests resemble the conventional \TEX syntax.
+
 \beginnarrower
   \nonproportional{\string\font\string\fontname\space= }%
   \meta{font name}
   \dots
 \endnarrower
+\endsubsection
 
-Unbracketed (or, for lack of a better word: \emphasis{anonymous})
-font requests resemble the conventional \TEX syntax.
-%
 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}).
@@ -443,6 +463,13 @@
   \font \cambriamath = "file:cambria.ttc(1)" at 10pt
 \endlisting
 
+and likewise, requesting subfont inside a TTC container by path:
+
+\beginlisting
+  \font \asanamain = "[/home/typesetter/.fonts/math/asana.ttc](0):mode=node;+tlig" at 10pt
+  \font \asanamath = "[/home/typesetter/.fonts/math/asana.ttc](1):mode=base" at 10pt
+\endlisting
+
 \endsubsubsection
 
 \beginsubsubsection{Loading by Font Name}