Misc. documentation fixes

And update the mode section to reflect current defaults.

1 files changed, 84 insertions, 87 deletions

diff --git a/luaotfload.dtx b/luaotfload.dtx
index a1cd68d..0308865 100644
--- a/luaotfload.dtx
+++ b/luaotfload.dtx
@@ -107,6 +107,7 @@ and the derived files
   [2011/02/16 v1.24 OpenType layout system]%
 \documentclass{ltxdoc}
 \usepackage{metalogo,multicol,mdwlist,fancyvrb,xcolor,xspace}
+\usepackage{lmodern}
 \usepackage{charter}
 \usepackage[
   bookmarks=true,
@@ -212,12 +213,12 @@ and the derived files
 %
 % \paragraph{Prefix}
 %
-% The \meta{prefix} be either \texttt{file:} or \texttt{name:}, which specify
+% The \meta{prefix} be either |file:| or |name:|, which specify
 % whether to use a select the font from its filename or font name,
-% respectively. If no prefix is specified, then \texttt{file:} is assumed.
+% respectively. If no prefix is specified, then |file:| is assumed.
 %
 % For compatibility with \xetex, surrounding the \meta{font name}
-% with square brackets is synonymous to using the \texttt{file:} prefix.
+% with square brackets is synonymous to using the |file:| prefix.
 %
 % Accessing fonts by fontname allows loading system installed fonts as well as
 % \textsc{texmf} ones, and requires a font names database; see
@@ -253,20 +254,16 @@ and the derived files
 % The supported keys are:
 % \begin{description}
 % \item [mode] \hfill \\
-% \textsf{luaotfload} has two OpenType processing modes;
-% \texttt{base} or \texttt{node}.
-% Using \texttt{mode=base}
-% only supports a subset of OpenType features and works by mapping those
-% features to traditional \tex ligature and kerning mechanisms and is a bit
-% faster
-% Using \texttt{mode=node} hopefully supports OpenType fully and
-% works by direct processing of the node list with Lua; it is slower and
-% is not designed to work in math mode.
-%
-% By default \texttt{mode=base} is used, but it is advisable to always
-% enable \texttt{node} made, except for math fonts, otherwise many OpenType
-% features will not function properly or even not work at all, especially for
-% advanced scripts like Arabic.
+% \textsf{luaotfload} has two OpenType processing modes; |base| and
+% |node|. |base| mode works mapping those features to traditional
+% \tex ligature and kerning mechanisms and thus supports only a subset of
+% OpenType features but is a bit faster and is the only processing mode
+% supports in math mode. |node| works by direct processing of the node
+% list at Lua end and have more wide support of OpenType features but is a bit
+% slower.
+%
+% By default |node| mode is used, and you have to manually force
+% |base| mode when needed e.g. for math fonts.
 %
 % \item [script] \hfill \\
 % OpenType script string, default value is |dflt|. Some fonts don't assign
@@ -300,7 +297,7 @@ and the derived files
 % Both keys control microtypographic features of the font, namely glyph
 % protrusion and expansion. The value of the key is the name of predefined
 % Lua tables of protrusion and expansion values; see the end of
-% \texttt{otfl-font-dum.lua} file for an example of such tables. The only
+% |otfl-font-dum.lua| file for an example of such tables. The only
 % predefined value is |default|.
 %
 % For example, to enable default protrusion\footnote{You also need to set
@@ -316,14 +313,14 @@ and the derived files
 % OpenType, currently three features are defined:
 %
 % \begin{itemize*}
-% \item \texttt{anum}: replaces European numbers with eastern Arabic numbers or
+% \item |anum|: replaces European numbers with eastern Arabic numbers or
 % Persian numbers, depending on the value of |language|.
-% \item \texttt{tlig}: applies legacy \tex ligatures (|``''-- -- !` ?` <<>>|).
-% \item \texttt{trep}: applies legacy \tex replacements (|`'"|).
+% \item |tlig|: applies legacy \tex ligatures (|``''-- -- !` ?` <<>>|).
+% \item |trep|: applies legacy \tex replacements (|`'"|).
 % \end{itemize*}
 %
 % (For \xetex users: these last two are the equivalent of writing
-%  \texttt{mapping=text-tex} using \xetex's input remapping feature.)
+%  |mapping=text-tex| using \xetex's input remapping feature.)
 %
 %
 % \section{Font names database}
@@ -389,39 +386,39 @@ and the derived files
 % taken from \context as far as possible, but we changed their names to
 % prevent name clashes.
 %
-% The \context files are renamed by adding the prefix \texttt{otfl-} to them
-% (\texttt{otfl} as \texttt{OTF L}oad). The files are:
+% The \context files are renamed by adding the prefix |otfl-| to them
+% (|otfl| as |OTF L|oad). The files are:
 %
 % \begin{multicols}{3}
 % \begin{itemize*}
-% \item \texttt{luat-dum.lua}
-% \item \texttt{data-con.lua}
-% \item \texttt{node-inj.lua}
-% \item \texttt{node-dum.lua}
-% \item \texttt{font-ini.lua}
-% \item \texttt{font-tfm.lua}
-% \item \texttt{font-cid.lua}
-% \item \texttt{font-ott.lua}
-% \item \texttt{font-otf.lua}
-% \item \texttt{font-otd.lua}
-% \item \texttt{font-oti.lua}
-% \item \texttt{font-otb.lua}
-% \item \texttt{font-otn.lua}
-% \item \texttt{font-ota.lua}
-% \item \texttt{font-otc.lua}
-% \item \texttt{font-def.lua}
-% \item \texttt{font-xtx.lua}
-% \item \texttt{font-map.lua}
-% \item \texttt{font-dum.lua}
+% \item |luat-dum.lua|
+% \item |data-con.lua|
+% \item |node-inj.lua|
+% \item |node-dum.lua|
+% \item |font-ini.lua|
+% \item |font-tfm.lua|
+% \item |font-cid.lua|
+% \item |font-ott.lua|
+% \item |font-otf.lua|
+% \item |font-otd.lua|
+% \item |font-oti.lua|
+% \item |font-otb.lua|
+% \item |font-otn.lua|
+% \item |font-ota.lua|
+% \item |font-otc.lua|
+% \item |font-def.lua|
+% \item |font-xtx.lua|
+% \item |font-map.lua|
+% \item |font-dum.lua|
 % \end{itemize*}
 % \end{multicols}
 %
 % The following files have been written for this package:
 % \begin{multicols}{3}
 % \begin{itemize*}
-% \item \texttt{font-clr.lua}
-% \item \texttt{font-nms.lua}
-% \item \texttt{luat-ovr.lua}
+% \item |font-clr.lua|
+% \item |font-nms.lua|
+% \item |luat-ovr.lua|
 % \end{itemize*}
 % \end{multicols}
 %
@@ -451,7 +448,7 @@ and the derived files
 %    First some usual initializations.
 %
 %    \begin{macrocode}
-module('luaotfload', package.seeall)
+module("luaotfload", package.seeall)
 
 luaotfload.module = {
     name          = "luaotfload",
@@ -473,7 +470,7 @@ local error, warning, info, log = luatexbase.provides_module(luaotfload.module)
 %    fine even if |\pdfpkresolution| is changed.
 %
 %    \begin{macrocode}
-kpse.init_prog('', 600, '/')
+kpse.init_prog("", 600, "/")
 %    \end{macrocode}
 %
 %    The minimal required \luatex version.
@@ -482,7 +479,7 @@ kpse.init_prog('', 600, '/')
 local luatex_version = 60
 
 if tex.luatexversion < luatex_version then
-    warning('LuaTeX v%.2f is old, v%.2f is recommended.',
+    warning("LuaTeX v%.2f is old, v%.2f is recommended.",
              tex.luatexversion/100,
              luatex_version   /100)
 end
@@ -491,18 +488,18 @@ end
 % \subsection{Module loading}
 %
 %    We load the \context files with this function. It automatically adds the
-%    \texttt{otfl-} prefix to it, so that we call it with the actual \context
+%    |otfl-| prefix to it, so that we call it with the actual \context
 %    name.
 %
 %    \begin{macrocode}
 function luaotfload.loadmodule(name)
-    local tofind = 'otfl-'..name
+    local tofind = "otfl-"..name
     local found = kpse.find_file(tofind,"tex")
     if found then
-        log('loading file %s.', found)
+        log("loading file %s.", found)
         dofile(found)
     else
-        error('file %s not found.', tofind)
+        error("file %s not found.", tofind)
     end
 end
 %    \end{macrocode}
@@ -512,12 +509,12 @@ end
 %    low-level \context functions.
 %
 %    \begin{macrocode}
-luaotfload.loadmodule('luat-dum.lua') -- not used in context at all
-luaotfload.loadmodule('luat-ovr.lua') -- override some luat-dum functions
-luaotfload.loadmodule('data-con.lua') -- maybe some day we don't need this one
+luaotfload.loadmodule("luat-dum.lua") -- not used in context at all
+luaotfload.loadmodule("luat-ovr.lua") -- override some luat-dum functions
+luaotfload.loadmodule("data-con.lua") -- maybe some day we don't need this one
 %    \end{macrocode}
 %
-%    A hack to remove a warning from \texttt{node-dum.lua} as it is \context
+%    A hack to remove a warning from |node-dum.lua| as it is \context
 %    specific.
 %
 %    \begin{macrocode}
@@ -527,9 +524,9 @@ tex.attribute[0] = 0
 %    Node support modules.
 %
 %    \begin{macrocode}
-luaotfload.loadmodule('font-ini.lua')
-luaotfload.loadmodule('node-dum.lua')
-luaotfload.loadmodule('node-inj.lua')
+luaotfload.loadmodule("font-ini.lua")
+luaotfload.loadmodule("node-dum.lua")
+luaotfload.loadmodule("node-inj.lua")
 %    \end{macrocode}
 %
 %    By default \context takes some private attributes for internal use. To
@@ -540,7 +537,7 @@ luaotfload.loadmodule('node-inj.lua')
 %
 %    \begin{macrocode}
 function attributes.private(name)
-    local attr   = 'otfl@' .. name
+    local attr   = "otfl@" .. name
     local number = luatexbase.attributes[attr]
     if not number then
         number = luatexbase.new_attribute(attr)
@@ -552,20 +549,20 @@ end
 %    Font handling modules.
 %
 %    \begin{macrocode}
-luaotfload.loadmodule('font-tfm.lua')
-luaotfload.loadmodule('font-cid.lua')
-luaotfload.loadmodule('font-ott.lua')
-luaotfload.loadmodule('font-map.lua')
-luaotfload.loadmodule('font-otf.lua')
-luaotfload.loadmodule('font-otd.lua')
-luaotfload.loadmodule('font-oti.lua')
-luaotfload.loadmodule('font-otb.lua')
-luaotfload.loadmodule('font-otn.lua')
-luaotfload.loadmodule('font-ota.lua')
-luaotfload.loadmodule('font-otc.lua')
-luaotfload.loadmodule('font-def.lua')
-luaotfload.loadmodule('font-xtx.lua')
-luaotfload.loadmodule('font-dum.lua')
+luaotfload.loadmodule("font-tfm.lua")
+luaotfload.loadmodule("font-cid.lua")
+luaotfload.loadmodule("font-ott.lua")
+luaotfload.loadmodule("font-map.lua")
+luaotfload.loadmodule("font-otf.lua")
+luaotfload.loadmodule("font-otd.lua")
+luaotfload.loadmodule("font-oti.lua")
+luaotfload.loadmodule("font-otb.lua")
+luaotfload.loadmodule("font-otn.lua")
+luaotfload.loadmodule("font-ota.lua")
+luaotfload.loadmodule("font-otc.lua")
+luaotfload.loadmodule("font-def.lua")
+luaotfload.loadmodule("font-xtx.lua")
+luaotfload.loadmodule("font-dum.lua")
 %    \end{macrocode}
 %
 %    This is a patch for |otfl-font-def.lua|, that defines a reader for ofm
@@ -581,8 +578,8 @@ end
 %    \textsf{luaotfload} specific modules.
 %
 %    \begin{macrocode}
-luaotfload.loadmodule('font-nms.lua')
-luaotfload.loadmodule('font-clr.lua')
+luaotfload.loadmodule("font-nms.lua")
+luaotfload.loadmodule("font-clr.lua")
 %    \end{macrocode}
 %
 % \subsection{Post-processing TFM table}
@@ -604,7 +601,7 @@ local function def_font(...)
     if type(fontdata) == "table" and fontdata.shared then
 %    \end{macrocode}
 %
-% Then we populate \texttt{MathConstants} table, which is required for
+% Then we populate |MathConstants| table, which is required for
 % OpenType math.
 %
 %    \begin{macrocode}
@@ -663,19 +660,19 @@ end
 %    Finally we register the callbacks
 %
 %    \begin{macrocode}
-luatexbase.add_to_callback('pre_linebreak_filter',
+luatexbase.add_to_callback("pre_linebreak_filter",
                             nodes.simple_font_handler,
-                           'luaotfload.pre_linebreak_filter')
-luatexbase.add_to_callback('hpack_filter',
+                           "luaotfload.pre_linebreak_filter")
+luatexbase.add_to_callback("hpack_filter",
                             nodes.simple_font_handler,
-                           'luaotfload.hpack_filter')
-luatexbase.reset_callback('define_font')
-luatexbase.add_to_callback('define_font',
+                           "luaotfload.hpack_filter")
+luatexbase.reset_callback("define_font")
+luatexbase.add_to_callback("define_font",
                             def_font,
-                           'luaotfload.define_font', 1)
-luatexbase.add_to_callback('find_vf_file',
+                           "luaotfload.define_font", 1)
+luatexbase.add_to_callback("find_vf_file",
                             fonts.vf.find,
-                           'luaotfload.find_vf_file')
+                           "luaotfload.find_vf_file")
 %    \end{macrocode}
 %
 % \iffalse