Ubuntu Manpage: update-updmap — generate updmap.cfg from files in /etc/texmf/updmap.d/

NAME

       update-updmap — generate updmap.cfg from files in /etc/texmf/updmap.d/

SYNOPSIS

       update-updmap [option ...]

DESCRIPTION

This manual page documents update-updmap, a program that was written for the Debian distribution.

Overview
update-updmap is used to generate updmap(1)'s and updmap-sys(8)'s site-wide configuration file,
/var/lib/texmf/web2c/updmap.cfg, or the per-user configuration file, TEXMFCONFIG/web2c/updmap.cfg, from
the files with names ending in ‘.cfg’ located in /etc/texmf/updmap.d/.

The base TeX packages (texlive-) provide files in /etc/texmf/updmap.d/, which define the base contents of
the to-be-generated /var/lib/texmf/web2c/updmap.cfg (general settings and base fonts), or the per-user
file TEXMFCONFIG/web2c/updmap.cfg. With the underlying mechanism, system administrators can disable the
map files they want by commenting their entries in the appropriate files under /etc/texmf/updmap.d/.
Such changes will be preserved if the package in question is removed (not purged) and then reinstalled.

Users without local administration rights can use update-updmap to merge their local configuration and an
updated site-wide configuration (see “User-specific configuration” below). The local configuration
files, unless specified otherwise, are expected in $TEXMFCONFIG/updmap.d, (that is
~/.texmf-config/updmap.d ), and the default output file is $TEXMFVAR/web2c/updmap.cfg (in other words,
~/.texmf-var/web2c/updmap.cfg ).

Thanks to update-updmap, TeX-related font packages can have their own font map files referenced in
/var/lib/texmf/web2c/updmap.cfg without having to edit that file. The packages simply have to ship their
map files (e.g., foo.map) in /etc/texmf/map/dvips/ and one or more ‘.cfg’ file(s) under
/etc/texmf/updmap.d/ (e.g., 10foo.cfg) referencing the map files.

Mode of operation
update-updmap concatenates all the ‘.cfg’ files under /etc/texmf/updmap.d/ provided that:
- they do not contain the following pseudo-comment:

# -_- DebPkgProvidedMaps -_-
or;
- they have this pseudo-comment, are up-to-date (i.e., the same file with suffix ‘.dpkg-new’
doesn't exist) and are listed in a ‘.list’ file under /var/lib/tex-common/fontmap-cfg/, meaning
that the package shipping the ‘.cfg’ file is installed. The name of the ‘.list’ file is ignored
(but should be the name of the package that installed it). The file should contain the names of
the ‘.cfg’ files in /etc/texmf/updmap.d/ that should be enabled, without the ‘.cfg’ suffix,
e.g.

10foo
12bar

The first case is for configuration files added by the local system administrator. Files that contain the
magic pseudo-comment should be used by Debian packages. In this case, only the base name should appear in
the ‘.list’ file: for instance, ‘10foo’ for /etc/texmf/updmap.d/10foo.cfg; please refer to the Debian TeX
Policy for details.

Names for configuration files
Filenames should begin with two digits and must have the extension ‘.cfg’. The order used to process the
files is obtained by running sort(1) with the ‘C’ locale (for ordinary alphanumeric characters, it
corresponds to the ASCII order). The result obtained by concatenating them is stored as the new
updmap.cfg. Note that updmap(1)and updmap-sys(8)don't care about the order of entries, the sorting is
just for the user's convenience.

If you want to be able to use updmap(1)'s or updmap-sys(8)'s option --enable and --setoption, some
further Restrictions apply to the filenames used and the way entries are distributed among these files.
For --setoption to work, the options (like dvipsPreferOutline) must be kept in a file named 00updmap.cfg,
either in /etc/texmf/updmap.d/ as installed by the tex-common package, or in the conf-dir you specified.
If you use --enable Map some.map and there is no mention of some.map in any file in /etc/texmf/updmap.d/
(and in conf-dir, if specified), then the Map line will be introduced in a file whose name matches
*local*.cfg if it exists, or 99local.cfg will be created (in conf-dir if specified). For this to work,
you cannot have more than one file that matches that name, except that you can use conf-dir/*local.cfg to
supersede the site-wide file in /etc/texmf/updmap.d/.

In order to enable a Map file that already is listed in your configuration files, it must be commented
with the string '#! '. This is the sort of lines that
updmap --disable some.map
will produce - see also updmap.cfg(5). If such a line occurs in more than one file, updmap(1) will fail.
Again the exception is a file in conf-dir that shadows entries in a site-wide file.

Although not strictly mandatory, it is wise to keep corresponding Map entries in files with the same name
in conf-dir and the site-wide dir. Otherwise, the results may seem unpredictable.

User-specific configuration
If you want a different configuration for updmap(1) than the setup at your site provides, you can place
changed copies of the configuration files from /etc/texmf/updmap.d/ in a directory below $TEXMFCONFIG, or
create additional files there. Per default, files are looked for in $TEXMFCONFIG/updmap.d, where
$TEXMFCONFIG is ~/.texmf-config unless the configuration has been changed. When you call update-updmap
as a user, it will produce a user-specific updmap.cfg file as follows: if files with the same name exist
in both directories, the version in ~/.texmf-config/updmap.d/ will be used; files with unique names will
be used from either directory.

If you want to keep your files elsewhere, specify their location with options (see “OPTIONS” below).

OPTIONS

       -c, --conf-dir conf-dir
                  in user-specific mode, use configuration files from conf-dir instead of $TEXMFCONFIG/updmap.d/

       -o, --output-file outputfile
                  in user-specific mode, generate outputfile instead of $TEXMFVAR/web2c/updmap.cfg

       --check    Executes  additional  checks  that  all  necessary files are present in the kpathsea database.
                  Don't use this in maintainer scripts.

       --quiet    don't write anything to the standard output during normal operation

       --help     print a summary of the command-line usage of update-updmap and exit

       --version  output version information and exit

       Note that the -v option, which turns on verbose mode, is deprecated.  We are currently  in  a  transition
       phase where quiet mode is still the default (therefore, --quiet has no effect), but update-updmap will be
       verbose by default as soon as enough packages use --quiet in their maintainer scripts.

SYNTAX FOR THE .CFG FILES

       The  ‘.cfg’  files  under  /etc/texmf/updmap.d/  should  contain valid configuration lines for updmap(1).
       Usually, they will consist of lines of following one of these forms:

             Map <foo.map>
             MixedMap <bar.map>

       The MixedMap form should only be used if the font is available in both bitmap and scalable formats  (this
       way,  it  won't be declared in the default map file for Dvips that is used when dvipsPreferOutline is set
       to ‘false’ in updmap.cfg).

       The following comment (from updmap(1)'s point of view):


             # -_- DebPkgProvidedMaps -_-
       is treated in a particular way by update-updmap (see section “Mode of operation”  above)  and  should  be
       used  in  every  ‘.cfg’ file provided by a Debian package.  This ensures that the corresponding map files
       are disabled when the package is removed and reenabled when the package is reinstalled.

FILES

       /etc/texmf/updmap.d/00updmap.cfg
       /etc/texmf/updmap.d/*.cfg
       /var/lib/texmf/web2c/updmap.cfg
       /var/lib/tex-common/fontmap-cfg/*.list

DIAGNOSTICS

       update-updmap returns 0 on success, or a strictly positive integer on error.

AUTHORS

       This manual page was  written  by  Atsuhito  Kohda  <kohda@debian.org>  and  updated  by  Florent  Rougon
       <f.rougon@free.fr>  and  Frank Kuester <frank@debian.org> for the Debian distribution (and may be used by
       others).

Debian                                            Jul 19, 2005                                  UPDATE-UPDMAP(8)