path: root/luaotfload.dtx

% \iffalse meta-comment
%
% Copyright (C) 2009 by Elie Roux <elie.roux@telecom-bretagne.eu>
%
% 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/10 v1.07 ConTeXt font loading system}
\Msg{************************************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax

\preamble
This is a generated file.

Copyright (C) 2009 by Elie Roux <elie.roux@telecom-bretagne.eu>

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/10 v1.07 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/10 v1.07}
% \author{     Elie Roux    \footnote{\texttt{elie.roux@telecom-bretagne.eu}}
%         \and Khaled hosny \footnote{\texttt{khaledhosny@eglug.org}}}
%
% \maketitle
%
% \begin{abstract}
% Adaptation of \ConTeXt\ font loading system, providing the ability to load
% \textsf{OpenType} fonts with a lot of features, and extended font loading
% syntax.
% \end{abstract}
%
% \tableofcontents
%
% \section{Documentation}
%
% \subsection{Introduction}
%
% Font management and installation has always been painful with \TeX\ (and
% even more with \LaTeX). A lot of files are needed for one font (tfm, pfb,
% map, fd, vf), and they are limited to 256 characters. But the font world has
% evolved since, and new standard types of fonts have appeared, like
% \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 softwares fonts are of this type. Until now the (almost) only
% way to use them with \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\
% algorithm, for instance we can improve the font loading system; this is what
% we do in this package.
%
% This package is quite low-level, and should be loaded directly in the macro
% package, like it is in \ConTeXt. Sadly, Plain and \LaTeX\ are frozen and
% it's even impossible to adapt them to the new engines.
%
% \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}
%
% The curly brackets are optional and are used for escaping spaces in font names
% (\XeTeX-like double quotes can also used for the same purpose).
%
% \paragraph{Prefix}
%
% Can be either \texttt{file:} or \texttt{name:} and are used to select between
% filename based or font name based search mechanisms.
% Loading fonts based on filename is restricted to files found by
% \textsf{kpathsea} (typically in the \textsc{texmf} tree). Surrounding font
% name with square brackets is synonym to using \texttt{file:} prefix (for
% compatibility with \XeTeX).
% This is usually used for loading old \textsc{tfm} fonts.
% Accessing fonts by fontname allows loading system installed fonts as well as
% \textsc{texmf} ones, and requires a font names database that can be generated
% using the bundled |mkluatexfontdb.lua| script.
% \footnote{run |mkluatexfontdb.lua --help| for help and usage information}
%
% If no prefix is specified, then \texttt{file:} is assumed.
%
% \paragraph{Font name}
%
% Font name can be either a font filename or actual font name; based on the
% prefix specified.
%
% \paragraph{Font features}
%
% Font features are a semicolon separated list of items, 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} mode
% which supports only a subset of OpenType features and works by mapping those
% features to traditional \TeX\ ligaturing and kerning mechanisms and is a bit
% faster, and \texttt{node} mode which, hopefully, supports OpenType fully and
% works by direct processing of node list at lua end and is a bit slower.
% Note that \texttt{node} mode doesn't work inside math.
%
% By default, \texttt{base} mode is used, however 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 |dflt| script, in this case 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 Hex 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 bottom 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*}
%
% \subsection{\ConTeXt\ files needed}
%
% 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}
%
% \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, some feature like contextual substitution, |calt|, will only work with
% |node| mode.
%
% \section{\texttt{luaotfload.lua}}
%
% \iffalse
%<*lua>
% \fi
%
%    First some usual initializations.
%
%    \begin{macrocode}
module('luaotfload', package.seeall)

luaotfload.module = {
    name          = "luaotfload",
    version       = 1.07,
    date          = "2010/05/10",
    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
%
% \section{\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/10 v1.07 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