| 1 |
======================================================================= |
| 2 |
luaotfload-tool |
| 3 |
======================================================================= |
| 4 |
|
| 5 |
----------------------------------------------------------------------- |
| 6 |
generate and query the Luaotfload font names database |
| 7 |
----------------------------------------------------------------------- |
| 8 |
|
| 9 |
:Date: 2024-12-03 |
| 10 |
:Copyright: GPL v2.0 |
| 11 |
:Version: 3.29 |
| 12 |
:Manual section: 1 |
| 13 |
:Manual group: text processing |
| 14 |
|
| 15 |
SYNOPSIS |
| 16 |
======================================================================= |
| 17 |
|
| 18 |
**luaotfload-tool** [ -bcDfFiIlLnpqRSuvVhw ] |
| 19 |
|
| 20 |
**luaotfload-tool** --update [ --force ] [ --quiet ] [ --verbose ] |
| 21 |
[ --prefer-texmf ] [ --dry-run ] |
| 22 |
[ --formats=[+|-]EXTENSIONS ] |
| 23 |
[ --no-compress ] [ --no-strip ] |
| 24 |
[ --local ] [ --max-fonts=N ] |
| 25 |
|
| 26 |
**luaotfload-tool** --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ] |
| 27 |
[ --no-reload ] |
| 28 |
|
| 29 |
**luaotfload-tool** --flush-lookups |
| 30 |
|
| 31 |
**luaotfload-tool** --cache=DIRECTIVE |
| 32 |
|
| 33 |
**luaotfload-tool** --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ] |
| 34 |
|
| 35 |
**luaotfload-tool** --bisect=DIRECTIVE |
| 36 |
|
| 37 |
**luaotfload-tool** --help |
| 38 |
|
| 39 |
**luaotfload-tool** --version |
| 40 |
|
| 41 |
**luaotfload-tool** --show-blacklist |
| 42 |
|
| 43 |
**luaotfload-tool** --diagnose=CHECK |
| 44 |
|
| 45 |
**luaotfload-tool** --conf=FILE --dumpconf |
| 46 |
|
| 47 |
DESCRIPTION |
| 48 |
======================================================================= |
| 49 |
|
| 50 |
luaotfload-tool accesses the font names database that is required by |
| 51 |
the *Luaotfload* package. There are two general modes: **update** and |
| 52 |
**query**. |
| 53 |
|
| 54 |
+ **update**: update the database or rebuild it entirely; |
| 55 |
+ **query**: resolve a font name or display close matches. |
| 56 |
|
| 57 |
OPTIONS |
| 58 |
======================================================================= |
| 59 |
|
| 60 |
update mode |
| 61 |
----------------------------------------------------------------------- |
| 62 |
--update, -u Update the database; indexes new fonts. |
| 63 |
--force, -f Force rebuilding of the database; re-indexes |
| 64 |
all fonts. |
| 65 |
--local, -L Include font files in ``$PWD``. This option |
| 66 |
will cause large parts of the database to be |
| 67 |
rebuilt. Thus it is quite inefficient. |
| 68 |
Additionally, if local font files are found, |
| 69 |
the database is prevented from being saved |
| 70 |
to disk, so the local fonts need to be parsed |
| 71 |
with every invocation of ``luaotfload-tool``. |
| 72 |
--no-reload, -n Suppress auto-updates to the database (e.g. |
| 73 |
when ``--find`` is passed an unknown name). |
| 74 |
--no-compress, -c Do not filter the plain text version of the |
| 75 |
font index through gzip. Useful for debugging |
| 76 |
if your editor is built without zlib. |
| 77 |
|
| 78 |
--prefer-texmf, -p Organize the file name database in a way so |
| 79 |
that it prefer fonts in the *TEXMF* tree over |
| 80 |
system fonts if they are installed in both. |
| 81 |
--formats=EXTENSIONS Extensions of the font files to index. |
| 82 |
Where *EXTENSIONS* is a comma-separated list of |
| 83 |
supported file extensions (otf, ttf, ttc). |
| 84 |
If the list is prefixed |
| 85 |
with a ``+`` sign, the given list is added to |
| 86 |
the currently active one; ``-`` subtracts. |
| 87 |
Default: *otf,ttf,ttc*. |
| 88 |
Examples: |
| 89 |
|
| 90 |
1) ``--formats=-ttc,ttf`` would skip |
| 91 |
TrueType fonts and font collections; |
| 92 |
2) ``--formats=otf`` would scan only OpenType |
| 93 |
files; |
| 94 |
3) ``--formats=+afm`` includes binary |
| 95 |
Postscript files accompanied by an AFM file. |
| 96 |
|
| 97 |
query mode |
| 98 |
----------------------------------------------------------------------- |
| 99 |
--find=NAME Resolve a font name; this looks up <name> in |
| 100 |
the database and prints the file name it is |
| 101 |
mapped to. |
| 102 |
``--find`` also understands request syntax, |
| 103 |
i.e. ``--find=file:foo.otf`` checks whether |
| 104 |
``foo.otf`` is indexed. |
| 105 |
--fuzzy, -F Show approximate matches to the file name if |
| 106 |
the lookup was unsuccessful (requires |
| 107 |
``--find``). |
| 108 |
|
| 109 |
--info, -i Display basic information to a resolved font |
| 110 |
file (requires ``--find``). |
| 111 |
--inspect, -I Display detailed information by loading the |
| 112 |
font and analyzing the font table; very slow! |
| 113 |
For the meaning of the returned fields see |
| 114 |
the LuaTeX documentation. |
| 115 |
(requires ``--find``). |
| 116 |
|
| 117 |
--list=CRITERION Show entries, where *CRITERION* is one of the |
| 118 |
following: |
| 119 |
|
| 120 |
1) the character ``*``, selecting all entries; |
| 121 |
2) a field of a database entry, for instance |
| 122 |
*version* or *format**, according to which |
| 123 |
the output will be sorted. |
| 124 |
Information in an unstripped database (see |
| 125 |
the option ``--no-strip`` above) is nested: |
| 126 |
Subfields of a record can be addressed using |
| 127 |
the ``->`` separator, e. g. |
| 128 |
``file->location``, ``style->units_per_em``, |
| 129 |
or |
| 130 |
``names->sanitized->english->prefmodifiers``. |
| 131 |
NB: shell syntax requires that arguments |
| 132 |
containing ``->`` be properly quoted! |
| 133 |
3) an expression of the form ``field:value`` to |
| 134 |
limit the output to entries whose ``field`` |
| 135 |
matches ``value``. The ``value`` can contain |
| 136 |
``*`` to match an arbitrary number of characters. |
| 137 |
|
| 138 |
For example, in order to output file names and |
| 139 |
corresponding versions, sorted by the font |
| 140 |
format:: |
| 141 |
|
| 142 |
./luaotfload-tool.lua --list="format" --fields="file->base,version" |
| 143 |
|
| 144 |
This prints:: |
| 145 |
|
| 146 |
otf latinmodern-math.otf Version 1.958 |
| 147 |
otf lmromancaps10-oblique.otf 2.004 |
| 148 |
otf lmmono8-regular.otf 2.004 |
| 149 |
otf lmmonoproplt10-bold.otf 2.004 |
| 150 |
otf lmsans10-oblique.otf 2.004 |
| 151 |
otf lmromanslant8-regular.otf 2.004 |
| 152 |
otf lmroman12-italic.otf 2.004 |
| 153 |
otf lmsansdemicond10-oblique.otf 2.004 |
| 154 |
... |
| 155 |
|
| 156 |
--fields=FIELDS Comma-separated list of fields that should be |
| 157 |
printed. |
| 158 |
Information in an unstripped database (see the |
| 159 |
option ``--no-strip`` above) is nested: |
| 160 |
Subfields of a record can be addressed using |
| 161 |
the ``->`` separator, e. g. |
| 162 |
``file->location``, ``style->units_per_em``, |
| 163 |
or ``names->sanitized->english->subfamily``. |
| 164 |
The default is plainname,version*. |
| 165 |
(Only meaningful with ``--list``.) |
| 166 |
|
| 167 |
font and lookup caches |
| 168 |
----------------------------------------------------------------------- |
| 169 |
--flush-lookups Clear font name lookup cache (experimental). |
| 170 |
|
| 171 |
--cache=DIRECTIVE Cache control, where *DIRECTIVE* is one of the |
| 172 |
following: |
| 173 |
|
| 174 |
1) ``purge`` -> delete Lua files from cache; |
| 175 |
2) ``erase`` -> delete Lua and Luc files from |
| 176 |
cache; |
| 177 |
3) ``show`` -> print stats. |
| 178 |
|
| 179 |
debugging methods |
| 180 |
----------------------------------------------------------------------- |
| 181 |
--show-blacklist, -b Show blacklisted files (not directories). |
| 182 |
--dry-run, -D Don’t load fonts when updating the database; |
| 183 |
scan directories only. |
| 184 |
(For debugging file system related issues.) |
| 185 |
--no-strip Do not strip redundant information after |
| 186 |
building the database. Warning: this will |
| 187 |
inflate the index to about two to three times |
| 188 |
the normal size. |
| 189 |
--max-fonts=N Process at most *N* font files, including fonts |
| 190 |
already indexed in the count. |
| 191 |
--bisect=DIRECTIVE Bisection of the font database. |
| 192 |
This mode is intended as assistance in |
| 193 |
debugging the Luatex engine, especially when |
| 194 |
tracking memleaks or buggy fonts. |
| 195 |
|
| 196 |
*DIRECTIVE* can be one of the following: |
| 197 |
|
| 198 |
1) ``run`` -> Make ``luaotfload-tool`` respect |
| 199 |
the bisection progress when running. |
| 200 |
Combined with ``--update`` and possibly |
| 201 |
``--force`` this will only process the files |
| 202 |
from the start up until the pivot and ignore |
| 203 |
the rest. |
| 204 |
2) ``start`` -> Start bisection: create a |
| 205 |
bisection state file and initialize the low, |
| 206 |
high, and pivot indices. |
| 207 |
3) ``stop`` -> Terminate the current bisection |
| 208 |
session by deleting the state file. |
| 209 |
4) ``good`` | ``bad`` -> Mark the section |
| 210 |
processed last as “good” or “bad”, |
| 211 |
respectively. The next bisection step will |
| 212 |
continue with the bad section. |
| 213 |
5) ``status`` -> Print status information about |
| 214 |
the current bisection session. Hint: Use |
| 215 |
with higher verbosity settings for more |
| 216 |
output. |
| 217 |
|
| 218 |
A bisection session is initiated by issuing the |
| 219 |
``start`` directive. This sets the pivot to the |
| 220 |
middle of the list of available font files. |
| 221 |
Now run *luaotfload-tool* with the ``--update`` |
| 222 |
flag set as well as ``--bisect=run``: only the |
| 223 |
fonts up to the pivot will be considered. If |
| 224 |
that task exhibited the issue you are tracking, |
| 225 |
then tell Luaotfload using ``--bisect=bad``. |
| 226 |
The next step of ``--bisect=run`` will continue |
| 227 |
bisection with the part of the files below the |
| 228 |
pivot. |
| 229 |
Likewise, issue ``--bisect=good`` in order to |
| 230 |
continue with the fonts above the pivot, |
| 231 |
assuming the tested part of the list did not |
| 232 |
trigger the bug. |
| 233 |
|
| 234 |
Once the culprit font is tracked down, ``good`` |
| 235 |
or ``bad`` will have no effect anymore. ``run`` |
| 236 |
will always end up processing the single font |
| 237 |
file that was left. |
| 238 |
Use ``--bisect=stop`` to clear the bisection |
| 239 |
state. |
| 240 |
|
| 241 |
miscellaneous |
| 242 |
----------------------------------------------------------------------- |
| 243 |
--verbose=N, -v Set verbosity level to *n* or the number of |
| 244 |
repetitions of ``-v``. |
| 245 |
--quiet No verbose output (log level set to zero). |
| 246 |
--log=CHANNEL Redirect log output (for database |
| 247 |
troubleshooting), where *CHANNEL* can be |
| 248 |
|
| 249 |
1) ``stdout`` -> all output will be |
| 250 |
dumped to the terminal (default); or |
| 251 |
2) ``file`` -> write to a file to the temporary |
| 252 |
directory (the name will be chosen |
| 253 |
automatically. |
| 254 |
|
| 255 |
--version, -V Show version numbers of components as well as |
| 256 |
some basic information and exit. |
| 257 |
--help, -h Show help message and exit. |
| 258 |
|
| 259 |
--diagnose=CHECK Run the diagnostic procedure *CHECK*. Available |
| 260 |
procedures are: |
| 261 |
|
| 262 |
1) ``files`` -> check *Luaotfload* files for |
| 263 |
modifications; |
| 264 |
2) ``permissions`` -> check permissions of |
| 265 |
cache directories and files; |
| 266 |
3) ``environment`` -> print relevant |
| 267 |
environment and kpse variables; |
| 268 |
4) ``repository`` -> check the git repository |
| 269 |
for new releases, |
| 270 |
5) ``index`` -> check database, display |
| 271 |
information about it. |
| 272 |
|
| 273 |
Procedures can be chained by concatenating with |
| 274 |
commas, e.g. ``--diagnose=files,permissions``. |
| 275 |
Specify ``thorough`` to run all checks. |
| 276 |
|
| 277 |
--conf=FILE Read the configuration from *FILE*. See |
| 278 |
**luaotfload.conf**\(%) for documentation |
| 279 |
concerning the format and available options. |
| 280 |
--dumpconf Print the currently active configuration; the |
| 281 |
output can be saved to a file and used for |
| 282 |
bootstrapping a custom configuration files. |
| 283 |
|
| 284 |
--aliases Dump the font name database as a kpathsea |
| 285 |
aliases file. This option is experimental and |
| 286 |
might go away. |
| 287 |
|
| 288 |
FILES |
| 289 |
======================================================================= |
| 290 |
|
| 291 |
The font name database is usually located in the directory |
| 292 |
``texmf-var/luatex-cache/generic/names/`` (``$TEXMFCACHE`` as set in |
| 293 |
``texmf.cnf``) of your *TeX Live* distribution as a zlib-compressed |
| 294 |
file ``luaotfload-names.lua.gz``. |
| 295 |
The experimental lookup cache will be created as |
| 296 |
``luaotfload-lookup-cache.lua`` in the same directory. |
| 297 |
These Lua tables are not used directly by Luaotfload, though. |
| 298 |
Instead, they are compiled to Lua bytecode which is written to |
| 299 |
corresponding files with the extension ``.luc`` in the same directory. |
| 300 |
When modifying the files by hand keep in mind that only if the bytecode |
| 301 |
files are missing will Luaotfload use the plain version instead. |
| 302 |
Both kinds of files are safe to delete, at the cost of regenerating |
| 303 |
them with the next run of *LuaTeX*. |
| 304 |
|
| 305 |
SEE ALSO |
| 306 |
======================================================================= |
| 307 |
|
| 308 |
**luaotfload.conf**\(5), **luatex**\(1), **lua**\(1) |
| 309 |
|
| 310 |
* ``texdoc luaotfload`` to display the manual for the *Luaotfload* |
| 311 |
package |
| 312 |
* Luaotfload development `<https://github.com/latex3/luaotfload>`_ |
| 313 |
* LuaLaTeX mailing list `<http://tug.org/pipermail/lualatex-dev/>`_ |
| 314 |
* LuaTeX `<http://luatex.org/>`_ |
| 315 |
* ConTeXt `<http://wiki.contextgarden.net>`_ |
| 316 |
* Luaotfload on CTAN `<http://ctan.org/pkg/luaotfload>`_ |
| 317 |
|
| 318 |
BUGS |
| 319 |
======================================================================= |
| 320 |
|
| 321 |
Tons, probably. |
| 322 |
|
| 323 |
AUTHORS |
| 324 |
======================================================================= |
| 325 |
|
| 326 |
*Luaotfload* was developed by the LuaLaTeX dev team |
| 327 |
(`<https://github.com/lualatex/>`__). It is currently maintained by the LaTeX |
| 328 |
Project Team at `<https://github.com/latex3/luaotfload>`__ |
| 329 |
The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt |
| 330 |
NL (`<http://pragma-ade.com/>`__). |
| 331 |
|
| 332 |
This manual page was written by Philipp Gesang <[email protected]>. |
| 333 |
|