summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilipp Gesang <phg42.2a@gmail.com>2013-04-29 12:51:52 +0200
committerPhilipp Gesang <phg42.2a@gmail.com>2013-04-29 12:51:52 +0200
commitbe7d5713a125033d686d97a38910cb5af62f9093 (patch)
tree594a685f24d9c874e16452f3bad186b18831a663
parent2adc02056a47717a8f9fee7a48e62ab5cf50c9c8 (diff)
downloadluaotfload-be7d5713a125033d686d97a38910cb5af62f9093.tar.gz
[doc] describe the various font requests
-rw-r--r--luaotfload.dtx184
1 files changed, 145 insertions, 39 deletions
diff --git a/luaotfload.dtx b/luaotfload.dtx
index 957dea1..abc737c 100644
--- a/luaotfload.dtx
+++ b/luaotfload.dtx
@@ -130,6 +130,8 @@ and the derived files
\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}
@@ -246,15 +248,15 @@ and the derived files
%
% \section{Loading Fonts}
%
-% \identifier{luaotfload} supports an extended font loading syntax:
+% \identifier{luaotfload} supports an extended font request syntax:
%
-% \begin{center}
+% \begin{quote}
% |\font\foo={|%
% \meta{prefix}|:|%
% \meta{font name}|:|%
% \meta{font features}|}|%
% \meta{\TEX font features}
-% \end{center}
+% \end{quote}
%
% \noindent
% The curly brackets are optional and escape the spaces in the enclosed
@@ -330,45 +332,93 @@ and the derived files
% \label{font-syntax}
% \end{figure}
%
-% %(* braces around the specification will preserve whitespace *)
-% %(* file lookups do not allow paths *)
-% %(* others like `aat', `icu', and `gr' are silently ignored *)
-%
-% \paragraph{Prefix}
-%
-% The \meta{prefix} is either |file:| or |name:|.
-% It determines whether the font loader should interpret the request as a
-% file name or font name, respectively, which again influences how it
-% will attempt to locate the font.
-% The prefix can be omitted, in which case |name:| is assumed.
-%
-%% \iffalse%% how am i supposed to friggin comment stuff in a dtx???
-%% TODO
-%% it would appear that the next paragraph is incorrect; I get
-%% name: lookups regardless unless the font file is actually
-%% in CWD
-%% \fi
-%% For compatibility with \XETEX, surrounding the \meta{font name} with
-%% square brackets is synonymous to using the |file:| prefix.
+% \subsection{Prefix -- the \identifier{luaotfload}\space 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
+% Please refer to section~\ref{sec:fontdb} below for instructions on how to
% create the database.
%
-% \paragraph{Font name}
+% 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 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{\hologo{XeTeX} 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.
%
-% The \meta{font name} can be either a font filename or actual font
-% name based on the \meta{prefix} as mentioned above.
+% \begin{quote}
+% |\font\fontname=[|\meta{path to file}|]|
+% \end{quote}
%
-% A filename request may optionally include the absolute path to the font file,
-% allowing for fonts outside the standard locations to be loaded as well.
-% If no path is specified, then \identifier{kpathsea} is used to locate the
-% font (which will typically be in the \fileent{texmf} tree or the
-% current directory).
+% \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.
%
-% \subparagraph{Examples for loading by file name}
+% \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:
@@ -380,8 +430,11 @@ and the derived files
% \end{quote}
%
% The \OpenType version of Janusz Nowacki’s font \emphasis{Antykwa
-% Półtawskiego} (in \TEX Live) in its condensed variant can be loaded as
-% follows:
+% 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}
@@ -399,7 +452,7 @@ and the derived files
% \end{verbatim}
% \end{quote}
%
-% \subparagraph{Examples for loading by font name}
+% \subsubsection{Loading by Font Name}
%
% The \verb|name:| lookup does not depend on cryptic filenames:
%
@@ -435,9 +488,62 @@ and the derived files
% \end{verbatim}
% \end{quote}
%
-% \paragraph{Font features}
+% \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}.
%
-% \meta{font features} is semicolon-separated list of feature
+% The element \meta{font features} is a semicolon-separated list of feature
% tags\footnote{%
% Cf. \url{http://www.microsoft.com/typography/otspec/featurelist.htm}.
% }
@@ -1078,7 +1184,7 @@ luaotfload.prefer_merge = config.luaotfload.prefer_merge or true
luaotfload.module = {
name = "luaotfload",
version = 2.2,
- date = "2013/04/15",
+ date = "2013/04/29",
description = "OpenType layout system.",
author = "Elie Roux & Hans Hagen",
copyright = "Elie Roux",