[doc] describe the various font requests

1 files changed, 145 insertions, 39 deletions

diff --git a/luaotfload.dtx b/luaotfload.dtx
index 957dea1..abc737c 100644
--- a/luaotfload.dtx
+++ b/luaotfload.dtx
@@ -130,6 +130,8 @@ and the derived files
 \setsansfont[Ligatures=TeX,Scale=MatchLowercase]{Iwona Medium}
 %setmathfont{XITS Math}
 
+\usepackage{hologo}
+
 \newcommand\TEX     {\TeX\xspace}
 \newcommand\LUA     {Lua\xspace}
 \newcommand\PDFTEX  {pdf\TeX\xspace}
@@ -246,15 +248,15 @@ and the derived files
 %
 % \section{Loading Fonts}
 %
-% \identifier{luaotfload} supports an extended font loading syntax:
+% \identifier{luaotfload} supports an extended font request syntax:
 %
-% \begin{center}
+% \begin{quote}
 %       |\font\foo={|%
 %       \meta{prefix}|:|%
 %       \meta{font name}|:|%
 %       \meta{font features}|}|%
 %       \meta{\TEX font features}
-% \end{center}
+% \end{quote}
 %
 % \noindent
 % The curly brackets are optional and escape the spaces in the enclosed
@@ -330,45 +332,93 @@ and the derived files
 %   \label{font-syntax}
 % \end{figure}
 %
-% %(* braces around the specification will preserve whitespace *)
-% %(* file lookups do not allow paths *)
-% %(* others like `aat', `icu', and `gr' are silently ignored *)
-%
-% \paragraph{Prefix}
-%
-% The \meta{prefix} is either |file:| or |name:|.
-% It determines whether the font loader should interpret the request as a
-% file name or font name, respectively, which again influences how it
-% will attempt to locate the font.
-% The prefix can be omitted, in which case |name:| is assumed.
-%
-%% \iffalse%% how am i supposed to friggin comment stuff in a dtx???
-%%      TODO
-%%      it would appear that the next paragraph is incorrect; I get
-%%      name: lookups regardless unless the font file is actually
-%%      in CWD
-%% \fi
-%% For compatibility with \XETEX, surrounding the \meta{font name} with
-%% square brackets is synonymous to using the |file:| prefix.
+% \subsection{Prefix -- the \identifier{luaotfload}\space Way}
 %
+% In \identifier{luaotfload}, the canonical syntax for font requests
+% requires a \emphasis{prefix}:
+% \begin{quote}
+%   |\font\fontname=|\meta{prefix}|:|\meta{fontname}\dots
+% \end{quote}
+% where \meta{prefix} is either \verb|file:| or \verb|name:|.
+% It determines whether the font loader should interpret the request as
+% a \emphasis{file name} or
+%   \emphasis{font name}, respectively,
+% which again influences how it will attempt to locate the font.
+% Examples for font names are
+%             “Latin Modern Italic”,
+%             “GFS Bodoni Rg”, and
+%             “PT Serif Caption”
+% -- they are the human readable identifiers
+% usually listed in drop-down menus and the like.
 % In order for fonts installed both in system locations and in your
 % \fileent{texmf} to be accessible by font name, \identifier{luaotfload} must
 % first collect the metadata included in the files.
-% Please refer to section ~\ref{sec:fontdb} below for instructions on how to
+% Please refer to section~\ref{sec:fontdb} below for instructions on how to
 % create the database.
 %
-% \paragraph{Font name}
+% File names are whatever your file system allows them to be, except
+% that that they may not contain the characters
+%                             \verb|(|,
+%                             \verb|:|, and
+%                             \verb|/|.
+% As obvious from the last exception, the \verb|file:| lookup will 
+% not process paths to the font location -- only those
+% files found when generating the database are addressable this way.
+% Continue below in the \XETEX section if you need to load your fonts
+% by path.
+% The file names corresponding to the example font names above are
+%           \fileent{lmroman12-italic.otf},
+%           \fileent{GFSBodoni.otf}, and
+%           \fileent{PTZ56F.ttf}.
+%
+% \subsection{\hologo{XeTeX} Compatibility Layer}
+%
+% In addition to the regular prefixed requests, \identifier{luaotfload}
+% accepts loading fonts the \XETEX way.
+% There are again two modes: bracketed and unbracketed.
+% A bracketed request looks as follows.
 %
-% The \meta{font name} can be either a font filename or actual font
-% name based on the \meta{prefix} as mentioned above.
+% \begin{quote}
+%   |\font\fontname=[|\meta{path to file}|]|
+% \end{quote}
 %
-% A filename request may optionally include the absolute path to the font file,
-% allowing for fonts outside the standard locations to be loaded as well.
-% If no path is specified, then \identifier{kpathsea} is used to locate the
-% font (which will typically be in the \fileent{texmf} tree or the
-% current directory).
+% \noindent
+% Inside the square brackets, every character except for a closing
+% bracket is permitted, allowing for specifying paths to a font file.
+% Naturally, path-less file names are equally valid and processed the
+% same way as an ordinary \verb|file:| lookup.
 %
-% \subparagraph{Examples for loading by file name}
+% \begin{quote}
+%   |\font\fontname=|\meta{font name} \dots
+% \end{quote}
+%
+% 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}).
+% If this fails, it performs a \verb|name:| lookup, which itself will
+% fall back to a \verb|file:| lookup if no database entry matches
+% \meta{font name}.
+%
+% Furthermore, \identifier{luaotfload} supports the slashed (shorthand)
+% font style notation from \XETEX.
+%
+% \begin{quote}
+%   |\font\fontname=|\meta{font name}|/|\meta{modifier}\dots
+% \end{quote}
+%
+% \noindent
+% Currently, four style modifiers are supported:
+%   \verb|i| for italic shape,
+%   \verb|b| for bold   weight,
+%   \verb|bi| or \verb|ib| for the combination of both.
+% Other “slashed” modifiers are too specific to the \XETEX engine and
+% have no meaning in \LUATEX.
+%
+% \subsection{Examples}
+%
+% \subsubsection{Loading by File Name}
 %
 % For example, conventional \abbrev{type1} font can be loaded with a \verb|file:|
 % request like so:
@@ -380,8 +430,11 @@ and the derived files
 % \end{quote}
 %
 % The \OpenType version of Janusz Nowacki’s font \emphasis{Antykwa
-% Półtawskiego} (in \TEX Live) in its condensed variant can be loaded as
-% follows:
+% Półtawskiego}\footnote{%
+%   \url{http://jmn.pl/antykwa-poltawskiego/}, also available in
+%   in \TEX Live.
+% }
+% in its condensed variant can be loaded as follows:
 %
 % \begin{quote}
 %   \begin{verbatim}
@@ -399,7 +452,7 @@ and the derived files
 %   \end{verbatim}
 % \end{quote}
 %
-% \subparagraph{Examples for loading by font name}
+% \subsubsection{Loading by Font Name}
 %
 % The \verb|name:| lookup does not depend on cryptic filenames:
 %
@@ -435,9 +488,62 @@ and the derived files
 %   \end{verbatim}
 % \end{quote}
 %
-% \paragraph{Font features}
+% \subsubsection{Modifiers}
+%
+% If the entire \emphasis{Iwona} family\footnote{%
+%   \url{http://jmn.pl/kurier-i-iwona/},
+%   also in \TEX Live.
+% }
+% is installed in some location accessible by \identifier{luaotfload},
+% the regular shape can be loaded as follows:
+%
+% \begin{quote}
+%   \begin{verbatim}
+%   \font\iwona=Iwona at 20pt
+%   \end{verbatim}
+% \end{quote}
+%
+% \noindent
+% To load the most common of the other styles, the slash notation can
+% be employed as shorthand:
+%
+% \begin{quote}
+%   \begin{verbatim}
+%   \font\iwonaitalic    =Iwona/i    at 20pt
+%   \font\iwonabold      =Iwona/b    at 20pt
+%   \font\iwonabolditalic=Iwona/bi   at 20pt
+%   \end{verbatim}
+% \end{quote}
+%
+% \noindent
+% which is equivalent to these full names:
+%
+% \begin{quote}
+%   \begin{verbatim}
+%   \font\iwonaitalic    ="Iwona Italic"       at 20pt
+%   \font\iwonabold      ="Iwona Bold"         at 20pt
+%   \font\iwonabolditalic="Iwona BoldItalic"   at 20pt
+%   \end{verbatim}
+% \end{quote}
+%
+% \section{Font features}
+%
+% \emphasis{Font features} are the second to last component in the
+% general scheme for font requests:
+%
+% \begin{quote}
+%       |\font\foo={|%
+%       \meta{prefix}|:|%
+%       \meta{font name}|:|%
+%       \meta{font features}|}|%
+%       \meta{\TEX font features}
+% \end{quote}
+%
+% \noindent
+% If style modifiers are present (\XETEX style), they must precede \meta{font
+% features}.
 %
-% \meta{font features} is semicolon-separated list of feature
+% The element \meta{font features} is a semicolon-separated list of feature
 % tags\footnote{%
 %   Cf. \url{http://www.microsoft.com/typography/otspec/featurelist.htm}.
 % }
@@ -1078,7 +1184,7 @@ luaotfload.prefer_merge     = config.luaotfload.prefer_merge or true
 luaotfload.module = {
     name          = "luaotfload",
     version       = 2.2,
-    date          = "2013/04/15",
+    date          = "2013/04/29",
     description   = "OpenType layout system.",
     author        = "Elie Roux & Hans Hagen",
     copyright     = "Elie Roux",