[ 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:

    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.


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:

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