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

The Debian TeX sub-policy
Chapter 4 - File Placement

This chapter describes the placement of TeX input files, so that they can be found by programs. Files that are not input files for TeX or related programs must not be put in a TEXMF tree (put them into /usr/share/package instead). As an exception, documentation files in plain text may be used inside a TEXMF tree, e.g. to explain the purpose of an otherwise empty directory.

4.1 File searching and libkpathsea / libkpse

File locations must follow the TeX Directory Structure, TDS. The TDS specification is available as tds.pdf and tds.html, and the latest version of the TDS is available at http://www.tug.org/twg/tds/. It is a bug if a package only conforms to an outdated TDS version. It is a more severe bug, however, if it conforms to the current TDS version but does not make sure to depend on an appropriately recent version of the Basic TeX packages or tex-common (that supports this TDS version).

The Basic TeX packages must provide a mechanism for searching through TEXMF trees that allows different files to be found depending on the invoking program and the specified file format. The only existing implementation is the libkpathsea library. Unfortunately, it was not originally designed for use as a dynamic shared library. A rewrite is under way to create a libkpse library with proper API specification and ABI compatibility. For the time being, the Basic TeX packages can provide a shared library, and program maintainers can decide to use it, or to link statically against their own copy of the code.

For use in scripts, the Basic TeX packages provide the utilities kpsewhich, kpsepath, kpsexpand, and kpsestat.

4.2 Directory trees

The following TEXMF trees are defined, as outlined below:

1. /usr/share/texmf-tetex/, part of TEXMFDIST

2. /usr/share/texmf-texlive/, part of TEXMFDIST

3. /usr/share/texmf/, referenced as TEXMFMAIN

4. /var/lib/texmf/, referenced as TEXMFSYSVAR

5. /etc/texmf/, referenced as TEXMFSYSCONFIG

6. /usr/local/share/texmf/, referenced as TEXMFLOCAL

7. Any directories listed in the TEXMFHOME configuration variable in texmf.cnf or as an environment variable,

8. optionally user-specific directories for configuration files (TEXMFCONFIG) and generated files (TEXMFVAR)

The search order is from bottom up (files in TEXMFHOME taking precedence over files in TEXMFMAIN) etc.

The role of the trees TEXMFMAIN and TEXMFDIST in Debian differ from upstream's original usage. Upstream uses TEXMFMAIN for the files that have to match the binary executables and TEXMFDIST for other TeX input files that are replaced when a new texmf tarball appears; this distinction is not necessary on a system with a decent package managment system. Instead, the basic TeX packages install their files into their TEXMFDIST directories [1] , while TEXMFMAIN is used by TeX add-on packages for their files and allows them to shadow older versions provided by the basic TeX packages. A couple of files from the basic TeX packages still need to be placed in TEXMFMAIN [2].

The order of basic TeX packages in TEXMFDIST may be changed by the user or by the basic TeX packages, and no implementation may rely on a particular order. This implies that for a package that needs a version of a particular file newer than provided by one of the basic TeX packages, it is not sufficient to declare a dependency on the other basic TeX package(s)[3].

Debian packages generally install files in TEXMFMAIN, and may ship or create empty directories in the other trees, in accordance with Debian Policy. Configuration file handling in TEXMFSYSCONFIG is described below in Configuration files, Section 5.1. Packages should take care to ignore TEXMFHOME in their maintainer scripts.

4.3 Generated files

Generated files should be created below TEXMFSYSVAR (or the user-specific variable directories, TEXMFVAR), with the subdirectory structure conforming to the TDS. Generated font files will either be created in each user's TEXMFVAR tree, or in the VARTEXFONTS tree[4]

An exception is the generated file /etc/texmf/texmf.cnf. It is not intended that local administrators edit that file, but if they do, the configuration update programs must respect these changes. Debian packages must not alter that file.

4.4 Filenames and installation of alternative files

Packages may not install files with the same name as a file already installed in a TEXMF tree, unless both files are in subdirectories where they will only be found by different applications, as determined by the --progname or --format switches to kpsewhich.

There are two exception to this rule:

1. Basic TeX packages install their files into their TEXMFDIST directory and will usually contain files that are also in other basic TeX packages.

2. Packages that need newer versions of a file than already supplied by a basic TeX package and installed in TEXMFDIST can place them into TEXMFMAIN. Thus, the outdated file will be shadowed, and the new one is in effect.

   The maintainer of the basic TeX package should be made aware of the problem [5] The package maintainer must make sure to follow new releases of the basic TeX packages and not continue shadowing a file that is newer than the version provided by the shadowing package.

   The package must make sure that the newer version is backward-compatible, meaning it must not break compilation of any TeX document, and it should not change the output file. A change of the output file may be acceptable if an obviously buggy behavior is corrected, and if it had previously not been possible to easily fix this behavior in user's documents (or if the updated package and a possible fix in the document combined lead to a correct document).

   Installing more than two versions of a file will most likely lead to confusion. Therefore, the possibility to shadow a file once should be enough, and the usage of dpkg-divert is discouraged.

It is also discouraged to use a file other than from the canonical source for that file, usually the CTAN network.

4.5 Documentation

Packages should make documentation available to texdoc. This can be done be either installing the files below /usr/share/doc/texmf, or by providing symlinks from subdirectories of that location to the actual documentation files. To allow partial parallel installation of different basic TeX packages, these always install their documentation files into /usr/share/doc/packagename and put symlinks into their respective TEXMFDIST.

A package must not install files into (subdirectories of) /usr/share/texmf/doc, which is a symbolic link to /usr/share/doc/texmf.

The entry points for documentation should have names that indicate what they document. Names like manual.pdf or index.html should be avoided, even if the directory name is unmistakable [6].

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

The Debian TeX sub-policy