<!doctype debiandoc system>
<debiandoc>

  <book>
    <titlepag>
      <title>Debian-specific information about TeX packages</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 covers Debian-specific information for <em>users</em> of
       the Debian TeX Live packages (all
       packages named <package>texlive-something</package>). 
       Further information, especially for
       <em>developers</em>, can be found in the Debian TeX Policy draft in
       <file>/usr/share/doc/tex-common/</file>.
      </abstract>

      <copyright>
        <copyrightsummary>
          Copyright &copy; 2004-2012 Frank Küster, Florent Rougon,
        Norbert Preining
        </copyrightsummary>
        <p>
          This document 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 document 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>
    <chapt>
      <heading>Overview of the packages</heading>

      <p>
        The Debian TeX Live packages are comprised of (currently) 80 packages
        in total. The most important are:
        <taglist>
          <tag><package>texlive-binaries</package></tag>
          <item>
            provides the basic binaries and scripts, but is practically
	    useless by itself
          </item>

          <tag><package>texlive-base</package></tag>
          <item>
	    provides a minimal system
          </item>

          <tag><package>texlive-latex-base</package></tag>
          <item>
            provides the most basic LaTeX input files, and will be
            sufficient for some simple documents
          </item>

          <tag><package>texlive-latex-recommended</package></tag>
          <item>
	    a recommended set of LaTeX packages which are sufficient
            for most typesetting purposes if you don't have any
            special requirements
          </item>

          <tag><package>texlive-fonts-recommended</package></tag>
          <item>
	    a recommended set of fonts which are sufficient
            for most typesetting purposes if you don't have any
            special requirements
          </item>

	  <tag><package>texlive</package></tag>
          <item>
	    a meta-package depending on a decent selection of
            packages, comprising all of the above
          </item>

	  <tag><package>texlive-full</package></tag>
          <item>
	    a meta-package depending on all packages from the TeX Live
	    group and on some other packages to create something
            similar to a full TeX Live installation
          </item>

	  <tag><package>texlive-doc-*</package></tag>
          <item>
	    packages like <package>texlive-doc-en</package> and
            <package>texlive-doc-de</package> provide documentation in
            the respective language
          </item>

	  <tag><package>texlive-lang-*</package></tag>
          <item>
	    packages like <package>texlive-lang-dutch</package> and
            <package>texlive-lang-spanish</package> provide
            language-specific support, like hyphenation patterns
          </item>
	</taglist>
        There are many more packages, providing extra functionality
        and extra fonts. Please see the respective descriptions of
        these packages.
      </p>
    </chapt>

    <chapt>
      <heading>Changing your configuration, file placement</heading>

      <sect id="sec-texmf-trees">
        <heading>
          Available <var>TEXMF</var> trees for users and system administrators
        </heading>
        <p>
          The following <var>TEXMF</var> trees are available.  They
          are displayed below in the order they are searched, where
          earlier ones override later ones.
          <taglist>
            <tag><var>TEXMFCONFIG</var></tag>
            <item>
              <p>
                Default location: <file>$HOME/.texmf-config/</file>
              </p>
              <p>
                Contains user-specific configuration
              </p>
            </item>

            <tag><var>TEXMFVAR</var></tag>
            <item>
              <p>
                Default location: <file>$HOME/.texmf-var/</file>
              </p>
              <p>
                Contains user-specific generated files
              </p>
            </item>

            <tag><var>TEXMFHOME</var></tag>
            <item>
              <p>
                Default location: <file>$HOME/texmf/</file>
              </p>
              <p>
                Contains user-specific static input files, e.g. new
                LaTeX packages.
              </p>
            </item>

            <tag><var>TEXMFSYSCONFIG</var></tag>
            <item>
              <p>
                Default location: <file>/etc/texmf</file>
              </p>
              <p>
                Contains system-wide configuration 
              </p>
            </item>

            <tag><var>TEXMFSYSVAR</var></tag>
            <item>
              <p>
                Default location: <file>/var/lib/texmf/</file>
              </p>
              <p>
                Contains system-wide generated files
              </p>
            </item>

            <tag><var>TEXMFDEBIAN</var></tag>
            <item>
              <p>
                Default location: <file>/usr/share/texmf/</file>
              </p>
              <p>
	        Contains files shipped by Debian packages other than
		the main texlive packages.
		This tree contains system-wide, <prgn>dpkg</prgn>-managed 
		input files.
              </p>
            </item>

            <tag><var>TEXMFMAIN</var></tag>
            <item>
              <p>
                Default location: <file>/usr/share/texlive/texmf/</file>
              </p>
              <p>
	        Contains files that are closely related to the binaries
		and the specific version, thus this tree has higher
		priority then <var>TEXMFLOCAL</var> below. It contains
		only few system-wide, <prgn>dpkg</prgn>-managed input files.
              </p>
            </item>

            <tag><var>TEXMFLOCAL</var></tag>
            <item>
              <p>
                Default location: <file>/usr/local/share/texmf/</file>
              </p>
              <p>
                Contains system-wide input files, used for configuration
		on specific systems.
              </p>
            </item>

            <tag><var>TEXMFDIST</var></tag>
            <item>
              <p>
                Default location: <file>/usr/share/texlive/texmf-dist</file>
              </p>
              <p>
	        Contains the binary-independent files that are distributed
		with TeX Live, comprising most of the input files, font
		files etc. 
              </p>
            </item>
          </taglist>
        </p> 

        <p>
          If you want to add files, you should usually use
          <var>TEXMFLOCAL</var> or <var>TEXMFHOME</var>, depending on whether
          you are the system administrator or a user. If needed, a system
          administrator can add additional trees to the <var>TEXMF</var>
          variable by copying the definition of <var>TEXMF</var> from
	  <file>/usr/share/texmf/web2c/texmf.cnf</file> into one file
	  in <file>/etc/texmf/texmf.d/</file>, for example
	  <file>/etc/texmf/texmf.d/00local.cnf</file> (earlier
          entries take precedence). <var>TEXMFCONFIG</var> and
          <var>TEXMFVAR</var> are used by the user-specific
          <prgn>texconfig</prgn>, <prgn>updmap</prgn>, and
          <prgn>fmtutil</prgn> commands. Note
	  that <prgn>texconfig</prgn> creates a copy of configuration
	  files from <var>TEXMFMAIN</var> (or <file>/etc/texmf</file>)
	  at the time it is first invoked to handle a particular file,
	  and does not track later system-wide changes, and it does
	  not know about <prgn>update-*</prgn> programs (see
	  below <ref id="sec-core-config-files">).
        </p>
      </sect>

      <sect>
        <heading>General hints</heading>

        <sect1>
          <heading>System-wide versus user-specific configuration</heading>
          <p>
            TeX Live supports a
            complete user-specific configuration setup in the user's
            home directory. System administrators must use the
            commands <prgn>texconfig-sys</prgn>,
            <prgn>fmtutil-sys</prgn> and <prgn>updmap-sys</prgn> which act on
            the system-wide configuration files. Users can invoke their user
            counterparts <prgn>texconfig</prgn>, <prgn>fmtutil</prgn> and
            <prgn>updmap</prgn>. This will put copies of the system-wide
            configuration files into the user's <var>TEXMFCONFIG</var> directory
            (by default, <file>$HOME/.texmf-config</file>), modify them and
            generate according formats, if applicable.
          </p>
	  <p>
	    There is no such mechanism for <file>texmf.cnf</file>.
	    For a way to customize <file>texmf.cnf</file> as a user,
	    see <ref id="sec-user-config-files">.
	  </p>

        <sect1>
          <heading>Configuration file placement</heading>
          <p>
            On a TeX system, in principle every TeX input file can be used to
            <em>change the behavior of the system</em> and hence could
            be treated as a configuration file. To avoid an inflation
            of configuration files, those that are used to control the
            typeset output - the appearance of documents - are not
            installed as configuration files.  It makes more sense to
            keep changed versions in the current directory for a
            certain project, or in <var>TEXMFHOME</var>
            or <var>TEXMFCONFIG</var> of a particular user.  However,
            local admins can take any file they want from
            the <var>TEXMFDIST</var>
            (<file>/usr/share/texlive/texmf-dist</file>)
            or <var>TEXMFDEBIAN</var> (<file>/usr/share/texmf</file>)
            trees and put changed copies into the respective
            directories below <file>/etc/texmf</file>
            (<var>TEXMFSYSCONFIG</var> which sorts before all other
            trees) or <file>/usr/local/share/texmf</file> 
	    (<var>TEXMFLOCAL</var> which sorts before the above two trees).
          </p>

          <p>
            Since the package management system does not know whether a file
            is treated as a configuration file on a specific system, it is up
            to the site admin or local user to check whether one of their
            changed files has changed in <var>TEXMFDIST</var> or
            <var>TEXMFDEBIAN</var>.
          </p>

         <sect1>
          <heading>What is configured where?</heading>
          <p>
            The central system-wide configuration files <file>texmf.cnf</file>
            (which controls the basic operation and file search paths for the
            included programs), <file>fmtutil.cnf</file> (which specifies the
            available TeX formats), (several) <file>updmap.cfg</file> (font
            configuration) and <file>language.dat</file>, 
	    <file>language.def</file>, <file>language.dat.lua</file>
	    (hyphenation patterns for latex, etex, lualatex, resp.)
	    are handled through a Debian-specific mechanism
            that allows the basic TeX packages, add-on packages and local
            administrators to combine their changes
            (see <ref id="sec-core-config-files"> below).
          </p>

      <sect>
        <heading>Hyphenation</heading>
        <p>
          Hyphenation should pretty much work out of the box.
          Please note that
          in Debian, language.dat, language.def, language.dat.lua are 
	  generated files (see <ref id="sec-core-config-files">).
        </p>

      <sect id="sec-core-config-files">
        <heading>
          The files <file>texmf.cnf</file>, <file>fmtutil.cnf</file>,
          <file>updmap.cfg</file> and <file>language.*</file> group
        </heading>
	<p>
	In the following we will refer to the three files
	<file>language.dat</file>, <file>language.def</file>, 
	<file>language.dat.lua</file>, as <file>language.*</file>.
	</p>

	<p>
	  In the following we describe ways to configure these files
	  for the <em>system administrator</em>, i.e. one that has
	  write access to the <file>/etc/texmf</file> hierachy. In
	  <ref id="sec-user-config-files"> we describe a per-user
	  configuration.
        <p>
          The files <file>texmf.cnf</file>, <file>fmtutil.cnf</file>,
          <file>updmap.cfg</file> and <file>language.dat</file>
          contain configuration options from TeX Live,
          possibly from you, and from other TeX-related packages. They
          are generated by scripts and may not be edited
          directly. Rather, you should work with the source files in the
          respective directories below <file>/etc/texmf/</file>.
        </p>

        <p>
          In order to make updates smooth, you should <em>avoid
          editing</em> system-wide files as far as possible, and
          instead <em>add new files</em> to change
          settings. For <file>texmf.cnf</file> snippets, this is
          particularly easy, since earlier entries override any later
          entries.  Only for removing settings
          from <file>fmtutil.cnf</file>, or <file>language.*</file>
	  it is necessary to edit existing files.
        </p>
	
         <sect1 id="sec-texmfcnf-and-update-texmf">
          <heading>
            <file>texmf.cnf</file> and <prgn>update-texmf</prgn>
          </heading>
          <p>
            The TeX binaries are built to look for and merge
	    <file>texmf.cnf</file> files in various trees. That means
	    that it is easy to override the default settings as shipped
	    in 
	    <file>/usr/share/texmf/web2c/texmf.cnf</file> by adding
	    entries in <file>/etc/texmf/web2c/texmf.cnf</file>.
            The Debian packaging includes a
            mechanism for constructing texmf.cnf from a collection of files
            under <file>/etc/texmf/texmf.d/</file>. To customize
            <file>texmf.cnf</file> while retaining the Debian-supplied
            configuration, create an appropriate file (or files) in
            <file>/etc/texmf/texmf.d/</file>, or change existing
            files, and then run <prgn>update-texmf</prgn>. This will
            generate the desired <file>texmf.cnf</file> for you.
	    By default nothing is shipped in <file>/etc/texmf/texmf.d/</file>
	    since no adaptions are necessary, but further addon packages
	    might ship parts.
          </p>

          <p>
            You may not edit the file <file>/etc/texmf/web2c/texmf.cnf</file>
	    directly, any local changes will be overwritten the next
	    time this file is generated.
          </p>

          <p>
            Instead, please edit the files in
            <file>/etc/texmf/texmf.d</file>, or create an additional one, and
            invoke <prgn>update-texmf</prgn>. This will write your changes
            into <file>/etc/texmf/web2c/texmf.cnf</file>.
          </p>

          <p>
            You should name your customization file something like
            <file>40macros.cnf</file>; the leading numerals will decide the
            order in which configuration fragments will be assembled by
            <prgn>update-texmf</prgn>, so it might be important to place your
            customizations in an appropriate place in the sequence &mdash;
            earlier definitions take precedence over later ones. In previous
            versions the extension <tt>.cnf</tt> was not necessary, and all
            files in the directory were used. If you had teTeX installed in
            woody, you might still have private files which need the extension
            to be added.
          </p>

         <sect1>
          <heading>
            <file>fmtutil.cnf</file> and <prgn>update-fmtutil</prgn>,
            <file>language.*</file> and <prgn>update-language</prgn>
          </heading>
          <p>
            These files are also generated files, just as it has been
            explained above for <file>texmf.cnf</file>. The difference to
            <file>texmf.cnf</file> is that the system-wide files will
            be put into <file>/var/lib/texmf/web2c</file>, and any
            change made in these files will be <strong>unconditionally
            overwritten</strong>
            by <prgn>update-fmtutil</prgn> and <prgn>update-language</prgn>,
            respectively.  Only the files in <file>/etc/texmf/fmt.d/</file>
	    and <file>/etc/texmf/hyphen.d/</file> will be treated as
	    configuration files.  Furthermore, the files 
	    <file>fmtutil.cnf</file> and <file>language.*</file> are
	    used on a first-found-first-used basis, if there are more
	    than one in the search path, whereas if there are
	    several <file>texmf.cnf</file> files in the search path,
	    their settings are combined as described
	    in <ref id="sec-user-config-files">.
          </p>

          <p>
            Just as for <file>texmf.cnf</file>, the right way to change
            settings is to edit or add files in
            <file>/etc/texmf/fmt.d/</file> 
	    or <file>/etc/texmf/language.d/</file>. The details have been
            described above (see <ref id="sec-texmfcnf-and-update-texmf">).
          </p>

         <sect1>
          <heading>
            <file>updmap.cfg</file>
          </heading>
	  <p>
	    <prgn>updmap-sys(8)</prgn> reads <em>all</em> available
	    <file>updmap.cfg</file> files found, stacking them
	    on top of each other. That means that local configurations
	    can be done by editing/adding a file in 
	    <file>/etc/texmf/web2c/updmap.cfg</file>.
	  </p>

	  <p>
	    <prgn>updmap-sys(8)</prgn> provides options for enabling
	    or disabling font map files.  When enabling a new map file
	    that is not mentioned, <prgn>updmap-sys</prgn> will
	    create or edit <file>/etc/texmf/web2c/updmap.cfg</file>. Note
	    that <prgn>updmap-sys</prgn>'s <tt>--edit</tt>
	    and <tt>--syncwithtrees</tt> options cannot be used on a
	    Debian system.
	  </p>

	  <p>
	    For more details on how to disable map files that are
	    enabled on a higher level, please see the man page
	    and help output of <prgn>updmap</prgn>.
	  </p>
	
         <sect1 id="sec-user-config-files">
          <heading>
	    Per user configuration changes
          </heading>
          <p>
	    <prgn>update-texmf</prgn> is only available for root; if a
	    user wants to maintain their own <file>texmf.cnf</file>,
	    they can put it into <tt><var>TEXMFCONFIG</var>/web2c</tt>
	    and must manually edit it.  However, in order for it to be
	    found, they need to set an environment variable
	    <footnote>
	      The reason for this is that the search
	      path for <file>texmf.cnf</file>, which is the file that
	      defines all search paths for later use, naturally cannot
	      be specified in the file, but is fixed at compile
	      time.
	    </footnote>:
<example>
export TEXMFCNF=$HOME/.texmf-config/web2c:
</example>
            The final colon includes the system wide default.  Since
	    all <file>texmf.cnf</file> files are read, with earlier
	    definitions taking precedence over later ones, it is best
	    to keep only a minimal set of definitions in the
	    user-specific file.
	  </p>

	  <p>
	    In contrast to the above&mdash;TeX reading and merging all
	    <file>texmf.cnf</file> files&mdash;the <em>first</em> found 
	    occurrence of one of the files <file>language.dat</file>,
	    <file>fmtutil.cnf</file> is used. Thus, when called by a
	    user, the other configuration update programs also work
	    with files in
	    <tt><var>TEXMFCONFIG</var>/fmt.d</tt> or
	    <tt><var>TEXMFCONFIG</var>/language.d</tt>, where
	    <var>TEXMFCONFIG</var> is usually 
	    <file><var>HOME</var>/.texmf-config</file>.  They combine
	    files in these directories with the files in the system-wide
	    directories&mdash;naturally the user-specific ones take
	    precedence if the names are equal
	    (see <ref id="sec-user-specific-installation">) &mdash;and
	    drop the respective generated file into the user's 
	    <var>TEXMFVAR</var>, effectively overriding the
	    system-wide config files. Note that changes to existing
	    configuration file snippets made by package updates will
	    not be propagated to the user's files.
	  </p>
	  <p>
	    <prgn>updmap(1)</prgn> provides the same options for
	    enabling and disabling map files
	    as <prgn>updmap-sys(8)</prgn>, see
	    above.  <file>updmap.cfg</file> is created or edited
	    in <tt><var>TEXMFCONFIG</var>/web2c/</tt>.
	  </p>

      <sect>
	<heading>Font caching</heading>
	<p>
	  A TeX system needs to generate new font data (pixel data, metric,
	  sources) on the fly. These files can be saved into the TeX font
	  cache and later be reused. By default, a separate font cache is
	  created for each user in their own <var>TEXMFVAR</var> directory
	  (<file>$<var>HOME</var>/.texmf-var/</file>). If this directory is
	  not writable, e.g. during automated package building, a directory
	  called <var>VARTEXFONTS</var>, <file>/tmp/texfonts/</file>, is used
	  instead, but this directory is cleaned up regularly.
	</p>
	<p>
	  On multi-user machines, it might be advisable that the local
	  administrator enables a site-wide font cache and sets
	  <var>VARTEXFONTS</var> to a persistent directory, e.g.
	  <file>/var/cache/fonts</file>.  The variable can be changed
	  by adding an entry via <file>/etc/texmf/texmf.d</file>, e.g.
	  <file>/etc/texmf/texmf.d/00local.cnf</file>. Do not forget to
	  run <prgn>update-texmf</prgn> after making the change. To enable a
	  side-wide font caching the admin should edit
	  <file>/etc/texmf/web2c/mktex.cnf</file> and use 'varfonts' instead
	  of 'texmfvar' in <var>MT_FEATURES</var>. Care should be taken to
	  specifiy appropriate permissions for the directory containing the
	  font cache. Either the local admin should create all available font
	  data and not allow write access, or else write access should be
	  limited to trusted users. Yet an other alternative is to bind-mount
	  <file>/var/cache/fonts</file> from a separate partition, so that
	  users are not able to fill up the <file>/var</file> partition with
	  font data.
	</p>
      </sect>

    </chapt>

    <chapt>
      <heading>Usage hints, Debian-specific adaptations</heading>

      <sect>
        <heading>Note on <prgn>dvips</prgn></heading>

        <p>
          Per default, <prgn>dvips</prgn> is in secure mode and won't execute
          shell commands in <tt>\special</tt> commands, like backticks in
          <tt>\DeclareGraphicsRule</tt>, etc. To enable this, change
          <tt>z1</tt> to <tt>z0</tt> in
          <file>/etc/texmf/dvips/config.ps</file> (second entry).
        </p>
      </sect>

      <sect>
        <heading>Note on <prgn>dvipdfmx</prgn></heading>

	<p>
	  The Debian TeX Live packages do evaluate the
          settings of <file>/etc/papersize</file>, please configure
	  your preferred paper size with <prgn>paperconfig</prgn>.
	  Alternatively, and more portable, thus recommended, set the
          paper geometry explicitly in the (La)TeX source, e.g. using
          the packages <tt>geometry</tt> or <tt>hyperref</tt>.
	</p>
      </sect>

      <sect>
        <heading>
          &ldquo;TeX capacity exceeded&rdquo; and similar errors
        </heading>

        <p>
          In most cases, this error is the symptom of a syntax error in the
          document&mdash;TeX is getting into an infinite loop, and after
          some time all its internal registers have been used. Sometimes,
          however, a large document that loads a package that uses a lot of
          TeX's registers leads to that error, or to a similar error message.
          The package documentation, the Google archive, or TeX-related
          mailing-lists or newsgroups will be helpful to find out which
          parameter needs to be changed in <file>/etc/texmf/texmf.cnf</file>
          (or rather in one of the files under 
	  <file>/etc/texmf/texmf.d/</file>, (see
          <ref id="sec-texmfcnf-and-update-texmf">)).
        </p>
     </sect>
    </chapt>

   <chapt>
      <heading>
        How to install additional or updated (La)TeX packages or fonts
      </heading>

      <p>
        If you want to install additional (La)TeX stuff, you have to:
        <!-- the compact enumlist is buggy... -->
        <enumlist>
          <item>
            install it at a place where TeX can find it;
          </item>
          <item>
            register it properly.
          </item>
        </enumlist>
      </p>

      <p>
        This can generally be done site-wide (by an administrator who has
        write access to at least <file>/usr/local/share/texmf</file> and
        <file>/etc/texmf</file>), or on a per-user basis. This can be done by
        any user on the system, without requiring write access to system
        directories. Some people might also find it more convenient in case
        they share their home directory between a couple of machines, even if
        they do have administrator rights.
      </p>

      <p>
        In the following, we first explain the principles by describing a
        site-wide setup; then we explain the details for user-specific setup.
      </p>

      <sect>
        <heading>(La)TeX input files</heading>

        <p>
          This is usually quite easy. Put the files in an appropriate
          directory below <var>TEXMFLOCAL</var>, which is the directory tree
          rooted at <file>/usr/local/share/texmf</file>.
        </p>

        <p>
          For LaTeX packages, create the directory
          <file>tex/latex/<var>packagename</var></file> within that tree (or
          use <file>tex/latex/misc</file>) and put the files there; the
          documentation should be put into
          <file>doc/latex/<var>packagename</var></file>. If the package comes
          as a pair of <file>.dtx</file> and <file>.ins</file> files, you need
          to run <prgn>latex</prgn> over the <file>.ins</file> file in order
          to produce the package files, and over the <file>.dtx</file> file to
          produce the documentation. After that, the <file>.dtx</file> and
          <file>.ins</file> files are no longer needed. Please refer to the
          <file>README</file> file of the package if there is one.
        </p>

        <p>
          After that, <em>registering</em> is easy: just run the command
          <prgn>mktexlsr</prgn> (also called <prgn>texhash</prgn>). This will
          regenerate the <file>ls-R</file> file for all <var>TEXMF</var> trees
          you have write access to.
        </p>
     </sect>

     <sect>
        <heading>Complex installations</heading>

        <p>
          With some packages, e.g. when they contain fonts, the
          procedure is more complicated. Please follow the
          instructions given in the package. The Debian-specific part
          comes in when the configuration files
          <file>texmf.cnf</file>, <file>fmtutil.cnf</file>,
          <file>updmap.cfg</file>, or <file>language.dat</file> need
          to be changed. See the description above (<ref
          id="sec-core-config-files">), the manual pages for
          <prgn>update-updmap</prgn>, <prgn>update-texmf</prgn>,
          <prgn>update-fmtutil</prgn>, <prgn>update-language</prgn>
          and <ref id="sec-font-installation">.
        </p>
     </sect>

     <sect id="sec-font-installation">
        <heading>Font installation</heading>

        <p>
          If you wish to install a font package in a system-wide manner,
          please follow the instructions in this section. If you are preparing
          a Debian package containing fonts, you should refer to the Debian
          TeX policy instead, which is shipped in the
          <package>tex-common</package> package.
        </p>

        <p>
          Generally, you should first have a look at the installation
          instructions that come with the font package, in case there is
          something specific to that package with respect to installation. But
          you should make sure that you install most files in a subdirectory
          of <var>TEXMFLOCAL</var> (see <ref id="sec-texmf-trees">). This is
          because we are describing here a system-wide installation that is
          not done by Debian packages.
        </p>

        <p>
          For instance, AFM files should be stored into
          <file><var>TEXMFLOCAL</var>/fonts/afm/<var>supplier</var>/<var>typeface</var>/</file>
          where <var>supplier</var> identifies the supplier of the fonts (for
          instance, <tt>adobe</tt>, <tt>urw</tt> or <tt>public</tt>) and
          <var>typeface</var> refers to the name of the font family (e.g.,
          <tt>marvosym</tt> or <tt>lm</tt>). If in doubt, you should have a
          look at the system trees managed by Debian packages,
          <file>/usr/share/texmf</file> and
	  <file>/usr/share/texlive/texmf-dist</file>; they follow the same
          layout, called the TeX Directory Structure (which is documented at
          <url id="http://www.tug.org/tds/" name="&urlname">).
        </p>

        <p>
          In order for the various TeX-related programs to be able to use a
          font, you need to somehow register its map files (simply copying the
          files to <var>TEXMFLOCAL</var> is not enough). You can do this with
          the following steps, performed as <tt>root</tt>, where
          <var>foo</var> stands for the name of the font package you are
          installing:

          <enumlist>
            <item>
              <p>
                Make sure you have stored all the relevant files shipped in
                the package (<file>.afm</file>, <file>.tfm</file>,
                <file>.pfb</file>, <file>.pfa</file>, <file>.mf</file>,
                <file>.fd</file>, <file>.enc</file>, <file>.map</file>,
                <file>.sty</file> are all relevant in this context) in the
                appropriate subdirectories of <var>TEXMFLOCAL</var>, as
                explained above.
              </p>

            <item>
              <p>
	        List the map files you stored in step 1 under 
		<var>TEXMFLOCAL</var>, with one line
                per file, as in:

<example>
# This is a comment line
Map <var>foo</var>.map
Map other-map-file-from-package-<var>foo</var>.map
</example>
		
		in the file
		<file>/usr/local/share/texmf/web2c/updmap.cfg</file>.
	      </p>

              <p>
                If a font is available both as bitmap and outline, you should
                use <tt>MixedMap</tt> instead of <tt>Map</tt>. Please refer to
                the manual pages for <prgn>updmap</prgn> for details.
              </p>

	      <p>
	        (not recommended, but possible)
		You can also use <tt>updmap-sys --enable
		Map <var>foo</var>.map</tt>; this will create/edit
		the <file>/etc/texmf/web2c/updmap.cfg</file> file for you.
		But since the real files are stored in 
		<var>TEXMFLOCAL</var> it is better to add the map directives
		to the <file>updmap.cfg</file> in the same tree.
	      </p>
            </item>

            <item>
              <p>
                Run the program <prgn>mktexlsr</prgn>. This will record all
               the newly created files in <file>ls-R</file> files (these are
               used by TeX-related programs as indices to find the files they
               need when operating).
              </p>
            </item>

            <item>
              <p>
                Run the program <prgn>updmap-sys</prgn>. This will use your
                updated <file>updmap.cfg</file> to generate files that are
                needed by <prgn>dvips</prgn>, <prgn>pdflatex</prgn>,
                <prgn>dvipdfm</prgn>, etc., such as <file>psfonts.map</file>
                and <file>pdftex.map</file>.
              </p>
            </item>
          </enumlist>
        </p>

        <p>
          At this point, the font package should be properly installed for all
          users on the system.
        </p>
      </sect>

     <sect id="sec-user-specific-installation">
        <heading>User-specific installation</heading>

        <p>
          Instead of a system-wide installation, one can also install input
          files and fonts in the private <var>TEXMFHOME</var>, which is set to
          <file>$HOME/texmf</file> by default. For fonts, compared to the
          system-wide installation explained above, the following changes have
          to be made:

          <list>
            <item>
              In step 1, copy all relevant files to the appropriate
              subdirectories in <var>TEXMFHOME</var>.
            </item>

            <item>
	      <p>
	      In step 2, edit <file><var>TEXMFHOME</var>/web2c/updmap.cfg</file>
	      instead.
	      </p>

	      <p>
		As for the site-wide installation, you can also
		use <tt>updmap --enable Map <var>foo</var>.map</tt>.
	      </p>
            </item>

            <item>
	      In step 3 run <prgn>updmap</prgn> instead of 
	      <prgn>updmap-sys</prgn>. The generated files are created 
	      in directories below <var>TEXMFVAR</var>.
            </item>
          </list>
        </p>

      </sect>
    </chapt>

   <chapt>
      <heading>Problems, bug reports</heading>

      <p>
        If the installation failed, please check the following points:

        <list compact>
          <item>
            Is there enough room on your hard disk?
          </item>

          <item>
            Is there any privately-compiled TeX system besides the Debian
            packages?
          </item>

          <item>
            Does the command:
<example>
kpsewhich --format=cnf texmf
</example>
            return <file>/usr/share/texmf/web2c/texmf.cnf</file>?
          </item>

          <item>
            Is <file>texmf.cnf</file> modified a lot? Please check
            <file>/etc/texmf/web2c/texmf.d/</file>.
          </item>

          <item>
            Did you set any TeX-related environment variable?
          </item>

          <item>
            Try again. This might work in some cases.
          </item>

          <item>
            Is your <file>language.dat</file> correct?
          </item>
        </list>
      </p>

      <p>
        How to report a bug:

        <list compact>
          <item>
            Please calm down anyway. ;)
          </item>

          <item>
            Please check the Debian Bug Tracking System first.
          </item>

          <item>
            Please read carefully the error messages, if any. It will help
            both you and us.
          </item>

          <item>
            Please use <prgn>reportbug</prgn> and include all
            information it gathers
          </item>

          <item>
            Please attach a simple and short sample file which causes the
            problem you want to report.
          </item>

          <item>
            Be prepared that we will have to ask more questions:  You
            should have time to exchange a couple of e-mails with us
          </item>

          <item>
            It will be helpful to show us the output of the command:
<example>
ls /etc/texmf/texmf.d/*
</example>
          </item>
        </list>
      </p>
    </chapt>
  </book>
</debiandoc>
