diff options
author | Philipp Gesang <phg42.2a@gmail.com> | 2013-04-29 12:51:52 +0200 |
---|---|---|
committer | Philipp Gesang <phg42.2a@gmail.com> | 2013-04-29 12:51:52 +0200 |
commit | be7d5713a125033d686d97a38910cb5af62f9093 (patch) | |
tree | 594a685f24d9c874e16452f3bad186b18831a663 | |
parent | 2adc02056a47717a8f9fee7a48e62ab5cf50c9c8 (diff) | |
download | luaotfload-be7d5713a125033d686d97a38910cb5af62f9093.tar.gz |
[doc] describe the various font requests
-rw-r--r-- | luaotfload.dtx | 184 |
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", |