<!doctype debiandoc system>
<debiandoc>

  <book>
    <titlepag>
      <title>The Debian TeX sub-policy</title>
      <author>
	<name>The Debian TeX mailing list</name>
	<email>debian-tex-maint@lists.debian.org</email>
      </author>
      <version>generated from $Id$</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 &copy; 2004-2012 Frank Küster, Richard Lewis, Norbert
          Preining, Ralf Stubner, Florent Rougon
	</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
	  <url id="file:///usr/share/common-licenses/GPL"
	  name="/usr/share/common-licenses/GPL"> in the Debian
<!-- 	  <file><url id="file:///usr/share/common-licenses/GPL" -->
<!-- 	  name="/usr/share/common-licenses/GPL"></file> in the Debian -->
	  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., 51 Franklin St, Fifth Floor,
	  Boston, MA 02110-1301, USA.
	</p>
      </copyright>
    </titlepag>

    <toc detail="sect">
    <chapt>
      <heading>About this document</heading>
      <p>
        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 <tt>debian-tex-maint@lists.debian.org</tt>.
      </p>
      <p>
	The latest copy of this document can be found in the
	<tt>Debian-TeX-Policy</tt> files in the <package>tex-common</package>
	package. 
    </chapt>
    <chapt>
      <heading>Terms and Definitions</heading>
      <p>The following terms are used in this document:</p>
      <p>
      <taglist>
        <tag>TeX-related package</tag>
	<item>

	  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
	  <var>TEXMF</var> tree, etc.

	</item>
	<tag><package>tex-common</package></tag>
	<item>

	  <p>This package provides basic infrastructure and some
	  configuration files for all TeX-related packages, including
	  the <prgn>configuration update programs</prgn>.
	  </p>

	</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.  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.</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.  The output formats <tt>dvi</tt>, 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.</p>

	  </item>

	<tag>TDS</tag>
	<item>
	
	<p> The TeX Directory Structure, which describes file
	  placement for TeX input files.  The current version of the
	  TDS is installed with this document
	  as <url id="file:///usr/share/doc/tex-common/tds.pdf"
	  name="tds.pdf">
	  and <url id="file:///usr/share/doc/tex-common/tds.html"
	  name="tds.html">.  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>.</p> </item>

	<tag><var>TEXMF</var> tree</tag> 
	<item> 

	  <p>One directory tree, arranged according to the TDS
	</item>
	
	<tag>TeX input file</tag> 
	<item> 

	  <p>A file that is meant to be used by a TeX-related program;
	technically any file that can be found by the
	<package>/kpathsea/kpse</package> library.  This includes
	e.g. Type1 font files.
	</item>
	
	<tag>configuration update programs</tag>
	<item>

	  <p>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
	  <var>TEXMFSYSVAR</var> tree.
	  </p>

	  <p>
	  Currently, the configuration update programs provided by
	  <package>tex-common</package> are:
	  <file>update-texmf</file>, <file>update-fmtutil</file>,
	  <file>update-language</file>, <file>update-updmap</file>.
	  </p>

	</item>
      </taglist>
      </p>
    </chapt>
    <chapt>
      <heading>TeX packages for the impatient</heading>
      <p>      
	<list>
	<item>
	  A package that only installs TeX input files, e.g. a new
	  LaTeX package, should install them in
	  the <var>TEXMFDEBIAN</var> tree
	  (<file>/usr/share/texmf/</file>) at the place indicated by
	  the TDS,
	  see <url id="file:///usr/share/doc/tex-common/tds.html"
	  name="tds.html"> and <ref id="tds-libkpse">, and register
	  them in the maintainer scripts, usually by
	  calling <prgn>dh_installtex</prgn>
	  in <file>debian/rules</file>
	</item>
	<item>
	  Packages that add fonts, hyphenation patterns or formats, or
	  want to change the basic configuration
	  in <file>texmf.cnf</file>, need to follow the rules in
	  <ref id="update-progs"> in addition to that.
	</item>
      </list>
      </p>
    </chapt>
    <chapt>
      <heading>Meta-packages and dependencies</heading>
      <p>
	The TeX Live collection of basic and add-on TeX packages
	provides some meta-packages for the convenience of users.
      </p>
      <p>
	Depending on the <package>texlive-*</package>
	metapackages is only acceptable
	for editors, IDEs and other tools which handle user-generated
	code.  TeX add-on packages, as well as automated input
	generators etc., must instead depend on a list of individual
	texlive packages which are actually used.
	<footnote>This is, for example, required to be able to adapt
	dependencies of metapackages according to the users'
	needs. </footnote>
      </p>
    </chapt>
    <chapt>
      <heading>File Placement</heading>
      <p>
      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
      <file>/usr/share/<var>package</var></file> instead).  As an
      exception, documentation files in plain text may be used inside
      a <var>TEXMF</var> tree, e.g. to explain the purpose of an
      otherwise empty directory.
      </p>
      <sect id="tds-libkpse">
      <heading>File searching and <package>libkpathsea</package> / <package>libkpse</package></heading>

        <p>
        File locations must follow the TeX Directory Structure, TDS.
        The TDS specification is available as
	<url id="file:///usr/share/doc/tex-common/tds.pdf" name="tds.pdf">
	and <url id="file:///usr/share/doc/tex-common/tds.html"
        name="tds.html">, and 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>.  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
        <package>tex-common</package> (that supports this TDS version).
        </p>
  
        <p>The Basic TeX packages must provide a mechanism for searching
        through <var>TEXMF</var> trees that allows different files to be
        found depending on the invoking program and the specified file
        format.  The only existing implementation is the
        <package>libkpathsea</package> library.  Unfortunately, it was
        not originally designed for use as a dynamic shared library.  A
        rewrite is under way to create a <package>libkpse</package>
        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.
        </p>
  
        <p>For use in scripts, the Basic TeX packages provide the
        utilities <prgn>kpsewhich</prgn>, <prgn>kpsepath</prgn>,
        <prgn>kpsexpand</prgn>, and <prgn>kpsestat</prgn>.</p>

      </sect>
      <sect>
      <heading>Directory trees</heading>

        <p>
        The following <var>TEXMF</var> trees are defined, as outlined
        below:
        <enumlist>
          <item><file>/usr/share/texlive/texmf-dist/</file>, referenced as <var>TEXMFDIST</var></item>
          <item><file>/usr/local/share/texmf/</file>, referenced as <var>TEXMFLOCAL</var></item>
          <item><file>/usr/share/texlive/texmf/</file>, referenced as <var>TEXMFMAIN</var></item>
          <item><file>/usr/share/texmf/</file>, referenced as <var>TEXMFDEBIAN</var></item>
          <item><file>/var/lib/texmf/</file>, referenced as <var>TEXMFSYSVAR</var></item>
          <item><file>/etc/texmf/</file>, referenced as <var>TEXMFSYSCONFIG</var></item>
          <item> Any directories listed in the <var>TEXMFHOME</var> configuration
                 variable in <file>texmf.cnf</file> or as an environment
                 variable,
	  </item>
          <item>optionally user-specific directories for
	      configuration files (<var>TEXMFCONFIG)</var> and generated files
	      (<var>TEXMFVAR</var>)</item>
        </enumlist>

          The search order is from bottom up (files in
          <var>TEXMFHOME</var> taking precedence over files in
          <var>TEXMFMAIN) etc.</var>
	  </p>

	  <p>
	  The role of the trees <var>TEXMFMAIN</var> and
          <var>TEXMFDIST</var> in Debian parallels the usage in
	  upstream TeX Live. Upstream uses <var>TEXMFMAIN</var> for the
          files that have to match the binary executables and
          <var>TEXMFDIST</var> for other TeX input files that are
          replaced when a new texmf tarball appears; 
	  <var>TEXMFDEBIAN</var> is an additional tree where TeX add-on
	  packages can put their files.
	  </p>

        <p>
        Debian packages generally install files in
        <var>TEXMFDEBIAN</var>, and may ship or create empty directories
        in the other trees, in accordance with Debian Policy.
        Configuration file handling in <var>TEXMFSYSCONFIG</var> is
        described below in <ref id="configurationfiles">.  Packages
        should take care to ignore <var>TEXMFHOME</var> in their
        maintainer scripts.
        </p>

      </sect>

      <sect>
	<heading>Generated files</heading>

	<p>
	Generated files should be created
	below <var>TEXMFSYSVAR</var> (or the user-specific
	variable directories, <var>TEXMFVAR</var>), with the
	subdirectory structure conforming to the TDS.  Generated font
	files will either be created in each
	user's <var>TEXMFVAR</var> tree, or in
	the <var>VARTEXFONTS</var> tree<footnote>Per default, this
	tree is located in the world-writeable
	directory <file>/tmp/texfonts/</file>, 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</footnote> <!-- If necessary, symbolic links -->
<!-- 	can point from static <var>TEXMF</var> trees to files -->
<!-- 	below <file>/var/</file>. -->
	</p>

	<p>An exception is the generated file
        <file>/etc/texmf/web2c/texmf.cnf</file>. 
	Local administrators should not edit this file, as manual
	changes will be overwritten later on. Instead, configuration
	file snippets in <file>/etc/texmf/texmf.d</file> must be used.
	</p>

      </sect>

      <sect id="sec-names-and-texmfsite">
	<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 <var>TEXMF</var> tree, unless both
	files are in subdirectories where they will only be found by
	different applications, as determined by the
	<tt>--progname</tt> or <tt>--format</tt> switches to kpsewhich.
	</p>

	<p>
	There are two exception to this rule:
	<enumlist>
  	  <item>
	  Basic TeX packages install their files into their
	  <var>TEXMFDIST</var> directory and will usually contain files
	  that are also in other basic TeX packages.
	  </item>

	  <item>
	  <p>Packages that need newer versions of a file than already
	  supplied by a basic TeX package and installed in
	  <var>TEXMFDIST</var> can place them into
	  <var>TEXMFDEBIAN</var>.  Thus, the outdated file will be
	  shadowed, and the new one is in effect.  
	  </p>

	  <p>
	  The maintainer of the basic TeX package should be made aware
	  of the problem <footnote>A wishlist bug on the shadowing
	  package, blocked by an other wishlist bug on the basic TeX
	  package, can help tracking these issues.</footnote> 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. 
	  </p>

	  <p>
	  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, <strong>and</strong>
	  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).
	  </p>

	  <p>
	  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
	  <prgn>dpkg-divert</prgn> is discouraged.
	  </p>

	  </item>

	</enumlist>
	</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>

      <sect id="sec-documentation">
	<heading>Documentation</heading>

	<p>
	Packages should make documentation available to
	<prgn>texdoc</prgn>.  This can be done be either installing
	the files below <file>/usr/share/texmf/doc</file>, 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
	<file>/usr/share/doc/<var>packagename</var></file> and put
	symlinks into their respective <var>TEXMFDIST</var>.
	</p>

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

	<p>
	The entry points for documentation should have names that
	indicate what they document.  Names like
	<file>manual.pdf</file> or <file>index.html</file> should be
	avoided, even if the directory name is unmistakable <footnote>
	This allows users to say <tt>texdoc
	<var>packagename</var></tt> directly.  Otherwise they will
	first have to find the right command line (e.g. <tt>texdoc
	<var>packagename</var>/user.dvi</tt>) using <tt>texdoc -s
	<var>keyword</var></tt> </footnote>.
	</p>

      </sect>

    </chapt> 
    <chapt>
      <heading>Configuration</heading>
      <sect id="configurationfiles">
        <heading>Configuration files</heading>
	<p>
	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.
	</p>
	<p>
	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.
	</p>
	<p>
	Note that <file>/etc/texmf/</file> is a usual TDS tree.  Files
	can be put into appropriate TDS-conforming subdirectories
	(e.g. <file>/etc/texmf/fonts/map/</file>), but directories not
	specified in TDS (or added Debian-specifically in
	<package>tex-common</package>'s files in
	<file>/etc/texmf/texmf.d/</file>) 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 <file>fmt.d</file> or
	<file>hyphen.d</file>).
	</p>
      </sect>
      <sect id="update-progs">
        <heading>Configuration update programs</heading>


	<p>
	Configuration files in the TeX world come in two classes: stackable
	and unstackable. The first class means that the respective programs
	read <em>all</em> configuration files found, while in the later case
	only the top or first configuration file is used.
	</p>

	<p>
	Stackable configuration files in TeX are 
	<file>TEXMFTREE/web2c/texmf.cnf</file> (central configuration
	for TeX applications) and
	<file>TEXMFTREE/web2c/updmap.cfg</file> (font configuration), 
	while unstackable configuration files are 
	<file>TEXMFTREE/tex/generic/config/language.dat</file> (language
	support/hyphenation patterns for latex based formats),
	<file>TEXMFTREE/tex/generic/config/language.def</file> (the same
	for etex based formats),
	<file>TEXMFTREE/tex/generic/config/language.dat.lua</file> (the
	same for luatex based formats), and
	<file>TEXMFTREE/web2c/fmtutil.cnf</file> (for format definitions).
	</p>

	<p>
	In Debian, by default the respective configuration files of the
	following trees are used: For <file>texmf.cnf</file>: TEXMFDEBIAN
	(the texmf.cnf file is a link to the one in TEXMFMAIN).
	For <file>updmap.cfg</file>:TEXMFDIST, TEXMFDEBIAN.
	For the unstackable configuration files the respective copies
	in TEXMFSYSVAR are used.
	</p>

	<p>
	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.
	</p>

	<p>
	The non stackable configuration files plus the file
	<file>/etc/texmf/web2c/texmf.cnf</file> are
	generated by configuration update programs from configuration
	files in subdirectories of <file>/etc/texmf</file>.  For all
	of them this is the only method of configuration.
	</p> 

	<p>
	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<footnote>
	  Note that in <file>texmf.cnf</file>, as well as in the
	  sequence of multiple <file>texmf.cnf</file> files that are
	  read, earlier entries override later ones.
	</footnote>.
        </p>

	<p>
	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.
	</p>

	<p>
	Packages that changed <file>updmap.cfg</file> must call
	<prgn>updmap-sys</prgn> as detailed in <ref
	id="sec-font-configuration">. Packages that changed
	<file>language.dat</file> or <file>fmtutil.cnf</file> must
	call <prgn>fmtutil-sys</prgn> (see below). They must make sure
	to issue the <prgn>mktexlsr</prgn> command before this.
	</p>

	<sect1 id="sec-font-configuration">
	  <heading>Font configuration</heading>

	  <p>
	  A package that provides PostScript Type&nbsp;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
          <prgn>debhelper</prgn> program <prgn>dh_installtex</prgn>
          provided by <package>tex-common</package>. See <manref
          name="dh_installtex" section="1"> for usage details.
	  </p>
	    
	  <sect2 id="font-configuration-details">
	    <heading>Description of manual font package setup</heading>

	  <p>
	    This section describes how <prgn>dh_installtex</prgn>
	    manages font packages, and what packages need to do that
	    want to do without it.
	  </p>
          <p>
          For the rest of this section, we'll assume we are dealing with a
          package named <var>package</var> that installs PostScript
          Type&nbsp;1 fonts for TeX. <var>package</var> should fulfill the
          following requirements:
            <enumlist>
              <item>
                It should depend on <package>tex-common</package> but not on
                any Basic TeX Package, unless needed for another task than
                simply installing the fonts for TeX.
              </item>

              <item>
                <p>
                It should install the necessary map files
                (<file>.map</file> extension) below
                <file><var>TEXMFMAIN</var>/fonts/map</file>.  The
                precise location must conform to the applicable TDS
                version.
                </p>
              </item>

              <item>
                It should also obviously install other needed or useful files
                provided by upstream to use the fonts with TeX-related
                programs (<file>.pfb</file>, <file>.tfm</file>,
                <file>.enc</file>, <file>.fd</file>, <file>.sty</file>,
                documentation, etc.).
              </item>

              <item>
                <p>
                It should install one or more configuration files with names
                following the pattern <tt>20<var>name</var>.cfg</tt> into
                <file>/etc/texmf/updmap.d/</file><footnote> Filenames
		  starting with <tt>10</tt> are reserved for the Basic
		  TeX packages.  However, sorting order is actually
		  only relevant for snippets
		  for <file>texmf.cnf</file>, <file>fmtutil.cnf</file>
		  and <file>language.dat</file>.
		</footnote>. Such files will be later
                merged by <prgn>update-updmap</prgn> to form
                <file>/var/lib/texmf/web2c/updmap.cfg</file>, the effective
                configuration file for <prgn>updmap-sys</prgn>.
                </p>

                <p>
                Exactly what to put in these files is documented in <manref
                name="update-updmap" section="1">. Basically, they should
                contain the pseudo-comment:

<example>
# -_- DebPkgProvidedMaps -_-
</example>

                as well as the usual <tt>Map</tt> and/or <tt>MixedMap</tt>
                lines that <var>package</var> needs to add to
                <file>/var/lib/texmf/web2c/updmap.cfg</file>.
                </p>
              </item>

              <item>
                <p>
                It should install a file named
                <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
                that contains a reference to every <tt>.cfg</tt> file from the
                previous step, one per line. For instance, if
                <var>package</var> installs <file>20foo.cfg</file> and
                <file>20bar.cfg</file> into <file>/etc/texmf/updmap.d/</file>,
                the contents of
                <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
                should be:

<example>
20foo
20bar
</example>

                This <file><var>package</var>.list</file> file must be shipped
                in the <tt>.deb</tt>, so that when <var>package</var> is
                removed (not necessarily purged),
                <file><var>package</var>.list</file> disappears from
                <file>/var/lib/tex-common/fontmap-cfg/</file>.
                </p>
              </item>

              <item>
                <p>
                It should run:
                <list compact>
                  <item>
                    in <file><var>package</var>.postinst</file>;
                  </item>
                  <item>
                    when <file><var>package</var>.postrm</file> is called with
                    <tt>remove</tt> or <tt>disappear</tt> as its first argument
                  </item>
                </list>
                the following commands in this order: <tt>update-updmap
                --quiet</tt>, <tt>mktexlsr</tt> and <tt>updmap-sys</tt>.
                </p>

                <p>
                Since <prgn>mktexlsr</prgn> and
                <prgn>updmap-sys</prgn> are provided by the Basic TeX
                Packages, <file><var>package</var>.postinst</file> has
                to ensure that they are only called when found in
                <tt>$PATH</tt> (unless <var>package</var> depends
                on the Basic TeX Packages for some reason). In
                <file><var>package</var>.postrm</file>, the same
                considerations must be taken into account, with the
                addition that <package>tex-common</package> (that
                provides <prgn>update-updmap</prgn>) can be
                unconfigured or even uninstalled.
                </p>

                <p>
                Note that even when <package>tex-common</package> is
                configured, it cannot be assumed that
                <prgn>update-updmap</prgn>, <prgn>mktexlsr</prgn> and
                <prgn>updmap-sys</prgn> can be safely run whenever available,
                because they internally use <prgn>kpsewhich</prgn> which only
                works after the <file>libkpathsea</file> library in a separate
                package has been configured properly.<footnote>However,
                <prgn>update-updmap</prgn> uses <file>libkpathsea</file> only
                in user-specific-mode. In system-wide mode, it doesn't matter
                whether <file>libkpathsea</file> is configured or
                not.</footnote> The following check can be used to determine
                whether <file>libkpathsea</file> is configured:

<example>
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
</example>

                </p>
              </item>
            </enumlist>
          </p>

          <p>
          A sample implementation of this scheme can be found in <ref
          id="appen-sample-font">, but the recommended way to implement this
          scheme is to use <prgn>dh_installtex</prgn>.
          </p>
	  </sect2>
	  <sect2 id="font-configuration-rationale">
	    <heading>Rationale</heading>
          <p>
          The rest of this section explains the rationale behind the previous
          recommendations.
            <list>
              <item>
                The dependency on <package>tex-common</package> ensures that
                in <file><var>package</var>.postinst</file>,
                <prgn>update-updmap</prgn> can be run and
                <file>texmf.cnf</file> is in a sane state, so that
                <prgn>mktexlsr</prgn> and <prgn>updmap-sys</prgn> can be run
                safely (if present and if <file>libkpathsea</file> is
                configured).
              </item>
          
              <item>
                The recommended order for running the programs
                <prgn>update-updmap</prgn>, <prgn>mktexlsr</prgn> and
                <prgn>updmap-sys</prgn> ensures that <prgn>updmap-sys</prgn>
                can locate the newly-installed files (in particular, the map
                files shipped by <var>package</var>), since
                <prgn>mktexlsr</prgn> is run before <prgn>updmap-sys</prgn>.
                It is also run after <prgn>update-updmap</prgn>, because
                <file>/var/lib/texmf/web2c/updmap.cfg</file> might have been
                created by <prgn>update-updmap</prgn>, although it more
                probably already existed. And since it would be of no use to
                call <prgn>mktexlsr</prgn> before <prgn>update-updmap</prgn>,
                we recommend to run it after, just in case.
              </item>

              <item>

              <p>
              Now, about the "magic comments" in
              <file>/etc/texmf/updmap.d/*.cfg</file> and the
              <file><var>package</var>.list</file> file in
              <file>/var/lib/tex-common/fontmap-cfg/</file>. When that
              <var>package</var> is removed, but not purged, it has to
              make sure that its <prgn>update-updmap</prgn>
              configuration files in <file>/etc/texmf/updmap.d/</file>
              are ignored.  Otherwise, any call to
              <prgn>updmap-sys</prgn> by an other package or the local
              admin would fail because it cannot find
              <var>package</var>'s map files. Besides, we want the
              <file>/etc/texmf/updmap.d/*.cfg</file> files to be
              conffiles (unless we really have no other choice),
              because then <prgn>dpkg</prgn> automatically handles
              upgrades while preserving user modifications for
              them. As a consequence, moving the <file>.cfg</file>
              files from <var>package</var> 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.
              </p>

              <p>
              The solution we chose was to add a little bit of logic into
              <prgn>update-updmap</prgn>, so that whenever it sees a
              <file>.cfg</file> file (let's call it <file>20foo.cfg</file>)
              that has the "magic comment", it actually includes its contents
              into <file>updmap.cfg</file> if, and only if:
                <list>
                  <item>
                    it is up-to-date (which is assumed if
                    <file>20foo.cfg.dpkg-new</file> doesn't exist in the same
                    directory);
                  </item>
                  <item>
                    <tt>20foo</tt> appears on a line by itself in one of the
                    <file>.list</file> files in
                    <file>/var/lib/tex-common/fontmap-cfg/</file>.
                  </item>
                </list>
              Additionally, that <file>.list</file> file should be named
              <file><var>package</var>.list</file> if <file>20foo.cfg</file>
              comes from <var>package</var>, for simple reasons of tidiness.
              </p>
          
              <p>
              With this little mechanism in place, all the rest follows as
              expected:
              <list>
                <item>
                  When <var>package</var> is removed, but not purged,
                  <file><var>package</var>.list</file> is first removed by
                  <prgn>dpkg</prgn> from
                  <file>/var/lib/tex-common/fontmap-cfg/</file>, thus
                  disabling the the <file>.cfg</file> files shipped by
                  <var>package</var> as far as <prgn>update-updmap</prgn> is
                  concerned. Then, <file><var>package</var>.postrm</file>
                  calls <prgn>update-updmap</prgn>, <prgn>mktexlsr</prgn> and
                  <prgn>updmap-sys</prgn>, with the result that
                  <var>package</var>'s map files aren't listed anymore in the
                  final map files (<file>psfonts.map</file>,
                  <file>pdftex.map</file>...) generated by
                  <prgn>updmap-sys</prgn>.
                </item>

                <item>
                  If <var>package</var> is reinstalled later, two files are
                  first created by <prgn>dpkg</prgn> during the unpack phase:
                  <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
                  and <file>/etc/texmf/updmap.d/20foo.cfg.dpkg-new</file>. As
                  long as the second one exists, the conffile
                  <file>/etc/texmf/updmap.d/20foo.cfg</file> will be ignored
                  by <prgn>update-updmap</prgn><footnote>An
                  <prgn>update-updmap</prgn> call could take place if another
                  package such as <package>texlive-*</package> is configured
                  in the meantime. That happens sometimes with APT.</footnote>
                  because it may be outdated. Eventually, <var>package</var>
                  is configured; <file><var>package</var>.postinst</file> runs
                  <prgn>update-updmap</prgn>, <prgn>mktexlsr</prgn> and
                  <prgn>updmap-sys</prgn>, and the <file>.cfg</file> files
                  shipped by <var>package</var> aren't ignored by
                  <prgn>update-updmap</prgn> this time, since they are
                  referenced in
                  <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
                  and the <file>.dpkg-new</file> files don't exist anymore.
                  Thus, the map files shipped by <var>package</var> do end up
                  in the final map files generated by <prgn>updmap-sys</prgn>.
                  </item> </list>
            </p>
          </list>
	  </sect2>
	</sect1>

	<sect1>
	  <heading>Language/Hyphenation configuration</heading>
	  <p>
	  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 <prgn>debhelper</prgn> program <prgn>dh_installtex</prgn>
	  provided by <package>tex-common</package>. See 
	  <manref name="dh_installtex" section="1"> for usage
	  details.  Note that for <file>language.dat</file>, order is
	  important: english should always be the first language.
	  </p>
	  <p>
	  These packages 
	  should put the actual hyphenation file into the respective
	  places in <var>TEXMFMAIN</var>, and have them registered by
	  putting a configuration file with extension <tt>.cnf</tt> into
	  <file>/etc/texmf/language.d</file> and calling
	  <tt>update-language</tt>. The file contents will then be
	  incorporated into
	  <file>/var/lib/texmf/tex/generic/config/language.dat</file>,
	  the effective configuration file for TeX and friends'
	  hyphenations.
	  </p>
	  <p>
	  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
	  <file>/etc/texmf/language.d/</file>, and the format
	  generation would fail if they would be included in
	  <file>language.dat</file>.  Therefore, an analogous
	  mechanism has been implemented as described for
	  <prgn>update-updmap</prgn>: If a file in
	  <file>/etc/texmf/language.d/</file> contains the "magic
	  comment"
<example>
# -_- DebPkgProvidedMaps -_-
</example>
          it will only be used as long it is:
          <list>
            <item>
              up-to-date (which is assumed if the same file with
              <file>.dpkg-new</file> suffix doesn't exist in the same
              directory);
            </item>
            <item>
              listed in a file in
              <file>/var/lib/tex-common/language-cnf/</file> which should have
              the name <file><var>package</var>.list</file>.
            </item>
          </list>
	  </p>

	  <p>
	  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
	  <tt>fmtutil-sys --byhyphen `kpsewhich --progname=latex
	  language.dat`</tt>.
	  </p>

	  <p>
	  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 <prgn>update-language</prgn> and
	  <tt>fmtutil-sys --byhyphen `kpsewhich --progname=latex
	  language.dat`</tt> in <file>postrm</file>
	  </p>

	  <p>
	  There is currently no mechanism (i.e., no
	  <prgn>update-language</prgn>) for automatic addition of
	  hyphenation patterns to formats that do not use the same
	  hyphenation configuration file as LaTeX.
	  </p>

	  <p>
	  The recommended way for implementing this scheme is to use
	  <prgn>dh_installtex</prgn>.
	  </p>

	</sect1>
	
	<sect1>
	  <heading>Format configuration</heading>

	  <p>
	  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 <prgn>debhelper</prgn> program <prgn>dh_installtex</prgn>
	  provided by <package>tex-common</package>. See
	  <manref name="dh_installtex" section="1"> for usage
	  details.  Note that for <file>fmtutil.cnf</file>, order is
	  important:  Formats will be created for each line, and thus
	  format files created from later lines will overwrite earlier
	  ones. 
	  </p>

	  <p>
	  These packages should put a
	  configuration file according to <prgn>fmtutil.cnf(5)</prgn>
	  into <file>/etc/texmf/fmt.d/</file>, run
	  <prgn>update-fmtutil</prgn> and subsequently create the
	  format with <tt>fmtutil-sys --byfmt <var>format</var></tt>.
	  <prgn>fmtutil-sys</prgn> will only try to create the format
	  if it can find the corresponding
	  <file><var>format</var>.ini</file> file (the last argument
	  in an <prgn>fmtutil.cnf</prgn> line).  Therefore the
	  <file><var>format</var>.ini</file> file should not be a
	  conffile.
	  </p>

	  <p>
	  If a package needs to create formats at runtime, it should
	  use a local <prgn>fmtutil.cnf</prgn> with the appropriate
	  entries and specifiy its location to <prgn>fmtutil</prgn> on
	  the command line, using the <tt>--cnffile</tt> switch.
	  </p>

	  <p>
	  Upon package removal, <prgn>update-fmtutil</prgn> must be
	  called in postrm, and the created formats and log files
	  should be removed from the directory specified by
	  <tt>`kpsewhich -var-value=TEXMFSYSVAR`/web2c</tt>.
	  </p>

	  <p>
	  The recommended way for implementing this scheme is to use
	  <prgn>dh_installtex</prgn>.
	  </p>

	</sect1>
      </sect>

      <sect>
	<heading>Best practices for packages that
	<tt>build-depend</tt> on the TeX system</heading>
	<sect1><heading>Configuration</heading>
	  <p>
	    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 <tt>--outputdir</tt>
	    and <tt>--add-file</tt> options.
	  </p>
	</sect1>
	<sect1><heading>Font cache data</heading>
	  <p>
	    Font cache data are created each time a font in Metafont
	    format is used, and placed by default
	    in <var>TEXMFVAR</var>.  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 <var>TEXMFVAR</var> to a subdirectory of the
	    current directory,
	    e.g. <file><var>$(CURDIR)</var>/.texmf-var</file>, using
	    Make's built-in variable.  Packages which do not
	    change <var>TEXMFVAR</var> <em>must</em> not create
	    documentation that uses Metafont fonts in
	    the <tt>binary</tt> target.
	  </p>
	</sect1>
      </sect>
      <sect>
        <heading>Command execution and format files</heading>
	<p>
	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
	<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 the
	depending package that does this check.  Maintainer scripts or
	programs in Debian packages should always use
	<prgn>fmtutil</prgn> or <prgn>fmtutil-sys</prgn> for format
	generation, and either add a <file>fmtutil.cnf</file> snippet
	in <file>/etc/texmf/fmt.d/</file> (with
	<prgn>fmtutil-sys</prgn>, for site-wide formats), or use
	<prgn>fmtutil</prgn> with the <tt>--cnffile</tt> option and an
	appropriate local <file>fmtutil.cnf</file> (for runtime
	programs) 
	</p>
	<p>
	Local administrators can override settings from
	<file>texmf.cnf</file> with environment variables; this has
	sometimes lead to errors in <file>postinst</file> scripts.  It
	is recommended that <file>postinst</file> scripts unset
	relevant variables before format creation or other problematic
	tasks. 
	</p>
	<p>
	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
<footnote>
The reason is that, in order to avoid other problems,
<prgn>update-fmtutil</prgn> ignores files in 
<file>/etc/texmf/fmt.d</file> that have a corresponding
<file>.dpkg-new</file> file, and that it is necessary to recreate all
formats when pool files or engines are updated.  Thus, some Basic TeX
packages call <tt>fmtutil --all</tt> in their postinst scripts.  When
Basic TeX packages are upgraded together while a package that
loads <file>latex.fmt</file> is installed and configured, then one of
the Basic TeX packages' postinst will call <prgn>update-fmtutil</prgn>
and <tt>fmtutil --all</tt> while others are is still unconfigured and
have <file>.dpkg-new</file> 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. <file>latex.fmt</file> are available, the
depending format can <tt>\input</tt> <file>latex.ini</file> and create
its own format without problems.
</footnote>.
Instead the <file>fmtutil.cnf</file>
	snippet and the <file><var>format</var>.ini</file> file must
	be changed so that the process of format creation is repeated.
	For example, if upstream creates their format by loading
	latex:
<example>
latex           pdfetex         language.dat    -translate-file=cp227.tcx *latex.ini
jadetex         etex            language.dat    &amp;latex jadetex.ini
</example>
and the following <file>jadetex.ini</file> file:
<example>
\input jadetex.ltx
\dump
</example>
        then the Debian package maintainer must
        load <file>latex.ini</file> instead of <file>latex.fmt</file>,
        making sure that <tt>\dump</tt> in <file>latex.ltx</file> has
        no effect, and create the following
        new <file>jadetex.ini</file>:
<example>
\let\savedump\dump
\let\dump\relax
\input latex.ini
\let\dump\savedump

\input jadetex.ltx
\dump
</example>
        and the following snippet for <file>fmtutil.cnf</file>:
<example>
jadetex         etex    language.dat    -translate-file=cp227.tcx *jadetex.ini
</example>
	</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 -->
<!-- 	<var>TEXMF</var> 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>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.</p>

      </sect>
    </chapt>
    <appendix>
      <heading>Sample code</heading>
      <p>
      This section contains sample code that implements the
      recommodations of this document.
      </p>
      <sect id="appen-sample-font">
        <heading>Sample code for font packages</heading>
        <p>
        Sample postinst script:
<example>
#
# postinst-texfonts
#
# postinst snippet for installing Type 1 fonts for TeX
#
# Author: Florent Rougon &lt;f.rougon@free.fr&gt;
#
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
</example>
        </p>
        <p>
        Sample postrm script:
<example>
#
# postrm-texfonts
#
# postrm snippet for installing Type 1 fonts for TeX
#
# Author: Florent Rougon &lt;f.rougon@free.fr&gt;
#
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 texlive-binaries 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 texlive-binaries 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
</example>
        </p>
      </sect>
    </appendix>
  </book>
</debiandoc>

