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 r59062 (2021-05-03 17:46:54 +0200)
17 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 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 Good luck.
58
60 --cnffile FILE
61 read FILE for the updmap configuration (can be given multiple
62 times, in which case
63 all the files are used)
65 --dvipdfmxoutputdir DIR
67 specify output directory (dvipdfm(x) syntax)
68 --dvipsoutputdir DIR
70 specify output directory (dvips syntax)
71 --pdftexoutputdir DIR
73 specify output directory (pdftex syntax)
74 --pxdvioutputdir DIR
76 specify output directory (pxdvi syntax)
77 --outputdir DIR
79 specify output directory (for all files)
80 --copy cp generic files rather than using symlinks
82 --force
84 recreate files even if config hasn't changed
85 --nomkmap
87 do not recreate map files
88 --nohash
90 do not run mktexlsr (a.k.a. texhash)
91 --sys affect system-wide files (equivalent to updmap-sys)
93 --user affect personal files (equivalent to updmap-user)
95 -n, --dry-run
97 only show the configuration, no output
98 --quiet, --silent
100 reduce verbosity
101 Commands:
103 --help show this message and exit
104 --version
106 show version information and exit
107 --showoption OPTION
109 show the current setting of OPTION
110 --showoptions OPTION
112 show possible settings for OPTION
113 --setoption OPTION VALUE
115 set OPTION to value; option names below
116 --setoption OPTION=VALUE
118 as above, just different syntax
119 --enable MAPTYPE MAPFILE
121 add "MAPTYPE MAPFILE" to updmap.cfg, where MAPTYPE is Map,
122 MixedMap, or KanjiMap
123 --enable Map=MAPFILE
125 add "Map MAPFILE" to updmap.cfg
126 --enable MixedMap=MAPFILE add "MixedMap MAPFILE" to updmap.cfg
128 --enable KanjiMap=MAPFILE add "KanjiMap MAPFILE" to updmap.cfg
130 --disable MAPFILE
132 disable MAPFILE, of whatever type
133 --listmaps
135 list all maps (details below)
136 --listavailablemaps
138 list available maps (details below)
139 --syncwithtrees
141 disable unavailable map files in updmap.cfg
142 The main output:
144 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 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 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 If no option is given, so the invocation is just "updmap-user"
160 or "updmap-sys", these output files are always recreated.
161 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 Explanation of the map types:
168 The normal type is Map.
170 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 KanjiMap entries are added to psfonts_t1.map and kanjix.map.
178 Explanation of the OPTION names for --showoptions, --showoption, --se‐
180 toption:
181 dvipsPreferOutline
183 true,false (default true)
184 Whether dvips uses bitmaps or outlines, when both are available.
186 dvipsDownloadBase35
188 true,false (default true)
189 Whether dvips includes the standard 35 PostScript fonts in its
191 output.
192 pdftexDownloadBase14
194 true,false (default true)
195 Whether pdftex includes the standard 14 PDF fonts in its output.
197 pxdviUse
199 true,false (default false)
200 Whether maps for pxdvi (Japanese-patched xdvi) are under up‐
202 dmap's control.
203 jaEmbed
205 (any string)
206 jaVariant
208 (any string)
209 scEmbed
211 (any string)
212 tcEmbed
214 (any string)
215 koEmbed
217 (any string)
218 See below.
220 LW35 URWkb,URW,ADOBEkb,ADOBE (default URWkb)
222 Adapt the font and file names of the standard 35 PostScript
224 fonts.
225 URWkb URW fonts with "berry" filenames (e.g. uhvbo8ac.pfb)
227 URW URW fonts with "vendor" filenames (e.g. n019064l.pfb)
229 ADOBEkb
231 Adobe fonts with "berry" filenames (e.g. phvbo8an.pfb)
232 ADOBE Adobe fonts with "vendor" filenames (e.g. hvnbo___.pfb)
234 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 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 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 In either case, if multiple updmap.cfg files are found, all the
261 maps mentioned in all the updmap.cfg files are merged.
262 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 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 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 (where YYYY is the TeX Live release version).
283 According to the actions, updmap might write to one of the given
285 files or create a new updmap.cfg, described further below.
286 Where and which updmap.cfg changes are saved:
288 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 1) If config files are given on the command line, then the first
295 one given is used to save any such changes.
296 2) If the config files are taken from kpsewhich output, then the
298 algorithm is more complex:
299 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 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 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 Resolving multiple definitions of a font:
316 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 Disabling maps:
323 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 #! Map mapname.map
329 or
331 #! MixedMap mapname.map
333 in the higher-priority updmap.cfg file.
335 (The #! must be at the
336 beginning of the line, with at least one space or tab afterward,
338 and whitespace between each word on the list.)
339 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 #! Map belleek.map Map mt-plus.map Map mt-yy.map
346 and call updmap.
348 Listing of maps:
350 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 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 updmap-user vs. updmap-sys:
365 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 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 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 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 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 dvips35.map
393 Map file for standard 35 PostScript fonts for use with dvips(1).
394 pdftex35.map
396 Map file for standard 35 PostScript fonts for use with pdf‐
397 tex(1).
398 ps2pk35.map
400 Map file for standard 35 PostScript fonts for use with ps2pk(1).
401 Output files:
403 psfonts.map
405 For dvips(1). Same as psfonts_t1.map if option dvipsPreferOut‐
406 line active, else as psfonts_pk.map.
407 psfonts_pk.map
409 For dvips(1). Without information from MixedMap files. (Set‐
410 ting of dvipsPreferOutline ignored.)
411 psfonts_t1.map
413 For dvips(1). With information from MixedMap files. (Setting
414 of dvipsPreferOutline ignored.)
415 download35.map
417 For dvips(1). Always downloads the standard 35 fonts. (Setting
418 of dvipsDownloadBase35 ignored.)
419 builtin35.map
421 For dvips(1). Never downloads the standard 35 fonts. (Setting
422 of dvipsDownloadBase35 ignored.)
423 pdftex.map
425 For pdftex(1). Same as pdftex_dl14.map if option pdftexDown‐
426 loadBase14 active, else as pdftex_ndl14.map.
427 pdftex_dl14.map
429 For pdftex(1). Always downloads the standard 14 fonts.
430 pdftex_ndl14.map
432 For pdftex(1). Never downloads the standard 14 fonts.
433 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 Configuration files for dvips(1):
439 config.builtin35
441 Loads builtin35.map instead of psfonts.map.
442 config.download35
444 Loads download35.map instead of psfonts.map.
445 config.outline
447 Loads psfonts_t1.map instead of psfonts.map.
448 config.pdf
450 Loads psfonts_t1.map instead of psfonts.map and has additional
451 optimizations for PDF generation.
452 config.pk
454 Loads psfonts_pk.map instead of psfonts.map.
455 config.www
457 Loads psfonts_t1.map instead of psfonts.map. (For compatibility
458 with old versions.)
459 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/>
466TeX Live May 2021 UPDMAP(1)