/usr/share/doc/tex-common/Debian-TeX-Policy.html/ch5.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">

<html>

<head>

<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">

<title>The Debian TeX sub-policy - File Placement</title>

<link href="index.html" rel="start">
<link href="ch4.html" rel="prev">
<link href="ch6.html" rel="next">
<link href="index.html#contents" rel="contents">
<link href="index.html#copyright" rel="copyright">
<link href="ch1.html" rel="chapter" title="1 About this document">
<link href="ch2.html" rel="chapter" title="2 Terms and Definitions">
<link href="ch3.html" rel="chapter" title="3 TeX packages for the impatient">
<link href="ch4.html" rel="chapter" title="4 Meta-packages and dependencies">
<link href="ch5.html" rel="chapter" title="5 File Placement">
<link href="ch6.html" rel="chapter" title="6 Configuration">
<link href="apA.html" rel="appendix" title="A Sample code">
<link href="ch5.html#s-tds-libkpse" rel="section" title="5.1 File searching and libkpathsea / libkpse">
<link href="ch5.html#s5.2" rel="section" title="5.2 Directory trees">
<link href="ch5.html#s5.3" rel="section" title="5.3 Generated files">
<link href="ch5.html#s-sec-names-and-texmfsite" rel="section" title="5.4 Filenames and installation of alternative files">
<link href="ch5.html#s-sec-documentation" rel="section" title="5.5 Documentation">
<link href="ch6.html#s-configurationfiles" rel="section" title="6.1 Configuration files">
<link href="ch6.html#s-update-progs" rel="section" title="6.2 Configuration update programs">
<link href="ch6.html#s6.3" rel="section" title="6.3 Best practices for packages that build-depend on the TeX system">
<link href="ch6.html#s6.4" rel="section" title="6.4 Command execution and format files">
<link href="ch6.html#s6.5" rel="section" title="6.5 The Dpkg Post-Invoke Mechanism">
<link href="apA.html#s-appen-sample-font" rel="section" title="A.1 Sample code for font packages">
<link href="ch6.html#s-sec-font-configuration" rel="subsection" title="6.2.1 Font configuration">
<link href="ch6.html#s-font-configuration-details" rel="subsection" title="6.2.1.1 Description of manual font package setup">
<link href="ch6.html#s-font-configuration-rationale" rel="subsection" title="6.2.1.2 Rationale">
<link href="ch6.html#s6.2.2" rel="subsection" title="6.2.2 Language/Hyphenation configuration">
<link href="ch6.html#s6.2.3" rel="subsection" title="6.2.3 Format configuration">
<link href="ch6.html#s6.3.1" rel="subsection" title="6.3.1 Configuration">
<link href="ch6.html#s6.3.2" rel="subsection" title="6.3.2 Font cache data">

</head>

<body>

<p><a name="ch5"></a></p>
<hr>

<p>
[ <a href="ch4.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch1.html">1</a> ]
[ <a href="ch2.html">2</a> ]
[ <a href="ch3.html">3</a> ]
[ <a href="ch4.html">4</a> ]
[ 5 ]
[ <a href="ch6.html">6</a> ]
[ <a href="apA.html">A</a> ]
[ <a href="ch6.html">next</a> ]
</p>

<hr>

<h1>
The Debian TeX sub-policy
<br>Chapter 5 - File Placement
</h1>

<hr>

<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
<code>/usr/share/<var>package</var></code> 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>

<hr>

<h2 id="s-tds-libkpse">5.1 File searching and <code>libkpathsea</code> / <code>libkpse</code></h2>

<p>
File locations must follow the TeX Directory Structure, TDS.  The TDS
specification is available as <code><a
href="file:///usr/share/doc/tex-common/tds.pdf">tds.pdf</a></code> and <code><a
href="file:///usr/share/doc/tex-common/tds.html">tds.html</a></code>, and the
latest version of the TDS is available at <samp><code><a
href="http://www.tug.org/twg/tds/">http://www.tug.org/twg/tds/</a></code></samp>.
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 <code>tex-common</code> (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 <code>libkpathsea</code> library.  Unfortunately, it was
not originally designed for use as a dynamic shared library.  A rewrite is
under way to create a <code>libkpse</code> 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
<code>kpsewhich</code>, <code>kpsepath</code>, <code>kpsexpand</code>, and
<code>kpsestat</code>.
</p>

<hr>

<h2 id="s5.2">5.2 Directory trees</h2>

<p>
The following <var>TEXMF</var> trees are defined, as outlined below:
</p>
<ol type="1" start="1" >
<li>
<p>
<code>/usr/share/texlive/texmf-dist/</code>, referenced as <var>TEXMFDIST</var>
</p>
</li>
</ol>
<ol type="1" start="2" >
<li>
<p>
<code>/usr/local/share/texmf/</code>, referenced as <var>TEXMFLOCAL</var>
</p>
</li>
</ol>
<ol type="1" start="3" >
<li>
<p>
<code>/usr/share/texlive/texmf/</code>, referenced as <var>TEXMFMAIN</var>
</p>
</li>
</ol>
<ol type="1" start="4" >
<li>
<p>
<code>/usr/share/texmf/</code>, referenced as <var>TEXMFDEBIAN</var>
</p>
</li>
</ol>
<ol type="1" start="5" >
<li>
<p>
<code>/var/lib/texmf/</code>, referenced as <var>TEXMFSYSVAR</var>
</p>
</li>
</ol>
<ol type="1" start="6" >
<li>
<p>
<code>/etc/texmf/</code>, referenced as <var>TEXMFSYSCONFIG</var>
</p>
</li>
</ol>
<ol type="1" start="7" >
<li>
<p>
Any directories listed in the <var>TEXMFHOME</var> configuration variable in
<code>texmf.cnf</code> or as an environment variable,
</p>
</li>
</ol>
<ol type="1" start="8" >
<li>
<p>
optionally user-specific directories for configuration files
(<var>TEXMFCONFIG)</var> and generated files (<var>TEXMFVAR</var>)
</p>
</li>
</ol>

<p>
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 <a href="ch6.html#s-configurationfiles">Configuration files, Section
6.1</a>.  Packages should take care to ignore <var>TEXMFHOME</var> in their
maintainer scripts.
</p>

<hr>

<h2 id="s5.3">5.3 Generated files</h2>

<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[<a href="footnotes.html#f2" name="fr2">2</a>]
</p>

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

<hr>

<h2 id="s-sec-names-and-texmfsite">5.4 Filenames and installation of alternative files</h2>

<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
<samp>--progname</samp> or <samp>--format</samp> switches to kpsewhich.
</p>

<p>
There are two exception to this rule:
</p>
<ol type="1" start="1" >
<li>
<p>
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.
</p>
</li>
</ol>
<ol type="1" start="2" >
<li>
<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 [<a
href="footnotes.html#f3" name="fr3">3</a>] 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 <code>dpkg-divert</code> is discouraged.
</p>
</li>
</ol>

<p>
It is also discouraged to use a file other than from the canonical source for
that file, usually the CTAN network.
</p>

<hr>

<h2 id="s-sec-documentation">5.5 Documentation</h2>

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

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

<p>
The entry points for documentation should have names that indicate what they
document.  Names like <code>manual.pdf</code> or <code>index.html</code> should
be avoided, even if the directory name is unmistakable [<a
href="footnotes.html#f4" name="fr4">4</a>].
</p>

<hr>

<p>
[ <a href="ch4.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch1.html">1</a> ]
[ <a href="ch2.html">2</a> ]
[ <a href="ch3.html">3</a> ]
[ <a href="ch4.html">4</a> ]
[ 5 ]
[ <a href="ch6.html">6</a> ]
[ <a href="apA.html">A</a> ]
[ <a href="ch6.html">next</a> ]
</p>

<hr>

<p>
The Debian TeX sub-policy
</p>

<address>
generated from $Id$<br>
<br>
The Debian TeX mailing list <code><a href="mailto:debian-tex-maint@lists.debian.org">mailto:debian-tex-maint@lists.debian.org</a></code><br>
<br>
</address>
<hr>

</body>

</html>
tex-common 4.04 / usr / share / doc / tex-common / Debian-TeX-Policy.html / ch5.html
