<!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>2015-09-03 (incomplete)</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-2015 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>
	Note that the previous location <file>/usr/share/doc/texmf</file>
	is obsolete and should not be used. Files installed there
	will not be found by <prgn>texdoc</prgn>.
	</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),
	<file>TEXMFTREE/web2c/updmap.cfg</file> (font configuration), and
	<file>TEXMFTREE/web2c/fmtutil.cnf</file> (for format definitions).
	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), and
	<file>TEXMFTREE/tex/generic/config/language.dat.lua</file> (the
	same for luatex based formats).
	</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 <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>
	  All package configuration related to TeX files can be done
	  using <package>tex-common</package>'s trigger
	  mechanism. That means that packages that
	  changed <file>updmap.cfg</file>
	  (via <prgn>update-updmap</prgn>) must either
	  call <prgn>update-texmf-config map</prgn> which will pass
	  the configuration work to <package>tex-common</package>, or
	  call <prgn>updmap-sys</prgn>.
	</p>

	<p>
	  In a similar way, packages that changed <file>language.dat</file>
	  or <file>fmtutil.cnf</file> must either
	  call <prgn>update-texmf-config hyphen</prgn>
	  (for <file>language.dat</file>) or
	  <prgn>update-texmf-config format</prgn>
	  (for <file>fmtutil.cnf</file>), which will pass
	  the configuration work to <package>tex-common</package>,
	  or call <prgn>fmtutil-sys</prgn> (see below). 
	</p>


	<p>
	  The recommended way to implement the configuration scheme
	  necessary 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>
      </sect>
  </book>
</debiandoc>

