[Tex/LaTex] n’t I use getnonfreefonts to install additional fonts? Why shouldn’t I use updmap when installing or removing fonts

Question

This question and answer is a response to a request from Joseph Wright.

• Why shouldn't I use getnonfreefonts to install additional fonts?

• Why shouldn't I use updmap when installing or removing fonts?

---

Background

There are a number of questions on the site concerning problems caused by people installing additional fonts and using updmap to update the 'map' files on which TeX depends.

One common cause of these problems is the use of getnonfreefonts.

Other causes are the use of other font installation scripts or executing updmap directly.

Answer 1

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:

• updmap
• updmap-sys

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!