[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
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
hyphen.d).
Configuration files in the TeX world come in two classes: stackable and unstackable. The first class means that the respective programs read all configuration files found, while in the later case only the top or first configuration file is used.
Stackable configuration files in TeX are TEXMFTREE/web2c/texmf.cnf
(central configuration for TeX applications) and
TEXMFTREE/web2c/updmap.cfg (font configuration), while unstackable
configuration files are TEXMFTREE/tex/generic/config/language.dat
(language support/hyphenation patterns for latex based formats),
TEXMFTREE/tex/generic/config/language.def (the same for etex based
formats), TEXMFTREE/tex/generic/config/language.dat.lua (the same
for luatex based formats), and TEXMFTREE/web2c/fmtutil.cnf (for
format definitions).
In Debian, by default the respective configuration files of the following trees
are used: For texmf.cnf: TEXMFDEBIAN (the texmf.cnf file is a link
to the one in TEXMFMAIN). For updmap.cfg:TEXMFDIST, TEXMFDEBIAN.
For the unstackable configuration files the respective copies in TEXMFSYSVAR
are used.
The stackable configuration files are either static (texmf.cnf) or generated automatically in the background without any need for configuration, since changes can be included in a higher order configuration file.
The non stackable configuration files plus the file
/etc/texmf/web2c/texmf.cnf are generated by configuration update
programs from configuration files in subdirectories of /etc/texmf.
For all of them this is the only method of configuration.
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].
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.
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.
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:
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.
It should install the necessary map files (.map extension) below
TEXMFMAIN/fonts/map. The precise location must conform
to the applicable TDS version.
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.).
It should install one or more configuration files with names following the
pattern 20name.cfg into
/etc/texmf/updmap.d/[6]. 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.
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/.
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.[7] 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.
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[8]
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.
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.
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.
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.
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.
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 [9]. 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
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$mailto:debian-tex-maint@lists.debian.org