[DRAFT]: The Debian TeX Policy
Hi all,
in the last months the wish to have a Debian TeX Policy came up several
times. I have tried to put together a first draft for such a document,
and attach it below, hoping you will read and critize it.
In fact it didn't become a real policy document, it's more like the
Developers' Reference. However, some real policy decisions are in
there. I fear it's neither very short and concise nor really long enough
to allow breaking it up into a Policy part and a "Best practices" part.
I have written it in debiandoc-sgml, and attach the source code as a
file. Below comes the result of debiandoc2text; debiandoc2pdf on the
sgml file will give you a nice PDF file (well, nice, hm, lot's of
nearly-empty pages).
Regards, Frank
========================================================================
*****************************DRAFT**************************************
The Debian TeX sub-policy
-------------------------
Frank Küster <frank@debian.org>
The Debian teTeX mailing List <debian-tetex-maint@lists.debian.org>
version 0.1, 2004-09-22
-------------------------------------------------------------------------------
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 Frank Küster
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/doc/copyright/GPL' in the Debian GNU/Linux 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., 59 Temple Place - Suite
330, Boston, MA 02111-1307, USA.
-------------------------------------------------------------------------------
Contents
--------
1. About this document
2. Terms and Definitions
3. File Placement
3.1. Generated files
3.2. Filenames and installation of alternative files
4. Configuration
4.1. Configuration update programs
4.2. Best practices remark for packages that `build-depend' on
the TeX system:
4.3. Command execution, format files, and bug severity
4.4. The Dpkg Post-Invoke Mechanism
-------------------------------------------------------------------------------
1. About this document
----------------------
The latest copy of this document can be found in the
`Debian-TeX-policy' files in the `tetex-bin' package.
-------------------------------------------------------------------------------
2. Terms and Definitions
------------------------
TeX-related package
Any Debian package that uses or provides parts of the TeX
infrastructure: The TeX or MetaFont program or derivatives
thereof, fonts or input files in a TEXMF tree, etc.
Basic TeX packages
A Basic TeX package is a Debian package that provides the basic
infrastructure for TeX-related programs. Usually, the Basic TeX
packages will be divided into an architecture-dependent and an
architecture-indpendent 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. Furthermore it
must provide the kpsewhich binary, and there must be a package
providing the kpathsea library. [1] 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.
TEXMF tree
One directory tree, arranged according to the TeX Directory
Structure, and searched by the kpathsea library, as implemented
by the web2c distribution. The latest version of the TDS is
available at `http://www.tug.org/twg/tds/'.
configuration update programs
The configuration information from files below `/etc/texmf' has
to be made available in appropriate form to the various
TeX-related programs. This is usually done by scripts that write
files into a TEXMF tree (on Debian, the VARTEXMF tree).
The Basic TeX packages define which scripts belong to the
configuration update programs. Currently, those are:
`update-texmf', `update-fmtutil', `update-updmap', and `updmap'.
[1] Unfortunately there is no clear, abstract specification for the
kpathsea library and the kpse`*' executables Packages should ensure
full compatibility with the current web2c implementation.
-------------------------------------------------------------------------------
3. File Placement
-----------------
File locations must follow the TeX Directory Structure, TDS. It is a
bug if a package does only conform to an outdated TDS version. It is
a more severe bug, however, it it conforms to the current TDS version
while the Basic TeX packages available or installed still do not
support this version.
Configuration files must be placed below `/etc/texmf', with symlinks
pointing from the TDS locations to files or directories below
`/etc/texmf'.
The following `TEXMF' trees can be used by packages, as outlined
below, and must be searched for by any implementation of TeX and the
kpathsea library:
1. `/usr/share/texmf/', referenced as TEXMFMAIN
2. `/var/lib/texmf/', referenced as VARTEXMF
3. `/usr/share/texmf-site/', referenced as SITETEXMF
4. `/usr/local/share/texmf/', referenced as TEXMFLOCAL
5. `$HOME/texmf/', referenced as HOMETEXMF
and optionally
6. `/usr/local/lib/texmf/', referenced as TEXMFOLDLOCAL
The search order should be from bottom up (files in HOMETEXMF taking
precedence over files in TEXMFMAIN), with the optional TEXMFOLDLOCAL
after TEXMFLOCAL.
3.1. Generated files
--------------------
Generated font files must be put in subdirectories of
`/var/cache/fonts', all other generated files should be below
`/var/lib/texmf', with the subdirectory structure conforming to the
TDS. If necessary, symbolic links can point from static `TEXMF' trees
to files below `/var/'.
3.2. 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
determinded by the `--progname' switch to kpsewhich.
As an exception to this rule, packages that need newer versions of a
file than already supplied by an other package and installed in
TEXMFMAIN, can place them into SITETEXMF. The package must make sure
that the newer version is backward-compatible, that is: 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 systematically fix this behavior.
Installing more than two versions of a file will most likely lead to
confusion. Therefore, the possibility to shadow a file once using
SITETEXMF 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. Configuration
----------------
4.1. 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', and format generation is
determinded by `/var/lib/texmf/web2c/fmtutil.cnf'. All three files
are generated by configuration update programs from configuration
files in subdirectories of `/etc/texmf'. For `updmap.cfg' 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, should
not change this file, but use the `update-texmf' mechanism.
Maintainer scripts should call the configuration update programs
without any options (excepct `-v') to allow for internal changes, e.g.
of the directories where the generated files are placed.
Packages are free to add configuration items to the common
configuration files, but they may not try to override configuration
items that are yet supplied by other packages. Rather, shared
configuration items must be supplied by the Basic TeX packages or any
other package on which all involved packages depend, with a setting
appropriate for all.
4.2. Best practices remark for packages that `build-depend' on the TeX
system:
----------------------------------------------------------------------------
If packages that build-depend on the TeX system need a changed
configuration, they should not try to provide it statically. Instead,
they should use the configuration update programs with the
`--outputdir' and `--add-file' options. 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 changed in the depended-on package, and such
failure cannot be foreseen by its maintainers.
4.3. Command execution, format files, and bug severity
------------------------------------------------------
TeX-related executables should provide an interface that allows for
non-interactive usage, and guarantee stability of this interface,
including error handling. If TeX formats need to be generated before
execution, this must 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 depending packages.
Format generation involves many configuration and input files. In
many cases format generation failed because of a bad local
configuration, missing files or files added in local TEXMF trees, and
consequently also the package post-installation script and
configuration failed. Therefore bug reports because of failed
post-installation scripts have a severity of _important_ unless
* the error occurs on a fresh install or
* the error occurs upon upgrade, and it has been shown that the
post-installation script would not have failed with the old
version of the package,
in which cases the severity would be _grave_.
4.4. The Dpkg Post-Invoke Mechanism
-----------------------------------
To be done...
Packages should be able 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 is unnecessary to call the
programs multiple times. Coding this is easy, however it is unclear
how it can be made sure that failures get attributed to the correct
program (even updmap has recently been reported to fail).
-------------------------------------------------------------------------------
The Debian TeX sub-policy
Frank Küster <frank@debian.org>
The Debian teTeX mailing List <debian-tetex-maint@lists.debian.org>
version 0.1, 2004-09-22
--
Frank Küster, Biozentrum der Univ. Basel
Abt. Biophysikalische Chemie
<!doctype debiandoc system [
<!-- include version information so we don't have to hard code it
within the document -->
<!entity % versiondata SYSTEM "version.ent"> %versiondata;
]>
<debiandoc>
<book>
<titlepag>
<title>The Debian TeX sub-policy</title>
<author>
<name>Frank Küster</name>
<email>frank@debian.org</email>
</author>
<author>
<name>The Debian teTeX mailing List</name>
<email>debian-tetex-maint@lists.debian.org</email>
</author>
<version>version &version;, &date;</version>
<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. <!-- This document -->
<!-- is part of the policy package for Debian. --> </abstract>
<copyright>
<copyrightsummary>
Copyright © 2004 Frank Küster
</copyrightsummary>
<p>
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.
</p>
<p>
This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied
warranty of merchantability or fitness for a particular
purpose. See the GNU General Public License for more
details.
</p>
<p>
A copy of the GNU General Public License is available as
<file>/usr/doc/copyright/GPL</file> in the Debian GNU/Linux
distribution or on the World Wide Web at
<url id="http://www.gnu.org/copyleft/gpl.html";
name="The GNU General Public Licence">. You can also obtain it by writing to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
</p>
</copyright>
</titlepag>
<toc detail="sect">
<chapt>
<heading>About this document</heading>
<p>
The latest copy of this document can be found in the
<tt>Debian-TeX-policy</tt> files in the <package>tetex-bin</package>
package. <!-- They are also available from the Debian web mirrors -->
<!-- at <tt><url name="/doc/packaging-manuals/menu-policy/" -->
<!-- id="http://www.debian.org/doc/packaging-manuals/menu-policy/";></tt> -->
<!-- and from the Debian archive mirrors at <tt><url -->
<!-- name="/doc/package-developer/menu-policy.txt.gz" -->
<!-- id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz";></tt>. -->
</p>
<p>
<!-- This document has been extracted and separated from the -->
<!-- <em>Menu</em> package to:<enumlist> -->
<!-- <item> -->
<!-- <p>Increase the visibility of the Menu sub policy</p> -->
<!-- </item> -->
<!-- <item> -->
<!-- <p> -->
<!-- Reduce the coupling between policy and -->
<!-- implementation. If this separation is not made, every -->
<!-- time we want to change menu policy, we have to arrange -->
<!-- to get the maintainer to release a new version of the -->
<!-- package, even if the package has not otherwise -->
<!-- changed. It also involves yet another layer, making the -->
<!-- policy changes that much harder to implement.</p> -->
<!-- </item> -->
<!-- </enumlist> -->
<!-- </p> -->
</chapt>
<chapt>
<heading>Terms and Definitions</heading>
<p>
<taglist compact="compact">
<tag>TeX-related package</tag>
<item>
Any Debian package that uses or provides parts of the TeX
infrastructure: The TeX or MetaFont program or derivatives
thereof, fonts or input files in a TEXMF tree, etc.
</item>
<tag>Basic TeX packages</tag>
<item>
<p>A Basic TeX package is a Debian package that provides the
basic infrastructure for TeX-related programs. Usually, the
Basic TeX packages will be divided into an
architecture-dependent and an architecture-indpendent
package.</p>
<p>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. Furthermore it must provide the kpsewhich binary,
and there must be a package providing the kpathsea library.
<footnote>
Unfortunately there is no clear, abstract specification
for the kpathsea library and the kpse<tt>*</tt> executables
Packages should ensure full compatibility with the current
web2c implementation.
</footnote>
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.</p>
</item>
<tag>TEXMF tree</tag>
<item>
One directory tree, arranged according to the TeX Directory
Structure, and searched by the kpathsea library, as
implemented by the web2c distribution. The latest version of
the TDS is available at <tt><url
name="http://www.tug.org/twg/tds/";
id="http://www.tug.org/twg/tds/";></tt>.
</item>
<tag>configuration update programs</tag>
<item>
<p>
The configuration information from files below
<file>/etc/texmf</file> has to be made available in appropriate
form to the various TeX-related programs. This is usually
done by scripts that write files into a TEXMF tree (on
Debian, the VARTEXMF tree).
</p>
<p>
The Basic TeX packages define which scripts belong to the
configuration update programs. Currently, those are:
<file>update-texmf</file>, <file>update-fmtutil</file>,
<file>update-updmap</file>, and <file>updmap</file>.
</p>
</item>
</taglist>
</p>
</chapt>
<chapt>
<heading>File Placement</heading>
<p>
File locations must follow the TeX Directory Structure, TDS. It is a bug if a
package does only conform to an outdated TDS version. It is a
more severe bug, however, it it conforms to the current TDS
version while the Basic TeX packages available or installed
still do not support this version.
</p>
<p>
Configuration files must be placed below <file>/etc/texmf</file>,
with symlinks pointing from the TDS locations to files or
directories below <file>/etc/texmf</file>.
</p>
<p>
The following <tt>TEXMF</tt> trees can be used by packages, as
outlined below, and must be searched for by any implementation
of TeX and the kpathsea library:
<enumlist>
<item><file>/usr/share/texmf/</file>, referenced as TEXMFMAIN</item>
<item><file>/var/lib/texmf/</file>, referenced as VARTEXMF</item>
<item><file>/usr/share/texmf-site/</file>, referenced as SITETEXMF</item>
<item><file>/usr/local/share/texmf/</file>, referenced as TEXMFLOCAL</item>
<item><file>$HOME/texmf/</file>, referenced as HOMETEXMF
<p> and optionally</p>
</item>
<item><file>/usr/local/lib/texmf/</file>, referenced as TEXMFOLDLOCAL</item>
</enumlist>
The search order should be from bottom up (files in HOMETEXMF
taking precedence over files in TEXMFMAIN), with the optional
TEXMFOLDLOCAL after TEXMFLOCAL.
</p>
<sect>
<heading>Generated files</heading>
<p>
Generated font files must be put in subdirectories of
<file>/var/cache/fonts</file>, all other generated files should be
below <file>/var/lib/texmf</file>, with the subdirectory structure
conforming to the TDS. If necessary, symbolic links can point
from static <tt>TEXMF</tt> trees to files below
<file>/var/</file>.
</p>
</sect>
<sect>
<heading>Filenames and installation of alternative files</heading>
<p>
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 determinded by the <tt>--progname</tt> switch
to kpsewhich.
</p>
<p>
As an exception to this rule, packages that need newer
versions of a file than already supplied by an other package
and installed in TEXMFMAIN, can place them into SITETEXMF. The
package must make sure that the newer version is
backward-compatible, that is: 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 systematically fix this behavior.
</p>
<p>
Installing more than two versions of a file will most likely
lead to confusion. Therefore, the possibility to shadow a file
once using SITETEXMF should be enough, and the usage of
<prgn>dpkg-divert</prgn> is discouraged.
</p>
<p>
It is also discouraged to use a file other than from the
canonical source for that file, usually the CTAN network.
</p>
</sect>
</chapt>
<chapt>
<heading>Configuration</heading>
<sect>
<heading>Configuration update programs</heading>
<p>
The central configuration file for TeX applications is
<file>/etc/texmf/texmf.cnf</file>, the central font configuration
file is <file>/var/lib/texmf/web2c/updmap.cfg</file>, and format
generation is determinded by
<file>/var/lib/texmf/web2c/fmtutil.cnf</file>. All three files are
generated by configuration update programs from configuration
files in subdirectories of <file>/etc/texmf</file>. For
<file>updmap.cfg</file> and <file>fmtutil.cnf</file>, this is the only
method of configuration. <file>texmf.cnf</file> can be edited
manually by local system administrators, and changes will be
handled by ucf. Package installation scripts, however, should
not change this file, but use the <file>update-texmf</file>
mechanism.
</p>
<p>
Maintainer scripts should call the configuration update
programs without any options (excepct <tt>-v</tt>) to allow
for internal changes, e.g. of the directories where the
generated files are placed.
</p>
<p>
Packages are free to add configuration items to the common
configuration files, but they may not try to override
configuration items that are yet supplied by other
packages. Rather, shared configuration items must be supplied
by the Basic TeX packages or any other package on which all
involved packages depend, with a setting appropriate for all.
</p>
</sect>
<sect>
<heading>Best practices remark for packages that
<tt>build-depend</tt> on the TeX system:</heading>
<p>
If packages that build-depend on the TeX system need a changed
configuration, they should not try to provide it
statically. Instead, they should use the configuration update
programs with the <tt>--outputdir</tt> and <tt>--add-file</tt>
options. 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 changed in the
depended-on package, and such failure cannot be foreseen by
its maintainers.
</p>
</sect>
<sect>
<heading>Command execution, format files, and bug severity</heading>
<p>
TeX-related executables should provide an interface that
allows for non-interactive usage, and guarantee stability of
this interface, including error handling. If TeX formats need
to be generated before execution, this must be done in the
post-installation script. Packages that depend on an
executable can thus simply declare <tt>Depends:</tt> on the
package providing the executable, and <em>only</em> 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 depending packages.
</p>
<p>
Format generation involves many configuration and input
files. In many cases format generation failed because of a bad
local configuration, missing files or files added in local
TEXMF trees, and consequently also the package
post-installation script and configuration failed. Therefore
bug reports because of failed post-installation scripts have a
severity of <em>important</em> unless
<list compact>
<item>the error occurs on a fresh install or</item>
<item>the error occurs upon upgrade, and it has been shown
that the post-installation script would not have failed with
the old version of the package, </item>
</list>
in which cases the severity would be <em>grave</em>.
</p>
</sect>
<sect>
<heading>The Dpkg Post-Invoke Mechanism</heading>
<p>To be done...</p>
<p>
Packages should be able 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 is unnecessary
to call the programs multiple times. Coding this is easy,
however it is unclear how it can be made sure that failures
get attributed to the correct program (even updmap has
recently been reported to fail).
</p>
</sect>
</chapt>
</book>
</debiandoc>
Reply to: