1UPDMAP(1) User Commands UPDMAP(1)
2
3
4
6 updmap - manage TeX font maps
7 updmap-sys - manage TeX font maps, system-wide
8 updmap-user - manage TeX font maps, per-user
9
11 updmap [-user|-sys] [OPTION] ... [COMMAND]
12 updmap-user [OPTION] ... [COMMAND]
13 updmap-sys [OPTION] ... [COMMAND]
14
16 updmap version r59062 (2021-05-03 17:46:54 +0200)
17
18 Update the default font map files used by pdftex (pdftex.map), dvips
19 (psfonts.map), and dvipdfm(x), and optionally pxdvi, as determined by
20 all configuration files updmap.cfg (the ones returned by running "kpse‐
21 which --all updmap.cfg", but see below).
22
23 Among other things, these map files are used to determine which fonts
24 should be used as bitmaps and which as outlines, and to determine which
25 font files are included, typically subsetted, in the PDF or PostScript
26 output.
27
28 updmap-sys (or updmap -sys) is intended to affect the system-wide con‐
29 figuration, while updmap-user (or updmap -user) affects personal con‐
30 figuration files only, overriding the system files.
31
32 As a consequence, once updmap-user has been run, even a single time,
33 running updmap-sys no longer has any effect. updmap-sys issues a warn‐
34 ing about this, since it is rarely desirable. See
35 https://tug.org/texlive/scripts-sys-user.html for details.
36
37 By default, the TeX filename database (ls-R) is also updated.
38
39 The updmap system is regrettably complicated, for both inherent and
40 historical reasons. A general overview:
41
42 - updmap.cfg files are mainly about listing other files, namely the
43
44 font-specific .maps, in which each line gives information about
45 a different TeX (.tfm) font.
46
47 - updmap reads the updmap.cfg files and then concatenates the
48
49 contents of those .map files into the main output files: ps‐
50 fonts.map for dvips and pdftex.map for pdftex and dvipdfmx.
51
52 - The updmap.cfg files themselves are created and updated at package
53
54 installation time, by the system installer or the package man‐
55 ager or by hand, and not (by default) by updmap.
56
57 Good luck.
58
60 --cnffile FILE
61 read FILE for the updmap configuration (can be given multiple
62 times, in which case
63
64 all the files are used)
65
66 --dvipdfmxoutputdir DIR
67 specify output directory (dvipdfm(x) syntax)
68
69 --dvipsoutputdir DIR
70 specify output directory (dvips syntax)
71
72 --pdftexoutputdir DIR
73 specify output directory (pdftex syntax)
74
75 --pxdvioutputdir DIR
76 specify output directory (pxdvi syntax)
77
78 --outputdir DIR
79 specify output directory (for all files)
80
81 --copy cp generic files rather than using symlinks
82
83 --force
84 recreate files even if config hasn't changed
85
86 --nomkmap
87 do not recreate map files
88
89 --nohash
90 do not run mktexlsr (a.k.a. texhash)
91
92 --sys affect system-wide files (equivalent to updmap-sys)
93
94 --user affect personal files (equivalent to updmap-user)
95
96 -n, --dry-run
97 only show the configuration, no output
98
99 --quiet, --silent
100 reduce verbosity
101
102 Commands:
103 --help show this message and exit
104
105 --version
106 show version information and exit
107
108 --showoption OPTION
109 show the current setting of OPTION
110
111 --showoptions OPTION
112 show possible settings for OPTION
113
114 --setoption OPTION VALUE
115 set OPTION to value; option names below
116
117 --setoption OPTION=VALUE
118 as above, just different syntax
119
120 --enable MAPTYPE MAPFILE
121 add "MAPTYPE MAPFILE" to updmap.cfg, where MAPTYPE is Map,
122 MixedMap, or KanjiMap
123
124 --enable Map=MAPFILE
125 add "Map MAPFILE" to updmap.cfg
126
127 --enable MixedMap=MAPFILE add "MixedMap MAPFILE" to updmap.cfg
128
129 --enable KanjiMap=MAPFILE add "KanjiMap MAPFILE" to updmap.cfg
130
131 --disable MAPFILE
132 disable MAPFILE, of whatever type
133
134 --listmaps
135 list all maps (details below)
136
137 --listavailablemaps
138 list available maps (details below)
139
140 --syncwithtrees
141 disable unavailable map files in updmap.cfg
142
143 The main output:
144
145 The main output of updmap is the files containing the individual
146 font map lines which the drivers (dvips, pdftex, etc.) read to
147 handle fonts.
148
149 The map files for dvips (psfonts.map) and pdftex and dvipdfmx
150 (pdftex.map) are written to TEXMFVAR/fonts/map/up‐
151 dmap/{dvips,pdftex}/.
152
153 In addition, information about Kanji fonts is written to TEXMF‐
154 VAR/fonts/map/updmap/dvipdfmx/kanjix.map, and optionally to
155 TEXMFVAR/fonts/map/updmap/pxdvi/xdvi-ptex.map. These are for
156 Kanji only and are not like other map files. dvipdfmx reads
157 pdftex.map for the map entries for non-Kanji fonts.
158
159 If no option is given, so the invocation is just "updmap-user"
160 or "updmap-sys", these output files are always recreated.
161
162 Otherwise, if an option such as --enable or --disable is given,
163 the output files are recreated if the list of enabled map files
164 (from updmap.cfg) has changed. The --force option overrides
165 this, always recreating the output files.
166
167 Explanation of the map types:
168
169 The normal type is Map.
170
171 The only difference between Map and MixedMap is that MixedMap
172 entries are not added to psfonts_pk.map. The purpose is to help
173 users with devices that render Type 1 outline fonts worse than
174 mode-tuned Type 3 bitmap fonts. So, MixedMap is used for fonts
175 that are available as both Type 1 and Metafont.
176
177 KanjiMap entries are added to psfonts_t1.map and kanjix.map.
178
179 Explanation of the OPTION names for --showoptions, --showoption, --se‐
180 toption:
181
182 dvipsPreferOutline
183 true,false (default true)
184
185 Whether dvips uses bitmaps or outlines, when both are available.
186
187 dvipsDownloadBase35
188 true,false (default true)
189
190 Whether dvips includes the standard 35 PostScript fonts in its
191 output.
192
193 pdftexDownloadBase14
194 true,false (default true)
195
196 Whether pdftex includes the standard 14 PDF fonts in its output.
197
198 pxdviUse
199 true,false (default false)
200
201 Whether maps for pxdvi (Japanese-patched xdvi) are under up‐
202 dmap's control.
203
204 jaEmbed
205 (any string)
206
207 jaVariant
208 (any string)
209
210 scEmbed
211 (any string)
212
213 tcEmbed
214 (any string)
215
216 koEmbed
217 (any string)
218
219 See below.
220
221 LW35 URWkb,URW,ADOBEkb,ADOBE (default URWkb)
222
223 Adapt the font and file names of the standard 35 PostScript
224 fonts.
225
226 URWkb URW fonts with "berry" filenames (e.g. uhvbo8ac.pfb)
227
228 URW URW fonts with "vendor" filenames (e.g. n019064l.pfb)
229
230 ADOBEkb
231 Adobe fonts with "berry" filenames (e.g. phvbo8an.pfb)
232
233 ADOBE Adobe fonts with "vendor" filenames (e.g. hvnbo___.pfb)
234
235 These options are only read and acted on by updmap; dvips, pdf‐
236 tex, etc., do not know anything about them. They work by chang‐
237 ing the default map file which the programs read, so they can be
238 overridden by specifying command-line options or configuration
239 files to the programs, as explained at the beginning of up‐
240 dmap.cfg.
241
242 The options jaEmbed and jaVariant (formerly kanjiEmbed and kan‐
243 jiVariant) specify special replacements in the map lines. If a
244 map contains the string @jaEmbed@, then this will be replaced by
245 the value of that option; similarly for jaVariant. In this way,
246 users of Japanese TeX can select different fonts to be included
247 in the final output. The counterpart for Simplified Chinese,
248 Traditional Chinese and Korean fonts are scEmbed, tcEmbed and
249 koEmbed respectively.
250
252 Explanation of trees and files normally used:
253
254 If --cnffile is specified on the command line (can be given mul‐
255 tiple times), its value(s) is(are) used. Otherwise, updmap
256 reads all the updmap.cfg files found by running `kpsewhich -all
257 updmap.cfg', in the order returned by kpsewhich (which is the
258 order of trees defined in texmf.cnf).
259
260 In either case, if multiple updmap.cfg files are found, all the
261 maps mentioned in all the updmap.cfg files are merged.
262
263 Thus, if updmap.cfg files are present in all trees, and the de‐
264 fault layout is used as shipped with TeX Live, the following
265 files are read, in the given order.
266
267 For updmap-sys:
268 TEXMFSYSCONFIG $TEXLIVE/YYYY/texmf-config/web2c/updmap.cfg
269 TEXMFSYSVAR $TEXLIVE/YYYY/texmf-var/web2c/updmap.cfg
270 TEXMFLOCAL $TEXLIVE/texmf-local/web2c/updmap.cfg
271 TEXMFDIST $TEXLIVE/YYYY/texmf-dist/web2c/updmap.cfg
272
273 For updmap-user:
274 TEXMFCONFIG $HOME/.texliveYYYY/texmf-config/web2c/updmap.cfg
275 TEXMFVAR $HOME/.texliveYYYY/texmf-var/web2c/updmap.cfg
276 TEXMFHOME $HOME/texmf/web2c/updmap.cfg
277 TEXMFSYSCONFIG $TEXLIVE/YYYY/texmf-config/web2c/updmap.cfg
278 TEXMFSYSVAR $TEXLIVE/YYYY/texmf-var/web2c/updmap.cfg
279 TEXMFLOCAL $TEXLIVE/texmf-local/web2c/updmap.cfg
280 TEXMFDIST $TEXLIVE/YYYY/texmf-dist/web2c/updmap.cfg
281
282 (where YYYY is the TeX Live release version).
283
284 According to the actions, updmap might write to one of the given
285 files or create a new updmap.cfg, described further below.
286
287 Where and which updmap.cfg changes are saved:
288
289 When no options are given, the updmap.cfg file(s) are only read,
290 not written. It's when an option --setoption, --enable or
291 --disable is specified that an updmap.cfg needs to be updated.
292 In this case:
293
294 1) If config files are given on the command line, then the first
295 one given is used to save any such changes.
296
297 2) If the config files are taken from kpsewhich output, then the
298 algorithm is more complex:
299
300 2a) If $TEXMFCONFIG/web2c/updmap.cfg or $TEXMFHOME/web2c/up‐
301 dmap.cfg appears in the list of used files, then the one listed
302 first by kpsewhich --all (equivalently, the one returned by
303 kpsewhich updmap.cfg), is used.
304
305 2b) If neither of the above two are present and changes are
306 made, a new config file is created in $TEXMFCONFIG/web2c/up‐
307 dmap.cfg.
308
309 In general, the idea is that if the user cannot write to a given
310 config file, a higher-level one can be used. That way, the dis‐
311 tribution's settings can be overridden system-wide using TEXM‐
312 FLOCAL, and system settings can be overridden again in a partic‐
313 ular user's TEXMFHOME.
314
315 Resolving multiple definitions of a font:
316
317 If a font is defined in more than one map file, then the defini‐
318 tion coming from the first-listed updmap.cfg is used. If a font
319 is defined multiple times within the same map file, one is cho‐
320 sen arbitrarily. In both cases a warning is issued.
321
322 Disabling maps:
323
324 updmap.cfg files with higher priority (listed earlier) can dis‐
325 able maps mentioned in lower priority (listed later) updmap.cfg
326 files by writing, e.g.,
327
328 #! Map mapname.map
329
330 or
331
332 #! MixedMap mapname.map
333
334 in the higher-priority updmap.cfg file.
335 (The #! must be at the
336
337 beginning of the line, with at least one space or tab afterward,
338 and whitespace between each word on the list.)
339
340 As an example, suppose you have a copy of MathTime Pro fonts and
341 want to disable the Belleek version of the fonts; that is, dis‐
342 able the map belleek.map. You can create the file $TEXMFCON‐
343 FIG/web2c/updmap.cfg with the content
344
345 #! Map belleek.map Map mt-plus.map Map mt-yy.map
346
347 and call updmap.
348
349 Listing of maps:
350
351 The two options --listmaps and --listavailablemaps list all maps
352 defined in any of the updmap.cfg files (for --listmaps), and
353 only those actually found on the system (for --listavail‐
354 ablemaps). The output format is one line per font map, with the
355 following fields separated by tabs: map, type (Map, MixedMap,
356 KanjiMap), status (enabled, disabled), origin (the updmap.cfg
357 file where it is mentioned, or 'builtin' for the three basic
358 maps).
359
360 In the case of --listmaps there can be one additional fields
361 (again separated by tab) containing '(not available)' for those
362 map files that cannot be found.
363
364 updmap-user vs. updmap-sys:
365
366 When updmap-sys is run, TEXMFSYSCONFIG and TEXMFSYSVAR are used
367 instead of TEXMFCONFIG and TEXMFVAR, respectively. This is the
368 primary difference between updmap-sys and updmap-user.
369
370 Other locations may be used if you give them on the command
371 line, or these trees don't exist, or you are not using the orig‐
372 inal TeX Live.
373
374 To see the precise locations of the various files that will be read and
375 written, give the -n option (or read the source).
376
378 The log file is written to TEXMFVAR/web2c/updmap.log.
379
380 For step-by-step instructions on making new fonts known to TeX, read
381 https://tug.org/fonts/fontinstall.html. For even more terse instruc‐
382 tions, read the beginning of the main updmap.cfg file.
383
385 Configuration and input files:
386
387 updmap.cfg
388 Main configuration file. In texmf-dist/web2c by default, but
389 may be located elsewhere depending on your distribution. Each
390 texmf tree read should have its own updmap.cfg.
391
392 dvips35.map
393 Map file for standard 35 PostScript fonts for use with dvips(1).
394
395 pdftex35.map
396 Map file for standard 35 PostScript fonts for use with pdf‐
397 tex(1).
398
399 ps2pk35.map
400 Map file for standard 35 PostScript fonts for use with ps2pk(1).
401
402 Output files:
403
404 psfonts.map
405 For dvips(1). Same as psfonts_t1.map if option dvipsPreferOut‐
406 line active, else as psfonts_pk.map.
407
408 psfonts_pk.map
409 For dvips(1). Without information from MixedMap files. (Set‐
410 ting of dvipsPreferOutline ignored.)
411
412 psfonts_t1.map
413 For dvips(1). With information from MixedMap files. (Setting
414 of dvipsPreferOutline ignored.)
415
416 download35.map
417 For dvips(1). Always downloads the standard 35 fonts. (Setting
418 of dvipsDownloadBase35 ignored.)
419
420 builtin35.map
421 For dvips(1). Never downloads the standard 35 fonts. (Setting
422 of dvipsDownloadBase35 ignored.)
423
424 pdftex.map
425 For pdftex(1). Same as pdftex_dl14.map if option pdftexDown‐
426 loadBase14 active, else as pdftex_ndl14.map.
427
428 pdftex_dl14.map
429 For pdftex(1). Always downloads the standard 14 fonts.
430
431 pdftex_ndl14.map
432 For pdftex(1). Never downloads the standard 14 fonts.
433
434 ps2pk.map
435 Similar to psfonts.map file, but forces all fonts to be down‐
436 loaded, so this map file can be used with xdvi(1) and ps2pk(1).
437
438 Configuration files for dvips(1):
439
440 config.builtin35
441 Loads builtin35.map instead of psfonts.map.
442
443 config.download35
444 Loads download35.map instead of psfonts.map.
445
446 config.outline
447 Loads psfonts_t1.map instead of psfonts.map.
448
449 config.pdf
450 Loads psfonts_t1.map instead of psfonts.map and has additional
451 optimizations for PDF generation.
452
453 config.pk
454 Loads psfonts_pk.map instead of psfonts.map.
455
456 config.www
457 Loads psfonts_t1.map instead of psfonts.map. (For compatibility
458 with old versions.)
459
460 config.gstopk
461 Loads psfonts_t1.map instead of psfonts.map.
462
464 Report bugs to: tex-live@tug.org
465 TeX Live home page: <https://tug.org/texlive/>
466
467
468
469TeX Live May 2021 UPDMAP(1)