path: root/luaotfload.dtx

% \iffalse meta-comment
%
% Copyright (C) 2009-2013
%      by  Elie Roux      <elie.roux@telecom-bretagne.eu>
%      and Khaled Hosny   <khaledhosny@eglug.org>
%      and Philipp Gesang <philipp.gesang@alumni.uni-heidelberg.de>
%
%      Home:      https://github.com/lualatex/luaotfload
%      Support:   <lualatex-dev@tug.org>.
%
% This work is under the GPL v2.0 license.
%
% This work consists of the main source file luaotfload.dtx
% and the derived files
%    luaotfload.sty, luaotfload.lua
%
% Unpacking:
%    tex luaotfload.dtx
%
% Documentation:
%    lualatex luaotfload.dtx
%
%    The class ltxdoc loads the configuration file ltxdoc.cfg
%    if available. Here you can specify further options, e.g.
%    use A4 as paper format:
%       \PassOptionsToClass{a4paper}{article}
%
%
%
%<*ignore>
\begingroup
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
\Msg{* Package: luaotfload v2.2 OpenType layout system}
\Msg{************************************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax

\preamble
This is a generated file.

Copyright (C) 2009-2013
     by  Elie Roux      <elie.roux@telecom-bretagne.eu>
     and Khaled Hosny   <khaledhosny@eglug.org>
     and Philipp Gesang <philipp.gesang@alumni.uni-heidelberg.de>

     Home:      https://github.com/lualatex/luaotfload
     Support:   <lualatex-dev@tug.org>.

This work is under the GPL v2.0 license.

This work consists of the main source file luaotfload.dtx
and the derived files
    luaotfload.sty, luaotfload.lua

\endpreamble

\let\MetaPrefix\DoubleperCent

\generate{%
  \usedir{tex/luatex/luaotfload}%
  \file{luaotfload.sty}{\from{luaotfload.dtx}{package}}%
}

% The following hacks are to generate a lua file with lua comments starting with
% -- instead of %%

\def\MetaPrefix{-- }

\def\luapostamble{%
  \MetaPrefix^^J%
  \MetaPrefix\space End of File `\outFileName'.%
}

\def\currentpostamble{\luapostamble}%

\generate{%
  \usedir{tex/luatex/luaotfload}%
  \file{luaotfload.lua}{\from{luaotfload.dtx}{lua}}%%
}

\obeyspaces
\Msg{************************************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* files into a directory searched by TeX:}
\Msg{*}
\Msg{*     luaotfload.sty, luaotfload.lua}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}

\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{luaotfload.drv}%
  [2013/05/20 v2.2c OpenType layout system]%
\documentclass{ltxdoc}
\usepackage{metalogo,multicol,mdwlist,fancyvrb,xspace}
\usepackage[x11names]{xcolor}
%
\def\primarycolor{DodgerBlue4}  %%-> rgb  16  78 139 | #104e8b
\def\secondarycolor{Goldenrod4} %%-> rgb 139 105 200 | #8b6914
%
\usepackage[
    bookmarks=true,
   colorlinks=true,
    linkcolor=\primarycolor,
     urlcolor=\secondarycolor,
    citecolor=\primarycolor,
     pdftitle={The luaotfload package},
   pdfsubject={OpenType layout system for Plain TeX and LaTeX},
    pdfauthor={Elie Roux & Khaled Hosny & Philipp Gesang},
  pdfkeywords={luatex, lualatex, unicode, opentype}
]{hyperref}
\usepackage{fontspec}
\usepackage{unicode-math}
\setmainfont[
% Numbers     = OldStyle, %% buggy with font cache
  Ligatures   = TeX,
  BoldFont    = {Linux Libertine O Bold},
  ItalicFont  = {Linux Libertine O Italic},
  SlantedFont = {Linux Libertine O Italic},
]{Linux Libertine O}
\setmonofont[Ligatures=TeX,Scale=MatchLowercase]{Liberation Mono}
%setsansfont[Ligatures=TeX]{Linux Biolinum O}
\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}
\newcommand\LUATEX   {Lua\TeX\xspace}
\newcommand\XETEX    {\XeTeX\xspace}
\newcommand\LATEX    {\LaTeX\xspace}
\newcommand\LUALATEX {Lua\LaTeX\xspace}
\newcommand\CONTEXT  {Con\TeX t\xspace}
\newcommand\OpenType {\identifier{Open\kern-.25ex Type}\xspace}

\def\definehighlight[#1][#2]%
 {\ifcsname #1\endcsname\else
    \expandafter\def\csname #1\endcsname%
      {\bgroup#2\csname #1_indeed\endcsname}
    \expandafter\def\csname #1_indeed\endcsname##1%
      {##1\egroup}%
  \fi}

\def\restoreunderscore{\catcode`\_=12\relax}

\definehighlight    [fileent][\ttfamily\restoreunderscore]         %% files, dirs
\definehighlight   [texmacro][\sffamily\itshape\textbackslash]     %% cs
\definehighlight[luafunction][\sffamily\itshape\restoreunderscore] %% lua identifiers
\definehighlight [identifier][\sffamily]                           %% names
\definehighlight     [abbrev][\rmfamily\scshape]                   %% acronyms
\definehighlight   [emphasis][\rmfamily\slshape]                   %% level 1 emph

\newcommand*\email[1]{\href{mailto:#1}{#1}}

\renewcommand\partname{Part}%% gets rid of the stupid “file” heading

\usepackage{syntax}%% bnf for font request syntax

\usepackage{titlesec}

\def\movecountertomargin#1{\llap{\rmfamily\upshape#1\hskip2em}}
\def\zeropoint{0pt}
\titleformat \part
             {\normalsize\rmfamily\bfseries}
             {\movecountertomargin\thepart} \zeropoint {}
\titleformat \section
             {\normalsize\rmfamily\scshape}
             {\movecountertomargin\thesection} \zeropoint {}
\titleformat \subsection
             {\small\rmfamily\itshape}
             {\movecountertomargin\thesubsection} \zeropoint {}
\titleformat \subsubsection
             {\normalsize\rmfamily\upshape}
             {\movecountertomargin\thesubsubsection} \zeropoint {}

\usepackage{tocloft}
\renewcommand \cftpartfont   {\rmfamily\upshape}
\renewcommand \cftsecfont    {\rmfamily\upshape}
\renewcommand \cftsubsecfont {\rmfamily\upshape}
\setlength \cftbeforepartskip {1ex}
\setlength \cftbeforesecskip  {1ex}

\VerbatimFootnotes
\begin{document}
  \DocInput{luaotfload.dtx}%
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \GetFileInfo{luaotfload.drv}
%
% \title{The \identifier{luaotfload} package}
% \date{2013/05/20 v2.2c}
% \author{Elie Roux · Khaled Hosny · Philipp Gesang\\
%         Home:      \url{https://github.com/lualatex/luaotfload}\\
%         Support:   \email{lualatex-dev@tug.org}}
%
% \maketitle
%
% \begin{abstract}
% This package is an adaptation of the \CONTEXT font loading system.
% It allows for loading \OpenType fonts with an extended syntax and adds
% support for a variety of font features.
% \end{abstract}
%
% \tableofcontents
%
% \part{Package Description}
%
% \section{Introduction}
%
% Font management and installation has always been painful with \TEX.  A lot of
% files are needed for one font (\abbrev{tfm}, \abbrev{pfb}, \abbrev{map},
% \abbrev{fd}, \abbrev{vf}), and due to the 8-Bit encoding each font is limited
% to 256 characters.
% But the font world has evolved since the original
% \TEX, and new typographic systems have appeared, most notably the so
% called \emphasis{smart font} technologies like \OpenType
% fonts (\abbrev{otf}).
% These fonts can contain many more characters than \TEX fonts, as well as additional
% functionality like ligatures, old-style numbers, small capitals,
% etc., and support more complex writing systems like Arabic and
% Indic\footnote{%
%   Unfortunately, \identifier{luaotfload} doesn‘t support many Indic
%   scripts right now.
%   Assistance in implementing the prerequisites is greatly
%   appreciated.
% }
% scripts.
% \OpenType fonts are widely deployed and available for all
% modern operating systems.
% As of 2013 they have become the de facto standard for advanced text
% layout.
% However, until recently the only way to use them directly in the \TEX
% world was with the \XETEX engine.
%
% Unlike \XETEX, \LUATEX has no built-in support for
% \OpenType or technologies other than the original \TEX fonts.
% Instead, it provides hooks for executing \LUA code during the \TEX run
% that allow implementing extensions for loading fonts and manipulating
% how input text is processed without modifying the underlying engine.
% This is where \identifier{luaotfload} comes into play:
% Based on code from \CONTEXT, it extends \LUATEX with functionality necessary
% for handling \OpenType fonts.
% Additionally, it provides means for accessing fonts known to the operating
% system conveniently by indexing the metadata.
%
%
% \section{Thanks}
%
% \identifier{Luaotfload} is part of \LUALATEX, the community-driven
% project to provide a foundation for using the \LATEX format with the
% full capabilites of the \LUATEX engine.
% As such, the distinction between end users, contributors, and project
% maintainers is intentionally kept less strict, lest we unduly
% personalize the common effort.
%
% Nevertheless, the current maintainers would like to express their
% gratitude to Khaled Hosny, Akira Kakuto, Hironori Kitagawa and Dohyun
% Kim.
% Their contributions -- be it patches, advice, or systematic
% testing -- made the switch from version 1.x to 2.2 possible.
% Also, Hans Hagen, the author of the font loader, made porting the
% code to \LATEX a breeze due to the extra effort he invested into
% isolating it from the rest of \CONTEXT, not to mention his assistance
% in the task and willingness to respond to our suggestions.
%
%
% \section{Loading Fonts}
%
% \identifier{luaotfload} supports an extended font request syntax:
%
% \begin{quote}
%       |\font\foo={|%
%       \meta{prefix}|:|%
%       \meta{font name}|:|%
%       \meta{font features}|}|%
%       \meta{\TEX font features}
% \end{quote}
%
% \noindent
% The curly brackets are optional and escape the spaces in the enclosed
% font name.
% Alternatively, double quotes serve the same purpose.
% A selection of individual parts of the syntax are discussed below;
% for a more formal description see figure \ref{font-syntax}.
%
% \begin{figure}[b]
%   \setlength\grammarparsep{12pt plus 2pt minus 2pt}
%   \setlength\grammarindent{5cm}
%   \begingroup
%     \small
%     \begin{grammar}
%       <definition>      ::= `\\font', {\sc csname}, `=', <font request>, [ <size> ] ;
%
%       <size>            ::= `at', {\sc dimension} ;
%
%       <font request>    ::= `"', <unquoted font request> `"'
%       \alt                  `{', <unquoted font request> `}'
%       \alt                  <unquoted font request> ;
%
%       <unquoted font request> ::= <specification>, [`:', <feature list> ]
%       \alt                        `[', <path lookup> `]', [ [`:'], <feature list> ] ;
%
%       <specification>    ::= <prefixed spec>, [ <subfont no> ], \{ <modifier> \}
%       \alt                   <anon lookup>, \{ <modifier> \} ;
%
%       <prefixed spec>    ::= `file:', <file lookup>
%       \alt                   `name:', <name lookup> ;
%
%       <file lookup>      ::= \{ <name character> \} ;
%
%       <name lookup>      ::= \{ <name character> \} ;
%
%       <anon lookup>      ::= {\sc tfmname} | <name lookup> ;
%
%       <path lookup>      ::= \{ {\sc all_characters} - `]' \} ;
%
%       <modifier>         ::= `/', (`I' | `B' | `BI' | `IB' | `S=', \{ {\sc digit} \} ) ;
%
%       <subfont no>       ::= `(', \{ {\sc digit} \}, `)' ;
%
%       <feature list>     ::= <feature expr>, \{ `;', <feature expr> \} ;
%
%       <feature expr>     ::= {\sc feature_id}, `=', {\sc feature_value}
%       \alt                   <feature switch>, {\sc feature_id} ;
%
%       <feature switch>   ::= `+' | `-' ;
%
%       <name character>   ::= {\sc all_characters} - ( `(' | `/' | `:' ) ;
%     \end{grammar}
%   \endgroup
%   \caption{Font request syntax.
%            Braces or double quotes around the
%            \emphasis{specification} rule will
%            preserve whitespace in file names.
%            In addition to the font style modifiers
%            (\emphasis{slash-notation}) given above, there
%            are others that are recognized but will be silently
%            ignored: {\ttfamily aat},
%                     {\ttfamily icu}, and
%                     {\ttfamily gr}.
%            The special terminals are:
%            {\sc feature\textunderscore id} for a valid font
%               feature name and
%            {\sc feature\textunderscore value} for the corresponding
%               value.
%            {\sc tfmname} is the name of a \abbrev{tfm} file.
%            {\sc digit}  again refers to bytes 48--57, and
%            {\sc all\textunderscore characters} to all byte values.
%            {\sc csname} and {\sc dimension} are the \TEX concepts.}
%   \label{font-syntax}
% \end{figure}
%
% \subsection{Prefix -- the \identifier{luaotfload}{ }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
% create the database.
%
% 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 is 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{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.
%
% \begin{quote}
%   |\font\fontname=[|\meta{path to file}|]|
% \end{quote}
%
% \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.
%
% \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:
%
% \begin{quote}
%   \begin{verbatim}
%   \font\lmromanten={file:ec-lmr10} at 10pt
%   \end{verbatim}
% \end{quote}
%
% The \OpenType version of Janusz Nowacki’s font \emphasis{Antykwa
% 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}
%   \font\apcregular=file:antpoltltcond-regular.otf at 42pt
%   \end{verbatim}
% \end{quote}
%
% The next example shows how to load the \emphasis{Porson} font digitized by
% the Greek Font Society using \XETEX-style syntax and an absolute path from a
% non-standard directory:
%
% \begin{quote}
%   \begin{verbatim}
%   \font\gfsporson="[/tmp/GFSPorson.otf]" at 12pt
%   \end{verbatim}
% \end{quote}
%
% \subsubsection{Loading by Font Name}
%
% The \verb|name:| lookup does not depend on cryptic filenames:
%
% \begin{quote}
%   \begin{verbatim}
%   \font\pagellaregular={name:TeX Gyre Pagella} at 9pt
%   \end{verbatim}
% \end{quote}
%
% A bit more specific but essentially the same lookup would be:
%
% \begin{quote}
%   \begin{verbatim}
%   \font\pagellaregular={name:TeX Gyre Pagella Regular} at 9pt
%   \end{verbatim}
% \end{quote}
%
% \noindent
% Which fits nicely with the whole set:
%
% \begin{quote}
%   \begin{verbatim}
%   \font\pagellaregular   ={name:TeX Gyre Pagella Regular}    at 9pt
%   \font\pagellaitalic    ={name:TeX Gyre Pagella Italic}     at 9pt
%   \font\pagellabold      ={name:TeX Gyre Pagella Bold}       at 9pt
%   \font\pagellabolditalic={name:TeX Gyre Pagella Bolditalic} at 9pt
%
%   {\pagellaregular     foo bar baz\endgraf}
%   {\pagellaitalic      foo bar baz\endgraf}
%   {\pagellabold        foo bar baz\endgraf}
%   {\pagellabolditalic  foo bar baz\endgraf}
%
%   ...
%   \end{verbatim}
% \end{quote}
%
% \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}.
%
% The element \meta{font features} is a semicolon-separated list of feature
% tags\footnote{%
%   Cf. \url{http://www.microsoft.com/typography/otspec/featurelist.htm}.
% }
% and font options.
% Prepending a font feature with a |+| (plus sign) enables it, whereas
% a |-| (minus) disables it. For instance, the request
%
% \begin{quote}
%   \begin{verbatim}
%   \font\test=LatinModernRoman:+clig;-kern
%   \end{verbatim}
% \end{quote}
%
% \noindent activates contextual ligatures (|clig|) and disables
% kerning (|kern|).
% Alternatively the options |true| or |false| can be passed to
% the feature in a key/value expression.
% The following request has the same meaning as the last one:
%
% \begin{quote}
%   \begin{verbatim}
%   \font\test=LatinModernRoman:clig=true;kern=false
%   \end{verbatim}
% \end{quote}
%
% \noindent
% Furthermore, this second syntax is required should a font feature
% accept other options besides a true/false switch.
% For example, \emphasis{stylistic alternates} (|salt|) are variants of given
% glyphs.
% They can be selected either explicitly by supplying the variant
% index (starting from one), or randomly by setting the value to,
% obviously, |random|.
%
% \iffalse TODO verify that this actually works with a font that supports
%               the salt/random feature!\fi
% \begin{quote}
%   \begin{verbatim}
%   \font\librmsaltfirst=LatinModernRoman:salt=1
%   \end{verbatim}
% \end{quote}
%
% \noindent Other font options include:
%
% \begin{description}
%
% \item [mode] \hfill \\
%        \identifier{luaotfload} has two \OpenType processing
%        \emphasis{modes}:
%        \identifier{base} and \identifier{node}.
%
%        \identifier{base} mode works by mapping \OpenType
%        features to traditional \TEX ligature and kerning mechanisms.
%        Supporting only non-contextual substitutions and kerning
%        pairs, it is the slightly faster, albeit somewhat limited, variant.
%        \identifier{node} mode works by processing \TeX’s internal
%        node list directly at the \LUA end and supports
%        a wider range of \OpenType features.
%        The downside is that the intricate operations required for
%        \identifier{node} mode may slow down typesetting especially
%        with complex fonts and it does not work in math mode.
%
%        By default \identifier{luaotfload} is in \identifier{node}
%        mode, and \identifier{base} mode has to be requested where needed,
%        e.~g. for math fonts.
%
% \item [script] \label{script-tag} \hfill \\
%        An \OpenType script tag;\footnote{%
%          See \url{http://www.microsoft.com/typography/otspec/scripttags.htm}
%          for a list of valid values.
%          For scripts derived from the Latin alphabet the value
%          |latn| is good choice.
%        }
%        the default value is |dlft|.
%        Some fonts, including very popular ones by foundries like Adobe,
%        do not assign features to the |dflt| script, in
%        which case the script needs to be set explicitly.
%
% \item [language] \hfill \\
%        An \OpenType language system identifier,\footnote{%
%          Cf. \url{http://www.microsoft.com/typography/otspec/languagetags.htm}.
%        }
%        defaulting to |dflt|.
%
% \item [featurefile] \hfill \\
%        A comma-separated list of feature files to be applied to the
%        font.
%        Feature files contain a textual representation of
%        \OpenType tables and extend the features of a font
%        on fly.
%        After they are applied to a font, features defined in a
%        feature file can be enabled or disabled just like any
%        other font feature.
%        The syntax is documented in \identifier{Adobe}’s
%        \OpenType Feature File Specification.\footnote{%
%          Cf. \url{http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html}.
%        }
%
%        For a demonstration of how to set a |tkrn| feature consult
%        the file |tkrn.fea| that is part of \identifier{luaotfload}.
%        It can be read and applied as follows:
%
%        |\font\test=Latin Modern Roman:featurefile=tkrn.fea;+tkrn|
%
% \item [color] \hfill \\
%        A font color, defined as a triplet of two-digit hexadecimal
%        \abbrev{rgb} values, with an optional fourth value for
%        transparency
%        (where |00| is completely transparent and |FF| is opaque).
%
%        For example, in order to set text in semitransparent red:
%
%        \begin{quote}
%           \begin{verbatim}
%           \font\test={Latin Modern Roman}:color=FF0000BB
%           \end{verbatim}
%        \end{quote}
%
% \item [protrusion \& expansion] \hfill \\
%        These keys control microtypographic features of the font,
%        namely \emphasis{character protrusion} and \emphasis{font
%        expansion}.
%        Their arguments are names of \LUA tables that contain
%        values for the respective features.\footnote{%
%           For examples of the table layout please refer to the
%           section of the file \fileent{luaotfload-fonts-ext.lua} where the
%           default values are defined.
%           Alternatively and with loss of information, you can dump
%           those tables into your terminal by issuing
%           \begin{verbatim}
%             \directlua{inspect(fonts.protrusions.setups.default)
%                        inspect(fonts.expansions.setups.default)}
%           \end{verbatim}
%           at some point after loading \fileent{luaotfload.sty}.
%        }
%        For both, only the set \identifier{default} is predefined.
%
%        For example, to enable default protrusion\footnote{%
%          You also need to set
%              \verb|pdfprotrudechars=2| and
%              \verb|pdfadjustspacing=2|
%          to activate protrusion and expansion, respectively.
%          See the
%          \href{http://mirrors.ctan.org/systems/pdftex/manual/pdftex-a.pdf}%
%               {\PDFTEX manual}
%          for details.
%        }:
%
%        \begin{quote}
%           \begin{verbatim}
%           \font\test=LatinModernRoman:protrusion=default
%           \end{verbatim}
%        \end{quote}
% \end{description}
%
% \paragraph{Non-standard font features}
% \identifier{luaotfload} adds a number of features that are not defined
% in the original \OpenType specification, most of them
% aiming at emulating the behavior familiar from other \TEX engines.
% Currently (2013) there are three of them:
%
% \begin{description}
%
%   \item [anum]
%           Substitutes the glyphs in the \abbrev{ascii} number range
%           with their counterparts from eastern Arabic or Persian,
%           depending on the value of \identifier{language}.
%
%   \item [tlig]
%           Applies legacy \TEX ligatures:
%
%           \begin{tabular}{rlrl}
%              ``  &  \verb|``|  &  ''  &  \verb|''|  \\
%              `   &  \verb|`|   &  '   &  \verb|'|   \\
%              "   &  \verb|"|   &  --  &  \verb|--|  \\
%              --- &  \verb|---| &  !`  &  \verb|!`|  \\
%              ?`  &  \verb|?`|  &      &             \\
%           \end{tabular}
%
%           \footnote{%
%             These contain the feature set \verb|trep| of earlier
%             versions of \identifier{luaotfload}.
%
%             Note to \XETEX users: this is the equivalent of the
%             assignment \verb|mapping=text-tex| using \XETEX's input
%             remapping feature.
%           }
%
%   \item [itlc]
%           Computes italic correction values (active by default).
%
% \end{description}
%
%
%
% \section{Font names database}
% \label{sec:fontdb}
%
% As mentioned above, \identifier{luaotfload} keeps track of which
% fonts are available to \LUATEX by means of a \emphasis{database}.
% This allows referring to fonts not only by explicit filenames but
% also by the proper names contained in the metadata which is often
% more accessible to humans.\footnote{%
%   The tool \href{http://www.lcdf.org/type/}{\fileent{otfinfo}} (comes
%   with \TEX Live), when invoked on a font file with the \verb|-i|
%   option, lists the variety of name fields defined for it.
% }
%
% When \identifier{luaotfload} is asked to load a font by a font name,
% it will check if the database exists and load it, or else generate a
% fresh one.
% Should it then fail to locate the font, an update to the database is
% performed in case the font has been added to the system only
% recently.  As soon as the database is updated, the resolver will try
% and look up the font again, all without user intervention.
% The goal is for \identifier{luaotfload} to act in the background and
% behave as unobtrusively as possible, while providing a convenient
% interface to the fonts installed on the system.
%
% Generating the database for the first time may take a while since it
% inspects every font file on your computer.
% This is particularly noticeable if it occurs during a typesetting run.
% In any case, subsequent updates to the database will be quite fast.
%
% \subsection[luaotfload-tool / mkluatexfontdb.lua]%
%            {\fileent{luaotfload-tool} /
%             \fileent{mkluatexfontdb.lua}\footnote{%
%   The script may be named just \fileent{mkluatexfontdb} in your
%   distribution.
% }}
%
% 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{luaotfload-tool} 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
% pass it as an argument to \fileent{texlua}.\footnote{%
%   Tests by the maintainer show only marginal performance gain by
%   running with Luigi Scarso’s
%   \href{https://foundry.supelec.fr/projects/luajittex/}%
%        {\identifier{Luajit\kern-.25ex\TEX}},
%   which is probably due to the fact that most of the time is spent
%   on file system operations.
%
%   \emphasis{Note}:
%   On \abbrev{MS} \identifier{Windows} systems, the script can be run
%   either by calling the wrapper application
%   \fileent{luaotfload-tool.exe} or as
%   \verb|texlua.exe luaotfload-tool.lua|.
% }
% Invoked with the argument \verb|--update| it will perform a database
% update, scanning for fonts not indexed.
%
% \begin{quote}
%   \begin{verbatim}
%     luaotfload-tool --update
%   \end{verbatim}
% \end{quote}
%
% Adding the \verb|--force| switch will initiate a complete
% rebuild of the database.
%
% \begin{quote}
%   \begin{verbatim}
%     luaotfload-tool --update --force
%   \end{verbatim}
% \end{quote}
%
% For sake of backwards compatibility, \fileent{luaotfload-tool} 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
% expected to be located on a given system.
% On a Linux machine it follows the paths listed in the
% \identifier{Fontconfig} configuration files;
% consult \verb|man 5 fonts.conf| for further information.
% On \identifier{Windows} systems, the standard location is
% \verb|Windows\Fonts|,
% while \identifier{Mac OS~X} requires a multitude of paths to
% be examined.
% The complete list is is given in table \ref{table-searchpaths}.
% Other paths can be specified by setting the environment variable
% \verb+OSFONTDIR+.
% If it is non-empty, then search will be extended to the included
% directories.
%
% \begin{table}[t]
%   \hrule
%   \caption{List of paths searched for each supported operating
%            system.}
%   \renewcommand{\arraystretch}{1.2}
%   \begin{center}
%     \begin{tabular}{lp{.5\textwidth}}
%       Windows     & \verb|%WINDIR%\Fonts|
%       \\
%       Linux       & \fileent{/usr/local/etc/fonts/fonts.conf} and\hfill\break
%                     \fileent{/etc/fonts/fonts.conf}
%       \\
%       Mac         & \fileent{\textasciitilde/Library/Fonts},\break
%                     \fileent{/Library/Fonts},\break
%                     \fileent{/System/Library/Fonts}, and\hfill\break
%                     \fileent{/Network/Library/Fonts}
%       \\
%     \end{tabular}
%   \end{center}
%   \label{table-searchpaths}
%   \hrule
% \end{table}
%
% \subsection{Querying from Outside}
%
% \fileent{luaotfload-tool} 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
% matching name.
% For instance, the invocation
%
% \begin{quote}
%   \begin{verbatim}
%     luaotfload-tool  --find="Iwona Regular"
%   \end{verbatim}
% \end{quote}
%
% \noindent
% will verify if “Iwona Regular” is found in the database and can be
% readily requested in a document.
%
% If you are unsure about the actual font name, then add the
% \verb|-F| (or \verb|--fuzzy|) switch to the command line to enable
% approximate matching.
% Suppose you cannot precisely remember if the variant of
% \identifier{Iwona} you are looking for was “Bright” or “Light”.
% The query
%
% \begin{quote}
%   \begin{verbatim}
%     luaotfload-tool  -F --find="Iwona Bright"
%   \end{verbatim}
% \end{quote}
%
% \noindent
% will tell you that indeed the latter name is correct.
%
% Basic information about fonts in the database can be displayed
% using the \verb|-i| option (\verb|--info|).
% \begin{quote}
%   \begin{verbatim}
%     luaotfload-tool  -i --find="Iwona Light Italic"
%   \end{verbatim}
% \end{quote}
% \noindent
% The meaning of the printed values is described in section 4.4 of the
% \LUATEX reference manual.\footnote{%
%   In \TEX Live: \fileent{texmf-dist/doc/luatex/base/luatexref-t.pdf}.
% }
%
% \verb|luaotfload-tool --help| will list the available command line
% switches, including some not discussed in detail here.
% For a full documentation of \identifier{luaotfload-tool} and its
% capabilities refer to the manpage
% (\verb|man 1 luaotfload-tool|).\footnote{%
%   Or see \verb|luaotfload-tool.rst| in the source directory.
% }
%
% \subsection{Blacklisting Fonts}
% \label{font-blacklist}
%
% 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|luaotfload-tool -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{luaotfload-blacklist.cnf}.
%
% A blacklist file is a list of font filenames, one per line.
% Specifying the full path to where the file is located is optional, the
% plain filename should suffice.
% File extensions (\fileent{.otf}, \fileent{.ttf}, etc.) may be omitted.
% Anything after a percent (|%|) character until the end of the line
% is ignored, so use this to add comments.
% Place this file to some location where the \identifier{kpse}
% library can find it, e.~g.
% \fileent{texmf-local/tex/luatex/luaotfload} if you are running
% \identifier{\TEX Live},\footnote{%
%   You may have to run \verb|mktexlsr| if you created a new file in
%   your \fileent{texmf} tree.
% }
% or just leave it in the working directory of your document.
% \identifier{luaotfload} reads all files named
% \fileent{luaotfload-blacklist.cnf} it finds, so the fonts in
% \fileent{./luaotfload-blacklist.cnf} extend the global blacklist.
%
% Furthermore, a filename prepended with a dash character (|-|) is
% removed from the blacklist, causing it to be temporarily whitelisted
% without modifying the global file.
% An example with explicit paths:
%
% \begin{verbatim}
% % example otf-blacklist.cnf
% /Library/Fonts/GillSans.ttc  % Luaotfload ignores this font.
% -/Library/Fonts/Optima.ttc   % This one is usable again, even if
%                              % blacklisted somewhere else.
% \end{verbatim}
%
% \section{Files from \CONTEXT and \LUATEX-Fonts}
%
% \identifier{luaotfload} relies on code originally written by Hans
% Hagen\footnote{%
%   The creator of the \href{http://wiki.contextgarden.net}{\CONTEXT}
%   format.
% }
% for and tested with \CONTEXT.
% It integrates the font loader as distributed in
% the \identifier{\LUATEX-Fonts} package.
% The original \LUA source files have been combined using the
% \fileent{mtx-package} script into a single, self-contained blob.
% In this form the font loader has no further dependencies\footnote{%
%   It covers, however, to some extent the functionality of the
%   \identifier{lualibs} package.
% }
% and requires only minor adaptions to integrate into
% \identifier{luaotfload}.
% The guiding principle is to let \CONTEXT/\LUATEX-Fonts take care of
% the implementation, and update the imported code from time to time.
% As maintainers, we aim at importing files from upstream essentially
% \emphasis{unmodified}, except for renaming them to prevent name
% clashes.
% This job has been greatly alleviated since the advent of
% \LUATEX-Fonts, prior to which the individual dependencies had to be
% manually spotted and extracted from the \CONTEXT source code in a
% complicated and error-prone fashion.
%
% Below is a commented list of the files distributed with
% \identifier{luaotfload} in one way or the other.
% See figure \ref{file-graph} on page \pageref{file-graph} for a
% graphical representation of the dependencies.
% From \LUATEX-Fonts, only the file \fileent{luatex-fonts-merged.lua}
% has been imported as \fileent{luaotfload-merged.lua}.
% It is generated by \fileent{mtx-package}, a \LUA source code merging
% too developed by Hans Hagen.\footnote{%
%   \fileent{mtx-package} is
%   \href
%     {http://repo.or.cz/w/context.git/blob_plain/refs/heads/origin:/scripts/context/lua/mtx-package.lua}
%     {part of \CONTEXT}
%   and requires \fileent{mtxrun}.
%   Run
%   \verb|mtxrun --script package --help|
%   to display further information.
%   For the actual merging code see the file
%   \fileent{util-mrg.lua} that is part of \CONTEXT.
% }
% It houses several \LUA files that can be classed in three
% categories.
%
%   \begin{itemize}
%     \let\normalitem=\item
%     \def\incitem#1{%
%       \normalitem{\fileent{#1}}
%     }
%     \normalitem \emphasis{\LUA utility libraries}, a subset
%                 of what is provided by the \identifier{lualibs}
%                 package.
%
%                 \begin{multicols}{2}
%                   \begin{itemize}
%                     \incitem{l-lua.lua}       \incitem{l-lpeg.lua}
%                     \incitem{l-function.lua}  \incitem{l-string.lua}
%                     \incitem{l-table.lua}     \incitem{l-io.lua}
%                     \incitem{l-file.lua}      \incitem{l-boolean.lua}
%                     \incitem{l-math.lua}      \incitem{util-str.lua}
%                   \end{itemize}
%                 \end{multicols}
%
%     \normalitem The \emphasis{font loader} itself.
%                 These files have been written for
%                 \LUATEX-Fonts and they are distributed along
%                 with \identifier{luaotfload}.
%                 \begin{multicols}{2}
%                   \begin{itemize}
%                     \incitem{luatex-basics-gen.lua}
%                     \incitem{luatex-basics-nod.lua}
%                     \incitem{luatex-fonts-enc.lua}
%                     \incitem{luatex-fonts-syn.lua}
%                     \incitem{luatex-fonts-tfm.lua}
%                     \incitem{luatex-fonts-chr.lua}
%                     \incitem{luatex-fonts-lua.lua}
%                     \incitem{luatex-fonts-def.lua}
%                     \incitem{luatex-fonts-ext.lua}
%                     \incitem{luatex-fonts-cbk.lua}
%                   \end{itemize}
%                 \end{multicols}
%
%     \normalitem Code related to \emphasis{font handling and
%                 node processing}, taken directly from
%                 \CONTEXT.
%                 \begin{multicols}{2}
%                   \begin{itemize}
%                     \incitem{data-con.lua} \incitem{font-ini.lua}
%                     \incitem{font-con.lua} \incitem{font-cid.lua}
%                     \incitem{font-map.lua} \incitem{font-oti.lua}
%                     \incitem{font-otf.lua} \incitem{font-otb.lua}
%                     \incitem{node-inj.lua} \incitem{font-ota.lua}
%                     \incitem{font-otn.lua} \incitem{font-def.lua}
%                     \incitem{font-otp.lua}
%                   \end{itemize}
%                 \end{multicols}
%   \end{itemize}
%
% Note that if \identifier{luaotfload} cannot locate the
% merged file, it will load the individual \LUA libraries
% instead.
% Their names remain the same as in \CONTEXT (without the
% \verb|otfl|-prefix) since we imported the relevant section of
% \fileent{luatex-fonts.lua} unmodified into \fileent{luaotfload.lua}.
% Thus if you prefer running bleeding edge code from the
% \CONTEXT beta, all you have to do is remove
% \fileent{luaotfload-merged.lua} from the search path.
%
% Also, the merged file at some point
% loads the Adobe Glyph List from a \LUA table that is contained in
% \fileent{luaotfload-glyphlist.lua}, which is automatically generated by the %
% script \fileent{mkglyphlist}.\footnote{%
%   See \fileent{luaotfload-font-enc.lua}.
%   The hard-coded file name is why we have to replace the procedure
%   that loads the file in \fileent{luaotfload-override.lua}.
% }
% There is a make target \identifier{glyphs} that will create a fresh
% glyph list so we don’t need to import it from \CONTEXT
% any longer.
%
% In addition to these, \identifier{luaotfload} requires a number of
% files not contained in the merge. Some of these have no equivalent in
% \LUATEX-Fonts or \CONTEXT, some were taken unmodified from the
% latter.
%
% \begin{itemize}
%     \let\normalitem=\item
%     \def\ouritem#1{%
%       \normalitem{\fileent{#1}}%
%       \space--\hskip1em
%     }
%     \ouritem {luaotfload-features.lua}   font feature handling;
%                                          incorporates some of the code from
%                                          \fileent{font-otc} from \CONTEXT;
%     \ouritem {luaotfload-lib-dir.lua}    \fileent{l-dir} from \CONTEXT;
%                                          contains functionality required
%                                          by \fileent{luaotfload-font-nms.lua}.
%     \ouritem {luaotfload-override.lua}   overrides the \CONTEXT logging
%                                          functionality.
%     \ouritem {luaotfload-loaders.lua}    registers the \OpenType
%                                          font reader as handler for
%                                          Postscript fonts
%                                          (\abbrev{pfa}, \abbrev{pfb}).
%     \ouritem {luaotfload-database.lua}   font names database.
%     \ouritem {luaotfload-colors.lua}     color handling.
%     \ouritem {luaotfload-auxiliary.lua}  access to internal functionality
%                                          for package authors
%                                          (proposals for additions welcome).
% \end{itemize}
%
% \begin{figure}[b]
%   \caption{Schematic of the files in \identifier{Luaotfload}}
%   \includegraphics[width=\textwidth]{filegraph.pdf}
%   \label{file-graph}
% \end{figure}
%
% \section{Auxiliary Functions}
%
% With release version 2.2, \identifier{luaotfload} received
% additional functions for package authors to call from outside
% (see the file \fileent{luaotfload-auxiliary.lua} for details).
% The purpose of this addition twofold.
% Firstly, \identifier{luaotfload} failed to provide a stable interface
% to internals in the past which resulted in an unmanageable situation
% of different packages abusing the raw access to font objects by means
% of the \luafunction{patch_font} callback.
% When the structure of the font object changed due to an update, all
% of these imploded and several packages had to be fixed while
% simultaneously providing fallbacks for earlier versions.
% Now the patching is done on the \identifier{luaotfload} side and can
% be adapted with future modifications to font objects without touching
% the packages that depend on it.
% Second, some the capabilities of the font loader and the names
% database are not immediately relevant in \identifier{luaotfload}
% itself but might nevertheless be of great value to package authors or
% end users.
%
% Note that the current interface is not yet set in stone and the
% development team is open to suggestions for improvements or
% additions.
%
% \subsection{Callback Functions}
%
% The \luafunction{patch_font} callback is inserted in the wrapper
% \identifier{luaotfload} provides for the font definition callback
% (see below, page \pageref{define-font}).
% At this place it allows manipulating the font object immediately after
% the font loader is done creating it.
% For a short demonstration of its usefulness, here is a snippet that
% writes an entire font object to the file \fileent{fontdump.lua}:
%
% \begin{quote}
%   \begin{verbatim}
%   \input luaotfload.sty
%   \directlua{
%     local dumpfile    = "fontdump.lua"
%     local dump_font   = function (tfmdata)
%       local data = table.serialize(tfmdata)
%       io.savedata(dumpfile, data)
%     end
%
%     luatexbase.add_to_callback(
%       "luaotfload.patch_font",
%       dump_font,
%       "my_private_callbacks.dump_font"
%     )
%   }
%   \font\dumpme=name:Iwona
%   \bye
%   \end{verbatim}
% \end{quote}
%
% \emphasis{Beware}: this creates a Lua file of around 150,000 lines of
% code, taking up 3~\abbrev{mb} of disk space.
% By inspecting the output you can get a first impression of how a font
% is structured in \LUATEX’s memory, what elements it is composed of,
% and in what ways it can be rearranged.
%
% \subsubsection{Compatibility with Earlier Versions}
%
% As has been touched on in the preface to this section, the structure
% of the object as returned by the fontloader underwent rather drastic
% changes during different stages of its development, and not all
% packages that made use of font patching have kept up with every one
% of it.
% To ensure compatibility with these as well as older versions of
% some packages, \identifier{luaotfload} sets up copies of or references
% to data in the font table where it used to be located.
% For instance, important parameters like the requested point size, the
% units factor, and the font name have again been made accessible from
% the toplevel of the table even though they were migrated to different
% subtables in the meantime.
%
% \subsubsection{Patches}
%
% These are mostly concerned with establishing compatibility with
% \XETEX.
%
% \begin{itemize}
%   \let\normalitem=\item
%   \def\ouritem#1{%
%     \normalitem{\luafunction{#1}}%
%     \hfill\break
%   }
%
%   \ouritem  {set_sscale_dimens}
%             Calculate \texmacro{fontdimen}s 10 and 11 to emulate \XETEX.
%
%   \ouritem  {set_capheight}
%             Calculates \texmacro{fontdimen} 8 like \XETEX.
%
%   \ouritem  {patch_cambria_domh}
%             Correct some values of the font \emphasis{Cambria Math}.
%
% \end{itemize}
%
% \subsection{Package Author’s Interface}
%
% As \LUATEX release 1.0 is nearing, the demand for a reliable interface
% for package authors increases.
%
% \subsubsection{Font Properties}
%
% Below functions mostly concern querying the different components of a
% font like for instance the glyphs it contains, or what font features
% are defined for which scripts.
%
% \begin{itemize}
%   \let\normalitem=\item
%   \def\ouritem#1{%
%     \normalitem{\luafunction{#1}}%
%     \hfill\break
%   }
%
%   \ouritem  {aux.font_has_glyph (id : int, index : int)}
%             Predicate that returns true if the font \luafunction{id}
%             has glyph \luafunction{index}.
%
%   \ouritem  {aux.slot_of_name(name : string)}
%             Translates an Adobe Glyph name to the corresponding glyph
%             slot.
%
%   \ouritem  {aux.name_of_slot(slot : int)}
%             The inverse of \luafunction{slot_of_name}; note that this
%             might be incomplete as multiple glyph names may map to the
%             same codepoint, only one of which is returned by
%             \luafunction{name_of_slot}.
%
%   \ouritem  {aux.provides_script(id : int, script : string)}
%             Test if a font supports \luafunction{script}.
%
%   \ouritem  {aux.provides_language(id : int, script : string, language : string)}
%             Test if a font defines \luafunction{language} for a given
%             \luafunction{script}.
%
%   \ouritem  {aux.provides_feature(id : int, script : string,
%              language : string, feature : string)}
%             Test if a font defines \luafunction{feature} for
%             \luafunction{language} for a given \luafunction{script}.
%
%   \ouritem  {aux.get_math_dimension(id : int, dimension : string)}
%             Get the dimension \luafunction{dimension} of font \luafunction{id}.
%
%   \ouritem  {aux.sprint_math_dimension(id : int, dimension : string)}
%             Same as \luafunction{get_math_dimension()}, but output the value
%             in scaled points at the \TEX end.
%
% \end{itemize}
%
% \subsubsection{Database}
%
% \begin{itemize}
%   \let\normalitem=\item
%   \def\ouritem#1{%
%     \normalitem{\luafunction{#1}}%
%     \hfill\break
%   }
%
%   \ouritem  {aux.scan_external_dir(dir : string)}
%             Include fonts in directory \luafunction{dir} in font lookups without
%             adding them to the database.
%
% \end{itemize}
%
% \section{Troubleshooting}
%
% If you encounter problems with some fonts, please first update to the latest
% version of this package before reporting a bug, as
% \identifier{luaotfload} is under active development and still a
% moving target.
% The development takes place on \identifier{github} at
% \url{https://github.com/lualatex/luaotfload} where there is an issue
% tracker for submitting bug reports, feature requests and the likes
% requests and the likes.
%
% Errors during database generation can be traced by increasing
% verbosity levels and redirecting log output to \fileent{stdout}:
%
% \begin{verbatim}
%   luaotfload-tool -fuvvv --log=stdout
% \end{verbatim}
%
% If this fails, the font last printed to the terminal is likely to be
% the culprit.
% Please specify it when reporting a bug, and blacklist it for the time
% being (see above, page \pageref{font-blacklist}).
%
% A common problem is the lack of features for some
% \OpenType fonts even when specified.
% This can be related to the fact that some fonts do not provide
% features for the \verb|dflt| script (see above on page
% \pageref{script-tag}),
% which is the default one in this package.
% If this happens, assigning a noth script when the font is defined should
% fix it.
% For example with \verb|latn|:
%
% \begin{verbatim}
%   \font\test=file:MyFont.otf:script=latn;+liga;
% \end{verbatim}
%
% Another strategy that helps avoiding problems is to not access raw \LUATEX
% internals directly.
% Some of them, even though they are dangerous to access, have not been
% overridden or disabled.
% Thus, whenever possible prefer the functions in the
% \luafunction{aux} namespace over direct manipulation of font objects.
% For example, raw access to the \luafunction{font.fonts} table like:
%
% \begin{verbatim}
%   local somefont = font.fonts[2]
% \end{verbatim}
%
% can render already defined fonts unusable.
% Instead, the function \luafunction{font.getfont()} should be used because
% it has been replaced by a safe variant.
%
% \part{Implementation}
%
% \section{\fileent{luaotfload.lua}}
%
% This file initializes the system and loads the font loader.
% To minimize potential conflicts between other packages and the
% code imported from \CONTEXT, several precautions are in order.
% Some of the functionality that the font loader expects to be present,
% like raw access to callbacks, are assumed to have been disabled by
% \identifier{luatexbase} when this file is processed.
% In some cases it is possible to trick it by putting dummies into
% place and restoring the behavior from \identifier{luatexbase} after
% initilization.
% Other cases such as attribute allocation require that we hook the
% functionality from \identifier{luatexbase} into locations where they
% normally wouldn’t be.
%
% Anyways we can import the code base without modifications, which is
% due mostly to the extra effort by
% Hans Hagen to make \LUATEX-Fonts self-contained and encapsulate it,
% and especially due to his willingness to incorporate our suggestions.
%
% \iffalse
%<*lua>
% \fi
%    \begin{macrocode}
luaotfload                  = luaotfload or {}
local luaotfload            = luaotfload

config                            = config or { }
config.luaotfload                 = config.luaotfload or { }
------.luaotfload.resolver        = config.luaotfload.resolver         or "normal"
config.luaotfload.resolver        = config.luaotfload.resolver         or "cached"
config.luaotfload.definer         = config.luaotfload.definer          or "patch"
config.luaotfload.compatibility   = config.luaotfload.compatibility    or false
config.luaotfload.loglevel        = config.luaotfload.loglevel  or 1
config.luaotfload.color_callback  = config.luaotfload.color_callback   or "pre_linebreak_filter"
--luaotfload.prefer_merge     = config.luaotfload.prefer_merge or true

luaotfload.module = {
    name          = "luaotfload",
    version       = 2.2,
    date          = "2013/05/20",
    description   = "OpenType layout system.",
    author        = "Elie Roux & Hans Hagen",
    copyright     = "Elie Roux",
    license       = "GPL v2.0"
}

local luatexbase       = luatexbase

local getmetatable     = getmetatable
local rawset           = rawset
local setmetatable     = setmetatable
local type, next       = type, next


local kpseexpand_path  = kpse.expand_path
local kpseexpand_var   = kpse.expand_var
local kpsefind_file    = kpse.find_file
local lfsisdir         = lfs.isdir
local lfsisfile        = lfs.isfile
local lfsmkdir         = lfs.mkdir
local stringexplode    = string.explode
local stringgmatch     = string.gmatch
local stringsub        = string.sub

local add_to_callback, create_callback =
      luatexbase.add_to_callback, luatexbase.create_callback
local reset_callback, call_callback =
      luatexbase.reset_callback, luatexbase.call_callback

local dummy_function = function () end

local error, warning, info, log =
    luatexbase.provides_module(luaotfload.module)

luaotfload.error        = error
luaotfload.warning      = warning
luaotfload.info         = info
luaotfload.log          = log

%    \end{macrocode}
%    We set the minimum version requirement for \LUATEX to v0.76,
%    because the font loader requires recent features like direct
%    attribute indexing and \luafunction{node.end_of_math()} that aren’t
%    available in earlier versions.\footnote{%
%     See Taco’s announcement of v0.76:
%     \url{http://comments.gmane.org/gmane.comp.tex.luatex.user/4042}
%     and this commit by Hans that introduced those features.
%     \url{http://repo.or.cz/w/context.git/commitdiff/a51f6cf6ee087046a2ae5927ed4edff0a1acec1b}.
%   }
%
%    \begin{macrocode}

local luatex_version = 76

if tex.luatexversion < luatex_version then
    warning("LuaTeX v%.2f is old, v%.2f is recommended.",
             tex.luatexversion/100,
             luatex_version   /100)
    --- we install a fallback for older versions as a safety
    if not node.end_of_math then
        local math_t          = node.id"math"
        local traverse_nodes  = node.traverse_id
        node.end_of_math = function (n)
            for n in traverse_nodes(math_t, n.next) do
                return n
            end
        end
    end
end

%    \end{macrocode}
%     Create $TEXMFCACHE if not present. This is necessary due to a bug
%     in Luatex-Fonts that surfaces if none of the possible cache
%     directories exists. We add a fixed version of lfs.mkdirs() first
%     that will be installed as soon as l-file.lua tries to insert its
%     buggy version.
%
%    \begin{macrocode}

local ostype      = os.type
local mkdirs = function (path)
  local full
  if ostype ~= "windows" and stringsub(path, 1, 1) == "/" then
    --- absolute path, force initial backslash
    full = ""
  end
  for sub in stringgmatch(path,"([^\\/]+)") do
    if full then
      full = full .. "/" .. sub
    else
      full = sub
    end
    if not lfsisdir(full) then
      lfsmkdir(full)
    end
  end
end

--- <hack version="2">

local backup_mkdirs -- just in case

local lfs_mt = getmetatable(lfs) or { } --- should be empty

lfs_mt.__newindex = function (t, k, v)
  if k == "mkdirs" then
    backup_mkdirs = v               --> backup
    rawset(t, "mkdirs", mkdirs)     --> ours
  else -- insert normally
    t[k] = v
  end
end

setmetatable(lfs, lfs_mt)

--- </hack>

%    \end{macrocode}
% \subsection{Module loading}
% We load the files imported from \CONTEXT with this function.
% It automatically prepends the prefix \fileent{luaotfload-} to its
% argument, so we can refer to the files with their actual \CONTEXT name.
%
%    \begin{macrocode}

local fl_prefix = "luaotfload" -- “luatex” for luatex-plain
local loadmodule = function (name)
    require(fl_prefix .."-"..name)
end

%    \end{macrocode}
% Before \TeX Live 2013 version, \LUATEX had a bug that made ofm fonts fail
% when called with their extension. There was a side-effect making ofm
% totally unloadable when luaotfload was present. The following lines are
% a patch for this bug. The utility of these lines is questionable as they
% are not necessary since \TeX Live 2013. They should be removed in the next
% version.
%
%    \begin{macrocode}
local Cs, P, lpegmatch = lpeg.Cs, lpeg.P, lpeg.match

local p_dot, p_slash = P".",  P"/"
local p_suffix       = (p_dot * (1 - p_dot - p_slash)^1 * P(-1)) / ""
local p_removesuffix = Cs((p_suffix + 1)^1)

local find_vf_file = function (name)
    local fullname = kpsefind_file(name, "ovf")
    if not fullname then
        --fullname = kpsefind_file(file.removesuffix(name), "ovf")
        fullname = kpsefind_file(lpegmatch(p_removesuffix, name), "ovf")
    end
    if fullname then
        log("loading virtual font file %s.", fullname)
    end
    return fullname
end

%    \end{macrocode}
% \subsection{Preparing the Font Loader}
% We treat the fontloader as a black box so behavior is consistent
% between formats.
% We do no longer run the intermediate wrapper file
% \fileent{luaotfload-fonts.lua} which we used to import from
% \href{http://standalone.contextgarden.net/current/context/experimental/tex/generic/context/luatex/}{\LUATEX-Plain}.
% Rather, we load the fontloader code directly in the same fashion as
% \identifier{luatex-fonts}.
% How this is executed depends on the presence on the \emphasis{merged
% font loader code}.
% In \identifier{luaotfload} this is contained in the file
% \fileent{luaotfload-merged.lua}.
% If this file cannot be found, the original libraries from \CONTEXT of
% which the merged code was composed are loaded instead.
% The imported font loader will call \luafunction{callback.register} once
% while reading \fileent{font-def.lua}.
% This is unavoidable unless we modify the imported files, but harmless
% if we make it call a dummy instead.
% However, this problem might vanish if we decide to do the merging
% ourselves, like the \identifier{lualibs} package does.
% With this step we would obtain the freedom to load our own overrides in
% the process right where they are needed, at the cost of losing
% encapsulation.
% The decision on how to progress is currently on indefinite hold.
%
%    \begin{macrocode}

local starttime = os.gettimeofday()

local trapped_register  = callback.register
callback.register       = dummy_function

%    \end{macrocode}
% By default, the fontloader requires a number of \emphasis{private
% attributes} for internal use.
% These must be kept consistent with the attribute handling methods as
% provided by \identifier{luatexbase}.
% Our strategy is to override the function that allocates new attributes
% before we initialize the font loader, making it a wrapper around
% \luafunction{luatexbase.new_attribute}.\footnote{%
%     Many thanks, again, to Hans Hagen for making this part
%     configurable!
% }
% The attribute identifiers are prefixed “\fileent{luaotfload@}” to
% avoid name clashes.
%
%    \begin{macrocode}

do
    local new_attribute    = luatexbase.new_attribute
    local the_attributes   = luatexbase.attributes

    attributes = attributes or { }

    attributes.private = function (name)
        local attr   = "luaotfload@" .. name --- used to be: “otfl@”
        local number = the_attributes[attr]
        if not number then
            number = new_attribute(attr)
        end
        return number
    end
end

%    \end{macrocode}
% These next lines replicate the behavior of \fileent{luatex-fonts.lua}.
%
%    \begin{macrocode}

local context_environment = { }

local push_namespaces = function ()
    log("push namespace for font loader")
    local normalglobal = { }
    for k, v in next, _G do
        normalglobal[k] = v
    end
    return normalglobal
end

local pop_namespaces = function (normalglobal, isolate)
    if normalglobal then
        local _G = _G
        local mode = "non-destructive"
        if isolate then mode = "destructive" end
        log("pop namespace from font loader -- " .. mode)
        for k, v in next, _G do
            if not normalglobal[k] then
                context_environment[k] = v
                if isolate then
                    _G[k] = nil
                end
            end
        end
        for k, v in next, normalglobal do
            _G[k] = v
        end
        -- just to be sure:
        setmetatable(context_environment,_G)
    else
        log("irrecoverable error during pop_namespace: no globals to restore")
        os.exit()
    end
end

luaotfload.context_environment  = context_environment
luaotfload.push_namespaces      = push_namespaces
luaotfload.pop_namespaces       = pop_namespaces

local our_environment = push_namespaces()

%    \end{macrocode}
% The font loader requires that the attribute with index zero be zero.
% We happily oblige.
% (Cf. \fileent{luatex-fonts-nod.lua}.)
%
%    \begin{macrocode}

tex.attribute[0] = 0

%    \end{macrocode}
% Now that things are sorted out we can finally load the fontloader.
%
%    \begin{macrocode}

loadmodule"merged.lua"
---loadmodule"font-odv.lua" --- <= Devanagari support from Context

if fonts then

    if not fonts._merge_loaded_message_done_ then
        --- a program talking first person -- HH sure believes in strong AI ...
        log[[“I am using the merged version of 'luaotfload.lua' here. If]]
        log[[ you run into problems or experience unexpected behaviour,]]
        log[[ and if you have ConTeXt installed you can try to delete the]]
        log[[ file 'luaotfload-font-merged.lua' as I might then use the]]
        log[[ possibly updated libraries. The merged version is not]]
        log[[ supported as it is a frozen instance. Problems can be]]
        log[[ reported to the ConTeXt mailing list.”]]
    end
    fonts._merge_loaded_message_done_ = true

else--- the loading sequence is known to change, so this might have to
    --- be updated with future updates!
    --- do not modify it though unless there is a change to the merged
    --- package!
    loadmodule("l-lua.lua")
    loadmodule("l-lpeg.lua")
    loadmodule("l-function.lua")
    loadmodule("l-string.lua")
    loadmodule("l-table.lua")
    loadmodule("l-io.lua")
    loadmodule("l-file.lua")
    loadmodule("l-boolean.lua")
    loadmodule("l-math.lua")
    loadmodule("util-str.lua")
    loadmodule('luatex-basics-gen.lua')
    loadmodule('data-con.lua')
    loadmodule('luatex-basics-nod.lua')
    loadmodule('font-ini.lua')
    loadmodule('font-con.lua')
    loadmodule('luatex-fonts-enc.lua')
    loadmodule('font-cid.lua')
    loadmodule('font-map.lua')
    loadmodule('luatex-fonts-syn.lua')
    loadmodule('luatex-fonts-tfm.lua')
    loadmodule('font-oti.lua')
    loadmodule('font-otf.lua')
    loadmodule('font-otb.lua')
    loadmodule('node-inj.lua')
    loadmodule('font-ota.lua')
    loadmodule('font-otn.lua')
    loadmodule('font-otp.lua')--- since 2013-04-23
    loadmodule('luatex-fonts-lua.lua')
    loadmodule('font-def.lua')
    loadmodule('luatex-fonts-def.lua')
    loadmodule('luatex-fonts-ext.lua')
    loadmodule('luatex-fonts-cbk.lua')
end --- non-merge fallback scope

%    \end{macrocode}
% Here we adjust the globals created during font loader initialization.
% If the second argument to \luafunction{pop_namespaces()} is \verb|true|
% this will restore the state of \luafunction{_G}, eliminating every
% global generated since the last call to \luafunction{push_namespaces()}.
% At the moment we see no reason to do this, and since the font loader is
% considered an essential part of \identifier{luatex} as well as a very
% well organized piece of code, we happily concede it the right to add to
% \luafunction{_G} if needed.
%
%    \begin{macrocode}

pop_namespaces(our_environment, false)-- true)

log("fontloader loaded in %0.3f seconds", os.gettimeofday()-starttime)

%    \end{macrocode}
%     Restore original \luafunction{kpse.expand_path} function.
%
%    \begin{macrocode}

if normal_expand_path ~= nil then
    kpse.expand_path = normal_expand_path
    phantom_kpse     = nil
end

%    \end{macrocode}
% \subsection{Callbacks}
% After the fontloader is ready we can restore the callback trap from
% \identifier{luatexbase}.
%
%    \begin{macrocode}

callback.register = trapped_register

%    \end{macrocode}
% We do our own callback handling with the means provided by luatexbase.
% Note: \luafunction{pre_linebreak_filter} and \luafunction{hpack_filter}
% are coupled in \CONTEXT in the concept of \emphasis{node processor}.
%
%    \begin{macrocode}

add_to_callback("pre_linebreak_filter",
                nodes.simple_font_handler,
                "luaotfload.node_processor",
                1)
add_to_callback("hpack_filter",
                nodes.simple_font_handler,
                "luaotfload.node_processor",
                1)
add_to_callback("find_vf_file",
                find_vf_file, "luaotfload.find_vf_file")

loadmodule"lib-dir.lua"    --- required by luaofload-database.lua
loadmodule"override.lua"   --- “luat-ovr”

logs.set_loglevel(config.luaotfload.loglevel)

%    \end{macrocode}
% Now we load the modules written for \identifier{luaotfload}.
%
%    \begin{macrocode}
loadmodule"loaders.lua"    --- “font-pfb” new in 2.0, added 2011
loadmodule"database.lua"   --- “font-nms”
loadmodule"colors.lua"     --- “font-clr”

%    \end{macrocode}
% Relying on the \verb|name:| resolver for everything has been the source
% of permanent trouble with the database.
% With the introduction of the new syntax parser we now have enough
% granularity to distinguish between the \XETEX emulation layer and the
% genuine \verb|name:| and \verb|file:| lookups of \LUATEX-Fonts.
% Another benefit is that we can now easily plug in or replace new lookup
% behaviors if necessary.
% The name resolver remains untouched, but it calls
% \luafunction{fonts.names.resolve()} internally anyways (see
% \fileent{luaotfload-database.lua}).
%
%    \begin{macrocode}

local request_resolvers   = fonts.definers.resolvers
local formats             = fonts.formats
formats.ofm               = "type1"

%    \end{macrocode}
% \identifier{luaotfload} promises easy access to system fonts.
% Without additional precautions, this cannot be achieved by
% \identifier{kpathsea} alone, because it searches only the
% \fileent{texmf} directories by default.
% Although it is possible for \identifier{kpathsea} to include extra
% paths by adding them to the \verb|OSFONTDIR| environment variable,
% this is still short of the goal »\emphasis{it just works!}«.
% When building the font database \identifier{luaotfload} scans
% system font directories anyways, so we already have all the
% information for looking sytem fonts.
% With the release version 2.2 the file names are indexed in the database
% as well and we are ready to resolve \verb|file:| lookups this way.
% Thus we no longer need to call the \identifier{kpathsea} library in
% most cases when looking up font files, only when generating the database.
%
%    \begin{macrocode}

local resolvefile = fonts.names.crude_file_lookup
--local resolvefile = fonts.names.crude_file_lookup_verbose

function request_resolvers.file(specification)
    local name    = resolvefile(specification.name)
    local suffix  = file.suffix(name)
    if formats[suffix] then
        specification.forced  = suffix
        specification.name    = file.removesuffix(name)
    else
        specification.name = name
    end
end


%    \end{macrocode}
% We classify as \verb|anon:| those requests that have neither a
% prefix nor brackets. According to Khaled\footnote{%
%     \url{https://github.com/phi-gamma/luaotfload/issues/4#issuecomment-17090553}.
% }
% they are the \XETEX equivalent of a \verb|name:| request, so we will be
% treating them as such.
%
%    \begin{macrocode}

--request_resolvers.anon = request_resolvers.name

%    \end{macrocode}
% There is one drawback, though.
% This syntax is also used for requesting fonts in \identifier{Type1}
% (\abbrev{tfm}, \abbrev{ofm}) format.
% These are essentially \verb|file:| lookups and must be caught before
% the \verb|name:| resolver kicks in, lest they cause the database to
% update.
% Even if we were to require the \verb|file:| prefix for all
% \identifier{Type1} requests, tests have shown that certain fonts still
% include further fonts (e.~g. \fileent{omlgcb.ofm} will ask for
% \fileent{omsecob.tfm}) \emphasis{using the old syntax}.
% For this reason, we introduce an extra check with an early return.
%
%    \begin{macrocode}

local type1_formats = { "tfm", "ofm", }

request_resolvers.anon = function (specification)
    local name = specification.name
    for i=1, #type1_formats do
        local format = type1_formats[i]
        if resolvers.findfile(name, format) then
            specification.name = file.addsuffix(name, format)
            return
        end
    end
    --- under some weird circumstances absolute paths get
    --- passed to the definer; we have to catch them
    --- before the name: resolver misinterprets them.
    name = specification.specification
    local exists, _ = lfsisfile(name)
    if exists then --- garbage; we do this because we are nice,
                   --- not because it is correct
        logs.names_report("log", 1, "load", "file “%s” exists", name)
        logs.names_report("log", 1, "load",
          "... overriding borked anon: lookup with path: lookup")
        specification.name = name
        request_resolvers.path(specification)
        return
    end
    request_resolvers.name(specification)
end

%    \end{macrocode}
% Prior to version 2.2, \identifier{luaotfload} did not distinguish
% \verb|file:| and \verb|path:| lookups, causing complications with the
% resolver.
% Now we test if the requested name is an absolute path in the file
% system, otherwise we fall back to the \verb|file:| lookup.
%
%    \begin{macrocode}

request_resolvers.path = function (specification)
    local name       = specification.name
    local exists, _  = lfsisfile(name)
    if not exists then -- resort to file: lookup
        logs.names_report("log", 1, "load",
          "path lookup of “%s” unsuccessful, falling back to file:",
          name)
        request_resolvers.file(specification)
    else
      local suffix = file.suffix(name)
      if formats[suffix] then
        specification.forced  = suffix
        specification.name    = file.removesuffix(name)
      else
        specification.name = name
      end
    end
end

%    \end{macrocode}
% We create a callback for patching fonts on the fly, to be used by other
% packages.
% It initially contains the empty function that we are going to override
% below.
%
%    \begin{macrocode}

create_callback("luaotfload.patch_font", "simple", dummy_function)

%    \end{macrocode}
% \subsection{\CONTEXT override}
% \label{define-font}
% We provide a simplified version of the original font definition
% callback.
%
%    \begin{macrocode}

local read_font_file = fonts.definers.read

--- spec -> size -> id -> tmfdata
local patch_defined_font = function (specification, size, id)
    local tfmdata = read_font_file(specification, size, id)
    if type(tfmdata) == "table" and tfmdata.shared then
        --- We need to test for the “shared” field here
        --- or else the fontspec capheight callback will
        --- operate on tfm fonts.
        call_callback("luaotfload.patch_font", tfmdata)
    end
    return tfmdata
end

reset_callback("define_font")

%    \end{macrocode}
% Finally we register the callbacks.
%
%    \begin{macrocode}

local font_definer = config.luaotfload.definer

if font_definer == "generic"  then
  add_to_callback("define_font",
                  fonts.definers.read,
                  "luaotfload.define_font",
                  1)
elseif font_definer == "patch"  then
  add_to_callback("define_font",
                  patch_defined_font,
                  "luaotfload.define_font",
                  1)
end

loadmodule"features.lua"    --- contains what was “font-ltx” and “font-otc”
loadmodule"extralibs.lua"   --- load additional Context libraries
loadmodule"auxiliary.lua"   --- additionaly high-level functionality (new)

-- vim:tw=71:sw=4:ts=4:expandtab

%    \end{macrocode}
%
% \iffalse
%</lua>
% \fi
%
% \section{\fileent{luaotfload.sty}}
%
% \iffalse
%<*package>
% \fi
%
%    Classical Plain+\LATEX package initialization.
%
%    \begin{macrocode}
\csname ifluaotfloadloaded\endcsname
\let\ifluaotfloadloaded\endinput
\bgroup\expandafter\expandafter\expandafter\egroup
\expandafter\ifx\csname ProvidesPackage\endcsname\relax
  \input luatexbase.sty
\else
  \NeedsTeXFormat{LaTeX2e}
  \ProvidesPackage{luaotfload}%
    [2013/05/20 v2.2c OpenType layout system]
  \RequirePackage{luatexbase}
\fi
\ifnum\luatexversion<76
  %% here some deprecation warning would be in order
  \RequireLuaModule{lualibs}
  \RequireLuaModule{luaotfload-legacy}
\else
  \RequireLuaModule{luaotfload}
\fi
\endinput
%    \end{macrocode}
% \iffalse
%</package>
% \fi
%
% \clearpage
% \section{The GNU GPL License v2}
%
% The GPL requires the complete license text to be distributed along
% with the code. I recommend the canonical source, instead:
% \url{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html}.
% But if you insist on an included copy, here it is.
% You might want to zoom in.
%
% \newsavebox{\gpl}
% \begin{lrbox}{\gpl}
% \begin{minipage}{3\textwidth}
% \columnsep=3\columnsep
% \begin{multicols}{3}
% \begin{center}
% {\Large GNU GENERAL PUBLIC LICENSE\par}
% \bigskip
% {Version 2, June 1991}
% \end{center}
%
% \begin{center}
% {\parindent 0in
%
% Copyright \textcopyright\ 1989, 1991 Free Software Foundation, Inc.
%
% \bigskip
%
% 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
%
% \bigskip
%
% Everyone is permitted to copy and distribute verbatim copies
% of this license document, but changing it is not allowed.
% }
% \end{center}
%
% \begin{center}
% {\bf\large Preamble}
% \end{center}
%
%
% The licenses for most software are designed to take away your freedom to
% share and change it.  By contrast, the GNU General Public License is
% intended to guarantee your freedom to share and change free software---to
% make sure the software is free for all its users.  This General Public
% License applies to most of the Free Software Foundation's software and to
% any other program whose authors commit to using it.  (Some other Free
% Software Foundation software is covered by the GNU Library General Public
% License instead.)  You can apply it to your programs, too.
%
% When we speak of free software, we are referring to freedom, not price.
% Our General Public Licenses are designed to make sure that you have the
% freedom to distribute copies of free software (and charge for this service
% if you wish), that you receive source code or can get it if you want it,
% that you can change the software or use pieces of it in new free programs;
% and that you know you can do these things.
%
% To protect your rights, we need to make restrictions that forbid anyone to
% deny you these rights or to ask you to surrender the rights.  These
% restrictions translate to certain responsibilities for you if you
% distribute copies of the software, or if you modify it.
%
% For example, if you distribute copies of such a program, whether gratis or
% for a fee, you must give the recipients all the rights that you have.  You
% must make sure that they, too, receive or can get the source code.  And
% you must show them these terms so they know their rights.
%
% We protect your rights with two steps: (1) copyright the software, and (2)
% offer you this license which gives you legal permission to copy,
% distribute and/or modify the software.
%
% Also, for each author's protection and ours, we want to make certain that
% everyone understands that there is no warranty for this free software.  If
% the software is modified by someone else and passed on, we want its
% recipients to know that what they have is not the original, so that any
% problems introduced by others will not reflect on the original authors'
% reputations.
%
% Finally, any free program is threatened constantly by software patents.
% We wish to avoid the danger that redistributors of a free program will
% individually obtain patent licenses, in effect making the program
% proprietary.  To prevent this, we have made it clear that any patent must
% be licensed for everyone's free use or not licensed at all.
%
% The precise terms and conditions for copying, distribution and
% modification follow.
%
% \begin{center}
% {\Large \sc Terms and Conditions For Copying, Distribution and
%   Modification}
% \end{center}
%
% \begin{enumerate}
% \item
% This License applies to any program or other work which contains a notice
% placed by the copyright holder saying it may be distributed under the
% terms of this General Public License.  The ``Program'', below, refers to
% any such program or work, and a ``work based on the Program'' means either
% the Program or any derivative work under copyright law: that is to say, a
% work containing the Program or a portion of it, either verbatim or with
% modifications and/or translated into another language.  (Hereinafter,
% translation is included without limitation in the term ``modification''.)
% Each licensee is addressed as ``you''.
%
% Activities other than copying, distribution and modification are not
% covered by this License; they are outside its scope.  The act of
% running the Program is not restricted, and the output from the Program
% is covered only if its contents constitute a work based on the
% Program (independent of having been made by running the Program).
% Whether that is true depends on what the Program does.
%
% \item You may copy and distribute verbatim copies of the Program's source
%   code as you receive it, in any medium, provided that you conspicuously
%   and appropriately publish on each copy an appropriate copyright notice
%   and disclaimer of warranty; keep intact all the notices that refer to
%   this License and to the absence of any warranty; and give any other
%   recipients of the Program a copy of this License along with the Program.
%
% You may charge a fee for the physical act of transferring a copy, and you
% may at your option offer warranty protection in exchange for a fee.
%
% \item
% You may modify your copy or copies of the Program or any portion
% of it, thus forming a work based on the Program, and copy and
% distribute such modifications or work under the terms of Section 1
% above, provided that you also meet all of these conditions:
%
% \begin{enumerate}
%
% \item
% You must cause the modified files to carry prominent notices stating that
% you changed the files and the date of any change.
%
% \item
% You must cause any work that you distribute or publish, that in
% whole or in part contains or is derived from the Program or any
% part thereof, to be licensed as a whole at no charge to all third
% parties under the terms of this License.
%
% \item
% If the modified program normally reads commands interactively
% when run, you must cause it, when started running for such
% interactive use in the most ordinary way, to print or display an
% announcement including an appropriate copyright notice and a
% notice that there is no warranty (or else, saying that you provide
% a warranty) and that users may redistribute the program under
% these conditions, and telling the user how to view a copy of this
% License.  (Exception: if the Program itself is interactive but
% does not normally print such an announcement, your work based on
% the Program is not required to print an announcement.)
%
% \end{enumerate}
%
%
% These requirements apply to the modified work as a whole.  If
% identifiable sections of that work are not derived from the Program,
% and can be reasonably considered independent and separate works in
% themselves, then this License, and its terms, do not apply to those
% sections when you distribute them as separate works.  But when you
% distribute the same sections as part of a whole which is a work based
% on the Program, the distribution of the whole must be on the terms of
% this License, whose permissions for other licensees extend to the
% entire whole, and thus to each and every part regardless of who wrote it.
%
% Thus, it is not the intent of this section to claim rights or contest
% your rights to work written entirely by you; rather, the intent is to
% exercise the right to control the distribution of derivative or
% collective works based on the Program.
%
% In addition, mere aggregation of another work not based on the Program
% with the Program (or with a work based on the Program) on a volume of
% a storage or distribution medium does not bring the other work under
% the scope of this License.
%
% \item
% You may copy and distribute the Program (or a work based on it,
% under Section 2) in object code or executable form under the terms of
% Sections 1 and 2 above provided that you also do one of the following:
%
% \begin{enumerate}
%
% \item
%
% Accompany it with the complete corresponding machine-readable
% source code, which must be distributed under the terms of Sections
% 1 and 2 above on a medium customarily used for software interchange; or,
%
% \item
%
% Accompany it with a written offer, valid for at least three
% years, to give any third party, for a charge no more than your
% cost of physically performing source distribution, a complete
% machine-readable copy of the corresponding source code, to be
% distributed under the terms of Sections 1 and 2 above on a medium
% customarily used for software interchange; or,
%
% \item
%
% Accompany it with the information you received as to the offer
% to distribute corresponding source code.  (This alternative is
% allowed only for noncommercial distribution and only if you
% received the program in object code or executable form with such
% an offer, in accord with Subsection b above.)
%
% \end{enumerate}
%
%
% The source code for a work means the preferred form of the work for
% making modifications to it.  For an executable work, complete source
% code means all the source code for all modules it contains, plus any
% associated interface definition files, plus the scripts used to
% control compilation and installation of the executable.  However, as a
% special exception, the source code distributed need not include
% anything that is normally distributed (in either source or binary
% form) with the major components (compiler, kernel, and so on) of the
% operating system on which the executable runs, unless that component
% itself accompanies the executable.
%
% If distribution of executable or object code is made by offering
% access to copy from a designated place, then offering equivalent
% access to copy the source code from the same place counts as
% distribution of the source code, even though third parties are not
% compelled to copy the source along with the object code.
%
% \item
% You may not copy, modify, sublicense, or distribute the Program
% except as expressly provided under this License.  Any attempt
% otherwise to copy, modify, sublicense or distribute the Program is
% void, and will automatically terminate your rights under this License.
% However, parties who have received copies, or rights, from you under
% this License will not have their licenses terminated so long as such
% parties remain in full compliance.
%
% \item
% You are not required to accept this License, since you have not
% signed it.  However, nothing else grants you permission to modify or
% distribute the Program or its derivative works.  These actions are
% prohibited by law if you do not accept this License.  Therefore, by
% modifying or distributing the Program (or any work based on the
% Program), you indicate your acceptance of this License to do so, and
% all its terms and conditions for copying, distributing or modifying
% the Program or works based on it.
%
% \item
% Each time you redistribute the Program (or any work based on the
% Program), the recipient automatically receives a license from the
% original licensor to copy, distribute or modify the Program subject to
% these terms and conditions.  You may not impose any further
% restrictions on the recipients' exercise of the rights granted herein.
% You are not responsible for enforcing compliance by third parties to
% this License.
%
% \item
% If, as a consequence of a court judgment or allegation of patent
% infringement or for any other reason (not limited to patent issues),
% conditions are imposed on you (whether by court order, agreement or
% otherwise) that contradict the conditions of this License, they do not
% excuse you from the conditions of this License.  If you cannot
% distribute so as to satisfy simultaneously your obligations under this
% License and any other pertinent obligations, then as a consequence you
% may not distribute the Program at all.  For example, if a patent
% license would not permit royalty-free redistribution of the Program by
% all those who receive copies directly or indirectly through you, then
% the only way you could satisfy both it and this License would be to
% refrain entirely from distribution of the Program.
%
% If any portion of this section is held invalid or unenforceable under
% any particular circumstance, the balance of the section is intended to
% apply and the section as a whole is intended to apply in other
% circumstances.
%
% It is not the purpose of this section to induce you to infringe any
% patents or other property right claims or to contest validity of any
% such claims; this section has the sole purpose of protecting the
% integrity of the free software distribution system, which is
% implemented by public license practices.  Many people have made
% generous contributions to the wide range of software distributed
% through that system in reliance on consistent application of that
% system; it is up to the author/donor to decide if he or she is willing
% to distribute software through any other system and a licensee cannot
% impose that choice.
%
% This section is intended to make thoroughly clear what is believed to
% be a consequence of the rest of this License.
%
% \item
% If the distribution and/or use of the Program is restricted in
% certain countries either by patents or by copyrighted interfaces, the
% original copyright holder who places the Program under this License
% may add an explicit geographical distribution limitation excluding
% those countries, so that distribution is permitted only in or among
% countries not thus excluded.  In such case, this License incorporates
% the limitation as if written in the body of this License.
%
% \item
% The Free Software Foundation may publish revised and/or new versions
% of the General Public License from time to time.  Such new versions will
% be similar in spirit to the present version, but may differ in detail to
% address new problems or concerns.
%
% Each version is given a distinguishing version number.  If the Program
% specifies a version number of this License which applies to it and ``any
% later version'', you have the option of following the terms and conditions
% either of that version or of any later version published by the Free
% Software Foundation.  If the Program does not specify a version number of
% this License, you may choose any version ever published by the Free Software
% Foundation.
%
% \item
% If you wish to incorporate parts of the Program into other free
% programs whose distribution conditions are different, write to the author
% to ask for permission.  For software which is copyrighted by the Free
% Software Foundation, write to the Free Software Foundation; we sometimes
% make exceptions for this.  Our decision will be guided by the two goals
% of preserving the free status of all derivatives of our free software and
% of promoting the sharing and reuse of software generally.
%
% \begin{center}
% {\Large\sc
% No Warranty
% }
% \end{center}
%
% \item
% {\sc Because the program is licensed free of charge, there is no warranty
% for the program, to the extent permitted by applicable law.  Except when
% otherwise stated in writing the copyright holders and/or other parties
% provide the program ``as is'' without warranty of any kind, either expressed
% or implied, including, but not limited to, the implied warranties of
% merchantability and fitness for a particular purpose.  The entire risk as
% to the quality and performance of the program is with you.  Should the
% program prove defective, you assume the cost of all necessary servicing,
% repair or correction.}
%
% \item
% {\sc In no event unless required by applicable law or agreed to in writing
% will any copyright holder, or any other party who may modify and/or
% redistribute the program as permitted above, be liable to you for damages,
% including any general, special, incidental or consequential damages arising
% out of the use or inability to use the program (including but not limited
% to loss of data or data being rendered inaccurate or losses sustained by
% you or third parties or a failure of the program to operate with any other
% programs), even if such holder or other party has been advised of the
% possibility of such damages.}
%
% \end{enumerate}
%
%
% \begin{center}
% {\Large\sc End of Terms and Conditions}
% \end{center}
%
%
% \pagebreak[2]
%
% \section*{Appendix: How to Apply These Terms to Your New Programs}
%
% If you develop a new program, and you want it to be of the greatest
% possible use to the public, the best way to achieve this is to make it
% free software which everyone can redistribute and change under these
% terms.
%
%   To do so, attach the following notices to the program.  It is safest to
%   attach them to the start of each source file to most effectively convey
%   the exclusion of warranty; and each file should have at least the
%   ``copyright'' line and a pointer to where the full notice is found.
%
% \begin{quote}
% one line to give the program's name and a brief idea of what it does. \\
% Copyright (C) yyyy  name of author \\
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
% \end{quote}
%
% Also add information on how to contact you by electronic and paper mail.
%
% If the program is interactive, make it output a short notice like this
% when it starts in an interactive mode:
%
% \begin{quote}
% Gnomovision version 69, Copyright (C) yyyy  name of author \\
% Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. \\
% This is free software, and you are welcome to redistribute it
% under certain conditions; type `show c' for details.
% \end{quote}
%
%
% The hypothetical commands {\tt show w} and {\tt show c} should show the
% appropriate parts of the General Public License.  Of course, the commands
% you use may be called something other than {\tt show w} and {\tt show c};
% they could even be mouse-clicks or menu items---whatever suits your
% program.
%
% You should also get your employer (if you work as a programmer) or your
% school, if any, to sign a ``copyright disclaimer'' for the program, if
% necessary.  Here is a sample; alter the names:
%
% \begin{quote}
% Yoyodyne, Inc., hereby disclaims all copyright interest in the program \\
% `Gnomovision' (which makes passes at compilers) written by James Hacker. \\
%
% signature of Ty Coon, 1 April 1989 \\
% Ty Coon, President of Vice
% \end{quote}
%
%
% This General Public License does not permit incorporating your program
% into proprietary programs.  If your program is a subroutine library, you
% may consider it more useful to permit linking proprietary applications
% with the library.  If this is what you want to do, use the GNU Library
% General Public License instead of this License.
%
% \end{multicols}
% \end{minipage}
% \end{lrbox}
%
% \begin{center}
% \scalebox{0.33}{\usebox{\gpl}}
% \end{center}
%
% \Finale
\endinput