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

# The Debian TeX sub-policy Chapter 6 - Configuration

## 6.1 Configuration files

Files that are used to modify the behavior of executables must be treated as any other configuration file in a Debian package. However, files that are used to control the typeset output - the appearance of documents - need not be treated as configuration files. It is up to the maintainer of the package to decide which files make sense to be used for site-wide (as opposed to per-project or per-document) customization.

A typical case for a site-wide configuration file is a file that must be changed if a style file should use additional modules (installed, for example, into TEXMFLOCAL). Options that only control document output are rather used for a particular document or documentation project and should usually not be installed as a configuration file.

Note that `/etc/texmf/` is a usual TDS tree. Files can be put into appropriate TDS-conforming subdirectories (e.g. `/etc/texmf/fonts/map/`), but directories not specified in TDS (or added Debian-specifically in `tex-common`'s files in `/etc/texmf/texmf.d/`) are generally not searched for TeX input files and can be used by packages for configuration files that are not TeX input files (e.g. the files in subdirectories `fmt.d` or `updmap.d`).

## 6.2 Configuration update programs

The central configuration file for TeX applications is `/etc/texmf/texmf.cnf`, the central font configuration file is `/var/lib/texmf/web2c/updmap.cfg`, the central language/hyphenation configuration `/var/lib/texmf/tex/generic/config/language.dat`, and format generation is determinded by `/var/lib/texmf/web2c/fmtutil.cnf`. All four files are generated by configuration update programs from configuration files in subdirectories of `/etc/texmf`. For `updmap.cfg`, `language.dat` and `fmtutil.cnf`, this is the only method of configuration. `texmf.cnf` can be edited manually by local system administrators, and changes will be handled by ucf. Package installation scripts, however, must not change this file, but use the `update-texmf` mechanism. Local administrators are encouraged to use the `update-texmf` mechanism, too.

Packages are free to add configuration items to the common configuration files, but they should not try to override configuration items that are supplied by other packages. Rather, shared configuration items should be supplied by the Basic TeX packages or any other package on which all involved packages depend, with a setting appropriate for all. If this is impractical, the involved packages must at least agree on the way different packages override other's settings[8].

Maintainer scripts should call `update-updmap` with the option --quiet. Besides that, the configuration update programs should be called without any options to allow for internal changes, e.g. of the directories where the generated files are placed.

Packages that changed `updmap.cfg` must call `updmap-sys` as detailed in Font configuration, Section 6.2.1. Packages that changed `language.dat` or `fmtutil.cnf` must call `fmtutil-sys` (see below). They must make sure to issue the `mktexlsr` command before this.

### 6.2.1 Font configuration

A package that provides PostScript Type 1 fonts for TeX should be usable with any Basic TeX Package. The recommended way to implement the configuration scheme described below is to use the `debhelper` program `dh_installtex` provided by `tex-common`. See `dh_installtex(1)` for usage details.

#### 6.2.1.1 Description of manual font package setup

This section describes how `dh_installtex` manages font packages, and what packages need to do that want to do without it.

For the rest of this section, we'll assume we are dealing with a package named package that installs PostScript Type 1 fonts for TeX. package should fulfill the following requirements:

1. It should depend on `tex-common` but not on any Basic TeX Package, unless needed for another task than simply installing the fonts for TeX.

1. It should install the necessary map files (`.map` extension) below `TEXMFMAIN/fonts/map`. The precise location must conform to the applicable TDS version.

1. It should also obviously install other needed or useful files provided by upstream to use the fonts with TeX-related programs (`.pfb`, `.tfm`, `.enc`, `.fd`, `.sty`, documentation, etc.).

1. It should install one or more configuration files with names following the pattern 20name.cfg into `/etc/texmf/updmap.d/`[9]. Such files will be later merged by `update-updmap` to form `/var/lib/texmf/web2c/updmap.cfg`, the effective configuration file for `updmap-sys`.

Exactly what to put in these files is documented in `update-updmap(1)`. Basically, they should contain the pseudo-comment:

```     # -_- DebPkgProvidedMaps -_-
```

as well as the usual Map and/or MixedMap lines that package needs to add to `/var/lib/texmf/web2c/updmap.cfg`.

1. It should install a file named `/var/lib/tex-common/fontmap-cfg/package.list` that contains a reference to every .cfg file from the previous step, one per line. For instance, if package installs `20foo.cfg` and `20bar.cfg` into `/etc/texmf/updmap.d/`, the contents of `/var/lib/tex-common/fontmap-cfg/package.list` should be:

```     20foo
20bar
```

This `package.list` file must be shipped in the .deb, so that when package is removed (not necessarily purged), `package.list` disappears from `/var/lib/tex-common/fontmap-cfg/`.

1. It should run:

• in `package.postinst`;

• when `package.postrm` is called with remove or disappear as its first argument

the following commands in this order: update-updmap --quiet, mktexlsr and updmap-sys.

Since `mktexlsr` and `updmap-sys` are provided by the Basic TeX Packages, `package.postinst` has to ensure that they are only called when found in \$PATH (unless package depends on the Basic TeX Packages for some reason). In `package.postrm`, the same considerations must be taken into account, with the addition that `tex-common` (that provides `update-updmap`) can be unconfigured or even uninstalled.

Note that even when `tex-common` is configured, it cannot be assumed that `update-updmap`, `mktexlsr` and `updmap-sys` can be safely run whenever available, because they internally use `kpsewhich` which only works after the `libkpathsea` library in a separate package has been configured properly.[10] The following check can be used to determine whether `libkpathsea` is configured:

```     if kpsewhich --version >/dev/null 2>&1; then
echo "kpsewhich is installed and libkpathsea is configured."
else
echo "Either kpsewhich is not installed, or libkpathsea is not configured."
fi
```

A sample implementation of this scheme can be found in Sample code for font packages, Section A.1, but the recommended way to implement this scheme is to use `dh_installtex`.

#### 6.2.1.2 Rationale

The rest of this section explains the rationale behind the previous recommendations.

• The dependency on `tex-common` ensures that in `package.postinst`, `update-updmap` can be run and `texmf.cnf` is in a sane state, so that `mktexlsr` and `updmap-sys` can be run safely (if present and if `libkpathsea` is configured).

• The recommended order for running the programs `update-updmap`, `mktexlsr` and `updmap-sys` ensures that `updmap-sys` can locate the newly-installed files (in particular, the map files shipped by package), since `mktexlsr` is run before `updmap-sys`. It is also run after `update-updmap`, because `/var/lib/texmf/web2c/updmap.cfg` might have been created by `update-updmap`, although it more probably already existed. And since it would be of no use to call `mktexlsr` before `update-updmap`, we recommend to run it after, just in case.

• Now, about the "magic comments" in `/etc/texmf/updmap.d/*.cfg` and the `package.list` file in `/var/lib/tex-common/fontmap-cfg/`. When that package is removed, but not purged, it has to make sure that its `update-updmap` configuration files in `/etc/texmf/updmap.d/` are ignored. Otherwise, any call to `updmap-sys` by an other package or the local admin would fail because it cannot find package's map files. Besides, we want the `/etc/texmf/updmap.d/*.cfg` files to be conffiles (unless we really have no other choice), because then `dpkg` automatically handles upgrades while preserving user modifications for them. As a consequence, moving the `.cfg` files from package out of the way when it is removed is not an option. Moreover, the user would wonder where his configuration files have gone in such a case.

The solution we chose was to add a little bit of logic into `update-updmap`, so that whenever it sees a `.cfg` file (let's call it `20foo.cfg`) that has the "magic comment", it actually includes its contents into `updmap.cfg` if, and only if:

• it is up-to-date (which is assumed if `20foo.cfg.dpkg-new` doesn't exist in the same directory);

• 20foo appears on a line by itself in one of the `.list` files in `/var/lib/tex-common/fontmap-cfg/`.

Additionally, that `.list` file should be named `package.list` if `20foo.cfg` comes from package, for simple reasons of tidiness.

With this little mechanism in place, all the rest follows as expected:

• When package is removed, but not purged, `package.list` is first removed by `dpkg` from `/var/lib/tex-common/fontmap-cfg/`, thus disabling the the `.cfg` files shipped by package as far as `update-updmap` is concerned. Then, `package.postrm` calls `update-updmap`, `mktexlsr` and `updmap-sys`, with the result that package's map files aren't listed anymore in the final map files (`psfonts.map`, `pdftex.map`...) generated by `updmap-sys`.

• If package is reinstalled later, two files are first created by `dpkg` during the unpack phase: `/var/lib/tex-common/fontmap-cfg/package.list` and `/etc/texmf/updmap.d/20foo.cfg.dpkg-new`. As long as the second one exists, the conffile `/etc/texmf/updmap.d/20foo.cfg` will be ignored by `update-updmap`[11] because it may be outdated. Eventually, package is configured; `package.postinst` runs `update-updmap`, `mktexlsr` and `updmap-sys`, and the `.cfg` files shipped by package aren't ignored by `update-updmap` this time, since they are referenced in `/var/lib/tex-common/fontmap-cfg/package.list` and the `.dpkg-new` files don't exist anymore. Thus, the map files shipped by package do end up in the final map files generated by `updmap-sys`.

### 6.2.2 Language/Hyphenation configuration

A package that provides additional hyphenation patterns for TeX should be usable with any Basic TeX Package. The recommended way to implement the configuration scheme described below is to use the `debhelper` program `dh_installtex` provided by `tex-common`. See `dh_installtex(1)` for usage details. Note that for `language.dat`, order is important: english should always be the first language.

These packages should put the actual hyphenation file into the respective places in TEXMFMAIN, and have them registered by putting a configuration file with extension .cnf into `/etc/texmf/language.d` and calling update-language. The file contents will then be incorporated into `/var/lib/texmf/tex/generic/config/language.dat`, the effective configuration file for TeX and friends' hyphenations.

Hyphenation patterns present the same problem as described in the previous section for font configuration files: If the package is removed, but not purged, the patterns are deleted, but the configuration information is still in `/etc/texmf/language.d/`, and the format generation would fail if they would be included in `language.dat`. Therefore, an analogous mechanism has been implemented as described for `update-updmap`: If a file in `/etc/texmf/language.d/` contains the "magic comment"

```     # -_- DebPkgProvidedMaps -_-
```

it will only be used as long it is:

• up-to-date (which is assumed if the same file with `.dpkg-new` suffix doesn't exist in the same directory);

• listed in a file in `/var/lib/tex-common/language-cnf/` which should have the name `package.list`.

Calling update-language is *not* sufficient to be able to use the new hyphenation patterns; instead the formats that use it need to be regenerated. This can be done by running fmtutil-sys --byhyphen `kpsewhich --progname=latex language.dat`.

If a package that provides additional hyphenation patterns is removed, it must make sure the formats are properly recreated without it. With the "magic comment" mechanism, this means to run `update-language` and fmtutil-sys --byhyphen `kpsewhich --progname=latex language.dat` in `postrm`

There is currently no mechanism (i.e., no `update-language`) for automatic addition of hyphenation patterns to formats that do not use the same hyphenation configuration file as LaTeX.

The recommended way for implementing this scheme is to use `dh_installtex`.

### 6.2.3 Format configuration

As with font map configuration and language hyphenation patterns configuration, packages that provide additional formats should be usable with any Basic TeX Package. The recommended way to implement the configuration scheme described below is to use the `debhelper` program `dh_installtex` provided by `tex-common`. See `dh_installtex(1)` for usage details. Note that for `fmtutil.cnf`, order is important: Formats will be created for each line, and thus format files created from later lines will overwrite earlier ones.

These packages should put a configuration file according to `fmtutil.cnf(5)` into `/etc/texmf/fmt.d/`, run `update-fmtutil` and subsequently create the format with fmtutil-sys --byfmt format. `fmtutil-sys` will only try to create the format if it can find the corresponding `format.ini` file (the last argument in an `fmtutil.cnf` line). Therefore the `format.ini` file should not be a conffile.

If a package needs to create formats at runtime, it should use a local `fmtutil.cnf` with the appropriate entries and specifiy its location to `fmtutil` on the command line, using the --cnffile switch.

Upon package removal, `update-fmtutil` must be called in postrm, and the created formats and log files should be removed from the directory specified by `kpsewhich -var-value=TEXMFSYSVAR`/web2c.

The recommended way for implementing this scheme is to use `dh_installtex`.

## 6.3 Best practices for packages that build-depend on the TeX system

### 6.3.1 Configuration

If packages that build-depend on the TeX system need a changed configuration, they should not try to provide it statically. If settings in any other configuration file are inappropriate for a package to build, this is (usually) a bug in the package that provides the file. It should be fixed in this package, not circumvented by a workaround in the build process. Such workarounds have proven to be problematic, because they might stop working after changes in the depended-on package, and such failure cannot be foreseen by its maintainers. If a change is still necessary, the package should use the configuration update programs with the --outputdir and --add-file options.

### 6.3.2 Font cache data

Font cache data are created each time a font in Metafont format is used, and placed by default in TEXMFVAR. During package build, this has to be avoided. In order to be able to clean up the generated files (and only those), the font cache should instead be put below the build directory. This can be achieved by setting TEXMFVAR to a subdirectory of the current directory, e.g. `\$(CURDIR)/.texmf-var`, using Make's built-in variable. Packages which do not change TEXMFVAR must not create documentation that uses Metafont fonts in the binary target.

## 6.4 Command execution and format files

If TeX formats need to be generated before execution, this should be done in the post-installation script. Packages that depend on an executable can thus simply declare Depends: on the package providing the executable, and only do that. Any additional checks, e.g. for the existence of format files, is unnecessary and harmful, causing internal changes (e.g. of format file extensions) to break the depending package that does this check. Maintainer scripts or programs in Debian packages should always use `fmtutil` or `fmtutil-sys` for format generation, and either add a `fmtutil.cnf` snippet in `/etc/texmf/fmt.d/` (with `fmtutil-sys`, for site-wide formats), or use `fmtutil` with the --cnffile option and an appropriate local `fmtutil.cnf` (for runtime programs)

Local administrators can override settings from `texmf.cnf` with environment variables; this has sometimes lead to errors in `postinst` scripts. It is recommended that `postinst` scripts unset relevant variables before format creation or other problematic tasks.

If an add-on package generates a format upon installation that needs a base format (e.g. latex.fmt), it must not load the existing base format [12]. Instead the `fmtutil.cnf` snippet and the `format.ini` file must be changed so that the process of format creation is repeated. For example, if upstream creates their format by loading latex:

```     latex           pdfetex         language.dat    -translate-file=cp227.tcx *latex.ini
jadetex         etex            language.dat    &latex jadetex.ini
```

and the following `jadetex.ini` file:

```     \input jadetex.ltx
\dump
```

then the Debian package maintainer must load `latex.ini` instead of `latex.fmt`, making sure that \dump in `latex.ltx` has no effect, and create the following new `jadetex.ini`:

```     \let\savedump\dump
\let\dump\relax
\input latex.ini
\let\dump\savedump

\input jadetex.ltx
\dump
```

and the following snippet for `fmtutil.cnf`:

```     jadetex         etex    language.dat    -translate-file=cp227.tcx *jadetex.ini
```

## 6.5 The Dpkg Post-Invoke Mechanism

This section was intended to deal with a once-planned mechanism that would allow to delay running of mktexlsr, updmap and perhaps even "fmtutil --all" until all TeX-related packages that want to do this are configured. Thus, it would be unnecessary to call the programs multiple times. Coding this is not hard, however it is unclear how it could be made sure that failures get attributed to the correct package. Therefore this plan has been dropped.

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

The Debian TeX sub-policy

generated from \$Id: Debian-TeX-Policy.sgml 2665 2007-04-11 11:15:11Z frank \$

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