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