Debian Codegraph @

texmf-dist/doc/luatex/luaotfload/luaotfload-main.tex

raw
1 %% Copyright (C) 2009-2021
2 %%
3 %% by Elie Roux <[email protected]>
4 %% and Khaled Hosny <[email protected]>
5 %% and Philipp Gesang <[email protected]>
6 %%
7 %% This file is part of Luaotfload.
8 %%
9 %% Home: https://github.com/lualatex/luaotfload
10 %% Support: <[email protected]>.
11 %%
12 %% Luaotfload is under the GPL v2.0 (exactly) license.
13 %%
14 %% ----------------------------------------------------------------------------
15 %%
16 %% Luaotfload is free software; you can redistribute it and/or
17 %% modify it under the terms of the GNU General Public License
18 %% as published by the Free Software Foundation; version 2
19 %% of the License.
20 %%
21 %% Luaotfload is distributed in the hope that it will be useful,
22 %% but WITHOUT ANY WARRANTY; without even the implied warranty of
23 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24 %% GNU General Public License for more details.
25 %%
26 %% You should have received a copy of the GNU General Public License
27 %% along with Luaotfload; if not, see <http://www.gnu.org/licenses/>.
28 %%
29 %% ----------------------------------------------------------------------------
30 %%
31
32 \beginfrontmatter
33
34 \setdocumenttitle {The \identifier{luaotfload} package}
35 \setdocumentdate {2024-12-03 v3.29}
36 \setdocumentauthor {LaTeX3 Project\\
37 Elie Roux · Khaled Hosny · Philipp Gesang · Ulrike Fischer · Marcel Krüger\\
38 Home: \hyperlink {https://github.com/latex3/luaotfload}}
39
40 \typesetdocumenttitle
41
42 \beginabstractcontent
43 This package is an adaptation of the \ConTeXt\ font loading system.
44 It allows for loading \OpenType\ fonts with an extended syntax and adds
45 support for a variety of font features.
46
47 After discussion of the font loading API, this manual gives an
48 overview of the core components of \identifier{Luaotfload}: The
49 packaged font loader code, the names database, configuration, and
50 helper functions on the \Lua\ end.
51 \endabstractcontent
52
53 \endfrontmatter
54
55 \pdfbookmark[1]{\contentsname}{table}
56 \typesetcontent
57 \beginsection {Engine and version support}
58 \identifier{luaotfload} is a quite large and complex package. It imports code from context which is actively developed along with the luatex binary. It is not possible
59 to support a large number of engines variants or versions.
60
61 Supported is the \identifier{luatex} versions of a current TeXLive 2019 (and a current MiKTeX). Beginning with version 3.1 of this package also \identifier{luahbtex} is supported.
62 \endsection
63
64 \beginsection{Changes}
65 \beginsubsection{New in version 3.29}
66 \begin{itemize}
67 \item Preserve subtypes while letterspacing.
68 \item Improve logging for auxiliary functions.
69 \item Improve cache path selection when parts of cache path are not writable.
70 \item Fix broken luaotfload-tool.
71 \end{itemize}
72 \endsubsection
73
74 \beginsubsection{New in version 3.28}
75 \begin{itemize}
76 \item Improving compatibility with Windows paths
77 \end{itemize}
78 \endsubsection
79
80 \beginsubsection{New in version 3.24}
81 \begin{itemize}
82 \item Add experimental configuration option to change default font lookup location
83 precedence.
84 \item Support xdvipsk in DVI mode
85 \item Preserve soft-hyphens when dropping default ignorable characters
86 \item Hash cache keys to better support certain rather inflexible operating
87 systems
88 \item Various bug fixes
89 \end{itemize}
90 \endsubsection
91
92 \beginsubsection{New in version 3.23}
93 \begin{itemize}
94 \item More reliable ToUnicode mappings in Harf mode
95 \item Various bug fixes
96 \end{itemize}
97 \endsubsection
98
99 \beginsubsection {New in version 3.22}
100 \begin{itemize}
101 \item Tailored case mappings
102 \item Avoid database rebuilds when switching Lua versions
103 \item Improved attribute settings of ActualText nodes in harf mode
104 \item Callback-based customization for color parameter
105 \item Various bug fixes
106 \end{itemize}
107 \endsubsection
108
109 \beginsubsection {New in version 3.21 (by Ulrike Fischer/Marcel Krüger)}
110 \begin{itemize}
111 \item Fix performance regression introduced in version 3.19.
112 \item More reliably support TrueType based variable fonts in \texttt{harf}
113 mode.
114 \end{itemize}
115 \endsubsection
116
117 \beginsubsection {New in version 3.20 (by Ulrike Fischer/Marcel Krüger)}
118 \begin{itemize}
119 \item A bug in luaotfload-tool has been corrected.
120 \item The directory for the font name database has been corrected and no
121 longer uses the development directory.
122 \end{itemize}
123 \endsubsection
124
125 \beginsubsection {New in version 3.19 (by Ulrike Fischer/Marcel Krüger)}
126 \begin{itemize}
127 \item When used with \LuaTeX\ 1.15.0 or newer, variable fonts are supported
128 when using the \texttt{harf} shaper too.
129 \item A new algorithm for selecting fonts based on font family names allows
130 to more reliably load fonts based on their family name.
131 \item The compiled font database gets compressed to reduce disk space and
132 improve performance on newer systems.
133 \item Broken rendering of some TrueType based variable fonts has been fixed.
134 \item Text automatically gets normalized to Unicode's NFC before shaping.
135 This improves rendering for text written in decomposed forms for many
136 fonts. This can be turned off by passing the \texttt{-normalize} font
137 feature.
138 \item A number of small bugfixes.
139 \end{itemize}
140 \endsubsection
141
142 \beginsubsection {New in version 3.18 (by Ulrike Fischer/Marcel Krüger)}
143 \begin{itemize}
144 \item Now variable fonts can be loaded with default values without specifying
145 any explicit axis values.
146 \item A number of small bugfixes.
147 \end{itemize}
148 \endsubsection
149
150 \beginsubsection {New in version 3.17 (by Ulrike Fischer/Marcel Krüger)}
151 \begin{itemize}
152 \item The experimental support for \OpenType\ variable fonts has been extended
153 to more reliably support modern fonts.
154 \item A number of small bugfixes.
155 \end{itemize}
156 \endsubsection
157
158 \beginsubsection {New in version 3.16 (by Ulrike Fischer/Marcel Krüger)}
159 \begin{itemize}
160 \item The entry point is called \identifier{luaotfload.lua} instead of
161 \identifier{luaotfload-main.lua} (but the old name is still provided for compatibility).
162 \item \inlinecode{pre/post_shaping_filter} callbacks has been added.
163 \item The number of \abbrev{lua}-files and submodules shown in the \abbrev{log}-file has been reduced. But it
164 is extended again by setting the environment variable \inlinecode{LUAOTFLOAD_TRACE_SUBMODULES=1}.
165 \item The HarfBuzz based shaper will in some situations drop hyphenation
166 points. This happens less frequently now since the new version uses
167 first/second discretionaries (the mechanism described in the LuaTeX manual,
168 section 5.6 for the of-f-ice example) to support a limited amount of
169 nesting.
170 \item When the \texttt{node} shaper is used, experimental support for \OpenType\ variable
171 fonts has been added. To use them, set the font feature \texttt{axis} to
172 a comma separated list of axis names and values. (E.g. \texttt{axis={weight=600}})
173 The supported axis names and value range depend on the font (see~page~\pageref{variablefonts}).
174 \item The font features \texttt{upper} and \texttt{lower} can be used to map
175 the text of a font to upper or lowercase before displaying it. Currently
176 this implements the untailored Unicode case mapping algorithm, but it is
177 planned to add tailoring later (see~page~\pageref{upperlower}).
178 \item A number of small bugfixes.
179 \end{itemize}
180 \endsubsection
181
182 \beginsubsection {New in version 3.15 (by Ulrike Fischer/Marcel Krüger)}
183 \begin{itemize}
184 \item The font database is updated more reliably if fonts get deleted.
185 \item In multiple error cases, error messages are shown instead of silently
186 generating bad output.
187 \item Write glyph ids instead of internal identifiers to DVI files. This
188 allows using \OpenType\ fonts when working with \identifier{dvilualatex}.
189 (This requires additional support from the DVI reader)
190 \item The\marginpar{\mbox{}\hfill \textbf{Change!}} set of font features which
191 are enabled by default has been changed to be more similar to HarfBuzz.
192 Especially \enquote{Above-base mark Positioning} (abvm),
193 \enquote{Below-base mark Positioning} (blwm), \enquote{Contextual
194 Alternates} (calt), \enquote{Cursive Positioning} (curs),
195 \enquote{Distances} (dist), and \enquote{Required Contextual Alternates}
196 (rclt) are now enabled by default for all scripts.
197 \item Added a \identifier{mathfontdimen} font feature which allows emulating
198 fontdimen values from xetex or traditional \TeX\ math fonts.
199 \item Initial support for variable fonts in \identifier{node} mode.
200 \end{itemize}
201 \endsubsection
202
203 \beginsubsection {New in version 3.14 (by Ulrike Fischer/Marcel Krüger)}
204 \begin{itemize}
205 \item a bug in luaotfload-tool has been corrected (reported on the texlive list)
206 \item the fontloader has been patched to resolve a problem with color fonts and save/restore pairs \gitissue{124}
207 \end{itemize}
208 \endsubsection
209
210 \beginsubsection {New in version 3.13 (by Ulrike Fischer/Marcel Krüger)}
211 \begin{itemize}
212 \item A\marginpar{\mbox{}\hfill \textbf{Change!}} problem with text fonts with minimal math table has been fixed \gitissue{148}:
213 In new luaotfload versions, math parameters will only be loaded for fonts with \texttt{script=math}.
214 If you do want to set math parameters for fonts with other scripts, add \texttt{-nomathparam}.
215 We strongly recommend against setting math parameters for text fonts because
216 these would overwrite parameters from actual math fonts.
217 \item A bug in harf-mode that could lead to missing chars and freezing was corrected \gitissue{141}.
218 \item A font size problem in harf-mode has been fixed \gitissue{147}.
219 \item An error if the main function was called twice has been fixed \gitissue{145}.
220 \item Allow .ttf fonts to be loaded with a map file with luahbtex \gitissue{142} \gitissue{143}.
221 \item Fonts installed for a single user on windows are now found \gitissue{138}.
222 \item A problem with wrong \TeX-ligatures in harf mode has been fixed \gitissue{139}.
223 \item The debugging output has been changed \gitissue{131}.
224 \item A missing \enquote{capital sharp s} (U+1E9E) in a font is replaced by SS instead of giving a missing character message:
225 ^^^^1e9e or {\sffamily ^^^^1e9e}
226 \item The color handling has been improved so that it is now compatible with the luacolor package.
227 \end{itemize}
228 \endsubsection
229 \beginsubsection {New in version 3.12 (by Ulrike Fischer/Marcel Krüger)}
230 \begin{itemize}
231 \item Corrected a number of small bugs in harf mode.
232 \item Extension\marginpar{Experimental!} of the \identifier{color} key to allow
233 coloring of specific output glyphs, see page~\pageref{color-glyphs}
234 \item A\marginpar{Experimental!} new \identifier{fallback} key to allow to define fallback fonts, see page~\pageref{fallback}
235 \item A\marginpar{Experimental!} new \identifier{multiscript} key to allow to use a font
236 for more than one script, see page~\pageref{multiscript}
237 \end{itemize}
238 \endsubsection
239 \beginsubsection {New in version 3.11 (by Ulrike Fischer/Marcel Krüger)}
240 \begin{itemize}
241 \item Changed the handling of the \identifier{script} key in harf mode to be more compatible with behaviour of the node mode. It now expects the name of a script that is actually in the font instead of a ISO 15924 script tag. See issue 117.
242 \item Corrected a number of small typos and bugs in harf mode.
243 \end{itemize}
244 \endsubsection
245 \beginsubsection {New in version 3.10 (by Ulrike Fischer/Marcel Krüger)}
246 \begin{itemize}
247 \item The package has been moved to the github of the LaTeX3 Project and is now maintained
248 officially by the LaTeX3 Project team.
249 \item Code to use the harfbuzz library of luahbtex has been added. See the description of the harf mode.
250 \item fonts in ttc-collections can now be indexed by name.
251 \item To reduce the pollution of the global lua environment a number of lua tables have been removed.
252 Only the tables \identifier{luaotfload}, \identifier{fonts} and \identifier{nodes} have been kept there.
253 \item The fontloader has been synched with the context files from 2019-10-29.
254
255 \end{itemize}
256 \endsubsection
257
258
259 \beginsubsection {New in version 3.00 (by Ulrike Fischer/Marcel Krüger)}
260 \begin{itemize}
261 \item Default Ignorable characters are now invisible by default (issue 63). This can be deactivated with the option \texttt{invisible}.
262 \end{itemize}
263 \endsubsection
264
265 \beginsubsection {New in version 2.99 (by Ulrike Fischer)}
266 \begin{itemize}
267 \item Code cleanup.
268 \item The fontloader has been synched with the context files from 2019-08-11.
269 \end{itemize}
270 \endsubsection
271 \beginsubsection {New in version 2.98 (by Ulrike Fischer)}
272 \begin{itemize}
273 \item The\marginpar{\mbox{}\hfill \textbf{breaking change!}} handling of missing chars has been changed. In This version a missing char will insert the \inlinecode{/.notdef} char of the fonts (this is sometimes a space, sometimes a rectangle with a cross) and no longer simply ignore the glyph. This behaviour can be reverted by using \inlinecode{notdef=false} as font feature.
274 \item The font feature \inlinecode{embolden} can now be used to fake a bold font.
275 \item The fontloader has been synched with the context files from 2019-07-04.
276 \end{itemize}
277 \endsubsection
278 \beginsubsection {New in version 2.97 (by Ulrike Fischer)}
279 \begin{itemize}
280 \item the new generic fontloader improves the handling of large fonts (but some fonts still need a 64bit luatex version to create the font files).
281 \item A number of small bug (also in luaotfload-tool) have been corrected, see the NEWS file for details.
282
283 \end{itemize}
284 \endsubsection
285
286 \beginsubsection {New in version 2.96 (by Ulrike Fischer)}
287 \begin{itemize}
288 \item In\marginpar{\mbox{}\hfill \textbf{Incompatible change!}}
289 version 2.95 letterspacing was broken due to a change in the fontloader (issue 38). This has been repaired. At the same time a number of oddities and bugs in the letterspacing has been corrected. This can change existing documents. See page~\pageref{p:letterspace} for more information.
290
291 \item A problem with the detection of bold fonts has been corrected (issue 41, pull request 42).
292
293 \end{itemize}
294 \endsubsection
295
296
297
298 \beginsubsection {New in version 2.95 (by Ulrike Fischer)}
299 \begin{itemize}
300 \item
301 This version imports from context the generic fontloader in the version of 2019-01-28. Contrary to the last announcement, it still works with luatex 1.07. So updates will continue.
302
303 \item The handling of the lucida-fonts had been improved (issue 33).
304
305 \item tex-files are no longer misused as font fallbacks (issue 35).
306
307 \item The resolver code has be refactorated (pull request 36).
308
309 \end{itemize}
310 \endsubsection
311 \beginsubsection {New in version 2.94 (by Ulrike Fischer)}
312 \begin{itemize}
313 \item
314 This version imports from context the generic fontloader in the version of 2018-12-19. It is the last version that works with luatex 1.07 and texlive 2018. As context has moved to luatex 1.09 newer versions of the fontloader needs now this luatex version too. This means that until the texlive 2018 freeze there will be probably no update of luaotfload.
315
316 \item This version changes the handling of the \inlinecode{mode} key. It no longer accepts only the values \inlinecode{base} and \inlinecode{node}, but can be used to load a font with an alternative font loader/renderer.
317
318
319 \end{itemize}
320 \endsubsection
321
322 \beginsubsection {New in version 2.93 (by Ulrike Fischer)}
323 Mainly internal clean up of the version info to allow automatic versioning.
324 \endsubsection
325
326 \beginsubsection {New in version 2.92 (by Ulrike Fischer)}
327
328 \begin{itemize}
329
330 \item Better devanagari support (issue \#9).
331 \item \identifier{Luaotfload} doesn't work when luatex is used with the option \inlinecode{--safer}. So it now aborts cleanly when the option is detected -- but you still can get errors from fontspec later! (issue \#12).
332 \item The syntax \inlinecode{file:} for legacy font works again (issue \#11).
333 \item The fontloader has been synched with the newest context version from october, 18.
334 \end{itemize}
335 \endsubsection
336 \beginsubsection {New in version 2.91 (by Ulrike Fischer)}
337
338 This version mostly correct two bugs found in the previous fontloader: Glyphvariants weren't copied and pasted correctly. Glyphs encoded in the PUA couldn't be accessed anymore.
339
340 \endsubsection
341
342
343 \beginsubsection {New in version 2.9 (by Ulrike Fischer)}
344
345 On the one side there is not very much new in this version: The native components of \identifier{Luaotfload} are nearly unchanged. A few bugs have been corrected, the various files lists which loads the components of the font loader have been cleaned up.
346
347 On the other side there is a lot new:
348
349 \begindescriptions
350
351 \beginaltitem {Fontloader} The fontloader files imported from \ConTeXt\ have been updated to the current version.
352 This was necessary to make \identifier{Luaotfload} compatible with the coming \LuaTeX\ 1.08/1.09. Compared to the previous version from february 2017 quite a number of things have changed. Most importantly the handling of arabic fonts has greatly improved. But this also means that changes in the output are possible.
353 \endaltitem
354
355 \beginaltitem {Lualibs} The update of the fontloader files also required an update of the \identifier{Lualibs} package. This \identifier{Luaotfload} version needs version 2.6 of \identifier{Lualibs}.
356 \endaltitem
357
358 \beginaltitem {Maintenance} As the current maintainer wasn't available and it was urgent to get a \identifier{Luaotfload} compatible with \LuaTeX\ 1.08/1.09 maintenance has been transferred to Ulrike Fischer and Marcel Krüger. The package was maintained and developed at \hyperlink{https://github.com/u-fischer/luaotfload}.
359 \endaltitem
360
361 \beginaltitem {Documentation}
362 The core of documentation is nearly unchanged. I added this introduction. I recreated with the help of @marmot the graphic on \pageref{file-graph}. I updated the file lists. I imported as appendix pdf versions of the two man files which are part of the \identifier{Luaotfload} documentation.
363 \endaltitem
364
365 \enddescriptions
366
367 \endsubsection
368 \endsection
369 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
370 \beginsection {Introduction}
371 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
372
373 Font management and installation has always been painful with \TeX. A
374 lot of files are needed for one font (\abbrev{tfm}, \abbrev{pfb},
375 \abbrev{map}, \abbrev{fd}, \abbrev{vf}), and due to the 8-Bit encoding
376 each font is limited to 256 characters.
377
378 But the font world has evolved since the original \TeX, and new
379 typographic systems have appeared, most notably the so called
380 \emphasis{smart font} technologies like \OpenType\ fonts (\abbrev{otf}).
381
382 These fonts can contain many more characters than \TeX\ fonts, as well
383 as additional functionality like ligatures, old-style numbers, small
384 capitals, etc., and support more complex writing systems like Arabic
385 and Indic\footnote{%
386 Unfortunately, the default fontloader of \identifier{luaotfload} doesn‘t support many Indic
387 scripts correctly. For these scripts it is recommended to use the harf mode along with the binary \identifier{luahbtex}.}
388 scripts.
389
390 \OpenType\ fonts are widely deployed and available for all modern
391 operating systems.
392
393 As of 2013 they have become the de facto standard for advanced text
394 layout.
395
396 However, until recently the only way to use them directly in the \TeX\
397 world was with the \XeTeX\ engine.
398
399 Unlike \XeTeX, \LuaTeX\ has no built-in support for \OpenType\ or
400 technologies other than the original \TeX\ fonts.
401
402 Instead, it provides hooks for executing \Lua\ code during the \TeX\ run
403 that allow implementing extensions for loading fonts and manipulating
404 how input text is processed without modifying the underlying engine.
405
406 This is where \identifier{luaotfload} comes into play:
407 Based on code from \ConTeXt, it extends \LuaTeX\ with functionality necessary
408 for handling \OpenType\ fonts.
409
410 Additionally, it provides means for accessing fonts known to the operating
411 system conveniently by indexing the metadata.
412
413 \endsection
414
415 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
416 \beginsection {Thanks}
417 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
418
419 \identifier{Luaotfload} is part of \hologo{LuaLaTeX}, the community-driven
420 project to provide a foundation for using the \LaTeX\ format with the
421 full capabilities of the \LuaTeX\ engine.
422 %
423 As such, the distinction between end users, contributors, and project
424 maintainers is intentionally kept less strict, lest we unduly
425 personalize the common effort.
426
427 Nevertheless, the current maintainers would like to express their
428 gratitude to Khaled Hosny, Akira Kakuto, Hironori Kitagawa and Dohyun
429 Kim.
430 %
431 Their contributions -- be it patches, advice, or systematic
432 testing -- made the switch from version 1.x to 2.2 possible.
433 %
434 Also, Hans Hagen, the author of the font loader, made porting the
435 code to \LaTeX\ a breeze due to the extra effort he invested into
436 isolating it from the rest of \ConTeXt, not to mention his assistance
437 in the task and willingness to respond to our suggestions.
438
439 \endsection
440
441 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
442 \beginsection {Loading Fonts}
443 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
444
445 \identifier{luaotfload} supports an extended font request syntax:
446
447 \beginnarrower
448 \nonproportional{\string\font\string\foo\space= \string{}%
449 \meta{prefix}\nonproportional{:}%
450 \meta{font name}\nonproportional{:}%
451 \meta{font features}\nonproportional{\string}}%
452 \meta{\TeX\ font features}
453 \endnarrower
454
455 \noindent
456 The curly brackets are optional and escape the spaces in the enclosed
457 font name.
458 %
459 Alternatively, double quotes serve the same purpose.
460 %
461 A selection of individual parts of the syntax are discussed below;
462 for a more formal description see figure \ref{font-syntax}.
463
464 \beginsyntaxfloat
465 {font-syntax}
466 {Font request syntax.
467 Braces or double quotes around the
468 \emphasis{specification} rule will
469 preserve whitespace in file names.
470 In addition to the font style modifiers
471 (\emphasis{slash-notation}) given above, there
472 are others that are recognized but will be silently
473 ignored: \nonproportional{aat},
474 \nonproportional{icu}, and
475 \nonproportional{gr}.
476 The special terminals are:
477 \smallcaps {feature\textunderscore id} for a valid font
478 feature name and
479 \smallcaps {feature\textunderscore value} for the corresponding
480 value.
481 \smallcaps {tfmname} is the name of a \abbrev{tfm} file.
482 \smallcaps {digit} again refers to bytes 48--57, and
483 \smallcaps {all\textunderscore characters} to all byte values.
484 \smallcaps {csname} and \smallcaps {dimension} are the \TeX\ concepts.}
485 %
486 <definition> ::= `\\font', {\sc csname}, `=', <font request>, [ <size> ] ;
487
488 <size> ::= `at', {\sc dimension} ;
489
490 <font request> ::= `"', <unquoted font request> `"'
491 \alt `{', <unquoted font request> `}'
492 \alt <unquoted font request> ;
493
494 <unquoted font request> ::= <specification>, [`:', <feature list> ]
495 \alt <path lookup>, [ [`:'], <feature list> ] ;
496
497 <specification> ::= <prefixed spec>, [ <subfont no> ], \{ <modifier> \}
498 \alt <anon lookup>, \{ <modifier> \} ;
499
500 <prefixed spec> ::= `combo:', <combo list>
501 \alt `file:', <file lookup>
502 \alt `name:', <name lookup> ;
503
504 <combo list> ::= <combo def 1>, \{ `;', <combo def> \} ;
505
506 <combo def 1> ::= <combo id>, `->', <combo id> ;
507
508 <combo def> ::= <combo id>, `->', <combo id chars> ;
509
510 <combo id> ::= (`(', \{ {\sc digit} \}, `)' | \{ {\sc digit} \} ) ;
511
512 <combo id chars> ::= (`(', \{ {\sc digit} \}, `,', <combo chars>, `)'
513 \alt \{ {\sc digit} \} ) ;
514
515 <combo chars> ::= `fallback'
516 \alt \{ <combo range>, \{ `*', <combo range> \} \} ;
517
518 <combo range> ::= <combo num>, [ `-', <combo num> ] ;
519
520 <combo num> ::= `0x', \{ {\sc hexdigit} \}
521 \alt `U+', \{ {\sc digit} \}
522 \alt \{ {\sc digit} \} ;
523
524 <file lookup> ::= \{ <name character> \} ;
525
526 <name lookup> ::= \{ <name character> \} ;
527
528 <anon lookup> ::= {\sc tfmname} | <name lookup> ;
529
530 <path lookup> ::= `[', \{ <path content> \}, `]', [ <subfont no> ] ;
531
532 <path content> ::= <path balanced>
533 \alt `\\', {\sc all_characters}
534 \alt {\sc all_characters} - `]'
535
536 <path balanced> ::= `[', [ <path content> ], `]'
537
538 <modifier> ::= `/', (`I' | `B' | `BI' | `IB' | `S=', \{ {\sc digit} \} ) ;
539
540 <subfont no> ::= `(', \{ {\sc digit} \}, `)' ;
541
542 <feature list> ::= <feature expr>, \{ `;', <feature expr> \} ;
543
544 <feature expr> ::= {\sc feature_id}, `=', {\sc feature_value}
545 \alt <feature switch>, {\sc feature_id} ;
546
547 <feature switch> ::= `+' | `-' ;
548
549 <name character> ::= {\sc all_characters} - ( `(' | `/' | `:' ) ;
550 \endsyntaxfloat
551
552 %% Below guarded space gets borked in index; why‽
553 \beginsubsection{Prefix -- the \texorpdfstring{\identifier{luaotfload}}{luaotfload}{ }Way}
554
555 In \identifier{luaotfload}, the canonical syntax for font requests
556 requires a \emphasis{prefix}:
557 %
558 \beginnarrower
559 \nonproportional{\string\font\string\fontname\space= }%
560 \meta{prefix}%
561 \nonproportional{:}%
562 \meta{fontname}%
563 \dots
564 \endnarrower
565 %
566 where \meta{prefix} is either \inlinecode{file:} or \inlinecode {name:}.\footnote{%
567 \identifier{Luaotfload} also knows two further prefixes, \inlinecode {kpse:}
568 and \inlinecode {my:}.
569 %
570 A \inlinecode {kpse} lookup is restricted to files that can be found by
571 \identifier{kpathsea} and will not attempt to locate system fonts.
572 %
573 This behavior can be of value when an extra degree of encapsulation is
574 needed, for instance when supplying a customized tex distribution.
575
576 The \inlinecode {my} lookup takes this a step further: it lets you define
577 a custom resolver function and hook it into the \luaident{resolve_font}
578 callback.
579 %
580 This ensures full control over how a file is located.
581 %
582 For a working example see the
583 \hyperlink [test in the luaotfload
584 repo]{https://github.com/latex3/luaotfload/blob/main/testfiles/my-resolver.lvt}.
585 }
586 %
587 It determines whether the font loader should interpret the request as
588 a \emphasis{file name} or
589 \emphasis{font name}, respectively,
590 which again influences how it will attempt to locate the font.
591 %
592 Examples for font names are
593 “Latin Modern Italic”,
594 “GFS Bodoni Rg”, and
595 “PT Serif Caption”
596 -- they are the human readable identifiers
597 usually listed in drop-down menus and the like.\footnote{%
598 Font names may appear like a great choice at first because they
599 offer seemingly more intuitive identifiers in comparison to arguably
600 cryptic file names:
601 %
602 “PT Sans Bold” is a lot more descriptive than \fileent{PTS75F.ttf}.
603 On the other hand, font names are quite arbitrary and there is no
604 universal method to determine their meaning.
605 %
606 While \identifier{luaotfload} provides fairly sophisticated heuristic
607 to figure out a matching font style, weight, and optical size, it
608 cannot be relied upon to work satisfactorily for all font files.
609 %
610 For an in-depth analysis of the situation and how broken font names
611 are, please refer to
612 \hyperlink [this post]{http://www.ntg.nl/pipermail/ntg-context/2013/073889.html}
613 by Hans Hagen, the author of the font loader.
614 %
615 If in doubt, use filenames.
616 %
617 \fileent{luaotfload-tool} can perform the matching for you with the
618 option \inlinecode {--find=<name>}, and you can use the file name it returns
619 in your font definition.
620 }
621 %
622 In order for fonts installed both in system locations and in your
623 \fileent{texmf} to be accessible by font name, \identifier{luaotfload} must
624 first collect the metadata included in the files.
625 %
626 Please refer to section~\ref{sec:fontdb} below for instructions on how to
627 create the database.
628
629 File names are whatever your file system allows them to be, except
630 that that they may not contain the characters
631 \inlinecode {(},
632 \inlinecode {:}, and
633 \inlinecode {/}.
634 %
635 As is obvious from the last exception, the \inlinecode {file:} lookup will
636 not process paths to the font location -- only those
637 files found when generating the database are addressable this way.
638 %
639 Continue below in the \XeTeX\ section if you need to load your fonts
640 by path.
641 %
642 The file names corresponding to the example font names above are
643 \fileent{lmroman12-italic.otf},
644 \fileent{GFSBodoni.otf}, and
645 \fileent{PTZ56F.ttf}.
646
647 \endsubsection
648
649 \beginsubsection {Bracketed Lookups}
650 \label{sec:bracket}
651 Bracketed lookups allow for arbitrary character content to be used in a
652 definition.
653 %
654 A simple bracketed request looks follows the scheme
655
656 \beginnarrower
657 \nonproportional{\string\font\string\fontname\space = [}%
658 \meta{/path/to/file}%
659 \nonproportional{]}
660 \endnarrower
661
662 \noindent
663 Inside the square brackets, every character except for a closing bracket is
664 permitted, allowing for arbitrary paths to a font file -- including Windows
665 style paths with UNC or drive letter prepended -- to be specified.
666 %
667 The \identifier{Luaotfload} syntax differs from \XeTeX\ in that the subfont
668 selector goes \emphasis{after} the closing bracket:
669
670 \beginnarrower
671 \nonproportional{\string\font\string\fontname\space = [}%
672 \meta{/path/to/file}%
673 \nonproportional{]}
674 \nonproportional{(}n\nonproportional{)}
675 \endnarrower
676
677 Naturally, path-less file names are equally valid and processed the
678 same way as an ordinary \inlinecode {file:} lookup.
679
680 \beginsubsection {Compatibility}
681
682 In addition to the regular prefixed requests, \identifier{luaotfload}
683 accepts loading fonts the \XeTeX\ way.
684 %
685 There are again two modes: bracketed and unbracketed.
686 For the bracketed variety, see above, \ref{sec:bracket}.
687
688 Unbracketed (or, for lack of a better word: \emphasis{anonymous})
689 font requests resemble the conventional \TeX\ syntax.
690
691 \beginnarrower
692 \nonproportional{\string\font\string\fontname\space= }%
693 \meta{font name}
694 \dots
695 \endnarrower
696 \endsubsection
697
698 However, they have a broader spectrum of possible interpretations:
699 before anything else, \identifier{luaotfload} attempts to load a
700 traditional \TeX\ Font Metric (\abbrev{tfm} or \abbrev{ofm}).
701 %
702 If this fails, it performs a \inlinecode {path:} lookup, which itself will
703 fall back to a \inlinecode {file:} lookup.
704 %
705 Lastly, if none of the above succeeded, attempt to resolve the request as a
706 \inlinecode {name:} lookup by searching the font index for \meta{font name}.
707 %
708 The behavior of this “anonymous” lookup is configurable, see the configuration
709 manpage for details.
710
711 Furthermore, \identifier{luaotfload} supports the slashed (shorthand)
712 font style notation from \XeTeX.
713
714 \beginnarrower
715 \nonproportional{\string\font\string\fontname\space= }%
716 \meta{font name}%
717 \nonproportional{/}%
718 \meta{modifier}
719 \dots
720 \endnarrower
721
722 \noindent
723 Currently, four style modifiers are supported:
724 \inlinecode {I} for italic shape,
725 \inlinecode {B} for bold weight,
726 \inlinecode {BI} or \inlinecode {IB} for the combination of both.
727 %
728 Other “slashed” modifiers are too specific to the \XeTeX\ engine and
729 have no meaning in \LuaTeX.
730
731 \endsubsection
732
733 \beginsubsection{Examples}
734
735 \beginsubsubsection{Loading by File Name}
736
737 For example, conventional \TeX\ font can be loaded with a
738 \inlinecode {file:} request like so:
739
740 \beginlisting
741 \font \lmromanten = {file:ec-lmr10} at 10pt
742 \endlisting
743
744 The \OpenType\ version of Janusz Nowacki’s font \emphasis{Antykwa
745 Półtawskiego}\footnote{%
746 \hyperlink {http://jmn.pl/antykwa-poltawskiego/}, also available in
747 in \TeX\ Live.
748 }
749 in its condensed variant can be loaded as follows:
750
751 \beginlisting
752 \font \apcregular = file:antpoltltcond-regular.otf at 42pt
753 \endlisting
754
755 The next example shows how to load the \emphasis{Porson} font digitized by
756 the Greek Font Society using \XeTeX-style syntax and an absolute path from a
757 non-standard directory:
758
759 \beginlisting
760 \font \gfsporson = "[/tmp/GFSPorson.otf]" at 12pt
761 \endlisting
762
763 \identifier{TrueType} collection files (the extension is usually
764 \inlinecode{.ttc}) contain more than a single font. In order to refer to these
765 subfonts, the respective index or the respective PostScript font name may be
766 added in parentheses after the file name.\footnote{%
767 Incidentally, this syntactical detail also prevents one from loading files
768 that end in balanced parentheses.
769 }
770
771 \beginlisting
772 \font \cambriamain = "file:cambria.ttc(0)" at 10pt
773 \font \cambriamath = "file:cambria.ttc(1)" at 10pt
774 \font \Cambriamain = "file:cambria.ttc(Cambria)" at 10pt
775 \font \Cambriamath = "file:cambria.ttc(CambriaMath)" at 10pt
776 \endlisting
777
778 and likewise, requesting subfont inside a TTC container by path:
779
780 \beginlisting
781 \font \asanamain = "[/home/typesetter/.fonts/math/asana.ttc](0):mode=node;+tlig" at 10pt
782 \font \asanamath = "[/home/typesetter/.fonts/math/asana.ttc](1):mode=base" at 10pt
783 \endlisting
784
785 \endsubsubsection
786
787 \beginsubsubsection{Loading by Font Name}
788
789 The \inlinecode {name:} lookup does not depend on cryptic filenames:
790
791 \beginlisting
792 \font \pagellaregular = {name:TeX Gyre Pagella} at 9pt
793 \endlisting
794
795 A bit more specific but essentially the same lookup would be:
796
797 \beginlisting
798 \font \pagellaregular = {name:TeX Gyre Pagella Regular} at 9pt
799 \endlisting
800
801 \noindent
802 Which fits nicely with the whole set:
803
804 \beginlisting
805 \font\pagellaregular = {name:TeX Gyre Pagella Regular} at 9pt
806 \font\pagellaitalic = {name:TeX Gyre Pagella Italic} at 9pt
807 \font\pagellabold = {name:TeX Gyre Pagella Bold} at 9pt
808 \font\pagellabolditalic = {name:TeX Gyre Pagella Bolditalic} at 9pt
809
810 {\pagellaregular foo bar baz\endgraf}
811 {\pagellaitalic foo bar baz\endgraf}
812 {\pagellabold foo bar baz\endgraf}
813 {\pagellabolditalic foo bar baz\endgraf}
814
815 ...
816 \endlisting
817
818 \endsubsubsection
819
820 \beginsubsubsection{Modifiers}
821
822 If the entire \emphasis{Iwona} family\footnote{%
823 \hyperlink {http://jmn.pl/kurier-i-iwona/},
824 also in \TeX\ Live.
825 }
826 is installed in some location accessible by \identifier{luaotfload},
827 the regular shape can be loaded as follows:
828
829 \beginlisting
830 \font \iwona = Iwona at 20pt
831 \endlisting
832
833 \noindent
834 To load the most common of the other styles, the slash notation can
835 be employed as shorthand:
836
837 \beginlisting
838 \font \iwonaitalic = Iwona/I at 20pt
839 \font \iwonabold = Iwona/B at 20pt
840 \font \iwonabolditalic = Iwona/BI at 20pt
841 \endlisting
842
843 \noindent
844 which is equivalent to these full names:
845
846 \beginlisting
847 \font \iwonaitalic = "Iwona Italic" at 20pt
848 \font \iwonabold = "Iwona Bold" at 20pt
849 \font \iwonabolditalic = "Iwona BoldItalic" at 20pt
850 \endlisting
851
852 \endsubsubsection
853 \endsubsection
854 \endsection
855
856 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
857 \beginsection {Font features}
858 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
859
860 \emphasis{Font features} are the second to last component in the
861 general scheme for font requests:
862
863 \beginnarrower
864 \nonproportional{\string\font\string\foo\space= "}%
865 \meta{prefix}%
866 \nonproportional{:}%
867 \meta{font name}%
868 \nonproportional{:}%
869 \meta{font features}%
870 \meta{\TeX\ font features}%
871 \nonproportional{"}
872 \endnarrower
873
874 \noindent
875 If style modifiers are present (\XeTeX\ style), they must precede
876 \meta{font features}.
877
878 The element \meta{font features} is a semicolon-separated list of feature
879 tags\footnote{%
880 Cf. \hyperlink {http://www.microsoft.com/typography/otspec/featurelist.htm}.
881 }
882 and font options.
883 %
884 Prepending a font feature with a \inlinecode{+} (plus sign) enables it,
885 whereas a \inlinecode{-} (minus) disables it. For instance, the request
886
887 \beginlisting
888 \font \test = LatinModernRoman:+clig;-kern
889 \endlisting
890
891 \noindent activates contextual ligatures (\inlinecode{clig}) and
892 disables kerning (\inlinecode{kern}).
893 %
894 Alternatively the options \inlinecode{true} or \inlinecode{false} can
895 be passed to the feature in a key/value expression.
896 %
897 The following request has the same meaning as the last one:
898
899 \beginlisting
900 \font \test = LatinModernRoman:clig=true;kern=false
901 \endlisting
902
903 \noindent
904 Furthermore, this second syntax is required should a font feature
905 accept other options besides a true/false switch.
906 %
907 For example, \emphasis{stylistic alternates} (\inlinecode{salt}) are
908 variants of given glyphs.
909 %
910 They can be selected either explicitly by supplying the variant
911 index (starting from one), or randomly by setting the value to,
912 obviously, \inlinecode{random}.
913
914 %% TODO verify that this actually works with a font that supports
915 %% the salt/random feature!\fi
916 \beginlisting
917 \font \librmsaltfirst = LatinModernRoman:salt=1
918 \endlisting
919
920 \beginsubsection {Basic font features}\label{sec:mode}
921
922 \begindescriptions
923
924 \beginaltitem {mode}
925 \identifier{luaotfload} had three \OpenType\ processing
926 \emphasis{modes}:
927 \identifier{base}, \identifier{node} and \identifier{harf}.
928
929 \identifier{base} mode works by mapping \OpenType\
930 features to traditional \TeX\ ligature and kerning mechanisms.
931 %
932 Supporting only non-contextual substitutions and kerning
933 pairs, it is the slightly faster, albeit somewhat limited, variant.
934 %
935 \identifier{node} mode works by processing \TeX’s internal
936 node list directly at the \Lua\ end and supports
937 a wider range of \OpenType\ features.
938 %
939 The downside is that the intricate operations required for
940 \identifier{node} mode may slow down typesetting especially
941 with complex fonts and it does not work in math mode.
942
943 By default \identifier{luaotfload} is in \identifier{node}
944 mode, and \identifier{base} mode has to be requested where needed,
945 e.~g. for math fonts.
946
947 \identifier{harf} mode is new in version 3.1 and needs the new \identifier{luahbtex} engine (the mode is ignored if \identifier{luahbtex} is not used). With it is possible to render a font using the harfbuzz library in-built in the new engine. \identifier{harf} mode improves greatly the rendering of indic and arabic scripts and is highly recommended for such scripts.
948
949 When using \identifier{harf} mode it is required to set also the script correctly.
950
951
952 \beginlisting
953 \font\burmesefont={file:NotoSerifMyanmar-Regular.ttf:mode=harf;script=mym2;}
954 \font\devafont={file:NotoSansDevanagari-Regular.ttf:mode=harf;script=dev2;}
955 \font\banglafont={name:Noto Sans Bengali:mode=harf;script=ben2;}
956 \font\tibetanfont={name:Noto Serif Tibetan:mode=harf;script=tibt;}
957 \endlisting
958
959 \includegraphics{scripts-demo}
960
961
962 It is possible to call other font renderers with the mode key. A simple example with a plain reader can be found at \url{https://github.com/latex3/luaotfload/pull/26#issuecomment-437716326}.
963
964 \endaltitem
965 \beginaltitem {shaper} \phantomsection\label{shaper-tag}
966 If \identifier{luahbtex} and \identifier{harf} mode are used it is possible to specify a shaper, like \identifier{graphite2} or \identifier{ot} (open type).
967
968 \beginlisting
969 \pardir TRT\textdir TRT
970 \font\test={file:AwamiNastaliq-Regular.ttf:mode=harf;shaper=ot}
971 \endlisting
972
973 \includegraphics{shaper-demo}
974
975 \beginlisting
976 \pardir TRT\textdir TRT
977 \font\test={file:AwamiNastaliq-Regular.ttf:mode=harf;shaper=graphite2}
978 \endlisting
979
980 \includegraphics{shaper-demo-graphite}
981
982 \endaltitem
983 \beginaltitem {script} \phantomsection\label{script-tag}
984 An \OpenType\ script tag;\footnote{%
985 See \hyperlink {http://www.microsoft.com/typography/otspec/scripttags.htm}
986 for a list of valid values.
987 %
988 For scripts derived from the Latin alphabet the value
989 \inlinecode{latn} is good choice.
990 }
991 the default value is \inlinecode{dflt}.
992 %
993 Some fonts, including very popular ones by foundries like Adobe,
994 do not assign features to the \inlinecode{dflt} script, in
995 which case the script needs to be set explicitly.
996 \endaltitem
997
998 \beginaltitem {language}
999 An \OpenType\ language system identifier,\footnote{%
1000 Cf. \hyperlink {http://www.microsoft.com/typography/otspec/languagetags.htm}.
1001 }
1002 defaulting to \inlinecode{dflt}.
1003 \endaltitem
1004
1005 \beginaltitem {color}
1006 A font color, defined as a triplet of two-digit hexadecimal
1007 \abbrev{rgb} values, with an optional fourth value for
1008 transparency
1009 (where \inlinecode{00} is completely transparent and
1010 \inlinecode{FF} is opaque).
1011
1012 For example, in order to set text in semitransparent red:
1013
1014 \beginlisting
1015 \font \test = "Latin Modern Roman:color=FF0000BB"
1016 \endlisting
1017
1018 Experimental!\marginpar{\mbox{}\hfill NEW in v3.12!}\phantomsection\label{color-glyphs} The \identifier{color} key has been
1019 extended to accept a table with color declarations of (output) glyphs. For example
1020
1021 \beginlisting
1022 \directlua{
1023 luaotfload.add_colorscheme("myscheme",
1024 {
1025 ["00FFFF30"] = {"default"},
1026 ["FF0000"] = {"kabeng","ebeng"},
1027 ["00FF00"] = {"ivowelsignbeng"},
1028 ["0000FF"] = {369} %% 369 is the GID of "nadarabeng"
1029 })
1030 }
1031 \endlisting
1032
1033 The keys in such a table are like above RGB colors with an optional transparency setting.
1034 The values are either lists of glyph names or GID numbers.
1035 Both types are font dependent! Not every font use the same
1036 glyph names (or even glyph names at all). GID number are font specific anyway. The GID can be found
1037 by looking up the \verb+["index"]+ entry in the lua file of a font.
1038
1039 Such a colorscheme can then be used like this:
1040 \beginlisting
1041 \font\test={name:Noto Sans Bengali:mode=harf;script=bng2;color=myscheme}
1042 \endlisting
1043
1044 and then would give this output:
1045
1046
1047 {\font\test={name:Noto Sans Bengali:mode=harf;script=bng2;color=myscheme}\test
1048 কণ্যা এখন কি করিবে
1049 \char"0995 \char"09BF
1050 \char"09A8 \char"09CD \char"09A6
1051 \char"09CD \char"09B0}
1052
1053 \endaltitem
1054
1055
1056 \beginaltitem {axis\&instance}
1057 Experimental!\marginpar{\mbox{}\hfill NEW in v3.15!} Support for \OpenType\
1058 variable fonts. \emph{Variable fonts use very different implementations in
1059 \texttt{harf} compared to \texttt{base} and \texttt{node} mode, so in
1060 case of unexpected behavior it can make sense to try the other mode.}
1061
1062 To specify the parameters of a variable font, you can either specify a
1063 predefined instance of the font by passing the associated
1064 \enquote{subfamily} name to \texttt{instance} or parameters for individual
1065 axis can be provided using the \texttt{axis} feature. You can \emph{not}
1066 use \texttt{instance} and \texttt{axis} together.
1067
1068 For example (needs the variable Fraunces font installed)
1069
1070 \beginlisting
1071 \def\fraunces#1#2{%
1072 \font\varfont = "Fraunces/B:mode=node;#1;" at #2pt\varfont
1073 }
1074 \fraunces{axis={wght=Regular}}{10}Regular font\par
1075 \fraunces{axis={wght=Black}}{10}Black variant (aka. very bold)\par
1076 \fraunces{axis={wght=Black,opsz=10}}{10}Black again, but with
1077 correct optical size\par
1078 \fraunces{axis={weight=100,opsz=10}}{10}Let's try giving axis values
1079 numerically\par
1080 \fraunces{instance=semibold}{10}A semi-bold one given as
1081 a instance
1082 (Corresponding to
1083 \verb|axis={opsz=144,wght=600,SOFT=100,WONG=1}|)\par
1084 \endlisting
1085
1086 {\def\fraunces#1#2{%
1087 \font\varfont = "Fraunces/B:mode=node;#1;" at #2pt\varfont
1088 }
1089 \fraunces{axis={wght=Regular}}{10}Regular font\par
1090 \fraunces{axis={wght=Black}}{10}Black variant (aka. very bold)\par
1091 \fraunces{axis={wght=Black,opsz=10}}{10}Black again, but with
1092 correct optical size\par
1093 \fraunces{axis={weight=100,opsz=10}}{10}Let's try giving axis values
1094 numerically\par
1095 \fraunces{instance=semibold}{10}A semi-bold one given as a
1096 instance\\
1097 (Corresponding to
1098 \verb|axis={opsz=144,wght=600,SOFT=100,WONG=1}|)\par
1099 }
1100
1101 \endaltitem
1102
1103 \beginaltitem {embolden}
1104 A factor, defined as a decimal number.
1105
1106 For example
1107
1108 \beginlisting
1109 \font\test = "Latin Modern Roman:mode=node;embolden=2;"
1110 \endlisting
1111
1112 {\font\test= "Latin Modern Roman:mode=node;"\test Dies is not bold.
1113 \font\test= "Latin Modern Roman:mode=node;embolden=2;" \test Dies is a faked bold font.}
1114
1115 \endaltitem
1116
1117 \beginaltitem {kernfactor \& letterspace}\phantomsection\label{p:letterspace}
1118 Define a font with letterspacing (tracking) enabled.
1119 %
1120 In \identifier{luaotfload}, letterspacing is implemented by
1121 inserting additional kerning between glyphs.
1122
1123 This approach is derived from and still quite similar to the
1124 \emphasis{character kerning} (\texmacro{setcharacterkerning} /
1125 \texmacro{definecharacterkerning} \& al.) functionality of
1126 Context, see the file \fileent{typo-krn.lua} there.
1127 %
1128 The main difference is that \identifier{luaotfload} does not
1129 use \LuaTeX\ attributes to assign letterspacing to regions,
1130 but defines virtual letterspaced versions of a font.
1131
1132 The option \identifier{kernfactor} accepts a numeric value that
1133 determines the letterspacing factor to be applied to the font
1134 size.
1135 %
1136 E.~g. a kern factor of $0.42$ applied to a $10$ pt font
1137 results in $4.2$ pt of additional kerning applied to each
1138 pair of glyphs.
1139 %
1140
1141 Spaces\marginpar{\mbox{}\hfill NEW in v2.96!} between words are now
1142 stretched too. This is consistent with the \XeTeX\ behaviour (and the amount of stretching should be similar). This
1143 naturally changes the output of a document. In case you want the old behaviour back use
1144 \beginlisting
1145 \directlua{luaotfload.letterspace.keepwordspacing = true}
1146 \endlisting
1147
1148 The difference between both options is obvious:
1149
1150 \begingroup
1151 \fontspec{IwonaMedium-Regular.otf}[LetterSpace=60]
1152 New: hello world
1153
1154 \directlua{luaotfload.letterspace.keepwordspacing = true}
1155
1156 Old: hello world
1157
1158 \directlua{luaotfload.letterspace.keepwordspacing = false}
1159 \endgroup
1160
1161
1162 Ligatures\marginpar{\mbox{}\hfill NEW in v2.96!} are no longer split into their component glyphs.
1163 This change too make the \identifier{luaotfload} more compatible with
1164 \XeTeX. It also makes it much easier to activate or deactivate ligature sets in letterspaced fonts.
1165 If you want to split ligatures, you should deactivate as you would do it with a not-letterspaced font, e.g. with the fontspec \identifier{Ligatures} option, or the low-level \identifier{-liga} and similar.
1166
1167
1168 {\font \test = "file:Iwona-Regular.otf:mode=base;+liga;+tlig;letterspace=12.5"
1169 \test With standard ligatures: fi -- ff\par
1170
1171 \font \test = "file:Iwona-Regular.otf:mode=base;-liga;+tlig;letterspace=12.5"
1172 \test Only with tlig: fi -- ff \par
1173
1174 \font \test = "file:Iwona-Regular.otf:mode=base;-liga;letterspace=12.5"
1175 \test No ligatures: fi -- ff \par
1176 }
1177
1178 For compatibility with \XeTeX\ an alternative
1179 \identifier{letterspace} option is supplied that interprets the
1180 supplied value as a \emphasis{percentage} of the font size but
1181 is otherwise identical to \identifier{kernfactor}.
1182 %
1183 Consequently, both definitions in below snippet yield the same
1184 letterspacing width:
1185
1186 \beginlisting
1187 \font \iwonakernedA = "file:Iwona-Regular.otf:kernfactor=0.125"
1188 \font \iwonakernedB = "file:Iwona-Regular.otf:letterspace=12.5"
1189 \endlisting
1190
1191 The \identifier{microtype} package uses a special implementation of letterspacing, and the commands \inlinecode{\lsstyle} and \inlinecode{\textls} are not affected by these changes.
1192
1193 Setting the ligatures with the font options is the recommended way, to activate or deactivate them. In case of special requirements
1194 specific pairs of letters and ligatures may be exempt from
1195 letterspacing by defining the \Lua\ functions
1196 \luaident{keeptogether} and \luaident{keepligature},
1197 respectively, inside the namespace \inlinecode {luaotfload.letterspace}.
1198 %
1199 Both functions are called whenever the letterspacing callback
1200 encounters an appropriate node or set of nodes.
1201 %
1202 If they return a true-ish value, no extra kern is inserted at
1203 the current position.
1204 %
1205 \luaident{keeptogether} receives a pair of consecutive
1206 glyph nodes in order of their appearance in the node list.
1207 %
1208 \luaident{keepligature} receives a single node which can be
1209 analyzed into components.
1210 %
1211 (For details refer to the \emphasis{glyph nodes} section in the
1212 \LuaTeX\ reference manual.)
1213 %
1214 The implementation of both functions is left entirely to the
1215 user.
1216 \endaltitem
1217
1218 \iffalse
1219 \startbuffer [printvectors]
1220 \directlua{inspect(fonts.protrusions.setups.default)
1221 inspect(fonts.expansions.setups.default)}
1222 \stopbuffer
1223 \fi
1224
1225 \beginaltitem {protrusion \& expansion}
1226 These keys control microtypographic features of the font,
1227 namely \emphasis{character protrusion} and \emphasis{font
1228 expansion}.
1229 %
1230 Their arguments are names of \Lua\ tables that contain
1231 values for the respective features.\footnote{%
1232 For examples of the table layout please refer to the
1233 section of the file \fileent{luaotfload-fonts-ext.lua} where the
1234 default values are defined.
1235 %
1236 Alternatively and with loss of information, you can dump
1237 those tables into your terminal by issuing
1238 \unless \iffalse
1239 \beginlisting
1240 \directlua{inspect(fonts.protrusions.setups.default)
1241 inspect(fonts.expansions.setups.default)}
1242 \endlisting
1243 \else
1244 \typebuffer [printvectors]
1245 \fi
1246 at some point after loading \fileent{luaotfload.sty}.
1247 }
1248 %
1249 For both, only the set \identifier{default} is predefined.
1250
1251 For example, to define a font with the default
1252 protrusion vector applied\footnote{%
1253 You also need to set
1254 \inlinecode {pdfprotrudechars=2} and
1255 \inlinecode {pdfadjustspacing=2}
1256 to activate protrusion and expansion, respectively.
1257 See the
1258 \hyperlink [\hologo{pdfTeX} manual]{http://mirrors.ctan.org/systems/pdftex/manual/pdftex-a.pdf}%
1259 for details.
1260 }:
1261
1262 \beginlisting
1263 \font \test = LatinModernRoman:protrusion=default
1264 \endlisting
1265 \endaltitem
1266
1267 \beginaltitem {invisible}
1268 Default Ignorable characters are control characters that should be invisible by default even if the font has glyphs for them. Since version 3.0 luaotfload makes them invisible, this can be switch on and off with the \texttt{invisible}. By default it is on.
1269
1270 For example
1271
1272 \beginlisting
1273 \font\amiri={file:amiri-regular.ttf} at 20pt \amiri
1274 \char"200Dي\char"200D
1275 \endlisting
1276
1277 {\font\amiri={file:amiri-regular.ttf} at 20pt \amiri \char"200Dي\char"200D}
1278
1279 \beginlisting
1280 \font\amiri={file:amiri-regular.ttf:-invisible;} at 20pt \amiri
1281 \char"200Dي\char"200D
1282 \endlisting
1283
1284 {\font\amiri={file:amiri-regular.ttf:-invisible;} at 20pt \amiri \char"200Dي\char"200D}
1285
1286
1287 \endaltitem
1288
1289 \beginaltitem {multiscript}
1290 In\phantomsection\label{multiscript}\marginpar{New in 3.12 -- experimental} fonts many shaping rules are implemented only for specific scripts and so you get correct typesetting only if the \identifier{script} feature is correctly set. This means that to write a text which uses more than one script you have to declare a font for each script and switch fonts even if the font contains glyphs for all scripts.
1291 \identifier{multiscript} tries to help here. The feature is experimental and bound to change. Feedback is welcome but you use it at your risk.
1292
1293 \identifier{multiscript} allows you to declare fonts for various script. The value is either \identifier{auto} described below, or a name which has been previously declared or a combination of both. An example for such a named multiscript could look like this (the colors are only for demonstration):
1294
1295 \beginlisting
1296 \directlua{
1297 luaotfload.add_multiscript
1298 ("cyrlgrekbeng",
1299 {
1300 Cyrl = "DejaVuSans:mode=node;script=cyrl;color=FF0000;",
1301 Grek = "texgyreheros:mode=harf;script=grek;color=0000FF;",
1302 Beng = "NotoSansBengali:mode=harf;script=bng2;color=00FF00;"
1303 }
1304 )
1305 }
1306 \endlisting
1307
1308 \identifier{cyrlgrekbeng} is the name of the multiscript (the name is case insensitive). The keys are ISO language tags (not open type tags!). They are case insensitive too: the example uses an uppercase letter for ISO tags to differentiate them from script tags. The values are font declarations.
1309
1310 The multiscript can then be used in a font like this:
1311
1312 \beginlisting
1313 \font\test={name:DejaVuSans:mode=node;multiscript=cyrlgrekbeng;}
1314 \endlisting
1315
1316 This would lead to this output:
1317
1318 {\Large \font\test={name:DejaVuSans:mode=node;multiscript=cyrlgrekbeng;}\test
1319 „a^^^^0301123!?“ „π^^^^0301123!?“ „a!?“ „Б123!?“ a „\char"0995\char"09BF 123“
1320 }
1321
1322 It shows that fonts are switched with the scripts.
1323
1324 Be aware of the following drawbacks:
1325
1326 \begin{itemize}
1327 \item Quite a lot chars can and should be used with more than one script, they belong to the Common or Inherited class. Examples are punctuation chars, digits, accents but also emoji. Currently these chars follow the active script. That's why the digits are all typeset with a different font, the accent over the pi is different to the one over the a, and why the opening quote is sometimes different to the closing quote. It is clear that some tools to force a script (and so a font) locally and globally for such chars are needed.
1328
1329 \item \identifier{multiscript} doesn't change hyphenation patterns or other language or script related features.
1330
1331 \item Language packages like \identifier{babel} or \identifier{polyglossia} have code to change the script too which could interfere or clash. This hasn't been tested yet.
1332
1333 \item \identifier{multiscript} can slow down the compilation.
1334 \end{itemize}
1335
1336 It is possible to use the value \identifier{auto} with \identifier{multiscript}. luaotfload will then switch the script if it detects a char belonging to another script (and if the font support this script). This can be useful for fonts supporting more than one script or when using the \identifier{fallback} key described below.
1337
1338 It is also possible to combine \identifier{auto} with a named multiscript with the syntax \identifier{multiscript=auto+name}. The rules of the named multiscript will in such cases take precedence and \identifier{auto} used only for other scripts.
1339
1340
1341
1342 \endaltitem
1343
1344 \beginaltitem {fallback}
1345 This\label{fallback}\marginpar{New in 3.12 -- experimental}
1346 allows you to define a chain of fonts which are used if glyphs are missing in the main font.
1347 It works only for text fonts, not for math fonts set with the \identifier{unicode-math} package.
1348 The feature is experimental and bound to change. Feedback is welcome but you use it at your risk.
1349 For example
1350
1351 \beginlisting
1352 \directlua
1353 {luaotfload.add_fallback
1354 ("myfallback",
1355 {
1356 "DejaVuSans:mode=harf;script=grek;color=FF0000;",
1357 "cmuserif:mode=node;script=cyrl;color=00FF00;",
1358 "NotoSansBengali:mode=harf;script=bng2;color=0000FF;",
1359 "NotoColorEmoji:mode=harf;"
1360 }
1361 )
1362 }
1363 \endlisting
1364
1365 This fallback can then be used e.g. like this:
1366
1367 \beginlisting
1368 \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;}
1369 \endlisting
1370
1371 {\Large
1372 \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;}\test
1373 1234 a^^^^0301 π^^^^0301 a!? π123!? a БѨ123!? a \char"1F600\ \char"1F986\ \char"0995\char"09BF a „π“ a „Б“
1374 }
1375
1376 Interesting points in the output are
1377 \begin{itemize}
1378 \item The accent over the pi, the digits and the quotes are all from the base font. Only missing glyphs are from the fallback.
1379 \item The cyrillic is printed with the DejaVu font, despite the fact that is sets the script to \identifier{grek} and that the next font in the fallback chain would fit better.
1380 \item The duck emoji is from the Noto font, while the face is from DejaVu as it comes first in the chain.
1381 \end{itemize}
1382
1383 The \identifier{fallback} can be combined with the \identifier{multiscript}. For example
1384
1385 \beginlisting
1386 \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;multiscript=auto;}
1387 \endlisting
1388
1389 {\Large
1390 \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;multiscript=auto;}\test
1391 1234 a^^^^0301 π^^^^0301 a!? π123!? a БѨ123!? a \char"1F600\ \char"1F986\ \char"0995\char"09BF a „π“ a „Б“
1392 }
1393
1394 Now the accent over the pi is better. The digits after the pi and the closing quote use the DejaVu font. The digits after
1395 the cyrillic use the Latin Modern font because of an interesting \enquote{feature} of this font: It claims to know the \identifier{cyrl} script despite the fact that it doesn't contain any cyrillic glyphs.
1396
1397 \identifier{fallback} can be nested: fonts in the fallback table can refer to another \identifier{fallback} table.
1398
1399 As with the \identifier{multiscript} key more control over the used glyph and script in edge cases will be needed.
1400 \endaltitem
1401
1402 \beginaltitem {upper/lower}
1403 The\phantomsection\label{upperlower}\marginpar{New in 3.16}
1404 font features \texttt{upper} and \texttt{lower} can be used to map
1405 the text of a font to upper or lowercase before displaying it.
1406
1407 By default the casemapping is automatically tailored based on the active
1408 \texttt{language} font feature. This automatic tailoring can be overwritten
1409 by passing a two letter language tag to the \texttt{upper} or \texttt{lower}
1410 feature. In addition to ordinary language tags, the tags \texttt{el-x-iota},
1411 \texttt{hy-x-yiwn} and \texttt{de-x-eszett} can be used. \texttt{el-x-iota}
1412 adapts the greek rules for uppercasing to keep iota subscripts as combining
1413 characters which sufficiently well behaving fonts can render in appropriate
1414 ways while the default for greek is to convert these into capital iotas.
1415 \texttt{de-x-eszett} adapts uppercasing for german to use the capital eszett
1416 instead of uppercasing the eszett to double capital s.
1417
1418 \beginlisting
1419 \font\test={kpse:LinLibertine_R.otf:mode=node;+upper;}
1420 \test Grüße
1421 \font\test={kpse:LinLibertine_R.otf:mode=node;upper=de-x-eszett;}
1422 \test Grüße
1423 \endlisting
1424
1425 {\Large
1426 \font\test={kpse:LinLibertine\string_R.otf:mode=node;+upper;}\test Grüße
1427 \font\test={kpse:LinLibertine\string_R.otf:mode=node;upper=de-x-eszett;}\test Grüße
1428 }
1429
1430 \beginlisting
1431 \font\test={kpse:LinLibertine_R.otf:mode=node;script=grek;+upper;}
1432 No specified language: {\test εἰσενέγκῄς ἡμᾶς}\par
1433 \font\test={kpse:LinLibertine_R.otf:mode=node;script=grek;language=ell;+upper;}
1434 Greek uppercasing: {\test εἰσενέγκῄς ἡμᾶς}\par
1435 \font\test={kpse:LinLibertine_R.otf:mode=node;script=grek;language=ell;+upper=el-x-iota;}
1436 Greek variant: {\test εἰσενέγκῄς ἡμᾶς}\par
1437 \endlisting
1438
1439 {%
1440 \font\test={kpse:LinLibertine\string_R.otf:mode=node;script=grek;+upper;}
1441 No specified language: {\test εἰσενέγκῄς ἡμᾶς}\par
1442 \font\test={kpse:LinLibertine\string_R.otf:mode=node;script=grek;language=ell;+upper;}
1443 Greek uppercasing: {\test εἰσενέγκῄς ἡμᾶς}\par
1444 \font\test={kpse:LinLibertine\string_R.otf:mode=node;script=grek;language=ell;+upper=el-x-iota;}
1445 Greek variant: {\test εἰσενέγκῄς ἡμᾶς}\par
1446 }
1447
1448
1449 \endaltitem
1450
1451 \beginaltitem {Variable fonts}
1452 When\phantomsection\label{variablefonts}\marginpar{New in 3.16}
1453 the \texttt{node} shaper is used,
1454 experimental support for \OpenType\ variable
1455 fonts has been added. To use them, set the font feature \texttt{axis} to
1456 a comma separated list of axis names and values. (E.g. \texttt{axis={weight=600}})
1457 The supported axis names and value range depend on the font (see~page~\pageref{variablefonts}).
1458 The following listing shows an example with the Source Code Variable font:
1459
1460 \begin{lstlisting}[columns=fullflexible]
1461 \documentclass{article}
1462 \DeclareFontFamily{TU}{sourcecode-variable}{}
1463 \newcommand\DeclareSourceVariable[2]{%
1464 \DeclareFontShape{TU}{sourcecode-variable}{#1}{n}{%
1465 <-> \UnicodeFontFile{SourceCodeVariable-Roman.otf}
1466 {\UnicodeFontTeXLigatures axis={weight=#2};}%
1467 }{}%
1468 \DeclareFontShape{TU}{sourcecode-variable}{#1}{it}{%
1469 <-> \UnicodeFontFile{SourceCodeVariable-Italic.otf}
1470 {\UnicodeFontTeXLigatures axis={weight=#2};}%
1471 }{}%
1472 }
1473 \DeclareSourceVariable{ul}{200}
1474 \DeclareSourceVariable{el}{250}
1475 \DeclareSourceVariable{l}{300}
1476 \DeclareSourceVariable{sl}{350}
1477 \DeclareSourceVariable{m}{400}
1478 \DeclareSourceVariable{sb}{500}
1479 \DeclareSourceVariable{b}{600}
1480 \DeclareSourceVariable{eb}{700}
1481 \DeclareSourceVariable{ub}{900}
1482 \begin{document}
1483 \fontfamily{sourcecode-variable}\selectfont
1484 \fontseries{ul}\selectfont a\textit{b}
1485 \fontseries{el}\selectfont c\textit{d}
1486 \fontseries{l}\selectfont e\textit{f}
1487 \fontseries{sl}\selectfont g\textit{h}
1488 \fontseries{m}\selectfont i\textit{j}
1489 \fontseries{sb}\selectfont k\textit{l}
1490 \fontseries{b}\selectfont m\textit{n}
1491 \fontseries{eb}\selectfont o\textit{p}
1492 \fontseries{ub}\selectfont q\textit{r}
1493 \end{document}
1494 \end{lstlisting}
1495
1496 \enddescriptions
1497
1498 \endsubsection
1499
1500 \beginsubsection {Non-standard font features}
1501 \identifier{luaotfload} adds a number of features that are not defined
1502 in the original \OpenType\ specification, most of them
1503 aiming at emulating the behavior familiar from other \TeX\ engines.
1504 %
1505 Currently (2014) there are three of them:
1506
1507 \begindescriptions
1508
1509 \beginaltitem {anum}
1510 Substitutes the glyphs in the \abbrev{ascii} number range
1511 with their counterparts from eastern Arabic or Persian,
1512 depending on the value of \identifier{language}.
1513 \endaltitem
1514
1515 \beginaltitem {tlig}
1516 Applies legacy \TeX\ ligatures\footnote{%
1517 These contain the feature set \inlinecode {trep} of earlier
1518 versions of \identifier{luaotfload}.
1519
1520 Note to \XeTeX\ users: this is the equivalent of the
1521 assignment \inlinecode {mapping=text-tex} using \XeTeX's input
1522 remapping feature.
1523 }:
1524
1525 \unless \iffalse
1526 %% Using braced arg syntax with inline code appears to be
1527 %% impossible within Latex tables -- just ignore the weird
1528 %% exclamation points below.
1529 \begintabulate [rlrl]
1530 \beginrow `` \newcell {\inlinecode !``! } \newcell '' \newcell {\inlinecode !''!} \endrow
1531 \beginrow ` \newcell {\inlinecode !`! } \newcell ' \newcell {\inlinecode !'! } \endrow
1532 \beginrow " \newcell {\inlinecode !"! } \newcell -- \newcell {\inlinecode !--!} \endrow
1533 \beginrow --- \newcell {\inlinecode !---!} \newcell !` \newcell {\inlinecode ?!`?} \endrow
1534 \beginrow ?` \newcell {\inlinecode !?`! } \newcell \newcell \endrow
1535 \endtabulate
1536 \else
1537 %% XXX find a way to wrap these in the tabulate environment
1538 \startframed [frame=off,width=broad,align=middle]
1539 \startframed [frame=off,width=\dimexpr(\textwidth/2)]
1540 \startxtable [align=middle]
1541 \startxrow \startxcell `` \stopxcell \startxcell \inlinecode {``} \stopxcell \startxcell '' \stopxcell \startxcell \inlinecode {''} \stopxcell \stopxrow
1542 \startxrow \startxcell ` \stopxcell \startxcell \inlinecode {`} \stopxcell \startxcell ' \stopxcell \startxcell \inlinecode {'} \stopxcell \stopxrow
1543 \startxrow \startxcell " \stopxcell \startxcell \inlinecode {"} \stopxcell \startxcell -- \stopxcell \startxcell \inlinecode {--} \stopxcell \stopxrow
1544 \startxrow \startxcell --- \stopxcell \startxcell \inlinecode {---} \stopxcell \startxcell !` \stopxcell \startxcell \inlinecode {!`} \stopxcell \stopxrow
1545 \startxrow \startxcell ?` \stopxcell \startxcell \inlinecode {?`} \stopxcell \startxcell \stopxcell \startxcell \stopxcell \stopxrow
1546 \stopxtable
1547 \stopframed
1548 \stopframed
1549 \fi
1550 \endaltitem
1551
1552 \beginaltitem {itlc}
1553 Computes italic correction values (active by default).
1554 \endaltitem
1555
1556 \enddescriptions
1557
1558 \endsubsection
1559
1560 \endsection
1561
1562 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1563 \beginsection {Combining fonts}
1564 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1565 Beside the new keys \identifier{multiscript} and \identifier{fallback} described earlier
1566 Version 2.7 and later support another method to combine characters from multiple fonts into a
1567 single virtualized one. This requires that the affected fonts be loaded in
1568 advance as well as a special \emphasis{request syntax}. Furthermore, this
1569 allows to define \emphasis{fallback fonts} to supplement fonts that may lack
1570 certain required glyphs.
1571
1572 Combinations are created by defining a font using the \luaident{combo:} prefix.
1573
1574 \beginsubsection {Fallbacks}
1575
1576 For example, the \identifier{Latin Modern} family of fonts does, as indicated
1577 in the name, not provide Cyrillic glyphs. If Latin script dominates in the copy
1578 with interspersed Cyrillic, a fallback can be created from a similar looking
1579 font like \identifier{Computer Modern Unicode}, taking advantage of the fact
1580 that it too derives from Knuth’s original \identifier{Computer Modern} series:
1581
1582 \beginlisting
1583 \input luaotfload.sty
1584 \font \lm = file:lmroman10-regular.otf:mode=base
1585 \font \cmu = file:cmunrm.otf:mode=base
1586 \font \lmu = "combo: 1->\fontid\lm; 2->\fontid\cmu,fallback"
1587 \lmu Eh bien, mon prince. Gênes et Lueques ne sont plus que des
1588 apanages, des поместья, de la famille Buonaparte.
1589 \bye
1590 \endlisting
1591
1592 As simple as this may look on the first glance, this approach is entirely
1593 inappropriate if more than a couple letters are required from a different font.
1594 Because the combination pulls nothing except the glyph data, all of the
1595 important other information that constitute a proper font -- kerning, styles,
1596 features, and suchlike -- will be missing.
1597
1598 \endsubsection %% Fallbacks
1599
1600 \beginsubsection {Combinations}
1601
1602 Generalizing the idea of a \emphasis{fallback font}, it is also possible to
1603 pick definite sets of glyphs from multiple fonts. On a bad day, for instance,
1604 it may be the sanest choice to start out with \identifier{EB Garamond} italics,
1605 typeset all decimal digits in the bold italics of \identifier{GNU Freefont},
1606 and tone down the punctuation with extra thin glyphs from \identifier{Source
1607 Sans}:
1608
1609 \beginlisting
1610 \def \feats {-tlig;-liga;mode=base;-kern}
1611 \def \fileone {EBGaramond12-Italic.otf}
1612 \def \filetwo {FreeMonoBoldOblique.otf}
1613 \def \filethree {SourceSansPro-ExtraLight.otf}
1614
1615 \input luaotfload.sty
1616
1617 \font \one = file:\fileone :\feats
1618 \font \two = file:\filetwo :\feats
1619 \font \three = file:\filethree:\feats
1620
1621 \font \onetwothree = "combo: 1 -> \fontid\one;
1622 2 -> \fontid\two, 0x30-0x39;
1623 3 -> \fontid\three, 0x21*0x3f; "
1624
1625 {\onetwothree \TeX—0123456789—?!}
1626 \bye
1627 \endlisting
1628
1629 \noindent Despite the atrocious result, the example demonstrates well the
1630 syntax that is used to specify ranges and fonts. Fonts are being referred to by
1631 their internal index which can be obtained by passing the font command into the
1632 \texmacro{fontid} macro, e. g. \inlinecode{\fontid\one}, after a font has been
1633 defined. The first component of the combination is the base font which will be
1634 extended by the others. It is specified by the index alone.
1635
1636 All further fonts require either the literal \inlinecode{fallback} or a list of
1637 codepoint definitions to be appended after a comma. The elements of this list
1638 again denote either single codepoints like \inlinecode{0x21} (referring to the
1639 exclamation point character) or ranges of codepoints (\inlinecode{0x30-0x39}).
1640 Elements are separated by the \identifier{ASCII} asterisk character
1641 (\inlinecode{*}). The characters referenced in the list will be imported from
1642 the respective font, if available.
1643
1644 \endsubsection %% Combinations
1645
1646 \endsection
1647
1648 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1649 \beginsection {Font names database}
1650 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1651
1652 \label{sec:fontdb}
1653
1654 As mentioned above, \identifier{luaotfload} keeps track of which
1655 fonts are available to \LuaTeX\ by means of a \emphasis{database}.
1656 %
1657 This allows referring to fonts not only by explicit filenames but
1658 also by the proper names contained in the metadata which is often
1659 more accessible to humans.\footnote{%
1660 The tool \hyperlink[\fileent{otfinfo}]{http://www.lcdf.org/type/}
1661 (comes with \TeX\ Live), when invoked on a font file with the
1662 \inlinecode {-i} option, lists the variety of name fields defined for
1663 it.
1664 }
1665
1666 When \identifier{luaotfload} is asked to load a font by a font name,
1667 it will check if the database exists and load it, or else generate a
1668 fresh one.
1669 %
1670 Should it then fail to locate the font, an update to the database is
1671 performed in case the font has been added to the system only
1672 recently.
1673 %
1674 As soon as the database is updated, the resolver will try
1675 and look up the font again, all without user intervention.
1676 %
1677 The goal is for \identifier{luaotfload} to act in the background and
1678 behave as unobtrusively as possible, while providing a convenient
1679 interface to the fonts installed on the system.
1680
1681 Generating the database for the first time may take a while since it
1682 inspects every font file on your computer.
1683 %
1684 This is particularly noticeable if it occurs during a typesetting run.
1685 In any case, subsequent updates to the database will be quite fast.
1686
1687 \beginsubsection[luaotfload-tool]
1688 {\fileent{luaotfload-tool}}
1689
1690 It can still be desirable at times to do some of these steps
1691 manually, and without having to compile a document.
1692 %
1693 To this end, \identifier{luaotfload} comes with the utility
1694 \fileent{luaotfload-tool} that offers an interface to the database
1695 functionality.
1696 %
1697 Being a \Lua\ script, there are two ways to run it:
1698 either make it executable (\inlinecode {chmod +x} on unixoid systems) or
1699 pass it as an argument to \fileent{texlua}.\footnote{%
1700 Tests by the maintainer show only marginal performance gain by
1701 running with Luigi Scarso’s
1702 \hyperlink [\identifier{Luajit\kern-.25ex\TeX}]{https://foundry.supelec.fr/projects/luajittex/},
1703 which is probably due to the fact that most of the time is spent
1704 on file system operations.
1705
1706 \emphasis{Note}:
1707 On \abbrev{MS} \identifier{Windows} systems, the script can be run
1708 either by calling the wrapper application
1709 \fileent{luaotfload-tool.exe} or as
1710 \inlinecode {texlua.exe luaotfload-tool.lua}.
1711 }
1712 %
1713 Invoked with the argument \inlinecode {--update} it will perform a database
1714 update, scanning for fonts not indexed.
1715
1716 \beginlisting
1717 luaotfload-tool --update
1718 \endlisting
1719
1720 Adding the \inlinecode {--force} switch will initiate a complete
1721 rebuild of the database.
1722
1723 \beginlisting
1724 luaotfload-tool --update --force
1725 \endlisting
1726
1727 \endsubsection
1728
1729 \beginsubsection{Search Paths}
1730
1731 \identifier{luaotfload} scans those directories where fonts are
1732 expected to be located on a given system.
1733 %
1734 On a Linux machine it follows the paths listed in the
1735 \identifier{Fontconfig} configuration files;
1736 consult \inlinecode {man 5 fonts.conf} for further information.
1737 %
1738 On \identifier{Windows} systems, the standard location is
1739 \inlinecode {Windows\\Fonts},
1740 %
1741 while \identifier{Mac OS~X} requires a multitude of paths to
1742 be examined.
1743 %
1744 The complete list is is given in table \ref{table-searchpaths}.
1745 Other paths can be specified by setting the environment variable
1746 \inlinecode {OSFONTDIR}.
1747 %
1748 If it is non-empty, then search will be extended to the included
1749 directories.
1750
1751 \tablefloat {table-searchpaths}
1752 {List of paths searched for each supported operating system.}
1753 {%
1754 \unless \iffalse
1755 \begincentered
1756 \begintabulate [lp{.5\textwidth}]
1757 \beginrow
1758 Windows \newcell \inlinecode !\% WINDIR\%\\ Fonts!
1759 \endrow
1760 \beginrow
1761 Linux \newcell \fileent{/usr/local/etc/fonts/fonts.conf} and\hfill\break
1762 \fileent{/etc/fonts/fonts.conf}
1763 \endrow
1764 \beginrow
1765 Mac \newcell \fileent{\textasciitilde/Library/Fonts},\break
1766 \fileent{/Library/Fonts},\break
1767 \fileent{/System/Library/Fonts}, and\hfill\break
1768 \fileent{/Network/Library/Fonts}
1769 \endrow
1770 \endtabulate
1771 \endcentered
1772 \else
1773 \setuplocalinterlinespace [14pt]
1774 \starttabulate [|l|p(.5\textwidth)|]
1775 \NC Windows \NC \inlinecode {\% WINDIR\%\\ Fonts} \NC \NR
1776 \NC Linux \NC \fileent{/usr/local/etc/fonts/fonts.conf} and\crlf
1777 \fileent{/etc/fonts/fonts.conf} \NC \NR
1778 \NC
1779 Mac \NC \fileent{\textasciitilde/Library/Fonts},\crlf
1780 \fileent{/Library/Fonts},\break
1781 \fileent{/System/Library/Fonts}, and\crlf
1782 \fileent{/Network/Library/Fonts} \NC \NR
1783 \stoptabulate
1784 \fi%
1785 }
1786
1787 \endsubsection
1788
1789 \beginsubsection{Querying from Outside}
1790
1791 \fileent{luaotfload-tool} also provides rudimentary means of
1792 accessing the information collected in the font database.
1793 %
1794 If the option \inlinecode {--find=}\emphasis{name} is given, the script will
1795 try and search the fonts indexed by \identifier{luaotfload} for a
1796 matching name.
1797 %
1798 For instance, the invocation
1799
1800 \beginlisting
1801 luaotfload-tool --find="Iwona Regular"
1802 \endlisting
1803
1804 \noindent
1805 will verify if “Iwona Regular” is found in the database and can be
1806 readily requested in a document.
1807
1808 If you are unsure about the actual font name, then add the
1809 \inlinecode {-F} (or \inlinecode {--fuzzy}) switch to the command line to enable
1810 approximate matching.
1811 %
1812 Suppose you cannot precisely remember if the variant of
1813 \identifier{Iwona} you are looking for was “Bright” or “Light”.
1814 The query
1815
1816 \beginlisting
1817 luaotfload-tool -F --find="Iwona Bright"
1818 \endlisting
1819
1820 \noindent
1821 will tell you that indeed the latter name is correct.
1822
1823 Basic information about fonts in the database can be displayed
1824 using the \inlinecode {-i} option (\inlinecode {--info}).
1825 %
1826 \beginlisting
1827 luaotfload-tool -i --find="Iwona Light Italic"
1828 \endlisting
1829 %
1830 \noindent
1831 The meaning of the printed values is described in section 4.4 of the
1832 \LuaTeX\ reference manual.\footnote{%
1833 In \TeX\ Live: \fileent{texmf-dist/doc/luatex/base/luatexref-t.pdf}.
1834 }
1835
1836 For a much more detailed report about a given font try the
1837 \inlinecode {-I} option instead (\inlinecode {--inspect}).
1838 \beginlisting
1839 luaotfload-tool -I --find="Iwona Light Italic"
1840 \endlisting
1841
1842 \inlinecode {luaotfload-tool --help} will list the available command line
1843 switches, including some not discussed in detail here.
1844 %
1845 For a full documentation of \identifier{luaotfload-tool} and its
1846 capabilities refer to the manpage
1847 (\inlinecode {man 1 luaotfload-tool}).\footnote{%
1848 Or see \inlinecode {luaotfload-tool.rst} in the source directory.
1849 }
1850
1851 \endsubsection
1852
1853 \beginsubsection {Blacklisting Fonts}
1854 \label{font-blacklist}
1855
1856 Some fonts are problematic in general, or just in \LuaTeX.
1857 %
1858 If you find that compiling your document takes far too long or eats
1859 away all your system’s memory, you can track down the culprit by
1860 running \inlinecode {luaotfload-tool -v} to increase verbosity.
1861 %
1862 Take a note of the \emphasis{filename} of the font that database
1863 creation fails with and append it to the file
1864 \fileent{luaotfload-blacklist.cnf}.
1865
1866 A blacklist file is a list of font filenames, one per line.
1867 Specifying the full path to where the file is located is optional, the
1868 plain filename should suffice.
1869 %
1870 File extensions (\fileent{.otf}, \fileent{.ttf}, etc.) may be omitted.
1871 %
1872 Anything after a percent (\inlinecode {\%}) character until the end of the line
1873 is ignored, so use this to add comments.
1874 %
1875 Place this file to some location where the \identifier{kpse}
1876 library can find it, e.~g.
1877 \fileent{texmf-local/tex/luatex/luaotfload} if you are running
1878 \identifier{\TeX\ Live},\footnote{%
1879 You may have to run \inlinecode {mktexlsr} if you created a new file in
1880 your \fileent{texmf} tree.
1881 }
1882 or just leave it in the working directory of your document.
1883 %
1884 \identifier{luaotfload} reads all files named
1885 \fileent{luaotfload-blacklist.cnf} it finds, so the fonts in
1886 \fileent{./luaotfload-blacklist.cnf} extend the global blacklist.
1887
1888 Furthermore, a filename prepended with a dash character (\inlinecode{-}) is
1889 removed from the blacklist, causing it to be temporarily whitelisted
1890 without modifying the global file.
1891 %
1892 An example with explicit paths:
1893
1894 \beginlisting
1895 % example otf-blacklist.cnf
1896 /Library/Fonts/GillSans.ttc % Luaotfload ignores this font.
1897 -/Library/Fonts/Optima.ttc % This one is usable again, even if
1898 % blacklisted somewhere else.
1899 \endlisting
1900
1901 \endsubsection
1902 \endsection
1903
1904 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1905 \beginsection {The Fontloader}
1906 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1907
1908 \beginsubsection {Overview}
1909
1910 To a large extent, \identifier{luaotfload} relies on code originally
1911 written by Hans Hagen for the
1912 \hyperlink[\identifier{\ConTeXt}]{http://wiki.contextgarden.net}
1913 format.
1914 %
1915 It integrates the font loader, written entirely in \Lua, as distributed
1916 in the \identifier{\LuaTeX-Fonts} package.
1917 %
1918 The original \Lua\ source files have been combined using the \ConTeXt\
1919 packaging library into a single, self-contained blob. In
1920 this form the font loader depends only on the \identifier{lualibs}
1921 package and requires only minor adaptions to integrate into
1922 \identifier{luaotfload}.
1923
1924 The guiding principle is to let \ConTeXt/\LuaTeX-Fonts take care of the
1925 implementation, and update the imported code as frequently as
1926 necessary.
1927 %
1928 As maintainers, we aim at importing files from upstream essentially
1929 \emphasis{unmodified}, except for renaming them to prevent name
1930 clashes.
1931 %
1932 This job has been greatly alleviated since the advent of
1933 \LuaTeX-Fonts, prior to which the individual dependencies had to be
1934 manually spotted and extracted from the \ConTeXt\ source code in a
1935 complicated and error-prone fashion.
1936
1937 \endsubsection
1938
1939 \beginsubsection {Contents and Dependencies}
1940
1941 Below is a commented list of the files distributed with
1942 \identifier{luaotfload} in one way or the other.
1943 %
1944 See see the figure on page \pageref{file-graph} for a
1945 graphical representation of the dependencies.
1946 %
1947 \label{package}%
1948 Through the script \fileent{mkimport} a \ConTeXt\ library
1949 is invoked to create the \identifier{luaotfload} fontloader as a merged
1950 (amalgamated) source file.\footnote{%
1951 In \ConTeXt, this facility can be accessed by means of a
1952 \hyperlink[script]{https://bitbucket.org/phg/context-mirror/src/beta/scripts/context/lua/mtx-package.lua?at=beta}
1953 which is integrated into \fileent{mtxrun} as a subcommand.
1954 Run \inlinecode {mtxrun --script package --help} to display further
1955 information.
1956 For the actual merging code see the file
1957 \fileent{util-mrg.lua} that is part of \ConTeXt.
1958 }
1959 %
1960 This file constitutes the “default fontloader” and is part of the
1961 \identifier{luaotfload} package as \fileent{fontloader-YY-MM-DD.lua},
1962 where the uppercase letters are placeholders for the build date.
1963 %
1964 A companion to it, \fileent{luatex-basics-gen.lua} (renamed to \fileent{fontloader-basics-gen.lua} in \identifier{luaotfload})
1965 must be loaded beforehand to set up parts of the environment required
1966 by the \ConTeXt\ libraries.
1967 %
1968 During a \TeX\ run, the fontloader initialization and injection happens
1969 in the module \fileent{luaotfload-init.lua}.
1970 %
1971 Additionally, the “reference fontloader” as imported from \LuaTeX-Fonts
1972 is provided as the file \fileent{fontloader-reference.lua}.
1973 %
1974 This file is self-contained in that it packages all the auxiliary \Lua\
1975 libraries too, as Luaotfload did up to the 2.5 series; since that job
1976 has been offloaded to the \identifier{Lualibs} package, loading this
1977 fontloader introduces a certain code duplication.
1978
1979 A number of \emphasis{\Lua\ utility libraries} are not part of the
1980 \identifier{luaotfload} fontloader, contrary to its equivalent in
1981 \LuaTeX-Fonts. These are already provided by the \identifier{lualibs}
1982 and have thus been omitted from the merge.\footnote{%
1983 Faithful listeners will remember the pre-2.6 era when the fontloader
1984 used to be integrated as-is which caused all kinds of code
1985 duplication with the pervasive \identifier{lualibs} package.
1986 This conceptual glitch has since been amended by tightening the
1987 coupling with the excellent \ConTeXt\ toolchain.
1988 }
1989
1990 \begindoublecolumns
1991 \begindefinitions
1992 \directlua{ printctxlibslist ()}
1993 \enddefinitions
1994 \enddoublecolumns
1995
1996 The reference fontloader is home to several \Lua\ files that can be
1997 grouped twofold as below:
1998
1999 \begindefinitions
2000 \beginnormalitem
2001 The \emphasis{font loader} itself.
2002 These files have been written for \LuaTeX-Fonts and they are
2003 distributed along with \identifier{luaotfload} so as to resemble
2004 the state of the code when it was imported. Their purpose is either
2005 to give a slightly aged version of a file if upstream considers
2006 latest developments for not yet ready for use outside Context; or,
2007 to install placeholders or minimalist versions of APIs relied upon
2008 but usually provided by parts of Context not included in the
2009 fontloader.
2010 \begindoublecolumns
2011 \begindefinitions
2012 \directlua{printctxallgenericlist ()}
2013 \enddefinitions
2014 \enddoublecolumns
2015 \endnormalitem
2016
2017 \beginnormalitem
2018 Code related to \emphasis{font handling and node processing}, taken
2019 directly from \ConTeXt.
2020 \begindoublecolumns
2021 \begindefinitions
2022 \directlua{printctxfontlist ()}
2023 \enddefinitions
2024 \enddoublecolumns
2025 \endnormalitem
2026 \enddefinitions
2027
2028 As an alternative to the merged file, \identifier {Luaotfload} may load
2029 individual unpackaged \Lua\ libraries that come with the source, or even
2030 use the files from Context directly.
2031 %
2032 Thus if you prefer running bleeding edge code from the \ConTeXt\ beta,
2033 choose the \inlinecode {context} fontloader via the configuration file
2034 (see sections \ref{sec:conf} and \ref{sec:pkg} below).
2035
2036 Also, the merged file at some point loads the Adobe Glyph List from a
2037 \Lua\ table that is contained in \fileent{luaotfload-glyphlist.lua},
2038 which is automatically generated by the script
2039 \fileent{mkglyphlist}.\footnote{%
2040 See \fileent{luaotfload-font-enc.lua}.
2041 The hard-coded file name is why we have to replace the procedure
2042 that loads the file in \fileent{luaotfload-init.lua}.
2043 }
2044 %
2045 There is a make target \identifier{glyphs} that will create a fresh
2046 glyph list so we don’t need to import it from \ConTeXt\ any longer.
2047
2048 In addition to these, \identifier{luaotfload} requires a number of
2049 files not contained in the merge. Some of these have no equivalent in
2050 \LuaTeX-Fonts or \ConTeXt, some were taken unmodified from the latter.
2051
2052
2053 \beginfilelist
2054 \beginaltitem {luaotfload-features.lua}
2055 font feature handling; incorporates some of the code from
2056 \fileent{font-otc} from \ConTeXt;
2057 \endaltitem
2058 \beginaltitem {luaotfload-configuration.lua}
2059 handling of \fileent{luaotfload.conf(5)}.
2060 \endaltitem
2061 \beginaltitem {luaotfload-log.lua}
2062 overrides the \ConTeXt\ logging functionality.
2063 \endaltitem
2064 \beginaltitem {luaotfload-loaders.lua}
2065 registers readers in the fontloader for various kinds of
2066 font formats
2067 \endaltitem
2068 \beginaltitem {luaotfload-parsers.lua}
2069 various \abbrev{lpeg}-based parsers.
2070 \endaltitem
2071 \beginaltitem {luaotfload-database.lua}
2072 font names database.
2073 \endaltitem
2074 \beginaltitem {luaotfload-resolvers.lua}
2075 file name resolvers.
2076 \endaltitem
2077 \beginaltitem {luaotfload-colors.lua}
2078 color handling.
2079 \endaltitem
2080 \beginaltitem {luaotfload-auxiliary.lua}
2081 access to internal functionality for package authors (proposals
2082 for additions welcome).
2083 \endaltitem
2084 \beginaltitem {luaotfload-letterspace.lua}
2085 font-based letterspacing.
2086 \endaltitem
2087 \beginaltitem {luaotfload-filelist.lua}
2088 data about the files in the package.
2089 \endaltitem
2090 \endfilelist
2091
2092 %\figurefloat
2093 % {file-graph}
2094 % {Schematic of the files in \identifier{Luaotfload}}
2095 % {filegraph.pdf}
2096
2097 \endsubsection
2098
2099 \beginsubsection {Packaging}
2100
2101 \label{sec:pkg}%
2102 The fontloader code is integrated as an isolated component that can be
2103 switched out on demand.
2104 %
2105 To specify the fontloader you wish to use, the configuration file
2106 (described in section \ref{sec:conf}) provides the option
2107 \inlinecode{fontloader}.
2108 %
2109 Its value can be one of the identifiers \inlinecode{default} or
2110 \inlinecode{reference} (see above, section \ref{package}) or the name
2111 of a file somewhere in the search path of \LuaTeX.
2112 %
2113 This will make \identifier {Luaotfload} locate the \ConTeXt\ source by
2114 means of \identifier{kpathsea} lookups and use those instead of the
2115 merged package.
2116 %
2117 The parameter may be extended with a path to the \ConTeXt\
2118 \fileent{texmf}, separated with a colon:
2119
2120 \beginlisting
2121 [run]
2122 fontloader = context:~/context/tex/texmf-context
2123 \endlisting
2124
2125 \noindent This setting allows accessing an installation -- e. g. the
2126 standalone distribution or a source repository -- outside the current
2127 \TeX\ distribution.
2128
2129 Like the \identifier{Lualibs} package, the fontloader is deployed as a
2130 \emphasis{merged package} containing a series of \Lua\ files joined
2131 together in their expected order and stripped of non-significant parts.
2132 %
2133 The \fileent{mkimport} utility assists in pulling the files from a
2134 \ConTeXt\ tree and packaging them for use with \identifier{Luaotfload}.%
2135 %
2136 The state of the files currently in \identifier{Luaotfload}’s
2137 repository can be queried:
2138 \beginlisting
2139 ./scripts/mkimport news
2140 \endlisting
2141 %
2142 The subcommand for importing takes the prefix of the desired \ConTeXt\
2143 \identifier{texmf} as an optional argument:
2144 \beginlisting
2145 ./scripts/mkimport import ~/context/tex/texmf-context
2146 \endlisting
2147 %
2148 Whereas the command for packaging requires a path to the
2149 \emphasis{package description file} and the output name to be passed.
2150 \beginlisting
2151 ./scripts/mkimport package fontloader-custom.lua
2152 \endlisting
2153
2154 From the toplevel makefile, the targets \inlinecode{import} and
2155 \inlinecode{package} provide easy access to the commands as invoked during
2156 the \identifier{Luaotfload} build process.\footnote{%
2157 \emphasis{Hint for those interested in the packaging process}: issue
2158 \inlinecode{make show} for a list of available build routines.
2159 }
2160 These will call \inlinecode{mkimport} script with the correct
2161 parameters to generate a datestamped package.
2162 %
2163 Whether files have been updated in the upstream distribution can be
2164 queried by \inlinecode{./scripts/mkimport news}.
2165 %
2166 This will compare the imported files with their counterparts in the
2167 \ConTeXt\ distribution and report changes.
2168
2169 \endsubsection
2170
2171 \endsection
2172
2173 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2174 \beginsection {Configuration Files}
2175 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2176
2177 \beginnarrower
2178 \emphasis{Caution}: For the authoritative documentation, consult the
2179 manpage for \fileent{luaotfload.conf(5)}.
2180 \endnarrower
2181
2182 \label{sec:conf}
2183 The runtime behavior of \identifier{Luaotfload} can be customized by
2184 means of a configuration file.
2185 % location
2186 At startup, it attempts to locate a file called \fileent
2187 {luaotfload.conf} or \fileent {luaotfloadrc} at a number of candidate
2188 locations:
2189
2190 \begincentered
2191 \begindefinitions
2192 \beginnormalitem \fileent{./luaotfload.conf} \endnormalitem
2193 \beginnormalitem \fileent{./luaotfloadrc} \endnormalitem
2194 \beginnormalitem \fileent{\$XDG_CONFIG_HOME/luaotfload/luaotfload.conf} \endnormalitem
2195 \beginnormalitem \fileent{\$XDG_CONFIG_HOME/luaotfload/luaotfload.rc} \endnormalitem
2196 \beginnormalitem \fileent{~/.luaotfloadrc} \endnormalitem
2197 \enddefinitions
2198 \endcentered
2199
2200 \beginnarrower
2201 \emphasis{Caution}: The configuration potentially modifies the final
2202 document. A project-local file belongs under version control along
2203 with the rest of the document. This is to ensure that everybody who
2204 builds the project also receives the same customizations as the
2205 author.
2206 \endnarrower
2207
2208 % syntax
2209 The syntax is fairly close to the format used by
2210 \fileent{git-config(1)} which in turn was derived from the popular
2211 \identifier{.INI} format: Lines of key-value pairs are grouped under
2212 different configuration “sections”.\footnote{%
2213 The configuration parser in \fileent {luoatfload-parsers.lua} might
2214 be employed by other packages for similar purposes.
2215 }
2216 % example settings
2217 An example for customization via \fileent {luaotfload.conf} might look
2218 as below:
2219
2220 \beginlisting
2221 ; Example luaotfload.conf containing a rudimentary configuration
2222 [db]
2223 update-live = false
2224 [run]
2225 color-callback = pre_linebreak_filter
2226 definer = info_patch
2227 log-level = 5
2228 [default-features]
2229 global = mode=base
2230 \endlisting
2231
2232 This specifies that for the given project, \identifier{Luaotfload}
2233 shall not attempt to automatically scan for fonts if it can’t resolve a
2234 request. The font-based colorization will happen during \LuaTeX’s
2235 pre-linebreak filter. The fontloader will output verbose information
2236 about the fonts at definition time along with globally increased
2237 verbosity. Lastly, the fontloader defaults to the less expensive
2238 \luaident{base} mode like it does in \ConTeXt.
2239
2240 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2241 \beginsection {Auxiliary Functions}
2242 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2243
2244 With release version 2.2, \identifier{Luaotfload} received
2245 additional functions for package authors to call from outside
2246 (see the file \fileent{luaotfload-auxiliary.lua} for details).
2247 %
2248 The purpose of this addition twofold.
2249 %
2250 Firstly, \identifier{luaotfload} failed to provide a stable interface
2251 to internals in the past which resulted in an unmanageable situation
2252 of different packages abusing the raw access to font objects by means
2253 of the \luaident{patch_font} callback.
2254 %
2255 When the structure of the font object changed due to an update, all
2256 of these imploded and several packages had to be fixed while
2257 simultaneously providing fallbacks for earlier versions.
2258 %
2259 Now the patching is done on the \identifier{luaotfload} side and can
2260 be adapted with future modifications to font objects without touching
2261 the packages that depend on it.
2262 %
2263 Second, some the capabilities of the font loader and the names
2264 database are not immediately relevant in \identifier{luaotfload}
2265 itself but might nevertheless be of great value to package authors or
2266 end users.
2267
2268 Note that the current interface is not yet set in stone and the
2269 development team is open to suggestions for improvements or
2270 additions.
2271
2272 \beginsubsection {Callback Functions}
2273
2274 The \luaident{patch_font} callback is inserted in the wrapper
2275 \identifier{luaotfload} provides for the font definition callback.
2276 %
2277 At this place it allows manipulating the font object immediately after
2278 the font loader is done creating it.
2279 %
2280 For a short demonstration of its usefulness, here is a snippet that
2281 writes an entire font object to the file \fileent{fontdump.lua}:
2282
2283 \beginlisting
2284 \input luaotfload.sty
2285 \directlua{
2286 local dumpfile = "fontdump.lua"
2287 local dump_font = function (tfmdata)
2288 local data = table.serialize(tfmdata)
2289 io.savedata(dumpfile, data)
2290 end
2291
2292 luatexbase.add_to_callback(
2293 "luaotfload.patch_font",
2294 dump_font,
2295 "my_private_callbacks.dump_font"
2296 )
2297 }
2298 \font \dumpme = name:Iwona
2299 \bye
2300 \endlisting
2301
2302 \emphasis{Beware}: this creates a Lua file of around 150,000 lines of
2303 code, taking up 3~\abbrev{mb} of disk space.
2304 %
2305 By inspecting the output you can get a first impression of how a font
2306 is structured in \LuaTeX’s memory, what elements it is composed of,
2307 and in what ways it can be rearranged.
2308
2309 The \luaident{pre_shaping_filter} and \luaident{post_shaping_filter}
2310 callbacks are a pair of \identifier{(reverse)list} callbacks running
2311 immediately before and after \identifier{luaotfload} shapes the text.
2312 They both use the interface
2313 \beginlisting
2314 function(head, groupcode, direction)
2315 \endlisting
2316 where \luaident{head} is the head of the to be shaped list,
2317 \luaident{groupcode} is the groupcode as documented for
2318 \luaident{pre_linebreak_filter} and \luaident{hpack_filter} and
2319 \luaident{direction} is the current direction.
2320
2321 Since most font processing happens during shaping, \LuaTeX's
2322 \luaident{ligaturing} and \luaident{kerning} callbacks are not involved
2323 in most ligature generation and kerning decisions and should therefore not be
2324 relied upon. Font processing for fonts loaded with \luaident{mode=base} might
2325 happen in any of these places.
2326
2327 The specific time when extended features are applied is unspecified and might
2328 not be consistent.
2329
2330 \beginsubsubsection {Compatibility with Earlier Versions}
2331
2332 As has been touched on in the preface to this section, the structure
2333 of the object as returned by the fontloader underwent rather drastic
2334 changes during different stages of its development, and not all
2335 packages that made use of font patching have kept up with every one
2336 of it.
2337 %
2338 To ensure compatibility with these as well as older versions of
2339 some packages, \identifier{luaotfload} sets up copies of or references
2340 to data in the font table where it used to be located.
2341 %
2342 For instance, important parameters like the requested point size, the
2343 units factor, and the font name have again been made accessible from
2344 the toplevel of the table even though they were migrated to different
2345 subtables in the meantime.
2346
2347 \endsubsubsection
2348
2349 \beginsubsubsection{Patches}
2350
2351 These are mostly concerned with establishing compatibility with \XeTeX.
2352
2353 \beginfunctionlist
2354
2355 \beginaltitem {set_sscale_dimens}
2356 Calculate \texmacro{fontdimen}s 10 and 11 to emulate \XeTeX.
2357 \endaltitem
2358
2359 \beginaltitem {set_capheight}
2360 Calculates \texmacro{fontdimen} 8 like \XeTeX.
2361 \endaltitem
2362
2363 \beginaltitem {patch_cambria_domh}
2364 Correct some values of the font \emphasis{Cambria Math}.
2365 \endaltitem
2366
2367 \endfunctionlist
2368
2369 \endsubsection
2370
2371 \beginsubsection {Package Author’s Interface}
2372
2373 As \LuaTeX\ release 1.0 is nearing, the demand for a reliable interface
2374 for package authors increases.
2375
2376 \endsubsubsection
2377
2378 \beginsubsubsection{Font Properties}
2379
2380 Below functions mostly concern querying the different components of a
2381 font like for instance the glyphs it contains, or what font features
2382 are defined for which scripts.
2383
2384 \beginfunctionlist
2385
2386 \beginaltitem {aux.font_has_glyph (id : int, index : int)}
2387 Predicate that returns true if the font \luaident{id}
2388 has glyph \luaident{index}.
2389 \endaltitem
2390
2391 \beginaltitem {aux.slot_of_name(id : int, name : string)}
2392 Translates a name for a glyph in font \luaident{id} to the
2393 corresponding glyph slot which can be used e.g.\ as an argument to
2394 \inlinecode{\char}. The number is assigned by the \identifier{luaotfload} code
2395 and not related to the glyph index (GID) of the font as stored in the \identifier{[index]} field
2396 of the lua-file.
2397 \endaltitem
2398
2399 \beginaltitem {aux.gid_of_name(id : int, name : string)}
2400 Translates\marginpar{New version 3.12} a name for a glyph in font \luaident{id} to the
2401 corresponding glyph index (GID) as stored in the \identifier{[index]} field.
2402 \endaltitem
2403
2404 \beginaltitem {aux.name_of_slot(id : int, slot : int)}
2405 The inverse of \luaident{slot_of_name}; note that this
2406 might be incomplete as multiple glyph names may map to the
2407 same codepoint, only one of which is returned by
2408 \luaident{name_of_slot}.
2409 \endaltitem
2410
2411 \beginaltitem {aux.gid_of_name(id : int, name : string)}
2412 Translates a Glyph name to the corresponding GID in font
2413 \luaident{id}. This corresponds to the value returned by
2414 \inlinecode{\XeTeXglyphindex} in \XeTeX.
2415 \endaltitem
2416
2417 \beginaltitem {aux.provides_script(id : int, script : string)}
2418 Test if a font supports \luaident{script}.
2419 \endaltitem
2420
2421 \beginaltitem {aux.provides_language(id : int, script : string, language : string)}
2422 Test if a font defines \luaident{language} for a given
2423 \luaident{script}.
2424 \endaltitem
2425
2426 \beginaltitem {aux.provides_feature(id : int, script : string,
2427 language : string, feature : string)}
2428 Test if a font defines \luaident{feature} for
2429 \luaident{language} for a given \luaident{script}.
2430 \endaltitem
2431
2432 \beginaltitem {aux.get_math_dimension(id : int, dimension : string)}
2433 Get the dimension \luaident{dimension} of font \luaident{id}.
2434 \endaltitem
2435
2436 \beginaltitem {aux.sprint_math_dimension(id : int, dimension : string)}
2437 Same as \luaident{get_math_dimension()}, but output the value
2438 in scaled points at the \TeX\ end.
2439 \endaltitem
2440
2441 \endfunctionlist
2442
2443 \endsubsubsection
2444
2445 \beginsubsubsection{Database}
2446
2447 %% not implemented, may come back later
2448 \beginfunctionlist
2449 % \beginaltitem {aux.scan_external_dir(dir : string)}
2450 % Include fonts in directory \luaident{dir} in font lookups without
2451 % adding them to the database.
2452 %
2453 \beginaltitem {aux.read_font_index (void)}
2454 Read the index file from the appropriate location (usually
2455 the bytecode file \fileent{luaotfload-names.luc} somewhere
2456 in the \fileent{texmf-var} tree) and return the result as a
2457 table. The file is processed with each call so it is up to
2458 the user to store the result for later access.
2459 \endaltitem
2460
2461 \beginaltitem {aux.font_index (void)}
2462 Return a reference of the font names table used internally
2463 by \identifier{luaotfload}. The index will be read if it
2464 has not been loaded up to this point. Also a font scan that
2465 overwrites the current index file might be triggered. Since
2466 the return value points to the actual index, any
2467 modifications to the table might influence runtime behavior
2468 of \identifier{luaotfload}.
2469 \endaltitem
2470
2471 \endfunctionlist
2472
2473 \endsubsubsection
2474
2475 \endsubsection
2476
2477 \beginsubsection {Format Author’s Interface}
2478
2479 Additionally some functions are provided which should only be needed for
2480 format authors trying to integrate \identifier{luaotfload}'s color handling
2481 with the conventions of a specific format.
2482
2483 End users should never have to work with these.
2484
2485 \endsubsubsection
2486
2487 \beginsubsubsection{Color setting}
2488
2489 \identifier{luaotfload}'s \inlinecode{color} feature can apply color in two
2490 different ways: By default it inserts \inlinecode{pdf_colorstack} whatsits
2491 containing the PDF code to change the color.
2492
2493 Alternatively a function can be provided which gets called on every glyph
2494 node to be colored. This function can then e.g. apply an attribute which gets
2495 interpreted later.
2496
2497 This can be enabled separately for colors and transparency by passing such
2498 callback functions:
2499
2500 \beginfunctionlist
2501
2502 \beginaltitem {luaotfload.set_colorhandler((head : node, n : node, color :
2503 string) -> (head : node, n : node)}
2504 Mark the node \luaident{n} in the list starting with \luaident{head}
2505 to be colored with color \luaident{color}.
2506
2507 By default the color is represented by literal PDF code setting the
2508 color.
2509 \endaltitem
2510
2511 \beginaltitem {luaotfload.set_transparenthandler((head : node, n : node,
2512 level : string) -> (head : node, n : node)}
2513 Mark the node \luaident{n} in the list starting with \luaident{head}
2514 to be set transparently with transparency level \luaident{level}.
2515
2516 By default the transparency level is represented by literal PDF code setting the
2517 transparency.
2518 \endaltitem
2519
2520 \endfunctionlist
2521
2522 When these functions aren't used, then the color is set based on colorstack 0.
2523 By default a new colorstack is allocated for transparency, but alternatively an
2524 existing colorstack for this purpose can be set:
2525
2526 \beginfunctionlist
2527
2528 \beginaltitem {luaotfload.set_transparent_colorstack(stack : int)}
2529 Use colorstack \luaident{stack} for setting transparency.
2530 \endaltitem
2531
2532 \endfunctionlist
2533
2534 \endsubsubsection
2535
2536 \beginsubsubsection{Color selection}
2537
2538 Additionally the translation of the argument to \inlinecode{color} to an
2539 actual PDF color can be customized though three \luaident{exclusive} callbacks:
2540
2541 Since there is only a single \inlinecode{color} feature which sets both the
2542 color and the transparency, the first callback
2543 \luaident{luaotfload.split_color} gets called with a single string representing
2544 the feature value and is supposed to return two values representing the color
2545 and the transparency part.
2546
2547 The default implementation splits the string the feature value at a comma and
2548 strips outer spaces for both result values, except the HTML style 8 hexdigit
2549 RGBA values get split into the first 6 and the last two digits.
2550
2551 Afterwards the return values get passed to the
2552 \luaident{luaotfload.parse_color} respectively
2553 \luaident{luaotfload.parse_transparent} callbacks (except that \luaident{false}
2554 and \luaident{nil} skip the corresponding callback).
2555
2556 These callbacks should translate these strings components into valid PDF
2557 commands applyind the described color or transparency.
2558
2559 All error handling and reporting should be done in the callbacks.
2560
2561 \endsubsubsection
2562
2563 \endsubsection
2564 \endsection
2565
2566 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2567 \beginsection {Troubleshooting}
2568 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2569
2570 \beginsubsection {Database Generation}
2571
2572 If you encounter problems with some fonts, please first update to the
2573 latest version of this package before reporting a bug, as
2574 \identifier{luaotfload} is under active development and still a moving
2575 target.
2576 %
2577 The development takes place on \identifier{github} at
2578 \hyperlink {https://github.com/lualatex/luaotfload} where there is an issue
2579 tracker for submitting bug reports, feature requests and the likes.
2580
2581 Bug reports are more likely to be addressed if they contain the output
2582 of
2583
2584 \beginlisting
2585 luaotfload-tool --diagnose=environment,files,permissions
2586 \endlisting
2587
2588 \noindent Consult the man page for a description of these options.
2589
2590 Errors during database generation can be traced by increasing the
2591 verbosity level and redirecting log output to \fileent{stdout}:
2592
2593 \beginlisting
2594 luaotfload-tool -fuvvv --log=stdout
2595 \endlisting
2596
2597 \noindent or to a file in \fileent{/tmp}:
2598
2599 \beginlisting
2600 luaotfload-tool -fuvvv --log=file
2601 \endlisting
2602
2603 \noindent In the latter case, invoke the \inlinecode {tail(1)} utility on the
2604 file for live monitoring of the progress.
2605
2606 If database generation fails, the font last printed to the terminal or
2607 log file is likely to be the culprit.
2608 %
2609 Please specify it when reporting a bug, and blacklist it for the time
2610 being (see above, page \pageref{font-blacklist}).
2611
2612 \endsubsection
2613
2614 \beginsubsection {Font Features}
2615
2616 A common problem is the lack of features for some
2617 \OpenType\ fonts even when specified.
2618 %
2619 This can be related to the fact that some fonts do not provide features
2620 for the \inlinecode {dflt} script (see above on page \pageref{script-tag}),
2621 which is the default one in this package.
2622 %
2623 If this happens, assigning a noth script when the font is defined should
2624 fix it.
2625 %
2626 For example with \inlinecode {latn}:
2627
2628 \beginlisting
2629 \font \test = file:MyFont.otf:script=latn;+liga;
2630 \endlisting
2631
2632 You can get a list of features that a font defines for scripts and
2633 languages by querying it in \fileent{luaotfload-tool}:
2634
2635 \beginlisting
2636 luaotfload-tool --find="Iwona" --inspect
2637 \endlisting
2638
2639 \endsubsection
2640
2641 \beginsubsection {\LuaTeX\ Programming}
2642
2643 Another strategy that helps avoiding problems is to not access raw
2644 \LuaTeX\ internals directly.
2645 %
2646 Some of them, even though they are dangerous to access, have not been
2647 overridden or disabled.
2648 %
2649 Thus, whenever possible prefer the functions in the \luaident{aux}
2650 namespace over direct manipulation of font objects. For example, raw
2651 access to the \luaident{font.fonts} table like:
2652
2653 \beginlisting
2654 local somefont = font.fonts[2]
2655 \endlisting
2656
2657 \noindent can render already defined fonts unusable.
2658 %
2659 Instead, the function \luaident{font.getfont()} should be used
2660 because it has been replaced by a safe variant.
2661
2662 However, \luaident{font.getfont()} only covers fonts handled by the
2663 font loader, e.~g. \OpenType\ and \identifier{TrueType}
2664 fonts, but not \abbrev{tfm} or \abbrev{ofm}.
2665 %
2666 Should you absolutely require access to all fonts known to \LuaTeX,
2667 including the virtual and autogenerated ones, then you need to query
2668 both \luaident{font.getfont()} and \luaident{font.fonts}.
2669 %
2670 In this case, best define you own accessor:
2671
2672 \beginlisting
2673 local unsafe_getfont = function (id)
2674 local tfmdata = font.getfont (id)
2675 if not tfmdata then
2676 tfmdata = font.fonts[id]
2677 end
2678 return tfmdata
2679 end
2680
2681 --- use like getfont()
2682 local somefont = unsafe_getfont (2)
2683 \endlisting
2684
2685 \endsubsection
2686 \endsection
2687
2688 \beginsection {License}
2689
2690 \identifier {luaotfload} is licensed under the terms of the
2691 \hyperlink [GNU General Public License version 2.0]%
2692 {https://www.gnu.org/licenses/old-licenses/gpl-2.0.html}.
2693 Following the underlying fontloader code \identifier {luaotfload}
2694 recognizes only that exact version as its license.
2695 The „any later version” clause of the original license text as
2696 copyrighted by the \hyperlink [Free Software Foundation]{http://www.fsf.org/}
2697 \emphasis {does not apply} to either \identifier {luaotfload} or the
2698 code imported from \ConTeXt.
2699
2700 The complete text of the license is given as a separate file \fileent
2701 {COPYING} in the toplevel directory of the
2702 \hyperlink [\fileent {Luaotfload} Git
2703 repository]{https://github.com/latex3/luaotfload/blob/main/COPYING}.\\
2704 Distributions probably package it as \fileent
2705 {doc/luatex/luaotfload/COPYING} in the relevant \fileent {texmf} tree.
2706
2707 \endsection
2708
2709 \endinput
2710
2711 % vim:ft=tex:tw=79:et:sw=2