summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--luaotfload.dtx173
1 files changed, 83 insertions, 90 deletions
diff --git a/luaotfload.dtx b/luaotfload.dtx
index b770a91..a6b1c1e 100644
--- a/luaotfload.dtx
+++ b/luaotfload.dtx
@@ -173,34 +173,32 @@ and the derived files
% \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.
+% 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{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 font technologies have
-% appeared, most notably the so called \emph{smart font} technologies like
-% \textsf{OpenType} fonts. These fonts can contain a lot of characters, and
-% additional functionalities like ligatures, old-style numbers, small capitals,
-% etc., and support more complex writing systems like Arabic and
-% Indic\footnote{Unfortunately, \textsf{luaotfload} doesn't support Indic
-% scripts right now} scripts.
-% They are widely deployed and available for all modern operating systems and
-% are becoming the de facto standard fonts for advanced text layout.
-% Until now the only way to use them directly in the \tex world was by using
-% them with \xetex.
+% 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 font technologies have appeared, most notably the so called
+% \emph{smart font} technologies like \textsf{OpenType} fonts. These fonts can
+% contain a lot of characters, and additional functionalities like ligatures,
+% old-style numbers, small capitals, etc., and support more complex writing
+% systems like Arabic and Indic\footnote{Unfortunately, \textsf{luaotfload}
+% doesn't support Indic scripts right now} scripts. They are widely deployed
+% and available for all modern operating systems and are becoming the de facto
+% standard fonts for advanced text layout. Until now the only way to use them
+% directly in the \tex world was by using them with \xetex.
%
% Unlike \xetex, \luatex does not provide direct support for using 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
-% text procession, which what this package is about.
+% 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 text
+% procession, which what this package is about.
%
% \section{Loading fonts}
%
@@ -217,12 +215,12 @@ and the derived files
%
% \paragraph{Prefix}
%
-% The \meta{prefix} can be either |file:| or |name:|, which specify
-% whether to use a select the font from its filename or font name,
-% respectively. If no prefix is specified |name:| is assumed.
+% The \meta{prefix} can be either |file:| or |name:|, which specify whether to
+% use a select the font from its filename or font name, respectively. If no
+% prefix is specified |name:| is assumed.
%
-% For compatibility with \xetex, surrounding the \meta{font name}
-% with square brackets is synonymous to using the |file:| prefix.
+% For compatibility with \xetex, surrounding the \meta{font name} with square
+% brackets is synonymous to using the |file:| prefix.
%
% Accessing fonts by fontname allows loading system installed fonts as well as
% \textsc{texmf} ones, and requires a font names database; see
@@ -230,14 +228,13 @@ and the derived files
%
% \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.
+% 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).
+% 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}
@@ -251,11 +248,9 @@ and the derived files
%
% \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:
+% \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; |base| and |node|.
@@ -277,11 +272,12 @@ and the derived files
% 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 syntax is documented in Adobe's
-% \href{http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html}{OpenType Feature File Specification}.
+% 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 syntax is documented in Adobe's
+% \href{http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html}
+% {OpenType Feature File Specification}.
%
% For example, to set a |tkrn| feature from |mykern.fea| file:
%
@@ -289,8 +285,8 @@ and the derived files
%
% \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.)
+% optionally another value for the transparency (where |00| is completely
+% transparent and |FF| is opaque.)
%
% For example, to set text in semitransparent red:
%
@@ -298,10 +294,9 @@ and the derived files
%
% \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
-% |otfl-font-dum.lua| file for an example of such tables. The only
-% predefined value is |default|.
+% protrusion and expansion. The value of the key is the name of predefined Lua
+% tables of protrusion and expansion values; see the end of |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,
@@ -323,15 +318,15 @@ and the derived files
% \end{itemize*}
%
% (For \xetex users: these last two are the equivalent of writing
-% |mapping=text-tex| using \xetex's input remapping feature.)
+% |mapping=text-tex| using \xetex's input remapping feature.)
%
%
% \section{Font names database}
% \label{sec:fontdb}
%
-% As introduced in the previous section, \textsf{luaotfload} uses a database
-% to keep track of fonts available to \luatex. Using this database, fonts can
-% be loaded by font name as well as filename.
+% As introduced in the previous section, \textsf{luaotfload} uses a database to
+% keep track of fonts available to \luatex. Using this database, fonts can be
+% loaded by font name as well as filename.
%
% When \textsf{luaotfload} is asked to load a font by font name, it will check
% if font names database exists and load it, or generate a new database if non
@@ -343,26 +338,26 @@ and the derived files
% However, it is sometimes desirable to update the database manually, so
% \textsf{luaotfload} provides a |mkluatexfontdb| utility to manually update
% the database. |mkluatexfontdb| is a lua script that can be either run
-% directly or as an argument to |texlua|, depending on your system\footnote{
-% On MS Windows it can be run either by calling the wrapper application
+% directly or as an argument to |texlua|, depending on your system\footnote{On
+% MS Windows it can be run either by calling the wrapper application
% |mkluatexfontdb.exe| or with |texlua.exe mkluatexfontdb.lua|}.
%
% The first time the database is generated may take quite some time to process
-% every font on your computer.
-% This is particularly noticeable if it occurs during a typesetting run.
-% Subsequent runs to update the database will be quite fast, however.
+% every font on your computer. This is particularly noticeable if it occurs
+% during a typesetting run. Subsequent runs to update the database will be
+% quite fast, however.
%
% \textsf{luaotfload} will parse standard places for fonts in your system to
% build the font database. On Linux, it will read |fontconfig| configuration
-% files to find the font locations;
-% on Windows and Mac~OS~X, it will search in the standard font locations,
-% |%WINDIR%\Fonts| in Windows and |~/Library/Fonts|, |/Library/Fonts|,
-% |/System/Library/Fonts|, and |/Network/Library/Fonts| in Mac~OS~X.
+% files to find the font locations; on Windows and Mac~OS~X, it will search in
+% the standard font locations, |%WINDIR%\Fonts| in Windows and
+% |~/Library/Fonts|, |/Library/Fonts|, |/System/Library/Fonts|, and
+% |/Network/Library/Fonts| in Mac~OS~X.
%
% If you do not wish the standard font locations be searched by default but
-% would rather specify the exact locations in which to find your fonts, set
-% the |OSFONTDIR| environment variable instead. When this variable is set,
-% only the specified directories will be searched.
+% would rather specify the exact locations in which to find your fonts, set the
+% |OSFONTDIR| environment variable instead. When this variable is set, only the
+% specified directories will be searched.
%
% |mkluatexfontdb.lua --help| provides a brief summary of the functionality of
% the script and includes some advanced options that we have not mentioned
@@ -381,9 +376,9 @@ and the derived files
% can find. You can either use the base name or the full path. Any thing after
% a |%| sign is ignored. \textsf{luaotfload} reads all files named named
% |otfl-blacklist.cnf|, so you can add your own fonts to the global blacklist
-% by creating a local file |otfl-blacklist.cnf| with the entries you need.
-% You can also remove a font from this blacklist by prepending the name with
-% a dash (|-|).
+% by creating a local file |otfl-blacklist.cnf| with the entries you need. You
+% can also remove a font from this blacklist by prepending the name with a dash
+% (|-|).
%
% \begin{verbatim}
% % example otf-blacklist.cnf
@@ -396,12 +391,12 @@ and the derived 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. So we try not to modify the files
-% taken from \context as far as possible, but we changed their names to
-% prevent name clashes.
+% update these files from time to time. So we try not to modify the files taken
+% from \context as far as possible, but we changed their names to prevent name
+% clashes.
%
-% The \context files are renamed by adding the prefix |otfl-| to them
-% (|otfl| as |OTF L|oad). The files are:
+% The \context files are renamed by adding the prefix |otfl-| to them (|otfl|
+% as |OTF L|oad). The files are:
%
% \begin{multicols}{3}
% \begin{itemize*}
@@ -441,11 +436,10 @@ and the derived files
% 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:
+% 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;|
%
@@ -473,11 +467,11 @@ luaotfload.module = {
local error, warning, info, log = luatexbase.provides_module(luaotfload.module)
% \end{macrocode}
%
-% This is a necessary initalization in order not to rebuild an existing font.
-% Maybe 600 should be replaced by |\pdfpkresolution| or |texconfig.pk_dpi|
-% (and it should be replaced dynamically), but we don't have access (yet) to
-% the |texconfig| table, so we let it be 600. Anyway, it does still work
-% fine even if |\pdfpkresolution| is changed.
+% This is a necessary initalization in order not to rebuild an existing
+% font. Maybe 600 should be replaced by |\pdfpkresolution| or
+% |texconfig.pk_dpi| (and it should be replaced dynamically), but we don't
+% have access (yet) to the |texconfig| table, so we let it be 600. Anyway,
+% it does still work fine even if |\pdfpkresolution| is changed.
%
% \begin{macrocode}
kpse.init_prog("", 600, "/")
@@ -524,8 +518,7 @@ end
% \subsection{Module loading}
%
% We load the \context files with this function. It automatically adds the
-% |otfl-| prefix to it, so that we call it with the actual \context
-% name.
+% |otfl-| prefix to it, so that we call it with the actual \context name.
%
% \begin{macrocode}
function luaotfload.loadmodule(name)
@@ -599,11 +592,11 @@ luaotfload.loadmodule("font-clr.lua")
%
% \subsection{Post-processing TFM table}
%
-% Here we do some final touches to the loaded TFM table before passing it
-% to the \tex end.
+% Here we do some final touches to the loaded TFM table before passing it to
+% the \tex end.
%
-% First we create a callback for patching fonts on the fly, to be used by
-% other packages.
+% First we create a callback for patching fonts on the fly, to be used by
+% other packages.
% \begin{macrocode}
luatexbase.create_callback("luaotfload.patch_font", "simple", function() end)
% \end{macrocode}
@@ -616,8 +609,8 @@ local function def_font(...)
if type(fontdata) == "table" and fontdata.shared then
% \end{macrocode}
%
-% Then we populate |MathConstants| table, which is required for
-% OpenType math.
+% Then we populate |MathConstants| table, which is required for OpenType
+% math.
%
% \begin{macrocode}
local otfdata = fontdata.shared.rawdata
@@ -640,7 +633,7 @@ local function def_font(...)
end
% \end{macrocode}
%
-% Execute any registered font patching callbacks.
+% Execute any registered font patching callbacks.
%
% \begin{macrocode}
luatexbase.call_callback("luaotfload.patch_font", fontdata)