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 updmap
.
Running getnonfreefonts --user
causes problems because it executes updmap
.
Other font installation scripts cause this problem because they execute updmap
.
(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 updmap
.
What is the problem with getnonfreefonts
[older versions] and getnonfreefonts --user
?
They run updmap
. (See previous section if you are still unclear on this point.)
What is the problem with updmap
?
Short answer
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).
Detailed explanation
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.
Both updmap
and 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
Map AnonymousPro.map
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
or 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.map
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
and updmap-sys
do the job.
But because 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 ~/.texliveYYYY/texmf-var
where YYYY
is the edition of TeX Live (e.g. 2017
).
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 TEXMFVAR
.
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.
Why?
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.)
But 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 updmap
again.
This is, to put it mildly, a Pain.
Running updmap
even once means that the system-wide font map information will never be read again.
In contrast, updmap-sys
deals with the system-wide configuration. When you use getnonfreefonts --sys
to install additional fonts, for example, the fonts are installed in TEXMFLOCAL
and updmap-sys
is used to add information about those fonts to the system-wide configuration.
When 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
Use getnonfreefonts --sys
to install additional fonts.
- Install
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
. getnonfreefonts --sys
should work in this case, too.]
- When installing fonts in the collection, use
getnonfreefonts --sys
.
- Although
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 updmap
.
If you need to update the map files directly, always use updmap-sys
.
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-value TEXMFVAR)) $(dirname $(kpsewhich --var-value 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.
Note that 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-value 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-value TEXMFHOME) $(kpsewhich --var-value TEXMFHOME).bkup
Again, you can remove the directory later if you are sure you don't need anything in it.
Note that 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!