The Debian TeX sub-policy ------------------------- The Debian TeX mailing list generated from $Id: Debian-TeX-Policy.sgml 1987 2006-12-06 16:13:15Z frank $ ------------------------------------------------------------------------------- Abstract -------- This document provides a set of rules for the packaging of applications, fonts and input files related to TeX within the Debian GNU/Linux distribution. Copyright Notice ---------------- Copyright (C) 2004-2006 Frank Küster, Richard Lewis, Norbert Preining, Ralf Stubner, Florent Rougon This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This is distributed in the hope that it will be useful, but _without any warranty_; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL (file:///usr/share/common-licenses/GPL) in the Debian distribution or on the World Wide Web at The GNU General Public Licence (http://www.gnu.org/copyleft/gpl.html). You can also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. ------------------------------------------------------------------------------- Contents -------- 1. About this document 2. Terms and Definitions 3. TeX packages for the impatient 4. File Placement 4.1. File searching and `libkpathsea' / `libkpse' 4.2. Directory trees 4.3. Generated files 4.4. Filenames and installation of alternative files 4.5. Documentation 5. Configuration 5.1. Configuration files 5.2. Configuration update programs 5.3. Best practices for packages that `build-depend' on the TeX system 5.4. Command execution and format files 5.5. The Dpkg Post-Invoke Mechanism A. Sample code A.1. Sample code for font packages ------------------------------------------------------------------------------- 1. About this document ---------------------- This document provides a set of rules for the packaging of applications, fonts and input files related to TeX within the Debian GNU/Linux distribution. It is still a in a draft state -- some things might not yet be fully implemented, and others are advisable, but not strictly necessary. If in doubt, please ask on `debian-tex-maint@lists.debian.org'. The latest copy of this document can be found in the `Debian-TeX-Policy' files in the `tex-common' package. ------------------------------------------------------------------------------- 2. Terms and Definitions ------------------------ The following terms are used in this document: TeX-related package Any Debian package that uses or provides parts of the TeX infrastructure, i.e. the TeX or Metafont program or derivatives thereof, fonts or input files in a tree, etc. `tex-common' This package provides basic infrastructure and some configuration files for all TeX-related packages, including the `configuration update programs'. Basic TeX packages A Basic TeX package is a Debian package that provides the basic infrastructure for TeX-related programs. It should provide sufficient functionality for typesetting most generated (La)TeX code, e.g. from docbook, debiandoc, or texinfo sources. Usually, the Basic TeX packages will be divided into an architecture-dependent and an architecture-independent package. The arch-dependent package must provide at least one binary that is fully compatible with Donald E. Knuth's original TeX program, and it should provide the original TeX itself. The output formats `dvi', PostScript and Adobe PDF must be available, either directly or by conversion of other output formats. The arch-independent package must provide at least the files necessary to create the formats for plain TeX and LaTeX and the input files required by the LaTeX distribution, as well as the Computer Modern fonts. TDS The TeX Directory Structure, which describes file placement for TeX input files. The current version of the TDS is installed with this document as tds.pdf (file:///usr/share/doc/tex-common/tds.pdf) and tds.html (file:///usr/share/doc/tex-common/tds.html). The latest version of the TDS is available at `http://www.tug.org/twg/tds/'. tree One directory tree, arranged according to the TDS TeX input file A file that is meant to be used by a TeX-related program; technically any file that can be found by the `/kpathsea/kpse' library. This includes e.g. Type1 font files. configuration update programs The configuration information from files provided by different TeX-related packages must be merged and made available in appropriate form to the various programs. This is usually done by scripts that write files into the tree. Currently, the configuration update programs provided by `tex-common' are: `update-texmf', `update-fmtutil', `update-language', `update-updmap'. ------------------------------------------------------------------------------- 3. TeX packages for the impatient --------------------------------- * A package that only installs TeX input files, e.g. a new LaTeX package, should install them in the tree (`/usr/share/texmf/') at the place indicated by the TDS, see tds.html (file:///usr/share/doc/tex-common/tds.html) and Section 4.1, `File searching and `libkpathsea' / `libkpse'', and register them in the maintainer scripts, usually by calling `dh_installtex' in `debian/rules' * Packages that add fonts, hyphenation patterns or formats, or want to change the basic configuration in `texmf.cnf', need to follow the rules in Section 5.2, `Configuration update programs' in addition to that. ------------------------------------------------------------------------------- 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/' instead). As an exception, documentation files in plain text may be used inside a 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 (file:///usr/share/doc/tex-common/tds.pdf) and tds.html (file:///usr/share/doc/tex-common/tdbs.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 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 trees are defined, as outlined below: 1. `/usr/share/texmf-tetex/', part of 2. `/usr/share/texmf-texlive/', part of 3. `/usr/share/texmf/', referenced as 4. `/var/lib/texmf/', referenced as 5. `/etc/texmf/', referenced as 6. `/usr/local/share/texmf/', referenced as 7. Any directories listed in the configuration variable in `texmf.cnf' or as an environment variable, 8. optionally user-specific directories for configuration files ( and generated files () The search order is from bottom up (files in taking precedence over files in The role of the trees and in Debian differ from upstream's original usage. Upstream uses for the files that have to match the binary executables and 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 directories [1] , while 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 [2]. The order of basic TeX packages in 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 , and may ship or create empty directories in the other trees, in accordance with Debian Policy. Configuration file handling in is described below in Section 5.1, `Configuration files'. Packages should take care to ignore in their maintainer scripts. [1] This is new, and the basic TeX packages currently transition their files to the new place. [2] Reasons include hardcoded paths in executables as well as the need for e.g. pool files to exactly match the binaries' version, so that shadowing must be prevented. [3] Of course this is only a problem if the file is needed in the configure phase. If it is needed only at runtime, a README file to instruct the local admin should be sufficient. 4.3. Generated files -------------------- Generated files should be created below (or the user-specific variable directories, ), with the subdirectory structure conforming to the TDS. Generated font files will either be created in each user's tree, or in the tree[1] 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. [1] Per default, this tree is located in the world-writeable directory `/tmp/texfonts/', in order to allow automatic package builds to work without user directories. On multi user systems, the admin might want to change this to a persistent directory and set up proper permissions 4.4. Filenames and installation of alternative files ---------------------------------------------------- Packages may not install files with the same name as a file already installed in a 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 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 can place them into . 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 [1] 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. [1] A wishlist bug on the shadowing package, blocked by an other wishlist bug on the basic TeX package, can help tracking these issues. 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/' and put symlinks into their respective . 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 [1]. [1] This allows users to say `texdoc ' directly. Otherwise they will first have to find the right command line (e.g. `texdoc /user.dvi') using `texdoc -s ' ------------------------------------------------------------------------------- 5. Configuration ---------------- 5.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'). 5.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[1]. 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 Section 5.2.1, `Font configuration'. 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. [1] Note that in `texmf.cnf', as well as in the sequence of multiple `texmf.cnf' files that are read, earlier entries override later ones. 5.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. 5.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 that installs PostScript Type 1 fonts for TeX. 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. 2. It should install the necessary map files (`.map' extension) below `/fonts/map'. The precise location must conform to the applicable TDS version. 3. 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.). 4. It should install one or more configuration files with names following the pattern `20.cfg' into `/etc/texmf/updmap.d/'[1]. 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 needs to add to `/var/lib/texmf/web2c/updmap.cfg'. 5. It should install a file named `/var/lib/tex-common/fontmap-cfg/.list' that contains a reference to every `.cfg' file from the previous step, one per line. For instance, if installs `20foo.cfg' and `20bar.cfg' into `/etc/texmf/updmap.d/', the contents of `/var/lib/tex-common/fontmap-cfg/.list' should be: 20foo 20bar This `.list' file must be shipped in the `.deb', so that when is removed (not necessarily purged), `.list' disappears from `/var/lib/tex-common/fontmap-cfg/'. 6. It should run: * in `.postinst'; * when `.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, `.postinst' has to ensure that they are only called when found in `$PATH' (unless depends on the Basic TeX Packages for some reason). In `.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.[2] 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 Section A.1, `Sample code for font packages', but the recommended way to implement this scheme is to use `dh_installtex'. [1] Filenames starting with `10' are reserved for the Basic TeX packages. However, sorting order is actually only relevant for snippets for `texmf.cnf', `fmtutil.cnf' and `language.dat'. [2] However, `update-updmap' uses `libkpathsea' only in user-specific-mode. In system-wide mode, it doesn't matter whether `libkpathsea' is configured or not. 5.2.1.2. Rationale ------------------ The rest of this section explains the rationale behind the previous recommendations. * The dependency on `tex-common' ensures that in `.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 ), 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 `.list' file in `/var/lib/tex-common/fontmap-cfg/'. When that 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 '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 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 `.list' if `20foo.cfg' comes from , for simple reasons of tidiness. With this little mechanism in place, all the rest follows as expected: * When is removed, but not purged, `.list' is first removed by `dpkg' from `/var/lib/tex-common/fontmap-cfg/', thus disabling the the `.cfg' files shipped by as far as `update-updmap' is concerned. Then, `.postrm' calls `update-updmap', `mktexlsr' and `updmap-sys', with the result that 's map files aren't listed anymore in the final map files (`psfonts.map', `pdftex.map'...) generated by `updmap-sys'. * If is reinstalled later, two files are first created by `dpkg' during the unpack phase: `/var/lib/tex-common/fontmap-cfg/.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'[1] because it may be outdated. Eventually, is configured; `.postinst' runs `update-updmap', `mktexlsr' and `updmap-sys', and the `.cfg' files shipped by aren't ignored by `update-updmap' this time, since they are referenced in `/var/lib/tex-common/fontmap-cfg/.list' and the `.dpkg-new' files don't exist anymore. Thus, the map files shipped by do end up in the final map files generated by `updmap-sys'. [1] An `update-updmap' call could take place if another package such as `tetex-bin' is configured in the meantime. That happens sometimes with APT. 5.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 , 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 `.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'. 5.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 '. `fmtutil-sys' will only try to create the format if it can find the corresponding `.ini' file (the last argument in an `fmtutil.cnf' line). Therefore the `.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'. 5.3. Best practices for packages that `build-depend' on the TeX system ---------------------------------------------------------------------- 5.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. 5.3.2. Font cache data ---------------------- Font cache data are created each time a font in MetaFont format is used, and placed by default in . 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 to a subdirectory of the current directory, e.g. `<$(CURDIR)>/.texmf-var', using Make's built-in variable. Packages which do not change _must_ not create documentation that uses MetaFont fonts in the `binary' target. 5.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 [1]. Instead the `fmtutil.cnf' snippet and the `.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 [1] The reason is that, in order to avoid other problems, `update-fmtutil' ignores files in `/etc/texmf/fmt.d' that have a corresponding `.dpkg-new' file, and that it is necessary to recreate all formats when pool files or engines are updated. Thus, some Basic TeX packages call `fmtutil --all' in their postinst scripts. When Basic TeX packages are upgraded together while a package that loads `latex.fmt' is installed and configured, then one of the Basic TeX packages' postinst will call `update-fmtutil' and `fmtutil --all' while others are is still unconfigured and have `.dpkg-new' files. Consequently, no format information for e.g. LaTeX is available, and the generation of the format that wants to load it would fail. However, since all files needed to create e.g. `latex.fmt' are available, the depending format can `\input' `latex.ini' and create its own format without problems. 5.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. ------------------------------------------------------------------------------- A. Sample code -------------- This section contains sample code that implements the recommodations of this document. A.1. Sample code for font packages ---------------------------------- Sample postinst script: # # postinst-texfonts # # postinst snippet for installing Type 1 fonts for TeX # # Author: Florent Rougon # update_fontmaps() { update-updmap --quiet # All of the following needs an installed and configured # basic TeX system, so check this. if kpsewhich --version >/dev/null 2>&1; then # mktexlsr is recommended now because updmap-sys relies # heavily on Kpathsea to locate updmap.cfg and the map files. # Also, it is slightly better not to specify a particular # directory to refresh because updmap.cfg is typically found # in TEXMFSYSVAR while the map files are in TEXMFMAIN or # TEXMFDIST. if which mktexlsr >/dev/null; then mktexlsr; fi if which updmap-sys >/dev/null; then printf "Running updmap-sys... " updmap-sys --quiet echo "done." fi fi return 0 } case "$1" in configure|abort-upgrade|abort-remove|abort-deconfigure) update_fontmaps ;; *) echo "postinst called with unknown argument '$1'" >&2 exit 1 ;; esac Sample postrm script: # # postrm-texfonts # # postrm snippet for installing Type 1 fonts for TeX # # Author: Florent Rougon # tell_that_errors_are_ok() { # Cheap option handling... if [ "$1" = -n ]; then prog="$2" endwith=' ' else prog="$1" endwith='\n' fi printf "\ Trying to run '$prog' (error messages can be ignored if tex-common is not configured)...$endwith" return 0 } # The function name is *try_to*_update_fontmaps because the following # scenario might happen: # 1. this package is deconfigured # 2. tex-common and tetex-bin are removed # 3. this package is removed or purged # # (cf. Policy § 6.5, step 2, about a conflicting package being removed due # to the installation of the package being discussed). # # In this case, update-updmap, mktexlsr and updmap-sys would all be gone once # tex-common and tetex-bin are removed, so we must append "|| true" to their # calls. try_to_update_fontmaps() { # Don't print alarming error messages if the programs aren't even # available. if which update-updmap >/dev/null; then tell_that_errors_are_ok -n update-updmap update-updmap --quiet || true echo "done." fi # All of the following needs an installed and configured basic TeX system. # If there is one, register the fonts. Otherwise, that will be done later # when the basic TeX system is configured, so we can exit without # worrying. kpsewhich --version >/dev/null 2>&1 || return 0 # mktexlsr is recommended now because updmap-sys relies heavily on # Kpathsea to locate updmap.cfg and the map files. Also, it is slightly # better not to specify a particular directory to refresh because # updmap.cfg is typically found in TEXMFSYSVAR while the map files are in # TEXMFMAIN. if which mktexlsr >/dev/null; then tell_that_errors_are_ok mktexlsr mktexlsr || true echo "done." fi if which updmap-sys >/dev/null; then tell_that_errors_are_ok -n updmap-sys updmap-sys --quiet || true echo "done." fi return 0 } case "$1" in remove|disappear) try_to_update_fontmaps ;; purge) # Supposing updmap.cfg & Co are clean (which I think is a reasonable # assumption), we don't need to call try_to_update_fontmaps(). # Calling it on remove _and_ on purge just for hypothetical users # who would break their config before purging this package seems to # be more annoying than useful (it takes a lot of time). ;; upgrade|failed-upgrade|abort-upgrade|abort-install) ;; *) echo "postrm called with unknown argument '$1'" >&2 exit 1 ;; esac ------------------------------------------------------------------------------- The Debian TeX sub-policy The Debian TeX mailing list generated from $Id: Debian-TeX-Policy.sgml 1987 2006-12-06 16:13:15Z frank $