[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ next ]

Debian-specific information about TeX packages
Chapter 2 - Changing your configuration, file placement

2.1 Available TEXMF trees for users and system administrators

The following TEXMF trees are available. They are displayed below in the order they are searched, where earlier ones override later ones.


Default location: $HOME/.texmf-config/

Contains user-specific configuration


Default location: $HOME/.texmf-var/

Contains user-specific generated files


Default location: $HOME/texmf/

Contains user-specific static input files, e.g. new LaTeX packages.


Default location: /etc/texmf

Contains system-wide configuration


Default location: /var/lib/texmf/

Contains system-wide generated files


Default location: /usr/local/share/texmf/

Contains system-wide input files


Default location: /usr/share/texmf/

Contains system-wide, dpkg-managed input files (TeX add-on packages)


Default location: /usr/share/texmf-texlive

Contains system-wide, dpkg-managed input files (basic TeX packages)

If you want to add files, you should usually use TEXMFLOCAL or TEXMFHOME, depending on whether you are the system administrator or a user. If needed, a system administrator can add additional trees to the TEXMF variable in /etc/texmf/texmf.d/05TeXMF.cnf (earlier entries take precedence). TEXMFCONFIG and TEXMFVAR are used by the user-specific texconfig, updmap, and fmtutil commands. Note that texconfig creates a copy of configuration files from TEXMFMAIN (or /etc/texmf) at the time it is first invoked to handle a particular file, and does not track later system-wide changes, and it does not know about update-* programs (see below The files texmf.cnf, fmtutil.cnf, updmap.cfg and language.dat, Section 2.4).

2.2 General hints

2.2.1 System-wide versus user-specific configuration

TeX Live supports a complete user-specific configuration setup in the user's home directory. System administrators must use the commands texconfig-sys, fmtutil-sys and updmap-sys which act on the system-wide configuration files. Users can invoke their user counterparts texconfig, fmtutil and updmap. This will put copies of the system-wide configuration files into the user's TEXMFCONFIG directory (by default, $HOME/.texmf-config), modify them and generate according formats, if applicable.

There is no such mechanism for texmf.cnf. For a way to customize texmf.cnf as a user, see Per user configuration changes, Section 2.4.4.

2.2.2 Configuration file placement

On a TeX system, in principle every TeX input file can be used to change the behavior of the system and hence could be treated as a configuration file. To avoid an inflation of configuration files, those that are used to control the typeset output - the appearance of documents - are not installed as configuration files. It makes more sense to keep changed versions in the current directory for a certain project, or in TEXMFHOME or TEXMFCONFIG of a particular user. However, local admins can take any file they want from the TEXMFDIST (/usr/share/texmf-texlive) or TEXMFMAIN (/usr/share/texmf) trees and put changed copies into the respective directories below /etc/texmf (TEXMFSYSCONFIG which sorts before all other trees).

Since the package management system does not know whether a file is treated as a configuration file on a specific system, it is up to the site admin or local user to check whether one of their changed files has changed in TEXMFMAIN or TEXMFDIST.

2.2.3 What is configured where?

The central system-wide configuration files texmf.cnf (which controls the basic operation and file search paths for the included programs), fmtutil.cnf (which specifies the available TeX formats), updmap.cfg (font configuration) and language.dat (hyphenation patterns for many formats) are handled through a Debian-specific mechanism that allows the basic TeX packages, add-on packages and local administrators to combine their changes (see The files texmf.cnf, fmtutil.cnf, updmap.cfg and language.dat, Section 2.4 below).

For some configuration changes, there is a program called texconfig-dialog (or simply texconfig for a commandline frontend); alternatively, you can of course make the necessary changes in configuration files by hand.

2.3 Hyphenation

Hyphenation should pretty much work out of the box. Please note that in Debian, language.dat is a generated file (see The files texmf.cnf, fmtutil.cnf, updmap.cfg and language.dat, Section 2.4).

For users of the ukranian language, the right pattern file depends on the output encoding (see /usr/share/texmf-texlive/tex/generic/ukrhyph/ukrhyph.tex); you can also choose different rule sets in the file.

2.4 The files texmf.cnf, fmtutil.cnf, updmap.cfg and language.dat

In the following we describe ways to configure these files for the system administrator, i.e. one that has write access to the /etc/texmf hierachy. In Per user configuration changes, Section 2.4.4 we describe a per-user configuration.

The files texmf.cnf, fmtutil.cnf, updmap.cfg and language.dat contain configuration options from TeX Live, possibly from you, and from other TeX-related packages. They are generated by scripts and should not—in fact, except texmf.cnf may not—be edited directly. Rather, you should work with the source files in the respective directories below /etc/texmf/.

In order to make updates smooth, you should avoid editing system-wide files as far as possible, and instead add new files to change settings. For texmf.cnf snippets, this is particularly easy, since earlier entries override any later entries. Only for removing settings from fmtutil.cnf, updmap.cfg or language.dat is it necessary to edit existing files.

2.4.1 texmf.cnf and update-texmf

The TeX binaries are built to look for texmf.cnf (the master config file for TeX and Metafont) in /usr/share/texmf/web2c/texmf.cnf (or $HOME/.texmf-config/web2c/texmf.cnf if it exists). The system-wide file is a symbolic link to /etc/texmf/texmf.cnf. The Debian packaging includes a mechanism for constructing texmf.cnf from a collection of files under /etc/texmf/texmf.d/. To customize texmf.cnf while retaining the Debian-supplied configuration, create an appropriate file (or files) in /etc/texmf/texmf.d/, or change existing files, and then run update-texmf. This will generate the desired texmf.cnf for you.

You should not edit this file directly! While changes made by the local administrator will not be overwritten, they will cause you trouble once a package is updated and brings in a configuration change. You will be shown the differences between the edited and the newly generated file. We will try to merge our and your changes, but that might not always work, and you will probably have to edit again.

Therefore, if you want a smooth upgrade, please edit the files in /etc/texmf/texmf.d, or create an additional one, and invoke update-texmf. This will write your changes into /etc/texmf/texmf.cnf.

You should name your customization file something like 40macros.cnf; the leading numerals will decide the order in which configuration fragments will be assembled by update-texmf, so it might be important to place your customizations in an appropriate place in the sequence — earlier definitions take precedence over later ones. In previous versions the extension .cnf was not necessary, and all files in the directory were used. If you had teTeX installed in woody, you might still have private files which need the extension to be added.

2.4.2 fmtutil.cnf and update-fmtutil, updmap.cfg and update-updmap, language.dat and update-language

These files are also generated files, just as it has been explained above for texmf.cnf. The difference to texmf.cnf is that the system-wide files will be put into /var/lib/texmf/web2c, and any change made in these files will be unconditionally overwritten by update-fmtutil, update-language and update-updmap, respectively. Only the files in /etc/texmf/updmap.d/, /etc/texmf/fmt.d/ and /etc/texmf/language.d/ will be treated as configuration files. Furthermore, the files fmtutil.cnf, updmap.cfg and language.dat are used on a first-found-first-used basis, if there are more than one in the search path, whereas if there are several texmf.cnf files in the search path, their settings are combined as described in Per user configuration changes, Section 2.4.4.

Just as for texmf.cnf, the right way to change settings is to edit or add files in /etc/texmf/updmap.d/, /etc/texmf/fmt.d/ or /etc/texmf/language.d/. The details have been described above (see texmf.cnf and update-texmf, Section 2.4.1). Note, however, that the extension for updmap.cfg snippets in /etc/texmf/updmap.d/ is .cfg, not .cnf.

updmap-sys(8) provides options for enabling or disabling font map files. When enabling a new map file that is not mentioned, updmap-sys will first create or edit 10local.cfg in the /etc/texmf/updmap.d directory and then call update-updmap. Note that updmap-sys's --edit and --syncwithtrees options cannot be used on a Debian system.

2.4.3 A special case in update-fmtutil: Formats which are based on other formats

The JadeTeX and xmlTeX formats are built on top of LaTeX and therefore require special treatment. This is done automatically for the Debian packages for these formats. However, local administrators who similarly base their custom formats on LaTeX (or any other format) might need to take special care, in particular when dist-upgrading.

JadeTeX is based on LaTeX such that during format generation, the LaTeX format dump is preloaded with this line in fmtutil.cnf:

     jadetex		etex	language.dat	&latex jadetex.ini

This is problematic if the package which provides LaTeX (currently texlive-latex-base) is upgraded at the same time as the package which provides the executables (currently texlive-base-bin). In this dpkg run, texlive-base-bin will be configured while texlive-latex-base is unpacked but unconfigured and might have a 10texlive-latex-base.cnf.dpkg-new file in /etc/texmf/fmt.d. texlive-base-bin will call update-fmtutil just before it executes fmtutil --all, and because of the dpkg-new file information for LaTeX will not be included. If JadeTeX would still be included, its format generation would consequently fail.

update-fmtutil knows about this problem and will ignore JadeTeX and xmlTeX if LaTeX is not available. It does not know which other (locally defined) formats are also based on LaTeX, though. To prevent failures (and actually a possible fork bomb, see Debian Bug #427562), local administrators should manually disable such formats before upgrading TeX Live packages.

2.4.4 Per user configuration changes

update-texmf is only available for root; if a user wants to maintain their own texmf.cnf, they can put it into TEXMFCONFIG/web2c and must manually edit it. However, in order for it to be found, they need to set an environment variable [1]:

     export TEXMFCNF=$HOME/.texmf-config/web2c:

The final colon includes the system wide default. Since all texmf.cnf files are read, with earlier definitions taking precedence over later ones, it is best to keep only a minimal set of definitions in the user-specific file.

In contrast to the above—TeX reading and merging all texmf.cnf files—the first found occurrence of one of the files updmap.cfg, language.dat, fmtutil.cnf is used. Thus, when called by a user, the other configuration update programs also work with files in TEXMFCONFIG/updmap.d, TEXMFCONFIG/fmt.d or TEXMFCONFIG/language.d, where TEXMFCONFIG is usually HOME/.texmf-config. They combine files in these directories with the files in the system-wide directories—naturally the user-specific ones take precedence if the names are equal (see User-specific installation, Section 4.4) —and drop the respective generated file into the user's TEXMFVAR, effectively overriding the system-wide config files. Note that changes to existing configuration file snippets made by package updates will not be propagated to the user's files.

updmap(1) provides the same options for enabling and disabling map files as updmap-sys(8), see above. 10local.cfg is created or edited in TEXMFCONFIG/updmap.d.

2.5 Font caching

A TeX system needs to generate new font data (pixel data, metric, sources) on the fly. These files can be saved into the TeX font cache and later be reused. By default, a separate font cache is created for each user in their own TEXMFVAR directory ($HOME/.texmf-var/). If this directory is not writable, e.g. during automated package building, a directory called VARTEXFONTS, /tmp/texfonts/, is used instead, but this directory is cleaned up regularly.

On multi-user machines, it might be advisable that the local administrator enables a site-wide font cache and sets VARTEXFONTS to a persistent directory, e.g. /var/cache/fonts. The variable is set in /etc/texmf/texmf.d/05TeXMF.cnf and can either be changed there or preferrably overwritten in a file that sorts before 05TeXMF.cnf, e.g. /etc/texmf/texmf.d/04VARTEXFONTS.cnf. Do not forget to run update-texmf after making the change. To enable a side-wide font caching the admin should edit /etc/texmf/web2c/mktex.cnf and use 'varfonts' instead of 'texmfvar' in MT_FEATURES. Care should be taken to specifiy appropriate permissions for the directory containing the font cache. Either the local admin should create all available font data and not allow write access, or else write access should be limited to trusted users. Yet an other alternative is to bind-mount /var/cache/fonts from a separate partition, so that users are not able to fill up the /var partition with font data.

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ next ]

Debian-specific information about TeX packages

generated from $Id: TeX-on-Debian.sgml 3103 2007-09-25 11:01:46Z preining $

The Debian TeX mailing list debian-tex-maint@lists.debian.org