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


The Debian TeX sub-policy
Chapter 4 - Configuration


4.1 Configuration files

In a TeX system, in principle every TeX input file can be changed to change the behavior of the system, and thus be regarded as a configuration file. To prevent inflation of configuration files, packages should not install any TeX input files as conffiles or configuration files. Instead, they should create an empty directory below /etc/texmf/tex and advice users which files are likely places for configuration. It is up to the local admin or individual user to place changed copies in TEXMFSYSCONFIG or TEXMFCONFIG, respectively.

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).


4.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[5].

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 4.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.


4.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_installtexfonts provided by tex-common. See dh_installtexfonts(1) for usage details.

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 TDS version 1.1.

  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 10name.cfg into /etc/texmf/updmap.d/. 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 10foo.cfg and 10bar.cfg into /etc/texmf/updmap.d/, the contents of /var/lib/tex-common/fontmap-cfg/package.list should be:

         10foo
         10bar
    

    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:

    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.

    As long as tex-common is configured, it is expected that mktexlsr and updmap-sys can be safely run whenever available (even if the packages that provide them aren't configured).

A sample implementation of this scheme can be found in Sample code for font packages, Section A.1, but don't forget that dh_installtexfonts can do the work for you.

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


4.2.2 Language/Hyphenation configuration

A package that provides additional hyphenation patterns for TeX 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 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.


4.2.3 Format configuration

Packages that provide additional formats 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.


4.3 Best practices for packages that build-depend on the TeX system:

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.


4.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.


4.5 The Dpkg Post-Invoke Mechanism

To be done...

Packages should be able 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 easy, however it is unclear how it can be made sure that failures get attributed to the correct program (even updmap has recently been reported to fail).


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


The Debian TeX sub-policy

generated from $Id: Debian-TeX-Policy.sgml 442 2005-12-29 18:51:51Z frank $

The Debian teTeX mailing List debian-tetex-maint@lists.debian.org