[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
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.
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.
The following TEXMF trees are defined, as outlined below:
/usr/share/texlive/texmf-dist/, referenced as TEXMFDIST
/usr/local/share/texmf/, referenced as TEXMFLOCAL
/usr/share/texlive/texmf/, referenced as TEXMFMAIN
/usr/share/texmf/, referenced as TEXMFDEBIAN
/var/lib/texmf/, referenced as TEXMFSYSVAR
/etc/texmf/, referenced as TEXMFSYSCONFIG
Any directories listed in the TEXMFHOME configuration variable in
texmf.cnf or as an environment variable,
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 parallels the usage in upstream TeX Live. 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; TEXMFDEBIAN is an additional tree where TeX add-on packages can put their files.
Debian packages generally install files in TEXMFDEBIAN, 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 6.1. Packages should take care to ignore TEXMFHOME in their maintainer scripts.
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[2]
An exception is the generated file /etc/texmf/web2c/texmf.cnf.
Local administrators should not edit this file, as manual changes will be
overwritten later on. Instead, configuration file snippets in
/etc/texmf/texmf.d must be used.
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:
Basic TeX packages install their files into their TEXMFDIST directory and will usually contain files that are also in other basic TeX packages.
Packages that need newer versions of a file than already supplied by a basic TeX package and installed in TEXMFDIST can place them into TEXMFDEBIAN. 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 [3] 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.
Packages should make documentation available to texdoc. This can
be done be either installing the files below /usr/share/texmf/doc,
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.
Note that the previous location /usr/share/doc/texmf is obsolete
and should not be used. Files installed there will not be found by
texdoc.
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 [4].
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
The Debian TeX sub-policy
generated from $Id$mailto:debian-tex-maint@lists.debian.org