summaryrefslogtreecommitdiff
path: root/luaotfload.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'luaotfload.dtx')
-rw-r--r--luaotfload.dtx100
1 files changed, 61 insertions, 39 deletions
diff --git a/luaotfload.dtx b/luaotfload.dtx
index 4ec2de5..8c2de48 100644
--- a/luaotfload.dtx
+++ b/luaotfload.dtx
@@ -102,7 +102,7 @@ and the derived files
\ProvidesFile{luaotfload.drv}%
[2010/05/10 v1.07 ConTeXt font loading system]%
\documentclass{ltxdoc}
-\usepackage{metalogo,multicol,mdwlist}
+\usepackage{metalogo,multicol,mdwlist,fancyvrb}
\usepackage[colorlinks=true]{hyperref}
\def\LuaTeX{Lua\TeX}
@@ -110,6 +110,7 @@ and the derived files
\EnableCrossrefs
\CodelineIndex
+\VerbatimFootnotes
\begin{document}
\DocInput{luaotfload.dtx}%
\end{document}
@@ -144,14 +145,15 @@ and the derived files
% \maketitle
%
% \begin{abstract}
-% \ConTeXt\ font loading system, providing the possibility to load OTF fonts
-% with a lot of features, and extended font loading syntax.
+% 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
@@ -171,7 +173,7 @@ and the derived files
%
% 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.
+% it's even impossible to adapt them to the new engines.
%
% \subsection{Loading fonts}
%
@@ -186,11 +188,12 @@ and the derived files
%
% \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).
+% 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
@@ -206,10 +209,10 @@ and the derived files
%
% \paragraph{Font features}
%
-% Font are a semicolon separated list of items, which are either font parameters
-% in the form of |key=value|, or switches to enable/disable certain font
+% 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 parameters are:
+% The supported keys are:
% \begin{description}
% \item [mode] \hfill \\
% \textsf{luaotfload} has two OpenType processing modes; \texttt{base} mode
@@ -217,10 +220,16 @@ and the derived files
% 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.
+% 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|.
+% \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|.
%
@@ -232,36 +241,45 @@ and the derived files
% \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.)
%
-% \item [protrosion] \hfill \\ TODO
-% \item [expansion] \hfill \\ TODO
+% 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{Additional font features}
+% \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.
+% \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*}
%
-% \subsubsection{Examples}
-% \begin{verbatim}
-% \font\testa=file:lmroman10-regular at 12pt \testa \input tufte \par
-% \font\testb=file:lmroman12-regular:+liga; at 24pt \testb effe flink fietsen \par
-% \font\testc=file:lmroman12-regular:mode=node;+liga; at 24pt \testc effe flink fietsen \par
-% \font\testd=name:lmroman10bold at 12pt \testd a bit bold \par
-%
-% \font\teste=[lmroman12-regular]:+liga at 30pt \teste text
-% \font\testf=[lmroman12-regular] at 40pt \testf more text
-% \end{verbatim}
-%
% \subsection{\ConTeXt\ files needed}
%
% This package is a wrapper for several files taken from the \ConTeXt\ macro
@@ -300,20 +318,24 @@ and the derived files
% \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 otf 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:
+% 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
@@ -424,7 +446,7 @@ luaotfload.loadmodule('node-ini.lua')
function attributes.private(name)
local number = luatexbase.attributes['otfl@'..name]
- if not number then
+ if not number then
error('asking for attribute %s, but not declared. '
..'Please report to the maintainer of luaotfload.',
name)
@@ -436,7 +458,7 @@ end
%
% 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.
%
@@ -469,7 +491,7 @@ luaotfload.loadmodule('font-clr.lua')
% \end{macrocode}
%
-% Finally two functions
+% Finally two functions
%
% \begin{macrocode}