Internals of TeX Live 2: multi-updmap

As a follow-up on a previous post on TeX Live internals, today something that is not so internal, but still something that hasn’t found wide knowledge: The new operation mode of updmap: reading all updmap.cfg files.
TeX Live 2013

What is updmap

Many of the fonts shipped in a TeX system are PostScript Type1 fonts. TeX itself does not know anything about these fonts, and only uses the metrics. The output drivers on the other hand need to know which TeX fonts are mapped in which way to external fonts. Typical output drivers are

  • pdf(la)tex: the TeX engine with pdf output. Since producing the pdf needs the actual fonts, pdftex is also an output driver
  • dvips: the classical output driver. Original TeX produced dvi (Device Independent) files, which were translated to PostScript files. During this process the fonts have to be embedded.
  • (x)dvipdf(m(x)): the family of dvipdf converters. Instead of going to PostScript first, these programs allowed direct translation into pdf. XeTeX uses one of these in the background. Japanese users often use dvipdfmx, since its support for Japanese fonts is good.
  • xdvi: display program, needs of course access to the fonts

These output drivers all need the font mapping in a slightly different format (yes, organically grown). Comes updmap into the game: It reads a list of specifications, and creates configuration files for the above programs, in the respective format.

Different layers of configuration

The files generated by updmap come a long way:

  • font map definition maps a TeX internal name to an external font with optional additional transformations
  • font map file a collection of font map definitions, normally one font map file per ‘package’ collecting all fonts shipped in that package
  • updmap config file list of font map files and options
  • output driver configuration files files read by the output drivers, these files are generated by updmap

Configuration of fonts in updmap.cfg

The central configuration file for updmap is updmap.cfg. In former times only the first one found by kpathsea was used, now all of them (see below). Each updmap.cfg file can contain the following items:

  • empty lines, comments with comment char #
  • settings
    SettingName SettingValue
    where SettingName is one of

    • dvipsPreferOutline: values true and false
      Whether dvips uses bitmaps or outlines, when both are available.
    • dvipsDownloadBase35: values true and false
      Whether dvips includes the standard 35 PostScript fonts in its output.
    • pdftexDownloadBase14: values true and false
      Whether pdftex includes the standard 14 PDF fonts in its output.
    • pxdviUse: values true and false
      Whether maps for pxdvi (Japanese-patched xdvi) are under updmap’s control.
    • kanjiEmbed and kanjiVariant: arbitrary strings
      Controls kanji font embedding.
    • LW35: values are URWkb, URW, ADOBEkb, ADOBE
      Controls which fonts are used for the base PostScript fonts.
  • map directives

    Map is used for fonts that are available only in PostScript format, MixedMap is for fonts where Metafont and PostScript variants are present, KanjiMap are used to generate a special map file.

Operation mode

The new operation mode, introduced in TeX Live 2013, now reads all updmap.cfg files found, i.e., all the files given by
kpsewhich -all updmap.cfg
in contrast to the former operation mode of only reading the first found.

Reasons to introduce this mode are various:

  • Configuration of available fonts can be put into the tree where the fonts are. Before the activation of a map file would not have survived when installing a new release of TeX Live, or reinstalling the current version. Now, if for example there are system local fonts in TEXMFLOCAL, and the updmap.cfg in TEXMFLOCAL/web2c lists them, they will automatically be picked up.
  • Users without write permission to the system installation can still have their own fonts, and do not need to have a copy of the system’s updmap.cfg.

Using all updmap.cfg files means that the following files – if they exist – are used (under the assumption of a standard TeX Live installation, where is the root of the TeX Live installation):

System mode (updmap-sys)

TEXMFSYSCONFIG $ROOT/YYYY/texmf-config/web2c/updmap.cfg
TEXMFSYSVAR $ROOT/YYYY/texmf-var/web2c/updmap.cfg
TEXMFLOCAL $ROOT/texmf-local/web2c/updmap.cfg
TEXMFDIST $ROOT/YYYY/texmf-dist/web2c/updmap.cfg

User mode (updmap)

TEXMFCONFIG $HOME/.texliveYYY/texmf-config/web2c/updmap.cfg
TEXMFVAR $HOME/.texliveYYYY/texmf-var/web2c/updmap.cfg
TEXMFHOME $HOME/texmf/web2c/updmap.cfg
TEXMFSYSCONFIG $ROOT/YYYY/texmf-config/web2c/updmap.cfg
TEXMFSYSVAR $ROOT/YYYY/texmf-var/web2c/updmap.cfg
TEXMFLOCAL $ROOT/texmf-local/web2c/updmap.cfg
TEXMFDIST $ROOT/YYYY/texmf-dist/web2c/updmap.cfg

The only remaining point in need of explanation is: How does one disable a map file activated at one of the configuration files, without editing it directly:

Assume that one the installation under discussion there is a copy of the MathTimePro fonts installed. As a consequence, the map files activating the Belleek fonts should not be used, but it is automatically activated in the updmap.cfg of TEXMFDIST. The solution is to put a disable line, starting with #! into a higher level configuration file.

Continuing the example, assume that the system administrator has put the fonts and support files of the mtpro2 package into TEXMFLOCAL and want to activate the fonts and disable the belleek fonts. The solution is to edit updmap.cfg in TEXMFLOCAL/web2c and add two lines:
#! Map

After that a run of mktexlsr, followed by updmap-sys, will do all the necessary steps.

Running updmap as user (instead of system administrator)

If a user (any) runs updmap (not updmap-sys) once, local copies of the configuration files for the output drivers are created, shadowing the system files. After an update of the installed fonts on the system, the user has to re-run updmap, but no further configuration is necessary. Before TL2013 it was necessary to update also the updmap.cfg file of the user.


For system administrators or anyone who used the former updmap-local.cfg way of configurating the updmap.cfg file, please convert to the new format. The only thing changed is the format of the disable lines:
old: #!
new: #! Map

For single user installations we recommend installation as normal user, putting additional fonts into TEXMFLOCAL, and always run the -sys variants.

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>