path: root/luaotfload.dtx

% \iffalse meta-comment
%
% Copyright (C) 2009-2010 by Elie Roux    <elie.roux@telecom-bretagne.eu>
%                        and Khaled Hosny <khaledhosny@eglug.org>
%
% This work is under the CC0 license.
%
% This work consists of the main source file luaotfload.dtx
% and the derived files
%    luaotfload.sty, luaotfload.lua
%
% Unpacking:
%    tex luaotfload.dtx
%
% Documentation:
%    pdflatex 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 2010/05/13 v1.08 ConTeXt font loading system}
\Msg{************************************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax

\preamble
This is a generated file.

Copyright (C) 2009-2010 by by Elie Roux    <elie.roux@telecom-bretagne.eu>
                          and Khaled Hosny <khaledhosny@eglug.org>

This work is under the CC0 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/luaodfload}%
  \file{luaotfload.sty}{\from{luaotfload.dtx}{package}}%
}

% The following hacks are to generate a lua file with lua comments starting by
% -- 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}%
  [2010/05/13 v1.08 ConTeXt font loading system]%
\documentclass{ltxdoc}
\usepackage{metalogo,multicol,mdwlist,fancyvrb}
\usepackage[colorlinks=true]{hyperref}

\def\LuaTeX{Lua\TeX}
\def\ConTeXt{Con\TeX t}

\EnableCrossrefs
\CodelineIndex
\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 \textsf{luaotfload} package}
% \date{2010/05/13 v1.08}
% \author{     Elie Roux\footnote{\texttt{elie.roux@telecom-bretagne.eu}}
%         \and Khaled Hosny\footnote{\texttt{khaledhosny@eglug.org}}}
%
% \maketitle
%
% \begin{abstract}
% This package is an adaptation of the \ConTeXt\ font loading system,
% providing the ability to load \textsf{OpenType} fonts with extended font
% loading syntax supporting a large selection of OpenType font features.
% \end{abstract}
%
% \tableofcontents
%
% \section{Documentation}
%
% \subsection{Introduction}
%
% Font management and installation has always been painful with \TeX.
% A lot of files are needed for one font (tfm, pfb,
% map, fd, vf), and as \TeX\ is 8-bit each font is limited to 256 characters.
% But the font world has
% evolved since \TeX, and new standard types of fonts have appeared, most
% notably
% \textsf{TrueType} and \textsf{OpenType} fonts. These fonts can contain a lot
% of characters, and have some functionalities (ligatures, old-style numbers,
% small capitals, etc.). They are everywhere, as the system fonts and most
% modern text software fonts are of this type. Until now the only
% way to use them directly with one of the descendents of \TeX\ was to use
% them with \XeTeX.
%
% Unlike \XeTeX , \LuaTeX\ does not provide facilities for these fonts by
% default, but it provides a way to hook Lua code in some points of the \TeX\
% processing; for instance, we can improve the font loading system, and this
% is what we do in this package.
%
% \subsection{Loading fonts}
%
% \textsf{luaotfload} supports an extended font loading syntax which looks
% like:
%
% \begin{center}
% |\font\foo={|\meta{prefix}|:|\meta{font name}|:|\meta{font features}|}| \meta{\TeX\ font features}
% \end{center}
%
% \noindent
% The curly brackets are optional and are used for escaping spaces in font
% names (double quotes can also used for the same purpose).
%
% \paragraph{Prefix}
%
% The \meta{prefix} be either \texttt{file:} or \texttt{name:}, which specify
% whether to use a select the font from its filename or font name,
% respectively. If no prefix is specified, then \texttt{file:} is assumed.
%
% For compatibility with \XeTeX, surrounding the \meta{font name}
% with square brackets is synonymous to using the \texttt{file:} prefix.
%
% Accessing fonts by fontname allows loading system installed fonts as well as
% \textsc{texmf} ones, and requires a font names database that must be
% pre-generated using the bundled |mkluatexfontdb.lua| script.^^A
% \footnote{Run |mkluatexfontdb.lua --help| for help and usage information}
%
% \paragraph{Font name}
%
% The \meta{font name} can be either a font filename or actual font name
% based on the \meta{prefix} as mentioned above.
%
% Fonts loaded by filename may either include their absolute path in the
% filesystem or consist of just the filename with a path.
% If no path is specified then \textsf{kpathsea} is used to locate the font
% (which will typically be in the \textsc{texmf} tree or the current
% directory).
%
% For example,
% \begin{quote}
% \begin{verbatim}
% \font\1={file:ec-lmr10} at 10pt
% \font\2={/Users/Shared/Fonts/aldus.otf} at 11pt
% \font\3={name:TeX Gyre Pagella} at 9pt
% \end{verbatim}
% \end{quote}
%
%
% \paragraph{Font features}
%
% \meta{font features} are a list of items separated by semi-colons,
% which are either
% |key=value| font parameters, or switches to enable/disable certain font
% features in the form of |+feat|/|-feat|.
% The supported keys are:
% \begin{description}
% \item [mode] \hfill \\
% \textsf{luaotfload} has two OpenType processing modes;
% \texttt{base} or \texttt{node}.
% Using \texttt{mode=base}
% only supports a subset of OpenType features and works by mapping those
% features to traditional \TeX\ ligature and kerning mechanisms and is a bit
% faster
% Using \texttt{mode=node} hopefully supports OpenType fully and
% works by direct processing of the node list with Lua; it is slower and
% is not designed to work in math mode.
%
% By default \texttt{mode=base} is used, but it is advisable to always
% enable \texttt{node} made, except for math fonts, otherwise many OpenType
% features will not function properly or even not work at all, especially for
% advanced scripts like Arabic.
%
% \item [script] \hfill \\
% OpenType script string, default value is |dflt|. Some fonts don't assign
% features to the |dflt| script, in which case the script need to be set
% explicitly.
%
% \item [language] \hfill \\
% OpenType language string, default value is |latn|.
%
% \item [featurefile] \hfill \\
% feature files are textual representation of OpenType tables and can be used to
% extend OpenType features of the font on fly. The file name of the feature file
% is passed, then features defined in the file can be enabled/disabled like any
% other feature. The actual syntax is described at
% \url{http://fontforge.sourceforge.net/featurefile.html} and
% \url{http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html}.
%
% For example, to set a |tkrn| feature from |mykern.fea| file:
%
% |\font\lmr=Latin Modern Roman:featurefile=mykern.fea;+tkrn|
%
% \item [color] \hfill \\
% font color, defined as a triplet of two-digit hexadecimal RGB values, with
% optionally another value for the transparency
% (where |00| is completely transparent and |FF| is opaque.)
%
% For example, to set text in semitransparent red:
%
% |\font\lmr=Latin Modern Roman:color=FF0000BB|
%
% \item [protrusion \& expansion] \hfill \\
% Both keys control microtypographic features of the font, namely glyph
% protrusion and expansion. The value of the key is the name of predefined
% Lua tables of protrusion and expansion values; see the end of
% \texttt{otfl-font-dum.lua} file for an example of such tables. The only
% predefined value is |default|.
%
% For example, to enable default protrusion\footnote{You also need to set
% |\pdfprotrudechars2 \pdfadjustspacing2| to activate protrusion and expansion,
% respectively. See PDF\TeX\ manual for details}:
%
% |\font\lmr=Latin Modern Roman:protrusion=default|
%
% \end{description}
%
% \subparagraph{Non-standard font features}
% \textsf{luaotfload} defines some additional font feature not defined in
% OpenType, currently three features are defined:
%
% \begin{itemize*}
% \item \texttt{anum}: replaces European numbers with eastern Arabic numbers or
% Persian numbers, depending on the value of |language|.
% \item \texttt{tlig}: applies legacy \TeX\ ligatures (|``''-- -- !` ?` <<>>|).
% \item \texttt{trep}: applies legacy \TeX\ replacements (|`'"|).
% \end{itemize*}
%
% (For \XeTeX\ users: these last two are the equivalent of writing
%  \texttt{mapping=text-tex} using \XeTeX's input remapping feature.)
%
% \subsection{Required \ConTeXt\ files}
%
% This package is a wrapper for several files taken from the \ConTeXt\ macro
% package. The philosophy is to let \ConTeXt\ do all the implementation and
% update these files from time to time. To do so we did not modify the files
% taken from \ConTeXt, we only changed their names to prevent name clashes.
% You can thus update the font system of this package simply by updating the
% files taken from \ConTeXt, without (theoretically) changing the \texttt{.sty}
% file nor the main \texttt{.lua} file.
%
% The \ConTeXt\ files are renamed by adding the prefix \texttt{otfl-} to them
% (\texttt{otfl} as \texttt{OTF L}oad). The files are:
%
% \begin{multicols}{3}
% \begin{itemize*}
% \item \texttt{luat-dum.lua}
% \item \texttt{data-con.lua}
% \item \texttt{node-ini.lua}
% \item \texttt{node-inj.lua}
% \item \texttt{node-fnt.lua}
% \item \texttt{node-dum.lua}
% \item \texttt{font-ini.lua}
% \item \texttt{font-tfm.lua}
% \item \texttt{font-cid.lua}
% \item \texttt{font-ott.lua}
% \item \texttt{font-otf.lua}
% \item \texttt{font-otd.lua}
% \item \texttt{font-oti.lua}
% \item \texttt{font-otb.lua}
% \item \texttt{font-otn.lua}
% \item \texttt{font-ota.lua}
% \item \texttt{font-otc.lua}
% \item \texttt{font-def.lua}
% \item \texttt{font-xtx.lua}
% \item \texttt{font-map.lua}
% \item \texttt{font-dum.lua}
% \end{itemize*}
% \end{multicols}
%
% The following files have been written for this package:
% \begin{multicols}{3}
% \begin{itemize*}
% \item \texttt{font-clr.lua}
% \item \texttt{font-nms.lua}
% \item \texttt{luat-ovr.lua}
% \end{itemize*}
% \end{multicols}
%
% \subsection{Troubleshooting}
%
% If you encounter problems with some fonts, please first update to the latest
% version of this package before reporting a bug, as this package is under
% active development.
%
% A very common problem is the lack of features for some OpenType fonts
% even when specified. It can be related to the fact that some fonts do not
% provide features for the |dflt| script, which is the default one in this
% package, so you may have to specify the script in the command line, for
% example:
%
% |\font\myfont = MyFont.otf:script=latn;+liga;|
%
% Also remember to set |mode=node| as most OpenType features
% (such as contextual substitution, |calt|), will not work without it.
%
% \part{\texttt{luaotfload.lua}}
%
% \iffalse
%<*lua>
% \fi
%
%    First some usual initializations.
%
%    \begin{macrocode}
module('luaotfload', package.seeall)

luaotfload.module = {
    name          = "luaotfload",
    version       = 1.08,
    date          = "2010/05/13",
    description   = "ConTeXt font loading system.",
    author        = "Elie Roux & Hans Hagen",
    copyright     = "Elie Roux",
    license       = "CC0"
}

luatexbase.provides_module(luaotfload.module)

%    \end{macrocode}
%
%    Some helper functions.
%
%    \begin{macrocode}

local format = string.format

local function log(...)
    luatexbase.module_log    ('luaotfload', format(...))
end

local function error(...)
    luatexbase.module_error  ('luaotfload', format(...))
end

local function warning(...)
    luatexbase.module_warning('luaotfload', format(...))
end

%    \end{macrocode}
%
%    The minimal required \LuaTeX\ version.
%
%    \begin{macrocode}

local luatex_version = 60

if tex.luatexversion < luatex_version then
    warning('LuaTeX v%.2f is old, v%.2f is recommended.',
             tex.luatexversion/100,
             luatex_version   /100)
end

%    \end{macrocode}
%
%    We load the \ConTeXt\ files with this function. It automatically adds the
%    \texttt{otfl-} prefix to it, so that we call it with the actual \ConTeXt\
%    name.
%
%    \begin{macrocode}

function luaotfload.loadmodule(name)
    local tofind = 'otfl-'..name
    local found = kpse.find_file(tofind,"tex")
    if found then
        log('loading file %s.', found)
        dofile(found)
    else
        error('file %s not found.', tofind)
    end
end

%    \end{macrocode}
%
%    We start loading some lua files. These two are some code not used by
%    \ConTeXt\ at all that allow other modules to be used, it provides some
%    low-level \ConTeXt\ functions.
%
%    \begin{macrocode}

luaotfload.loadmodule('luat-dum.lua') -- not used in context at all
luaotfload.loadmodule('luat-ovr.lua') -- override some luat-dum functions
luaotfload.loadmodule('data-con.lua') -- maybe some day we don't need this one

%    \end{macrocode}
%
%    This one is for node support.
%
%    \begin{macrocode}

luaotfload.loadmodule('node-ini.lua')

%    \end{macrocode}
%
%    By default \ConTeXt\ takes some private attributes for internal use. With
%    Plain and \LaTeX\ we can't do so, we use |\newluaattribute|. This
%    functions overrides a function defined in the previous module that
%    returns the number of a private attribute. We allocate new attributes in
%    the \texttt{.sty} file, and this function returns their number. Like this
%    we don't need any private attribute, and this package is compatible with
%    the others. We use the |otfl@| prefix for attributes.
%
%    \begin{macrocode}

function attributes.private(name)
    local number = luatexbase.attributes['otfl@'..name]
    if not number then
        error('asking for attribute %s, but not declared. '
            ..'Please report to the maintainer of luaotfload.',
               name)
    end
    return number
end

%    \end{macrocode}
%
%    Some more modules. We don't load neither \texttt{font-enc.lua} nor
%    \texttt{font-afm.lua} as it will never be used here.
%
%    We also remove a warning from \texttt{node-fnt.lua} as it is \ConTeXt\
%    specific.
%
%    \begin{macrocode}

tex.attribute[0] = 0

luaotfload.loadmodule('node-res.lua')
luaotfload.loadmodule('node-inj.lua')
luaotfload.loadmodule('node-fnt.lua')
luaotfload.loadmodule('node-dum.lua')

luaotfload.loadmodule('font-ini.lua')
luaotfload.loadmodule('font-tfm.lua')
luaotfload.loadmodule('font-cid.lua')
luaotfload.loadmodule('font-map.lua')
luaotfload.loadmodule('font-ott.lua')
luaotfload.loadmodule('font-otf.lua')
luaotfload.loadmodule('font-otd.lua')
luaotfload.loadmodule('font-oti.lua')
luaotfload.loadmodule('font-otb.lua')
luaotfload.loadmodule('font-otn.lua')
luaotfload.loadmodule('font-ota.lua')
luaotfload.loadmodule('font-otc.lua')
luaotfload.loadmodule('font-def.lua')
luaotfload.loadmodule('font-xtx.lua')
luaotfload.loadmodule('font-dum.lua')
luaotfload.loadmodule('font-nms.lua')
luaotfload.loadmodule('font-clr.lua')

%    \end{macrocode}
%
%    Finally two functions
%
%    \begin{macrocode}

function luaotfload.register_callbacks()
    luatexbase.add_to_callback('pre_linebreak_filter',
                                nodes.simple_font_handler,
                               'luaotfload.pre_linebreak_filter')
    luatexbase.add_to_callback('hpack_filter',
                                nodes.simple_font_handler,
                               'luaotfload.hpack_filter')
    luatexbase.reset_callback('define_font')
    luatexbase.add_to_callback('define_font',
                                fonts.define.read,
                               'luaotfload.define_font', 1)
    luatexbase.add_to_callback('find_vf_file',
                                fonts.vf.find,
                               'luaotfload.find_vf_file')
end

function luaotfload.unregister_callbacks()
    luatexbase.remove_from_callback('pre_linebreak_filter',
                                    'luaotfload.pre_linebreak_filter')
    luatexbase.remove_from_callback('hpack_filter',
                                    'luaotfload.hpack_filter')
    luatexbase.remove_from_callback('define_font',
                                    'luaotfload.define_font')
    luatexbase.remove_from_callback('find_vf_file',
                                     'luaotfload.find_vf_file')
end
%    \end{macrocode}
% \iffalse
%</lua>
% \fi
%
% \part{\texttt{luaotfload.sty}}
%
% \iffalse
%<*package>
% \fi
%
%    Classical Plain+\LaTeX\ package initialization.
%
%    \begin{macrocode}
\csname ifluaotfloadloaded\endcsname
\let\ifluaotfloadloaded\endinput

\expandafter\ifx\csname ProvidesPackage\endcsname\relax
  \input luatextra.sty
\else
  \NeedsTeXFormat{LaTeX2e}
  \ProvidesPackage{luaotfload}%
    [2010/05/13 v1.08 ConTeXt font loading system]
  \RequirePackage{luatextra}
\fi

\expandafter\edef\csname otfl@AtEnd\endcsname{%
  \catcode64 \the\catcode64\relax
}

\catcode64 11

%    \end{macrocode}
%
%    The attributes are allocated here. The |otfl@| prefix is added to prevent
%    name collision.
%
%    \begin{macrocode}

\newluatexattribute\otfl@state
\newluatexattribute\otfl@markbase
\newluatexattribute\otfl@markdone
\newluatexattribute\otfl@markmark
\newluatexattribute\otfl@cursbase
\newluatexattribute\otfl@curscurs
\newluatexattribute\otfl@cursdone
\newluatexattribute\otfl@kernpair
\newluatexattribute\otfl@color

%    \end{macrocode}
%
%    Two small macros to register or unregister the callbacks. Without the
%    callbacks this package is totally turned off.
%
%    \begin{macrocode}

\def\otfl@off{
\directlua{luaotfload.unregister_callbacks()}
}

\def\otfl@on{
\directlua{luaotfload.register_callbacks()}
}

%    \end{macrocode}
%
%    We load the |lua| file, and we turn the package on.
%
%    \begin{macrocode}

\luatexUseModule{luaotfload}

\otfl@on

\otfl@AtEnd
%    \end{macrocode}
% \iffalse
%</package>
% \fi
% \Finale
\endinput