summaryrefslogtreecommitdiff
path: root/luaotfload-tool.rst
blob: 27e0069531d494b91ab14d338d6f1b80c041ae87 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
=======================================================================
                            luaotfload-tool
=======================================================================

-----------------------------------------------------------------------
         generate and query the Luaotfload font names database
-----------------------------------------------------------------------

:Date:      2013-06-02
:Copyright: GPL v2.0
:Version:   2.3
:Manual section: 1
:Manual group: text processing

SYNOPSIS
=======================================================================

**luaotfload-tool** [ -bDcfFiIpquvVwh ]

**luaotfload-tool** --update [ --force ] [ --quiet ] [ --verbose ] [ --prefer-texmf ] [ --dry-run ]

**luaotfload-tool** --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ]

**luaotfload-tool** --flush-lookups

**luaotfload-tool** --cache=DIRECTIVE

**luaotfload-tool** --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ]

**luaotfload-tool** --help

**luaotfload-tool** --version

**luaotfload-tool** --show-blacklist

**luaotfload-tool** --diagnose=CHECK

DESCRIPTION
=======================================================================

luaotfload-tool accesses the font names database that is required by
the *Luaotfload* package. There are two general modes: **update** and
**query**.

+ **update**:  update the database or rebuild it entirely;
+ **query**:   resolve a font name or display close matches.

Note that if the script is named ``mkluatexfontdb`` it will behave like
earlier versions (<=1.3) and always update the database first. Also,
the verbosity level will be set to 2.

OPTIONS
=======================================================================

update mode
-----------------------------------------------------------------------
--update, -u            Update the database; indexes new fonts.
--force, -f             Force rebuilding of the database; re-indexes
                        all fonts.
--prefer-texmf, -p      Organize the file name database in a way so
                        that it prefer fonts in the *TEXMF* tree over
                        system fonts if they are installed in both.
--dry-run, -D           Don’t load fonts, scan directories only.
                        (For debugging file system related issues.)

query mode
-----------------------------------------------------------------------
--find=NAME             Resolve a font name; this looks up <name> in
                        the database and prints the file name it is
                        mapped to.
--fuzzy, -F             Show approximate matches to the file name if
                        the lookup was unsuccessful (requires
                        ``--find``).

--info, -i              Display basic information to a resolved font
                        file (requires ``--find``).
--inspect, -I           Display detailed information by loading the
                        font and analyzing the font table; very slow!
                        For the meaning of the returned fields see
                        the LuaTeX documentation.
                        (requires ``--find``).
--warnings, -w          Print the warnings generated by the fontloader
                        library (assumes ``-I``). Automatically enabled
                        if the verbosity level exceeds 2.

--show-blacklist, -b    Show blacklisted files (not directories).
--list=CRITERION        Show entries, where *CRITERION* is one of the
                        following:

                        1) the character ``*``, selecting all entries;
                        2) a field of a database entry, for instance
                           *fullname* or *units_per_em*, according to
                           which the output will be sorted; or
                        3) an expression of the form ``field:value`` to
                           limit the output to entries whose ``field``
                           matches ``value``.

--fields=FIELDS         Comma-separated list of fields that should be
                        printed.  The default is *fullname,version*.
                        (Only meaningful with ``--list``.)

font and lookup caches
-----------------------------------------------------------------------
--flush-lookups         Clear font name lookup cache (experimental).

--cache=DIRECTIVE       Cache control, where *DIRECTIVE* is one of the
                        following:

                        1) ``purge`` -> delete Lua files from cache;
                        2) ``erase`` -> delete Lua and Luc files from
                           cache;
                        3) ``show``  -> print stats.

miscellaneous
-----------------------------------------------------------------------
--verbose=N, -v         Set verbosity level to *n* or the number of
                        repetitions of ``-v``.
--quiet                 No verbose output (log level set to zero).
--log=CHANNEL           Redirect log output (for database
                        troubleshooting), where *CHANNEL* can be

                        1) ``stdout`` -> all output will be
                           dumped to the terminal; or
                        2) ``file`` -> write to a file to the temporary
                           directory (the name will be chosen
                           automatically (**experimental!**).

--version, -V           Show version number and exit.
--help, -h              Show help message and exit.

--diagnose=CHECK        Run the diagnostic procedure *CHECK*. Available
                        procedures are:

                        1) ``files`` -> check *Luaotfload* files for
                           modifications;
                        2) ``permissions`` -> check permissions of
                           cache directories and files;
                        3) ``repository`` -> check the git repository
                           for new releases.

                        Specify ``thorough`` to run all checks.

FILES
=======================================================================

The font name database is usually located in the directory
``texmf-var/luatex-cache/generic/names/`` (``$TEXMFCACHE`` as set in
``texmf.cnf``) of your *TeX Live* distribution as
``luaotfload-names.lua``.  The experimental lookup cache will be
created as ``luaotfload-lookup-cache.lua`` in the same directory.
Both files are safe to delete, at the cost of regenerating them with
the next run of *LuaTeX*.

SEE ALSO
=======================================================================

**luatex** (1), **lua** (1)

* ``texdoc luaotfload`` to display the manual for the *Luaotfload*
  package
* Luaotfload development `<https://github.com/lualatex/luaotfload>`_
* LuaLaTeX mailing list  `<http://tug.org/pipermail/lualatex-dev/>`_
* LuaTeX                 `<http://luatex.org/>`_
* ConTeXt                `<http://wiki.contextgarden.net>`_
* Luaotfload on CTAN     `<http://ctan.org/pkg/luaotfload>`_

BUGS
=======================================================================

Tons, probably.

AUTHORS
=======================================================================

*Luaotfload* is maintained by the LuaLaTeX dev team
(`<https://github.com/lualatex/>`__).
The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt
NL (`<http://pragma-ade.com/>`__).

This manual page was written by Philipp Gesang
<philipp.gesang@alumni.uni-heidelberg.de>.