What causes the problems?
The essential problem here is that
updmap is executed in some way, shape or form.
Running an older version of
getnonfreefonts causes problems because it executes
getnonfreefonts --user causes problems because it executes
Other font installation scripts cause this problem because they execute
(Of course, not all scripts do this. But our concern here is with those which do.)
Finally, of course, executing
updmap directly causes problems because it executes
What is the problem with
getnonfreefonts [older versions] and
updmap. (See previous section if you are still unclear on this point.)
What is the problem with
In essence, the problem is that
updmap creates personal font mapping files which are not updated when fonts are removed, added or updated for the system-wide installation of TeX Live (e.g. when
tlmgr is used to update).
Tex Live provides a series of commands for managing a TeX installation. An especially important group of commands come in two flavours. These commands are named like this:
<command name> and/or
<command name> --user
<command name>-sys and/or
<command name> --sys
The command we are interested in,
updmap, is one of these commands. That is, it comes in two flavours:
This means that the first command manages configuration and installation for the current user only. The second command,
updmap-sys, manages configuration and installation for all users, system-wide.
updmap-sys read a series of configuration files which tell them which
.map files to look for and which to activate, as well as some information about how fonts should be used. They then try to read these
.map files and use the information from them to create a number of 'super'
.map files for various programmes to use.
Suppose, for example, that the programme finds a configuration file with the following lines
This tells it, among other things, to read the file
AnonymousPro.map and enable the fonts that file describes.
For example, the first few lines of this file are
AnonymousPro-Regular-01 AnonymousPro <AnonymousPro-01.enc <AnonymousPro-Regular.pfb " fontinst-autoenc-AnonymousPro-01 ReEncodeFont "
AnonymousPro-Regular-02 AnonymousPro <AnonymousPro-02.enc <AnonymousPro-Regular.pfb " fontinst-autoenc-AnonymousPro-02 ReEncodeFont "
AnonymousPro-Regular-03 AnonymousPro <AnonymousPro-03.enc <AnonymousPro-Regular.pfb " fontinst-autoenc-AnonymousPro-03 ReEncodeFont "
which tells TeX, basically, what to do with requests for various fonts from the AnonymousPro family.
The crucial thing is that
updmap-sys read this file and add the relevant information to the 'super'
.map files they produce.
For example, they would add the following lines to
pdftex.map, which pdfTeX uses in translating your request for AnonymousPro fonts into reality:
AnonymousPro-Bold-01 AnonymousPro-Bold <AnonymousPro-01.enc <AnonymousPro-Bold.pfb " fontinst-autoenc-AnonymousPro-01 ReEncodeFont "
AnonymousPro-Bold-02 AnonymousPro-Bold <AnonymousPro-02.enc <AnonymousPro-Bold.pfb " fontinst-autoenc-AnonymousPro-02 ReEncodeFont "
AnonymousPro-Bold-03 AnonymousPro-Bold <AnonymousPro-03.enc <AnonymousPro-Bold.pfb " fontinst-autoenc-AnonymousPro-03 ReEncodeFont "
When you compile a document using pdfTeX or TeX, the small
.map file fragment which is part of the package of AnonymousPro fonts is not read: TeX only reads the 'super'
.map files which include information about all of the fonts available to the installation.
So far, both
updmap-sys do the job.
updmap configures things only at the level of the individual user, it creates 'super'
.map files in
TEXMFVAR. On a typical GNU/Linux installation, this is
YYYY is the edition of TeX Live (e.g.
The immediate results of this are great. The individual user finds everything works and newly installed fonts are suddenly available for use in documents.
But the files in
TEXMFVAR now supersede the system-wide copies of
pdftex.map and so on. Right now, that's OK because all of the system-wide information will be replicated in the new versions in
The problems begin when the installation is updated. Let's suppose that the user now runs
tlmgr to update the installation and is excited to see that a new type1 postscript font, GorgeousGraffiti, is installed.
tlmgr does all the updating of everything, so it should be all ready to use. The user reads the documentation and tries to use the new font in a document.
TeX now complains that it cannot find the font. As it isn't sure what to do, it tries to find an
.mf recipe to create a
.pk file but, of course, there isn't one. Compilation fails.
When the user compiles with pdfTeX, the programme reads the 'super'
.map files it uses. It gives priority to the ones in
TEXMFVAR - not the system-wide ones. For example, it gives priority to the user's personal
pdftex.map and doesn't read the system-wide one. (Similar things happen if the user uses TeX rather than pdfTeX.)
tlmgr manages the system-wide configuration and installation. So it added the information about GorgeousGraffiti not to the individual user's copy of
pdftex.map but, rather, to the system-wide copy in
TEXMFSYSVAR. In order to get the information about GorgeousGraffiti added to the user's copy of
pdftex.map, the user needs to run
updmap again. And the same thing will happen every time
tlmgr makes changes to the system font configuration - to integrate those changes in the user's copy of
pdftex.map, the user needs to run
This is, to put it mildly, a Pain.
updmap even once means that the system-wide font map information will never be read again.
updmap-sys deals with the system-wide configuration. When you use
getnonfreefonts --sys to install additional fonts, for example, the fonts are installed in
updmap-sys is used to add information about those fonts to the system-wide configuration.
tlmgr is used to update the installation in this case, it will add the information about GorgeousGraffiti to the system-wide
pdftex.map etc. as before. But this time, when the user compiles a document which uses that font, pdfTeX will not find any copy of
pdftex.map in the user's personal
TEXMFVAR. So, it will use the system-wide one from
TEXMFSYSVAR instead. Since this version has been updated with the new information, pdfTeX will know all about GorgeousGraffiti and the document will compile successfully.
The moral of the story
getnonfreefonts --sys to install additional fonts.
getnonfreefonts in the usual way.
- This will install a command,
getnonfreefonts, with two flavours:
getnonfreefonts --user and
getnonfreefonts --sys. [Older installations may instead have
getnonfreefonts for the user case and
getnonfreefonts-sys in place of
getnonfreefonts --sys should work in this case, too.]
- When installing fonts in the collection, use
getnonfreefonts --sys and
getnonfreefonts --user are the same basic command, the flavour you choose matters. If you call it by
getnonfreefonts --sys, it will do The Right Thing. If you call it by
getnonfreefonts --user, it will do The Wrong Thing.
- Remember that Shakespeare was talking about roses - not font installation scripts: A font installation script by any other name does NOT smell as sweet.
If you use another font installation script, make sure it uses
updmap-sys. Do not use a script which will run
If you need to update the map files directly, always use
If you read this too late
Start by executing the following command to move the files generated by
updmap out of the way. This only renames the directory. If all goes well, you can delete it later.
mv -n $(dirname $(kpsewhich -var TEXMFVAR)) $(dirname $(kpsewhich -var TEXMFVAR)).bkup
Note that running this command may cause slower compilation of some documents initially. For example, cache information will have to be regenerated by LuaTeX,
.pk fonts will need to be recreated etc. It will be similar to first compilation after installing a new edition of TeX Live.
TEXMFVAR only contains generated files. So everything here can be regenerated by TeX as required.
Now make sure that any fonts and associated files installed in
TEXMFHOME are removed. If you aren't sure where that is, run
kpsewhich -var TEXMFHOME. Do not delete the entire directory! If you have installed custom classes or packages, you want to keep those. You will need to check what should be removed and what not.
If you are sure you've not installed custom packages or classes into
TEXMFHOME, you can try
mv -n $(kpsewhich -var TEXMFHOME) $(kpsewhich -var TEXMFHOME).bkup
Again, you can remove the directory later if you are sure you don't need anything in it.
TEXMFHOME contains non-generated files. So if you delete essential stuff here, TeX cannot remake it for you!
When you are done, write the moral of the story on a note for yourself so you don't have to go through this again!