From: Manoj Srivastava <srivasta@debian.org>
Date: Thu, 16 Jun 2005 05:04:58 +0000 (+0000)
Subject: New version
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=88a29ddc386bab01a2d6d88ee043616873ce4a08;p=debian%2Fdebian-policy.git

New version

Author: srivasta
Date: 1998/11/27 07:45:27
New version

git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-20
---

diff --git a/packaging.sgml b/packaging.sgml
index 4a3f0a5..a040af4 100644
--- a/packaging.sgml
+++ b/packaging.sgml
@@ -1,4 +1,8 @@
-<!doctype debiandoc system>
+<!doctype debiandoc system[
+<!-- include version information so we don't have to hard code it
+     within the document -->
+<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+]>
 
 <!--
  Debian GNU/Linux Packaging Manual.
@@ -8,3567 +12,5052 @@
  Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
  -->
 
-<book>
-
-<title>Debian Packaging Manual
-<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
-<author>Revised: David A. Morris <email/bweaver@debian.org/
-<author>Maintainer: Christian Schwarz <email/schwarz@debian.org/
-<version>version 2.4.1.0, 14 April 1998
-
-<abstract>
-This manual describes the technical aspects of creating Debian binary
-and source packages.  It also documents the interface between
-<prgn/dselect/ and its access method scripts.  It does not deal with
-the Debian Project policy requirements, and it assumes familiarity
-with <prgn/dpkg/'s functions from the system administrator's
-perspective.
-
-<copyright>Copyright &copy;1996 Ian Jackson.
-<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>
-
-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>
-
-A copy of the GNU General Public License is available as
-<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
-distribution or on the World Wide Web at
-<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it
-by writing to the Free Software Foundation, Inc., 59 Temple Place -
-Suite 330, Boston, MA 02111-1307, USA.
-<p>
-
-<toc sect>
-
-<!-- Describes the technical interface between a package and dpkg.
-
-How to safely put shared libraries in a package.  Details of dpkg's
-handling of individual files.  Sections on when to use which feature
-(eg Replaces vs. Replaces/Conflicts vs. update-alternatives
-vs. diversions) Cross-references to the policy document (see below)
-where appropriate.  Description of the interface between dselect and
-its access methods.  Hints on where to start with a new package (ie,
-the hello package).  What to do about file aliasing.
-
-file aliasing
-
-Manpages are required for: update-rc.d, diversions,
-update-alternatives, install-info in a package.
-
--->
-
-<chapt id="scope">Introduction and scope of this manual
-<p>
-
-<prgn/dpkg/ is a suite of programs for creating binary package files
-and installing and removing them on Unix systems.<footnote><prgn/dpkg/
-is targetted primarily at Debian GNU/Linux, but may work on or be
-ported to other systems.</footnote>
-<p>
-
-The binary packages are designed for the management of installed
-executable programs (usually compiled binaries) and their associated
-data, though source code examples and documentation are provided as
-part of some packages.
-<p>
-
-This manual describes the technical aspects of creating Debian binary
-packages (<tt/.deb/ files).  It documents the behaviour of the
-package management programs <prgn/dpkg/, <prgn/dselect/ et al. and and the
-way they interact with packages.
-<p>
-
-It also documents the interaction between <prgn/dselect/'s core and the
-access method scripts it uses to actually install the selected
-packages, and describes how to create a new access method.
-<p>
-
-This manual does not go into detail about the options and usage of the
-package building and installation tools.  It should therefore be read
-in conjuction with those programs' manpages.
-<p>
-
-The utility programs which are provided with <prgn/dpkg/ for managing
-various system configuration and similar issues, such as
-<prgn/update-rc.d/ and <prgn/install-info/, are not described in
-detail here - please see their manpages.
-<p>
-
-It does <em/not/ describe the policy requirements imposed on Debian
-packages, such as the permissions on files and directories,
-documentation requirements, upload procedure, and so on.  You should
-see the Debian packaging policy manual for these details.  (Many of
-them will probably turn out to be helpful even if you don't plan to
-upload your package and make it available as part of the
-distribution.)
-<p>
-
-It is assumed that the reader is reasonably familiar with the
-<prgn/dpkg/ System Administrators' manual.  Unfortunately this manual
-does not yet exist.
-<p>
-
-The Debian version of the FSF's GNU hello program is provided as an
-example for people wishing to create Debian packages. The Debian
-<prgn/debmake/ package is recommended as a very helpful tool in
-creating and maintaining Debian packages. However, while the tools and
-examples are helpful, they do not replace the need to read and follow
-the Policy and Programmer's Manual.
-
-<chapt id="binarypkg">Binary packages
-<p>
-
-The binary package has two main sections.  The first part consists of
-various control information files and scripts used by <prgn/dpkg/ when
-installing and removing.  See <ref id="controlarea">.
-<p>
-
-The second part is an archive containing the files and directories to
-be installed. 
-<p>
-
-In the future binary packages may also contain other components, such
-as checksums and digital signatures. The format for the archive is
-described in full in the <tt>deb(5)</> manpage.
-
-
-<sect id="bincreating">Creating package files - <prgn/dpkg-deb/
-<p>
-
-All manipulation of binary package files is done by <prgn/dpkg-deb/;
-it's the only program that has knowledge of the format.
-(<prgn/dpkg-deb/ may be invoked by calling <prgn/dpkg/, as <prgn/dpkg/ will
-spot that the options requested are appropriate to <prgn/dpkg-deb/ and
-invoke that instead with the same arguments.)
-<p>
-
-In order to create a binary package you must make a directory tree
-which contains all the files and directories you want to have in the
-filesystem data part of the package.  In Debian-format source packages
-this directory is usually <tt>debian/tmp</tt>, relative to the top of
-the package's source tree.
-<p>
-
-They should have the locations (relative to the root of the directory
-tree you're constructing) ownerships and permissions which you want
-them to have on the system when they are installed.
-<p>
-
-With current versions of <prgn/dpkg/ the uid/username and gid/groupname
-mappings for the users and groups being used should be the same on the
-system where the package is built and the one where it is installed.
-<p>
-
-You need to add one special directory to the root of the miniature
-filesystem tree you're creating: <prgn/DEBIAN/.  It should contain the
-control information files, notably the binary package control file
-(see <ref id="controlfile">).
-<p>
-
-The <prgn/DEBIAN/ directory will not appear in the filesystem archive of
-the package, and so won't be installed by <prgn/dpkg/ when the package
-is installed.
-<p>
-
-When you've prepared the package, you should invoke:
-<example>
-dpkg --build <var/directory/
-</example>
-<p>
-
-This will build the package in <tt/<var/directory/.deb/.
-(<prgn/dpkg/ knows that <tt/--build/ is a <prgn/dpkg-deb/ option, so it
-invokes <prgn/dpkg-deb/ with the same arguments to build the package.)
-<p>
-
-See the manpage <manref name="dpkg-deb" section=8> for details of how
-to examine the contents of this newly-created file.  You may find the
-output of following commands enlightening:
-<example>
-dpkg-deb --info <var/filename/.deb
-dpkg-deb --contents <var/filename/.deb
-dpkg --contents <var/filename/.deb
-</example>
-To view the copyright file for a package you could use this command:
-<example>
-dpkg --fsys-tarfile <var/filename/.deb | tar xof usr/doc/<var/\*/copyright | less
-</example>
-
-<sect id="controlarea">Package control information files
-<p>
-
-The control information portion of a binary package is a collection of
-files with names known to <prgn/dpkg/.  It will treat the contents of
-these files specially - some of them contain information used by
-<prgn/dpkg/ when installing or removing the package; others are scripts
-which the package maintainer wants <prgn/dpkg/ to run.
-<p>
-
-It is possible to put other files in the package control area, but
-this is not generally a good idea (though they will largely be
-ignored).
-<p>
-
-Here is a brief list of the control info files supported by <prgn/dpkg/
-and a summary of what they're used for.
-<p>
-
-<taglist>
-<tag><tt/control/
-<item>
-
-This is the key description file used by <prgn/dpkg/.  It specifies the
-package's name and version, gives its description for the user, states
-its relationships with other packages, and so forth.
-See <ref id="controlfile">.
-<p>
-
-It is usually generated automatically from information in the source
-package by the <prgn/dpkg-gencontrol/ program, and with assistance
-from <prgn/dpkg-shlibdeps/.  See <ref id="sourcetools">.
-
-<tag><tt/postinst/, <tt/preinst/, <tt/postrm/, <tt/prerm/
-<item>
-
-These are exectuable files (usually scripts) which <prgn/dpkg/ runs
-during installation, upgrade and removal of packages.  They allow the
-package to deal with matters which are particular to that package or
-require more complicated processing than that provided by <prgn/dpkg/.
-Details of when and how they are called are in
-<ref id="maintainerscripts">.
-<p>
-
-It is very important to make these scripts idempotent.<footnote>That
-means that if it runs successfully or fails and then you call it again
-it doesn't bomb out, but just ensures that everything is the way it
-ought to be.</footnote>  This is so that if an error occurs, the user
-interrupts <prgn/dpkg/ or some other unforeseen circumstance happens you
-don't leave the user with a badly-broken package.
-<p>
-
-The maintainer scripts are guaranteed to run with a controlling
-terminal and can interact with the user.  If they need to prompt for
-passwords, do full-screen interaction or something similar you should
-do these things to and from <tt>/dev/tty</>, since <prgn/dpkg/ will at
-some point redirect scripts' standard input and output so that it can
-log the installation process.  Likewise, because these scripts may be
-executed with standard output redirected into a pipe for logging
-purposes, Perl scripts should set unbuffered output by setting
-<tt/$|=1/ so that the output is printed immediately rather than being
-buffered.
-<p>
-
-Each script should return a zero exit status for success, or a nonzero
-one for failure.
-
-<tag><tt/conffiles/
-<item>
-
-This file contains a list of configuration files which are to be
-handled automatically by <prgn/dpkg/ (see <ref id="conffiles">).  Note
-that not necessarily every configuration file should be listed here.
-
-<tag><tt/shlibs/
-<item>
-
-This file contains a list of the shared libraries supplied by the
-package, with dependency details for each.  This is used by
-<prgn/dpkg-shlibdeps/ when it determines what dependencies are
-required in a package control file. The <tt/shlibs/ file format is 
-described on <ref id="shlibs">.
-<p>
-
-</taglist>
-
-<sect id="controlfile">The main control information file: <tt/control/
-<p>
-
-The most important control information file used by <prgn/dpkg/ when it
-installs a package is <tt/control/.  It contains all the package's
-`vital statistics'.
-<p>
-
-The binary package control files of packages built from Debian sources
-are made by a special tool, <prgn/dpkg-gencontrol/, which reads
-<tt>debian/control</> and <tt>debian/changelog</> to find the
-information it needs.  See <ref id="sourcepkg"> for more details.
-<p>
-
-The fields in binary package control files are:
-<list compact>
-
-<item><qref id="f-Package"><tt/Package/</> (mandatory)
-<item><qref id="versions"><tt/Version/</> (mandatory)
-
-<item><qref id="f-Architecture"><tt/Architecture/</>
-(mandatory)<footnote>This field should appear in all packages, though
-<prgn/dpkg/ doesn't require it yet so that old packages can still be
-installed.</footnote>
-
-<item><qref id="relationships"><tt/Depends/, <tt/Provides/ et al.</>
-<item><qref id="f-Essential"><tt/Essential/</>
-<item><qref id="f-Maintainer"><tt/Maintainer/</>
-<item><qref id="f-classification"><tt/Section/, <tt/Priority/</>
-<item><qref id="f-Source"><tt/Source/</>
-<item><qref id="descriptions"><tt/Description/</>
-<item><qref id="f-Installed-Size"><tt/Installed-Size/</>
-
-</list>
-<p>
-
-A description of the syntax of control files and the purpose of these
-fields is available in <ref id="controlfields">.
-
-
-<chapt id="sourcepkg">Source packages
-<p>
-
-The Debian binary packages in the distribution are generated from
-Debian sources, which are in a special format to assist the easy and
-automatic building of binaries.
-<p>
-
-There was a previous version of the Debian source format, which is now
-being phased out.  Instructions for converting an old-style package
-are given in the Debian policy manual.
-
-<sect id="sourcetools">Tools for processing source packages
-<p>
-
-Various tools are provided for manipulating source packages; they pack
-and unpack sources and help build of binary packages and help manage
-the distribution of new versions.
-<p>
-
-They are introduced and typical uses described here; see <manref
-name=dpkg-source section=1> for full documentation about their
-arguments and operation.
-<p>
-
-For examples of how to construct a Debian source package, and how to
-use those utilities that are used by Debian source packages, please
-see the <prgn/hello/ example package.
-
-<sect1><prgn/dpkg-source/ - packs and unpacks Debian source packages
-<p>
-
-This program is frequently used by hand, and is also called from
-package-independent automated building scripts such as
-<prgn/dpkg-buildpackage/.
-<p>
-
-To unpack a package it is typically invoked with
-<example>
-dpkg-source -x <var>.../path/to/filename</>.dsc
-</example>
-with the <tt/<var/filename/.tar.gz/ and
-<tt/<var/filename/.diff.gz/ (if applicable) in the same directory.  It
-unpacks into <tt/<var/package/-<var/version//, and if applicable
-<tt/<var/package/-<var/version/.orig/, in the current directory.
-<p>
-
-To create a packed source archive it is typically invoked:
-<example>
-dpkg-source -b <var/package/-<var/version/
-</example>
-This will create the <tt/.dsc/, <tt/.tar.gz/ and <tt/.diff.gz/ (if
-appropriate) in the current directory.  <prgn/dpkg-source/ does not
-clean the source tree first - this must be done separately if it is
-required.
-<p>
-
-See also <ref id="sourcearchives">.
-
-
-<sect1><prgn/dpkg-buildpackage/ - overall package-building control
-script
-<p>
-
-<prgn/dpkg-buildpackage/ is a script which invokes <prgn/dpkg-source/,
-the <tt>debian/rules</> targets <prgn/clean/, <prgn/build/ and
-<prgn/binary/, <prgn/dpkg-genchanges/ and <prgn/pgp/ to build a signed
-source and binary package upload.
-<p>
-
-It is usually invoked by hand from the top level of the built or
-unbuilt source directory.  It may be invoked with no arguments; useful
-arguments include:
-<taglist compact>
-<tag><tt/-uc/, <tt/-us/
-<item>Do not PGP-sign the <tt/.changes/ file or the source package
-<tt/.dsc/ file, respectively.
-
-<tag><tt/-p<var/pgp-command//
-<item>Invoke <var/pgp-command/ instead of finding <tt/pgp/ on the
-<prgn/PATH/.  <var/pgp-command/ must behave just like <prgn/pgp/.
-
-<tag><tt/-r<var/root-command//
-<item>When root privilege is required, invoke the command
-<var/root-command/.  <var/root-command/ should invoke its first
-argument as a command, from the <prgn/PATH/ if necessary, and pass its
-second and subsequent arguments to the command it calls.  If no
-<var/root-command/ is supplied then <var/dpkg-buildpackage/ will take
-no special action to gain root privilege, so that for most packages it
-will have to be invoked as root to start with.
-
-<tag><tt/-b/, <tt/-B/
-<item>Two types of binary-only build and upload - see <manref
-name=dpkg-source section=1>.
-</taglist>
-
-
-<sect1><prgn/dpkg-gencontrol/ - generates binary package control files
-<p>
-
-This program is usually called from <tt>debian/rules</> (see <ref
-id="sourcetree">) in the top level of the source tree.
-<p>
-
-This is usually done just before the files and directories in the
-temporary directory tree where the package is being built have their
-permissions and ownerships set and the package is constructed using
-<prgn/dpkg-deb/<footnote>This is so that the control file which is
-produced has the right permissions</footnote>.
-<p>
-
-<prgn/dpkg-gencontrol/ must be called after all the files which are to
-go into the package have been placed in the temporary build directory,
-so that its calculation of the installed size of a package is correct.
-<p>
-
-It is also necessary for <prgn/dpkg-gencontrol/ to be run after
-<prgn/dpkg-shlibdeps/ so that the variable substitutions created by
-<prgn/dpkg-shlibdeps/ in <tt>debian/substvars</> are available.
-<p>
-
-For a package which generates only one binary package, and which
-builds it in <tt>debian/tmp</> relative to the top of the source
-package, it is usually sufficient to call:
-<example>
-dpkg-gencontrol
-</example>
-<p>
-
-Sources which build several binaries will typically need something
-like:
-<example>
-dpkg-gencontrol -Pdebian/tmp-<var/pkg/ -p<var/package/
-</example>
-The <tt/-P/ tells <prgn/dpkg-gencontrol/ that the package is being
-built in a non-default directory, and the <tt/-p/ tells it which
-package's control file should be generated.
-<p>
-
-<prgn/dpkg-gencontrol/ also adds information to the list of files in
-<tt>debian/files</>, for the benefit of (for example) a future
-invocation of <prgn/dpkg-genchanges/.
-
-
-<sect1><prgn/dpkg-shlibdeps/ - calculates shared library dependencies
-<p>
-
-This program is usually called from <tt>debian/rules</> just before
-<prgn/dpkg-gencontrol/ (see <ref id="sourcetree">), in the top level
-of the source tree.
-<p>
-
-Its arguments are executables<footnote>They may be specified either
-in the locations in the source tree where they are created or in the
-locations in the temporary build tree where they are installed prior
-to binary package creation.</footnote> for which shared library
-dependencies should be included in the binary package's control file.
-<p>
-
-If some of the executable(s) shared libraries should only warrant a
-<tt/Recommends/ or <tt/Suggests/, or if some warrant a
-<tt/Pre-Depends/, this can be achieved by using the
-<tt/-d<var/dependency-field// option before those executable(s).
-(Each <tt/-d/ option takes effect until the next <tt/-d/.)
-<p>
-
-<prgn/dpkg-shlibdeps/ does not directly cause the output control file
-to be modified.  Instead by default it adds to the
-<tt>debian/substvars</> file variable settings like
-<tt/shlibs:Depends/.  These variable settings must be referenced in
-dependency fields in the appropriate per-binary-package sections of
-the source control file.
-<p>
-
-For example, the <prgn/procps/ package generates two kinds of
-binaries, simple C binaries like <prgn/ps/ which require a
-predependency and full-screen ncurses binaries like <prgn/top/ which
-require only a recommendation.  It can say in its <tt>debian/rules</>:
-<example>
-dpkg-shlibdeps -dPre-Depends ps -dRecommends top
-</example>
-and then in its main control file <tt>debian/control</>:
-<example>
-<var/.../
-Package: procps
-Pre-Depends: ${shlibs:Pre-Depends}
-Recommends: ${shlibs:Recommends}
-<var/.../
-</example>
-<p>
-
-Sources which produce several binary packages with different shared
-library dependency requirements can use the <tt/-p<var/varnameprefix//
-option to override the default <tt/shlib:/ prefix (one invocation of
-<prgn/dpkg-shlibdeps/ per setting of this option).  They can thus
-produce several sets of dependency variables, each of the form
-<tt/<var/varnameprefix/:<var/dependencyfield//, which can be referred
-to in the appropriate parts of the binary package control files.
-
-
-<sect1><prgn/dpkg-distaddfile/ - adds a file to <tt>debian/files</>
-<p>
-
-Some packages' uploads need to include files other than the source and
-binary package files.
-<p>
-
-<prgn/dpkg-distaddfile/ adds a file to the <tt>debian/files</> file so
-that it will be included in the <tt/.changes/ file when
-<prgn/dpkg-genchanges/ is run.
-<p>
-
-It is usually invoked from the <prgn/binary/ target of
-<tt>debian/rules</>:
-<example>
-dpkg-distaddfile <var/filename/ <var/section/ <var/priority/
-</example>
-The <var/filename/ is relative to the directory where
-<prgn/dpkg-genchanges/ will expect to find it - this is usually the
-directory above the top level of the source tree.  The
-<tt>debian/rules</> target should put the file there just before or
-just after calling <prgn/dpkg-distaddfile/.
-<p>
-
-The <var/section/ and <var/priority/ are passed unchanged into the
-resulting <tt/.changes/ file.  See <ref id="f-classification">.
-
-
-<sect1><prgn/dpkg-genchanges/ - generates a <tt/.changes/ upload
-control file
-<p>
-
-This program is usually called by package-independent automatic
-building scripts such as <prgn/dpkg-buildpackage/, but it may also be
-called by hand.
-<p>
-
-It is usually called in the top level of a built source tree, and when
-invoked with no arguments will print out a straightforward
-<tt/.changes/ file based on the information in the source package's
-changelog and control file and the binary and source packages which
-should have been built.
-
-
-<sect1><prgn/dpkg-parsechangelog/ - produces parsed representation of
-a changelog
-<p>
-
-This program is used internally by <prgn/dpkg-source/ et al.  It may
-also occasionally be useful in <tt>debian/rules</> and elsewhere.  It
-parses a changelog, <tt>debian/changelog</> by default, and prints a
-control-file format representation of the information in it to
-standard output.
-
-<sect id="sourcetree">The Debianised source tree
-<p>
-
-The source archive scheme described later is intended to allow a
-Debianised source tree with some associated control information to be
-reproduced and transported easily.  The Debianised source tree is a
-version of the original program with certain files added for the
-benefit of the Debianisation process, and with any other changes
-required made to the rest of the source code and installation scripts.
-<p>
-
-The extra files created for Debian are in the subdirectory <tt/debian/
-of the top level of the Debianised source tree.  They are described
-below.
-
-<sect1><tt>debian/rules</tt> - the main building script
-<p>
-
-This file is an executable makefile, and contains the package-specific
-recipies for compiling the package and building binary package(s) out
-of the source.
-<p>
-
-It must start with the line <tt>#!/usr/bin/make -f</tt>, so that it
-can be invoked by saying its name rather than invoking <prgn/make/
-explicitly.
-<p>
-
-The targets which are required to be present are:
-
-<taglist>
-<tag/<tt/build//
-<item>
-
-This should perform all non-interactive configuration and compilation
-of the package.  If a package has an interactive pre-build
-configuration routine, the Debianised source package should be built
-after this has taken place, so that it can be built without rerunning
-the configuration.
-<p>
-
-For some packages, notably ones where the same source tree is compiled
-in different ways to produce two binary packages, the <prgn/build/
-target does not make much sense.  For these packages it is good enough
-to provide two (or more) targets (<tt/build-a/ and <tt/build-b/ or
-whatever) for each of the ways of building the package, and a
-<prgn/build/ target that does nothing.  The <prgn/binary/ target will have
-to build the package in each of the possible ways and make the binary
-package out of each.
-<p>
-
-The <prgn/build/ target must not do anything that might require root
-privilege.
-<p>
-
-The <prgn/build/ target may need to run <prgn/clean/ first - see below.
-<p>
-
-When a package has a configuration routine that takes a long time, or
-when the makefiles are poorly designed, or when <prgn/build/ needs to
-run <prgn/clean/ first, it is a good idea to <tt/touch build/ when the
-build process is complete.  This will ensure that if <tt>debian/rules
-build</tt> is run again it will not rebuild the whole program.
-
-<tag/<tt/binary/, <tt/binary-arch/, <tt/binary-indep/
-<item>
-
-The <prgn/binary/ target should be all that is necessary for the user
-to build the binary package.  It is split into two parts:
-<prgn/binary-arch/ builds the packages' output files which are
-specific to a particular architecture, and <prgn/binary-indep/
-builds those which are not.
-<p>
-
-<prgn/binary/ should usually be a target with no commands which simply
-depends on <prgn/binary-arch/ and <prgn/binary-indep/.
-<p>
-
-Both <prgn/binary-*/ targets should depend on the <prgn/build/ target,
-above, so that the package is built if it has not been already.  It
-should then create the relevant binary package(s), using
-<prgn/dpkg-gencontrol/ to make their control files and <prgn/dpkg-deb/
-to build them and place them in the parent of the top level directory.
-<p>
-
-If one of the <prgn/binary-*/ targets has nothing to do (this will be
-always be the case if the source generates only a single binary
-package, whether architecture-dependent or not) it <em/must/ still
-exist, but should always succeed.
-<p>
-
-<ref id="binarypkg"> describes how to construct binary packages.
-<p>
-
-The <prgn/binary/ targets must be invoked as root.
-
-<tag/<tt/clean//
-<item>
-
-This should undo any effects that the <prgn/build/ and <prgn/binary/
-targets may have had, except that it should leave alone any output
-files created in the parent directory by a run of <prgn/binary/.
-<p>
-
-If a <prgn/build/ file is touched at the end of the <prgn/build/ target,
-as suggested above, it must be removed as the first thing that
-<prgn/clean/ does, so that running <prgn/build/ again after an interrupted
-<prgn/clean/ doesn't think that everything is already done.
-<p>
-
-The <prgn/clean/ target must be invoked as root if <prgn/binary/ has
-been invoked since the last <prgn/clean/, or if <prgn/build/ has been
-invoked as root (since <prgn/build/ may create directories, for
-example).
-
-<tag/<tt/get-orig-source/ (optional)/
-<item>
-
-This target fetches the most recent version of the original source
-package from a canonical archive site (via FTP or WWW, for example),
-does any necessary rearrangement to turn it into the original source
-tarfile format described below, and leaves it in the current directory.
-<p>
-
-This target may be invoked in any directory, and should take care to
-clean up any temporary files it may have left.
-<p>
-
-This target is optional, but providing it if possible is a good idea.
-
-</taglist>
-
-The <prgn/build/, <prgn/binary/ and <prgn/clean/ targets must be
-invoked with a current directory of the package's top-level
-directory.
-
-<p>
-
-Additional targets may exist in <tt>debian/rules</tt>, either as
-published or undocumented interfaces or for the package's internal
-use.
-
-
-<sect1><tt>debian/control</tt>
-<p>
-
-This file contains version-independent details about the source
-package and about the binary packages it creates.
-<p>
-
-It is a series of sets of control fields, each syntactically similar
-to a binary package control file.  The sets are separated by one or
-more blank lines.  The first set is information about the source
-package in general; each subsequent set describes one binary package
-that the source tree builds.
-<p>
-
-The syntax and semantics of the fields are described below in
-<ref id="controlfields">.
-<p>
-
-The general (binary-package-independent) fields are:
-<list compact>
-<item><qref id="f-Source"><tt/Source/</> (mandatory)
-<item><qref id="f-Maintainer"><tt/Maintainer/</>
-<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</>
-(classification, mandatory)
-<item><qref id="f-Standards-Version"><tt/Standards-Version/</>
-</list>
-<p>
-
-The per-binary-package fields are:
-<list compact>
-<item><qref id="f-Package"><tt/Package/</> (mandatory)
-<item><qref id="f-Architecture"><tt/Architecture/</> (mandatory)
-<item><qref id="descriptions"><tt/Description/</>
-<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</> (classification)
-<item><qref id="f-Essential"><tt/Essential/</>
-<item><qref id="relationships"><tt/Depends/ et al.</> (package interrelationships)
-</list>
-<p>
-
-These fields are used by <prgn/dpkg-gencontrol/ to generate control
-files for binary packages (see below), by <prgn/dpkg-genchanges/ to
-generate the <tt/.changes/ file to accompany the upload, and by
-<prgn/dpkg-source/ when it creates the <tt/.dsc/ source control file as
-part of a source archive.
-<p>
-
-The fields here may contain variable references - their values will be
-substituted by <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ or
-<prgn/dpkg-source/ when they generate output control files.  See <ref
-id="srcsubstvars"> for details.
-<p>
-
-<sect2>User-defined fields
-<p>
-
-Additional user-defined fields may be added to the source package
-control file.  Such fields will be ignored, and not copied to (for
-example) binary or source package control files or upload control
-files.
-<p>
-
-If you wish to add additional unsupported fields to these output files
-you should use the mechanism described here.
-<p>
-
-Fields in the main source control information file with names starting
-<tt/X/, followed by one or more of the letters <tt/BCS/ and a hyphen
-<tt/-/, will be copied to the output files.  Only the part of the
-field name after the hyphen will be used in the output file.  Where
-the letter <tt/B/ is used the field will appear in binary package
-control files, where the letter <tt/S/ is used in source package
-control files and where <tt/C/ is used in upload control
-(<tt/.changes/) files.
-<p>
-
-For example, if the main source information control file contains the
-field
-<example>
-XBS-Comment: I stand between the candle and the star.
-</example>
-then the binary and source package control files will contain the
-field
-<example>
-Comment: I stand between the candle and the star.
-</example>
-
-<sect1 id="dpkgchangelog"><tt>debian/changelog</>
-<p>
-
-This file records the changes to the Debian-specific parts of the
-package<footnote>Though there is nothing stopping an author who is
-also the Debian maintainer from using it for all their changes, it
-will have to be renamed if the Debian and upstream maintainers become
-different people.</footnote>.
-<p>
-
-It has a special format which allows the package building tools to
-discover which version of the package is being built and find out
-other release-specific information.
-<p>
-
-That format is a series of entries like this:
-<p>
-<example>
-<var/package/ (<var/version/) <var/distribution(s)/; urgency=<var/urgency/
-
-  * <var/change details/
-    <var/more change details/
-  * <var/even more change details/
-
- -- <var/maintainer name and email address/  <var/date/
-</example>
-<p>
-
-<var/package/ and <var/version/ are the source package name and
-version number. 
-<p> 
-<var/distribution(s)/ lists the distributions where
-this version should be installed when it is uploaded - it is copied to
-the <tt/Distribution/ field in the <tt/.changes/ file.  See <ref
-id="f-Distribution">.
-<p>
-
-<var/urgency/ is the value for the <tt/Urgency/ field in the
-<tt/.changes/ file for the upload.  See <ref id="f-Urgency">.  It is
-not possible to specify an urgency containing commas; commas are used
-to separate <tt/<var/keyword/=<var/value// settings in the <prgn/dpkg/
-changelog format (though there is currently only one useful
-<var/keyword/, <tt/urgency/).
-<p>
-
-The change details may in fact be any series of lines starting with at
-least two spaces, but conventionally each change starts with an
-asterisk and a separating space and continuation lines are indented so
-as to bring them in line with the start of the text above.  Blank
-lines may be used here to separate groups of changes, if desired.
-<p>
-
-The maintainer name and email address should <em/not/ necessarily be
-those of the usual package maintainer.  They should be the details of
-the person doing <em/this/ version.  The information here will be
-copied to the <tt/.changes/ file, and then later used to send an
-acknowledgement when the upload has been installed.
-<p>
-
-The <var/date/ should be in RFC822 format<footnote>This is generated
-by the <prgn/822-date/ program.</footnote>; it should include the
-timezone specified numerically, with the timezone name or abbreviation
-optionally present as a comment.
-<p>
-
-The first `title' line with the package name should start at the left
-hand margin; the `trailer' line with the maintainer and date details
-should be preceded by exactly one space.  The maintainer details and
-the date must be separated by exactly two spaces.
-<p>
-
-An Emacs mode for editing this format is available: it is called
-<tt/debian-changelog-mode/.  You can have this mode selected
-automatically when you edit a Debian changelog by adding a local
-variables clause to the end of the changelog.
-
-<sect2>Defining alternative changelog formats
-<p>
-
-It is possible to use a different format to the standard one, by
-providing a parser for the format you wish to use.
-<p>
-
-In order to have <tt/dpkg-parsechangelog/ run your parser, you must
-include a line within the last 40 lines of your file matching the Perl
-regular expression:
-<tt>\schangelog-format:\s+([0-9a-z]+)\W</tt>
-The part in parentheses should be the name of the format.  For
-example, you might say:
-<example>
-@@@ changelog-format: joebloggs @@@
-</example>
-Changelog format names are non-empty strings of alphanumerics.
-<p>
-
-If such a line exists then <tt/dpkg-parsechangelog/ will look for the
-parser as <tt>/usr/lib/dpkg/parsechangelog/<var/format-name/</> or
-<tt>/usr/local/lib/dpkg/parsechangelog/<var/format-name/</>; it is an
-error for it not to find it, or for it not to be an executable
-program.  The default changelog format is <tt/dpkg/, and a parser for
-it is provided with the <tt/dpkg/ package.
-<p>
-
-The parser will be invoked with the changelog open on standard input
-at the start of the file.  It should read the file (it may seek if it
-wishes) to determine the information required and return the parsed
-information to standard output in the form of a series of control
-fields in the standard format.  By default it should return
-information about only the most recent version in the changelog; it
-should accept a <tt/-v<var/version// option to return changes
-information from all versions present <em/strictly after/
-<var/version/, and it should then be an error for <var/version/ not to
-be present in the changelog.
-<p>
-
-The fields are:
-<list compact>
-<item><qref id="f-Source"><tt/Source/</>
-<item><qref id="versions"><tt/Version/</> (mandatory)
-<item><qref id="f-Distribution"><tt/Distribution/</> (mandatory)
-<item><qref id="f-Urgency"><tt/Urgency/</> (mandatory)
-<item><qref id="f-Maintainer"><tt/Maintainer/</> (mandatory)
-<item><qref id="f-Date"><tt/Date/</>
-<item><qref id="f-Changes"><tt/Changes/</> (mandatory)
-</list>
-<p>
-
-If several versions are being returned (due to the use of <tt/-v/),
-the urgency value should be of the highest urgency code listed at the
-start of any of the versions requested followed by the concatenated
-(space-separated) comments from all the versions requested; the
-maintainer, version, distribution and date should always be from the
-most recent version.
-<p>
-
-For the format of the <tt/Changes/ field see <ref id="f-Changes">.
-<p>
-
-If the changelog format which is being parsed always or almost always
-leaves a blank line between individual change notes these blank lines
-should be stripped out, so as to make the resulting output compact.
-<p>
-
-If the changelog format does not contain date or package name
-information this information should be omitted from the output.  The
-parser should not attempt to synthesise it or find it from other
-sources.
-<p>
-
-If the changelog does not have the expected format the parser should
-exit with a nonzero exit status, rather than trying to muddle through
-and possibly generating incorrect output.
-<p>
-
-A changelog parser may not interact with the user at all.
-
-<sect1 id="srcsubstvars"><tt>debian/substvars</> and variable substitutions
-<p>
-
-When <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ and
-<prgn/dpkg-source/ generate control files they do variable
-substitutions on their output just before writing it.  Variable
-substitutions have the form <tt/${<var/variable-name/}/.  The optional
-file <tt>debian/substvars</> contains variable substitutions to be
-used; variables can also be set directly from <tt>debian/rules</>
-using the <tt/-V/ option to the source packaging commands, and certain
-predefined variables are available.
-<p>
-
-The is usually generated and modified dynamically by
-<tt>debian/rules</> targets; in this case it must be removed by the
-<prgn/clean/ target.
-<p>
-
-
-
-See <manref name=dpkg-source section=1> for full details about source
-variable substitutions, including the format of
-<tt>debian/substvars</>.
-
-<sect1><tt>debian/files</>
-<p>
-
-This file is not a permanent part of the source tree; it is used while
-building packages to record which files are being generated.
-<prgn/dpkg-genchanges/ uses it when it generates a <tt/.changes/ file.
-<p>
-
-It should not exist in a shipped source package, and so it (and any
-backup files or temporary files such as
-<tt/files.new/<footnote><tt/files.new/ is used as a temporary file by
-<prgn/dpkg-gencontrol/ and <prgn/dpkg-distaddfile/ - they write a new
-version of <tt/files/ here before renaming it, to avoid leaving a
-corrupted copy if an error occurs</footnote>) should be removed by the
-<prgn/clean/ target.  It may also be wise to ensure a fresh start by
-emptying or removing it at the start of the <prgn/binary/ target.
-<p>
-
-<prgn/dpkg-gencontrol/ adds an entry to this file for the <tt/.deb/
-file that will be created by <prgn/dpkg-deb/ from the control file
-that it generates, so for most packages all that needs to be done with
-this file is to delete it in <prgn/clean/.
-<p>
-
-If a package upload includes files besides the source package and any
-binary packages whose control files were made with
-<prgn/dpkg-gencontrol/ then they should be placed in the parent of the
-package's top-level directory and <prgn/dpkg-distaddfile/ should be
-called to add the file to the list in <tt>debian/files</>.
-
-<sect1><tt>debian/tmp</>
-<p>
-
-This is the canonical temporary location for the construction of
-binary packages by the <prgn/binary/ target.  The directory <tt/tmp/
-serves as the root of the filesystem tree as it is being constructed
-(for example, by using the package's upstream makefiles install
-targets and redirecting the output there), and it also contains the
-<tt/DEBIAN/ subdirectory.  See <ref id="bincreating">.
-<p>
-
-If several binary packages are generated from the same source tree it
-is usual to use several <tt>debian/tmp<var/something/</> directories,
-for example <tt/tmp-a/ or <tt/tmp-doc/.
-<p>
-
-Whatever <tt>tmp</> directories are created and used by <prgn/binary/
-must of course be removed by the <prgn/clean/ target.
-
-
-<sect id="sourcearchives">Source packages as archives
-<p>
-
-As it exists on the FTP site, a Debian source package consists of
-three related files.  You must have the right versions of all three to
-be able to use them.
-<p>
-
-<taglist>
-<tag/Debian source control file - <tt/.dsc//
-<item>
-
-This file contains a series of fields, identified and separated just
-like the fields in the control file of a binary package.  The fields
-are listed below; their syntax is described above, in
-<ref id="controlfields">.
-<list compact>
-<item><qref id="f-Source"><tt/Source/</>
-<item><qref id="versions"><tt/Version/</>
-<item><qref id="f-Maintainer"><tt/Maintainer/</>
-<item><qref id="f-Binary"><tt/Binary/</>
-<item><qref id="f-Architecture"><tt/Architecture/</>
-<item><qref id="f-Standards-Version"><tt/Standards-Version/</>
-<item><qref id="f-Files"><tt/Files/</>
-</list>
-<p>
-
-The source package control file is generated by <prgn/dpkg-source/
-when it builds the source archive, from other files in the source
-package, described above.  When unpacking it is checked against the
-files and directories in the other parts of the source package, as
-described below.
-
-<tag/Original source archive - <tt/<var/package/_<var/upstream-version/.orig.tar.gz//
-<item>
-
-This is a compressed (with <tt/gzip -9/) <prgn/tar/ file containing
-the source code from the upstream authors of the program.  The tarfile
-unpacks into a directory
-<tt/<var/package/-<var/upstream-version/.orig/, and does not contain
-files anywhere other than in there or in its subdirectories.
-
-<tag/Debianisation diff - <tt/<var/package/_<var/upstream_version-revision/.diff.gz//
-<item>
-
-This is a unified context diff (<tt/diff -u/) giving the changes which
-are required to turn the original source into the Debian source.
-These changes may only include editing and creating plain files.  The
-permissions of files, the targets of symbolic links and the
-characteristics of special files or pipes may not be changed and no
-files may be removed or renamed.
-<p>
-
-All the directories in the diff must exist, except the <tt/debian/
-subdirectory of the top of the source tree, which will be created by
-<prgn/dpkg-source/ if necessary when unpacking.
-<p>
-
-The <prgn/dpkg-source/ program will automatically make the
-<tt>debian/rules</tt> file executable (see below).
-
-</taglist>
-<p>
-
-If there is no original source code - for example, if the package is
-specially prepared for Debian or the Debian maintainer is the same as
-the upstream maintainer - the format is slightly different: then there
-is no diff, and the tarfile is named
-<tt/<var/package/_<var/version/.tar.gz</> and contains a directory
-<tt/<var/package/-<var/version/</>.
-
-<sect>Unpacking a Debian source package without <prgn/dpkg-source/
-<p>
-
-<tt/dpkg-source -x/ is the recommended way to unpack a Debian source
-package.  However, if it is not available it is possible to unpack a
-Debian source archive as follows:
-
-<enumlist compact>
-<item>Untar the tarfile, which will create a <tt/.orig/ directory.
-<item>Rename the <tt/.orig/ directory to
-<tt/<var/package/-<var/version//.
-<item>Create the subdirectory <tt/debian/ at the top of the source
-tree.
-<item>Apply the diff using <tt/patch -p0/.
-<item>Untar the tarfile again if you want a copy of the original
-source code alongside the Debianised version.
-</enumlist>
-<p>
-
-It is not possible to generate a valid Debian source archive without
-using <prgn/dpkg-source/.  In particular, attempting to use
-<prgn/diff/ directly to generate the <tt/.diff.gz/ file will not work.
-
-<sect1>Restrictions on objects in source packages
-<p>
-
-The source package may not contain any hard links<footnote>This is not
-currently detected when building source packages, but only when
-extracting them.</footnote><footnote>Hard links may be permitted at
-some point in the future, but would require a fair amount of
-work.</footnote>, device special files, sockets or setuid or setgid
-files.<footnote>Setgid directories are allowed.</footnote>
-<p>
-
-The source packaging tools manage the changes between the original and
-Debianised source using <prgn/diff/ and <prgn/patch/.  Turning the
-original source tree as included in the <tt/.orig.tar.gz/ into the
-debianised source must not involve any changes which cannot be handled
-by these tools.  Problematic changes which cause <prgn/dpkg-source/ to
-halt with an error when building the source package are:
-<list compact>
-<item>Adding or removing symbolic links, sockets or pipes.
-<item>Changing the targets of symbolic links.
-<item>Creating directories, other than <tt/debian/.
-<item>Changes to the contents of binary files.
-</list>
-Changes which cause <prgn/dpkg-source/ to print a warning but continue
-anyway are:
-<list compact>
-<item>Removing files, directories or symlinks.  <footnote>Renaming a
-file is not treated specially - it is seen as the removal of the old
-file (which generates a warning, but is otherwise ignored), and the
-creation of the new one.</footnote>
-<item>Changed text files which are missing the usual final newline
-(either in the original or the modified source tree).
-</list>
-Changes which are not represented, but which are not detected by
-<prgn/dpkg-source/, are:
-<list compact>
-<item>Changing the permissions of files (other than
-<tt>debian/rules</>) and directories.
-</list>
-<p>
-
-The <tt/debian/ directory and <tt>debian/rules</> are handled
-specially by <prgn/dpkg-source/ - before applying the changes it will
-create the <tt/debian/ directory, and afterwards it will make
-<tt>debian/rules</> world-exectuable.
-
-<chapt id="controlfields">Control files and their fields
-<p>
-
-Many of the tools in the <prgn/dpkg/ suite manipulate data in a common
-format, known as control files.  Binary and source packages have
-control data as do the <tt/.changes/ files which control the
-installation of uploaded files, and <prgn/dpkg/'s internal databases
-are in a similar format.
-
-<sect>Syntax of control files
-<p>
-
-A file consists of one or more paragraphs of fields.  The paragraphs
-are separated by blank lines.  Some control files only allow one
-paragraph; others allow several, in which case each paragraph often
-refers to a different package.
-<p>
-
-Each paragraph is a series of fields and values; each field consists
-of a name, followed by a colon and the value.  It ends at the end of
-the line.  Horizontal whitespace (spaces and tabs) may occur before or
-after the value and is ignored there; it is conventional to put a
-single space after the colon.
-<p>
-
-Some fields' values may span several lines; in this case each
-continuation line <em/must/ start with a space or tab.  Any trailing
-spaces or tabs at the end of individual lines of a field value are
-ignored.
-<p>
-
-Except where otherwise stated only a single line of data is allowed
-and whitespace is not significant in a field body.  Whitespace may
-never appear inside names (of packages, architectures, files or
-anything else), version numbers or in between the characters of
-multi-character version relationships.
-<p>
-
-Field names are not case-sensitive, but it is usual to capitalise the
-fields using mixed case as shown below.
-<p>
-
-Blank lines, or lines consisting only of spaces and tabs, are not
-allowed within field values or between fields - that would mean a new
-paragraph.
-<p>
-
-It is important to note that there are several fields which are
-optional as far as <prgn/dpkg/ and the related tools are concerned,
-but which must appear in every Debian package, or whose omission may
-cause problems.  When writing the control files for Debian packages
-you <em/must/ read the Debian policy manual in conjuction with the
-details below and the list of fields for the particular file.
-
-<sect>List of fields
-
-<sect1 id="f-Package"><tt/Package/
-<p>
-
-The name of the binary package.  Package names consist of the
-alphanumerics and <tt/+/ <tt/-/ <tt/./ (plus, minus and full
-stop).<footnote>The characters <tt/@/ <tt/:/ <tt/=/ <tt/%/ <tt/_/ (at,
-colon, equals, percent and underscore) used to be legal and are still
-accepted when found in a package file, but may not be used in new
-packages</footnote>
-<p>
-
-They must be at least two characters and must start with an
-alphanumeric.  In current versions of dpkg they are sort of
-case-sensitive<footnote>This is a bug.</footnote>; use lowercase
-package names unless the package you're building (or referring to, in
-other fields) is already using uppercase.
-
-<sect1 id="f-Version"><tt/Version/
-<p>
-
-This lists the source or binary package's version number - see <ref
-id="versions">.
-
-<sect1 id="f-Architecture"><tt/Architecture/
-<p>
-
-This is the architecture string; it is a single word for the CPU
-architecture.
-<p>
-
-<prgn/dpkg/ will check the declared architecture of a binary package
-against its own compiled-in value before it installs it.
-<p>
-
-The special value <tt/all/ indicates that the package is
-architecture-independent.
-<p>
-
-In the main <tt>debian/control</> file in the source package, or in
-the source package control file <tt/.dsc/, a list of architectures
-(separated by spaces) is also allowed, as is the special value
-<tt/any/.  A list indicates that the source will build an
-architecture-dependent package, and will only work correctly on the
-listed architectures.  <tt/any/ indicates that though the source
-package isn't dependent on any particular architecture and should
-compile fine on any one, the binary package(s) produced are not
-architecture-independent but will instead be specific to whatever the
-current build architecture is.
-<p>
-
-In a <tt/.changes/ file the <tt/Architecture/ field lists the
-architecture(s) of the package(s) currently being uploaded.  This will
-be a list; if the source for the package is being uploaded too the
-special entry <tt/source/ is also present.
-<p>
-
-The current build architecture can be determined using <tt/dpkg
---print-architecture/.<footnote>This actually invokes
-<example>
-gcc --print-libgcc-file-name
-</example>
-and parses and decomposes the output and looks the CPU type from the
-GCC configuration in a table in <prgn/dpkg/.  This is so that it will
-work if you're cross-compiling.
-</footnote>
-This value is automatically used by <prgn/dpkg-gencontrol/ when
-building the control file for a binary package for which the source
-control information doesn't specify architecture <tt/all/.
-<p>
-
-There is a separate option, <tt/--print-installation-architecture/,
-for finding out what architecture <prgn/dpkg/ is willing to install.
-This information is also in the output of <tt/dpkg --version/.
-
-<sect1 id="f-Maintainer"><tt/Maintainer/
-<p>
-
-The package maintainer's name and email address.  The name should come
-first, then the email address inside angle brackets <tt/&lt;&gt/ (in
-RFC822 format).
-<p>
-
-If the maintainer's name contains a full stop then the whole field
-will not work directly as an email address due to a misfeature in the
-syntax specified in RFC822; a program using this field as an address
-must check for this and correct the problem if necessary (for example
-by putting the name in round brackets and moving it to the end, and
-bringing the email address forward).
-<p>
-
-In a <tt/.changes/ file or parsed changelog data this contains the
-name and email address of the person responsible for the particular
-version in question - this may not be the package's usual maintainer.
-<p>
-
-This field is usually optional in as far as the <prgn/dpkg/ are
-concerned, but its absence when building packages usually generates a
-warning.
-
-<sect1 id="f-Source"><tt/Source/
-<p>
-
-This field identifies the source package name.
-<p>
-
-In a main source control information or a <tt/.changes/ or <tt/.dsc/
-file or parsed changelog data this may contain only the name of the
-source package.
-<p>
-
-In the control file of a binary package (or in a <tt/Packages/ file)
-it may be followed by a version number in parentheses.<footnote>It is
-usual to leave a space after the package name if a version number is
-specified.</footnote> This version number may be omitted (and is, by
-<prgn/dpkg-gencontrol/) if it has the same value as the <tt/Version/
-field of the binary package in question.  The field itself may be
-omitted from a binary package control file when the source package has
-the same name and version as the binary package.
-
-<sect1>Package interrelationship fields:
-<tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/
-<tt/Suggests/, <tt/Conflicts/, <tt/Provides/, <tt/Replaces/
-<p>
-
-These fields describe the package's relationships with other packages.
-Their syntax and semantics are described in <ref id="relationships">.
-
-<sect1 id="f-Description"><tt/Description/
-<p>
-
-In a binary package <tt/Packages/ file or main source control file
-this field contains a description of the binary package, in a special
-format.  See <ref id="descriptions"> for details.
-<p>
-
-In a <tt/.changes/ file it contains a summary of the descriptions for
-the packages being uploaded.  The part of the field before the first
-newline is empty; thereafter each line has the name of a binary
-package and the summary description line from that binary package.
-Each line is indented by one space.
-
-<sect1 id="f-Essential"><tt/Essential/
-<p>
-
-This is a boolean field which may occur only in the control file of a
-binary package (or in the <tt/Packages/ file) or in a per-package
-fields paragraph of a main source control data file.
-<p>
-
-If set to <tt/yes/ then <prgn/dpkg/ and <prgn/dselect/ will refuse to
-remove the package (though it can be upgraded and/or replaced).  The
-other possible value is <tt/no/, which is the same as not having the
-field at all.
-
-<sect1 id="f-classification"><tt/Section/ and <tt/Priority/
-<p>
-
-These two fields classify the package.  The <tt/Priority/ represents
-how important that it is that the user have it installed; the
-<tt/Section/ represents an application area into which the package has
-been classified.
-<p>
-
-When they appear in the <tt>debian/control</> file these fields give
-values for the section and priority subfields of the <tt/Files/ field
-of the <tt/.changes/ file, and give defaults for the section and
-priority of the binary packages.
-<p>
-
-The section and priority are represented, though not as separate
-fields, in the information for each file in the <qref
-id="f-Files"><tt/Files/</> field of a <tt/.changes/ file.  The
-section value in a <tt/.changes/ file is used to decide where to
-install a package in the FTP archive.
-<p>
-
-These fields are not used by by <prgn/dpkg/ proper, but by
-<prgn/dselect/ when it sorts packages and selects defaults.  See the
-Debian policy manual for the priorities in use and the criteria for
-selecting the priority for a Debian package, and look at the Debian
-FTP archive for a list of currently in-use priorities.
-<p>
-
-These fields may appear in binary package control files, in which case
-they provide a default value in case the <tt/Packages/ files are
-missing the information.  <prgn/dpkg/ and <prgn/dselect/ will only use
-the value from a <tt/.deb/ file if they have no other information; a
-value listed in a <tt/Packages/ file will always take precedence.  By
-default <prgn/dpkg-genchanges/ does not include the section and
-priority in the control file of a binary package - use the <tt/-isp/,
-<tt/-is/ or <tt/-ip/ options to achieve this effect.
-
-<sect1 id="f-Binary"><tt/Binary/
-<p>
-
-This field is a list of binary packages.
-<p>
-
-When it appears in the <tt/.dsc/ file it is the list of binary
-packages which a source package can produce.  It does not necessarily
-produce all of these binary packages for every architecture.  The
-source control file doesn't contain details of which architectures are
-appropriate for which of the binary packages.
-<p>
-
-When it appears in a <tt/.changes/ file it lists the names of the
-binary packages actually being uploaded.
-<p>
-
-The syntax is a list of binary packages separated by
-commas.<footnote>A space after each comma is conventional.</footnote>
-Currently the packages must be separated using only spaces in the
-<tt/.changes/ file.
-
-<sect1 id="f-Installed-Size"><tt/Installed-Size/
-<p>
-
-This field appears in the control files of binary packages, and in the
-<tt/Packages/ files.  It gives the total amount of disk space
-required to install the named package.
-<p>
-
-The disk space is represented in kilobytes as a simple decimal number.
-
-<sect1 id="f-Files"><tt/Files/
-<p>
-
-This field contains a list of files with information about each one.
-The exact information and syntax varies with the context.  In all
-cases the the part of the field contents on the same line as the field
-name is empty.  The remainder of the field is one line per file, each
-line being indented by one space and containing a number of sub-fields
-separated by spaces.
-<p>
-
-In the <tt/.dsc/ (Debian source control) file each line contains the
-MD5 checksum, size and filename of the tarfile and (if applicable)
-diff file which make up the remainder of the source
-package.<footnote>That is, the parts which are not the
-<tt/.dsc/.</footnote> The exact forms of the filenames are described
-in <ref id="sourcearchives">.
-<p>
-
-In the <tt/.changes/ file this contains one line per file being
-uploaded.  Each line contains the MD5 checksum, size, section and
-priority and the filename.  The section and priority are the values of
-the corresponding fields in the main source control file - see <ref
-id="f-classification">.  If no section or priority is specified then
-<tt/-/ should be used, though section and priority values must be
-specified for new packages to be installed properly.
-<p>
-
-The special value <tt/byhand/ for the section in a <tt/.changes/ file
-indicates that the file in question is not an ordinary package file
-and must by installed by hand by the distribution maintainers.  If the
-section is <tt/byhand/ the priority should be <tt/-/.
-<p>
-
-If a new Debian revision of a package is being shipped and no new
-original source archive is being distributed the <tt/.dsc/ must still
-contain the <tt/Files/ field entry for the original source archive
-<tt/<var/package/-<var/upstream-version/.orig.tar.gz/, but the
-<tt/.changes/ file should leave it out.  In this case the original
-source archive on the distribution site must match exactly,
-byte-for-byte, the original source archive which was used to generate
-the <tt/.dsc/ file and diff which are being uploaded.
-
-
-<sect1 id="f-Standards-Version"><tt/Standards-Version/
-<p>
-
-The most recent version of the standards (the <prgn/dpkg/ programmers'
-and policy manuals and associated texts) with which the package
-complies.  This is updated manually when editing the source package to
-conform to newer standards; it can sometimes be used to tell when a
-package needs attention.
-<p>
-
-Its format is the same as that of a version number except that no
-epoch or Debian revision is allowed - see <ref id="versions">.
-
-
-<sect1 id="f-Distribution"><tt/Distribution/
-<p>
-
-In a <tt/.changes/ file or parsed changelog output this contains the
-(space-separated) name(s) of the distribution(s) where this version of
-the package should be or was installed.  Distribution names follow the
-rules for package names.  (See <ref id="f-Package">).
-<p>
-
-Current distribution values are:
-<taglist>
-<tag/<em/stable//
-<item>
-This is the current `released' version of Debian GNU/Linux.  A new
-version is released approximately every 3 months after the
-<em/development/ code has been <em/frozen/ for a month of testing.
-Once the distribution is <em/stable/ only major bug fixes are
-allowed. When changes are made to this distribution, the minor version
-number is increased (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
-
-<tag/<em/unstable//
-<item>
-This distribution value refers to the <em/developmental/ part of the Debian
-distribution tree. New packages, new upstream versions of packages and
-bug fixes go into the <em/unstable/ directory tree. Download
-from this distribution at your own risk.
-
-<tag/<em/contrib//
-<item>
-The packages with this distribution value do not meet the criteria for
-inclusion in the main Debian distribution as defined by the Policy
-Manual, but meet the criteria for the <em/contrib/ Distribution. There
-is currently no distinction between stable and unstable packages in
-the <em/contrib/ or <em/non-free/ distributions. Use your best
-judgement in downloading from this Distribution.
-
-<tag/<em/non-free//
-<item>
-Like the packages in the <em/contrib/ seciton, the packages in
-<em/non-free/ do not meet the criteria for inclusion in the main
-Debian distribution as defined by the Policy Manual. Again, use your
-best judgement in downloading from this Distribution.
-
-<tag/<em/experimental//
-<item>
-The packages with this distribution value are deemed by their
-maintainers to be high risk. Oftentimes they represent early beta or
-developmental packages from various sources that the maintainers want
-people to try, but are not ready to be a part of the other parts of
-the Debian distribution tree. Download at your own risk.
-
-<tag/<em/frozen//
-<item>
-From time to time, (currently, every 3 months) the <em/unstable/
-distribution enters a state of `code-freeze' in anticipation of
-release as a <em/stable/ version. During this period of testing
-(usually 4 weeks) only fixes for existing or newly-discovered bugs
-will be allowed.
-
-</taglist>
-<p>
-You should list <em/all/ distributions that the package should be
-installed into. Except in unusual circumstances, installations to
-<em/stable/ should also go into <em/frozen/ (if it exists) and
-<em/unstable/. Likewise, installations into <em/frozen/ should also go
-into <em/unstable/.
-
-<sect1 id="f-Urgency"><tt/Urgency/
-<p>
-
-This is a description of how important it is to upgrade to this
-version from previous ones.  It consists of a single keyword usually
-taking one of the values <tt/LOW/, <tt/MEDIUM/ or <tt/HIGH/) followed
-by an optional commentary (separated by a space) which is usually in
-parentheses.  For example:
-<example>
-Urgency: LOW (HIGH for diversions users)
-</example>
-<p>
-
-This field appears in the <tt/.changes/ file and in parsed changelogs;
-its value appears as the value of the <tt/urgency/ attribute in a
-<prgn/dpkg/-style changelog (see <ref id="dpkgchangelog">).
-<p>
-
-Urgency keywords are not case-sensitive.
-
-<sect1 id="f-Date"><tt/Date/
-<p>
-
-In <tt/.changes/ files and parsed changelogs, this gives the date the
-package was built or last edited.
-
-<sect1 id="f-Format"><tt/Format/
-<p>
-
-This field occurs in <tt/.changes/ files, and specifies a format
-revision for the file.  The format described here is version <tt/1.5/.
-The syntax of the format value is the same as that of a package
-version number except that no epoch or Debian revision is allowed -
-see <ref id="versions">.
-
-<sect1 id="f-Changes"><tt/Changes/
-<p>
-
-In a <tt/.changes/ file or parsed changelog this field contains the
-human-readable changes data, describing the differences between the
-last version and the current one.
-<p>
-
-There should be nothing in this field before the first newline; all
-the subsequent lines must be indented by at least one space; blank
-lines must be represented by a line consiting only of a space and a
-full stop.
-<p>
-
-Each version's change information should be preceded by a `title' line
-giving at least the version, distribution(s) and urgency, in a
-human-readable way.
-<p>
-
-If data from several versions is being returned the entry for the most
-recent version should be returned first, and entries should be
-separated by the representation of a blank line (the `title' line may
-also be followed by the representation of blank line).
-
-<sect1 id="f-Filename"><tt/Filename/ and <tt/MSDOS-Filename/
-<p>
-
-These fields in <tt/Packages/ files give the filename(s) of (the parts
-of) a package in the distribution directories, relative to the root of
-the Debian hierarchy.  If the package has been split into several
-parts the parts are all listed in order, separated by spaces.
-
-<sect1 id="f-Size"><tt/Size/ and <tt/MD5sum/
-<p>
-
-These fields in <tt/Packages/ files give the size (in bytes, expressed
-in decimal) and MD5 checksum of the file(s) which make(s) up a binary
-package in the distribution.  If the package is split into several
-parts the values for the parts are listed in order, separated by
-spaces.
-
-<sect1 id="f-Status"><tt/Status/
-<p>
-
-This field in <prgn/dpkg/'s status file records whether the user wants a
-package installed, removed or left alone, whether it is broken
-(requiring reinstallation) or not and what its current state on the
-system is.  Each of these pieces of information is a single word.
-
-<sect1 id="f-Config-Version"><tt/Config-Version/
-<p>
-
-If a package is not installed or not configured, this field in
-<prgn/dpkg/'s status file records the last version of the package which
-was successfully configured.
-
-<sect1 id="f-Conffiles"><tt/Conffiles/
-<p>
-
-This field in <prgn/dpkg/'s status file contains information about the
-automatically-managed configuration files held by a package.  This
-field should <em/not/ appear anywhere in a package!
-
-<sect1>Obsolete fields
-<p>
-
-These are still recognised by <prgn/dpkg/ but should not appear anywhere
-any more.
-
-<taglist compact>
-
-<tag><tt/Revision/
-<tag><tt/Package-Revision/
-<tag><tt/Package_Revision/
-<item>
-The Debian revision part of the package version was at one point in a
-separate control file field.  This field went through several names.
-
-<tag><tt/Recommended/
-<item>Old name for <tt/Recommends/
-
-<tag><tt/Optional/
-<item>Old name for <tt/Suggests/.
-
-<tag><tt/Class/
-<item>Old name for <tt/Priority/.
-
-</taglist>
-
-<chapt id="versions">Version numbering
-<p>
-
-Every package has a version number, in its <tt/Version/ control file
-field.
-<p>
-
-<prgn/dpkg/ imposes an ordering on version numbers, so that it can tell
-whether packages are being up- or downgraded and so that <prgn/dselect/
-can tell whether a package it finds available is newer than the one
-installed on the system.  The version number format has the most
-significant parts (as far as comparison is concerned) at the
-beginning.
-<p>
-
-The version number format is:
-&lsqb<var/epoch/<tt/:/&rsqb;<var/upstream-version/&lsqb;<tt/-/<var/debian-revision/&rsqb;.
-<p>
-
-The three components here are:
-
-<taglist>
-
-<tag><var/epoch/
-<item>
-
-This is a single unsigned integer, which should usually be small.  It
-may be omitted, in which case zero is assumed.  If it is omitted then
-the <var/upstream-version/ may not contain any colons.
-<p>
-
-It is provided to allow mistakes in the version numbers of older
-versions of a package, and also a package's previous version numbering
-schemes, to be left behind.
-<p>
-
-<prgn/dpkg/ will not usually display the epoch unless it is essential
-(non-zero, or if the <var/upstream-version/ contains a colon);
-<prgn/dselect/ does not display epochs at all in the main part of the
-package selection display.
-
-<tag><var/upstream-version/
-<item>
-
-This is the main part of the version.  It is usually version number of
-the original (`upstream') package of which the <tt/.deb/ file has been
-made, if this is applicable.  Usually this will be in the same format
-as that specified by the upstream author(s); however, it may need to
-be reformatted to fit into <prgn/dpkg/'s format and comparison scheme.
-<p>
-
-The comparison behaviour of <prgn/dpkg/ with respect to the
-<var/upstream-version/ is described below.  The <var/upstream-version/
-portion of the version number is mandatory.
-<p>
-
-The <var/upstream-version/ may contain only alphanumerics and the
-characters <tt/+/ <tt/./ <tt/-/ <tt/:/ (full stop, plus, hyphen,
-colon) and should start with a digit.  If there is no
-<var/debian-revision/ then hyphens are not allowed; if there is no
-<var/epoch/ then colons are not allowed.
-
-<tag><var/debian-revision/
-<item>
-
-This part of the version represents the version of the modifications
-that were made to the package to make it a Debian binary package.  It
-is in the same format as the <var/upstream-version/ and <prgn/dpkg/
-compares it in the same way.
-<p>
-
-It is optional; if it isn't present then the <var/upstream-version/
-may not contain a hyphen.  This format represents the case where a
-piece of software was written specifically to be turned into a Debian
-binary package, and so there is only one `debianization' of it and
-therefore no revision indication is required.
-<p>
-
-It is conventional to restart the <var/debian-revision/ at <tt/1/ each
-time the <var/upstream-version/ is increased.
-<p>
-
-<prgn/dpkg/ will break the <var/upstream-version/ and
-<var/debian-revision/ apart at the last hyphen in the string.  The
-absence of a <var/debian-revision/ compares earlier than the presence
-of one (but note that the <var/debian-revision/ is the least
-significant part of the version number).
-<p>
-
-The <var/debian-revision/ may contain only alphanumerics and the
-characters <tt/+/ and <tt/./ (plus and full stop).
-
-</taglist>
-
-The <var/upstream-version/ and <var/debian-revision/ parts are
-compared by <prgn/dpkg/ using the same algorithm:
-<p>
-
-The strings are compared from left to right.
-<p>
-
-First the initial part of each string consisting entirely of non-digit
-characters is determined.  These two parts (one of which may be empty)
-are compared lexically.  If a difference is found it is returned.  The
-lexical comparison is a comparison of ASCII values modified so that
-all the letters sort earlier than all the non-letters.
-<p>
-
-Then the initial part of the remainder of each string which consists
-entirely of digit characters is determined.  The numerical values of
-these two parts are compared, and any difference found is returned as
-the result of the comparison.  For these purposes an empty string
-(which can only occur at the end of one or both version strings being
-compared) counts as zero.
-<p>
-
-These two steps are repeated (chopping initial non-digit strings and
-initial digit strings off from the start) until a difference is found
-or both strings are exhausted.
-<p>
-
-Note that the purpose of epochs is to allow us to leave behind
-mistakes in version numbering, and to cope with situations where the
-version numbering changes.  It is <em/not/ there to cope with version
-numbers containing strings of letters which <prgn/dpkg/ cannot interpret
-(such as <tt/ALPHA/ or <tt/pre-/), or with silly orderings (the author
-of this manual has heard of a package whose versions went <tt/1.1/,
-<tt/1.2/, <tt/1.3/, <tt/1/, <tt/2.1/, <tt/2.2/, <tt/2/ and so forth).
-<p>
-
-If an upstream package has problematic version numbers they should be
-converted to a sane form for use in the <tt/Version/ field.
-<p>
-
-If you need to compare version numbers ina script, you may use
-<tt>dpkg --compare-versions ...</>. Type <tt>dpkg --help</> -->
---for details on arguments.
-
-<chapt id="maintainerscripts">Package maintainer scripts
-and installation procedure
-<sect>Introduction to package maintainer scripts
-<p>
-
-It is possible supply scripts as part of a package which <prgn/dpkg/
-will run for you when your package is installed, upgraded or removed.
-<p>
-
-These scripts should be the files <tt/preinst/, <tt/postinst/,
-<tt/prerm/ and <tt/postrm/ in the control area of the package.  They
-must be proper exectuable files; if they are scripts (which is
-recommended) they must start with the usual <tt/#!/ convention.  They
-should be readable and executable to anyone, and not world-writeable.
-<p>
-
-<prgn/dpkg/ looks at the exit status from these scripts.  It is
-important that they exit with a non-zero status if there is an error,
-so that <prgn/dpkg/ can stop its processing.  For shell scripts this
-means that you <em/almost always/ need to use <tt/set -e/ (this is
-usually true when writing shell scripts, in fact).  It is also
-important, of course, that they don't exit with a non-zero status if
-everything went well.
-<p>
-
-It is necessary for the error recovery procedures that the scripts be
-idempotent: ie, invoking the same script several times in the same
-situation should do no harm.  If the first call failed, or aborted
-half way through for some reason, the second call should merely do the
-things that were left undone the first time, if any, and exit with a
-success status.
-<p>
-
-When a package is upgraded a combination of the scripts from the old
-and new packages is called in amongst the other steps of the upgrade
-procedure.  If your scripts are going to be at all complicated you
-need to be aware of this, and may need to check the arguments to your
-scripts.
-<p>
-
-Broadly speaking the <prgn/preinst/ is called before (a particular
-version of) a package is installed, and the <prgn/postinst/ afterwards;
-the <prgn/prerm/ before (a version of) a package is removed and the
-<prgn/postrm/ afterwards.
-<p>
-<!--
- next paragraph by Guy Maor to close bug #2481
- --> 
-
-Programs called from maintainer scripts should not normally have a
-path prepended to them. Before installation is started <prgn/dpkg/
-checks to see if the programs <prgn/ldconfig/,
-<prgn/start-stop-daemon/, <prgn/install-info/, and <prgn/update-rc.d/
-can be found via the <tt/PATH/ environment variable. Those programs,
-and any other program that one would expect to on the <tt/PATH/,
-should thus be invoked without an absolute pathname. Maintainer
-scripts should also not reset the <tt/PATH/, though they might choose
-to modify it by pre- or appending package-specific directories. These
-considerations really apply to all shell scripts.
-
-<sect id="mscriptsinstact">Summary of ways maintainer scripts are called
-<p>
-
-<list compact>
-<item><var/new-preinst/ <tt/install/
-<item><var/new-preinst/ <tt/install/ <var/old-version/
-<item><var/new-preinst/ <tt/upgrade/ <var/old-version/
-<item><var/old-preinst/ <tt/abort-upgrade/ <var/new-version/
-</list>
-<p>
-
-<list compact>
-<item><var/postinst/ <tt/configure/ <var/most-recently-configured-version/
-<item><var/old-postinst/ <tt/abort-upgrade/ <var/new version/
-<item><var/conflictor's-postinst/ <tt/abort-remove/
-    <tt/in-favour/ <var/package/ <var/new-version/
-<item><var/deconfigured's-postinst/ <tt/abort-deconfigure/
-    <tt/in-favour/ <var/failed-install-package/ <var/version/
-    <tt/removing/ <var/conflicting-package/ <var/version/
-</list>
-<p>
-
-<list compact>
-<item><var/prerm/ <tt/remove/
-<item><var/old-prerm/ <tt/upgrade/ <var/new-version/
-<item><var/new-prerm/ <tt/failed-upgrade/ <var/old-version/
-<item><var/conflictor's-prerm/ <tt/remove/ <tt/in-favour/
-    <var/package/ <var/new-version/
-<item><var/deconfigured's-prerm/ <tt/deconfigure/
-    <tt/in-favour/ <var/package-being-installed/ <var/version/
-    <tt/removing/ <var/conflicting-package/ <var/version/
-</list>
-<p>
-
-<list compact>
-<item><var/postrm/ <tt/remove/
-<item><var/postrm/ <tt/purge/
-<item><var/old-postrm/ <tt/upgrade/ <var/new-version/
-<item><var/new-postrm/ <tt/failed-upgrade/ <var/old-version/
-<item><var/new-postrm/ <tt/abort-install/
-<item><var/new-postrm/ <tt/abort-install/ <var/old-version/
-<item><var/new-postrm/ <tt/abort-upgrade/ <var/old-version/
-<item><var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/new-version/
-</list>
-
-
-<sect id="unpackphase">Details of unpack phase of installation or upgrade
-<p>
-
-The procedure on installation/upgrade/overwrite/disappear (ie, when
-running <tt/dpkg --unpack/, or the unpack stage of <tt/dpkg
---install/) is as follows.  In each case if an error occurs the
-actions in are general run backwards - this means that the maintainer
-scripts are run with different arguments in reverse order.  These are
-the `error unwind' calls listed below.
-
-<enumlist>
-<item>
-
-<enumlist>
-<item>
-If a version the package is already
-installed, call
-<example>
-<var/old-prerm/ upgrade <var/new-version/
-</example>
-
-<item>
-If this gives an error (ie, a non-zero exit status), dpkg will
-attempt instead:
-<example>
-<var/new-prerm/ failed-upgrade <var/old-version/
-</example>
-Error unwind, for both the above cases:
-<example>
-<var/old-postinst/ abort-upgrade <var/new-version/
-</example>
-
-</enumlist>
-
-<item>
-If a `conflicting' package is being removed at the same time:
-<enumlist>
-
-<item>
-If any packages depended on that conflicting package and
-<tt/--auto-deconfigure/ is specified, call, for each such package:
-<example>
-<var/deconfigured's-prerm/ deconfigure \
-    in-favour <var/package-being-installed/ <var/version/ \
-    removing <var/conflicting-package/ <var/version/
-</example>
-Error unwind:
-<example>
-<var/deconfigured's-postinst/ abort-deconfigure \
-    in-favour <var/package-being-installed-but-failed/ <var/version/ \
-    removing <var/conflicting-package/ <var/version/
-</example>
-The deconfigured packages are marked as requiring configuration, so
-that if <tt/--install/ is used they will be configured again if
-possible.
-
-<item>
-To prepare for removal of the conflicting package, call:
-<example>
-<var/conflictor's-prerm/ remove in-favour <var/package/ <var/new-version/
-</example>
-Error unwind:
-<example>
-<var/conflictor's-postinst/ abort-remove \
-    in-favour <var/package/ <var/new-version/
-</example>
-
-</enumlist>
-
-<item>
-<enumlist>
-<item>
-If the package is being upgraded, call:
-<example>
-<var/new-preinst/ upgrade <var/old-version/
-</example>
-
-<item>
-Otherwise, if the package had some configuration files from a previous
-version installed (ie, it is in the `configuration files only' state):
-<example>
-<var/new-preinst/ install <var/old-version/
-</example>
-
-<item>
-Otherwise (ie, the package was completely purged):
-<example>
-<var/new-preinst/ install
-</example>
-Error unwind versions, respectively:
-<example>
-<var/new-postrm/ abort-upgrade <var/old-version/
-<var/new-postrm/ abort-install <var/old-version/
-<var/new-postrm/ abort-install
-</example>
-
-</enumlist>
-
-<item>
-The new package's files are unpacked, overwriting any that may be on
-the system already, for example any from the old version of the same
-package or from another package (backups of the old files are left
-around, and if anything goes wrong dpkg will attempt to put them back
-as part of the error unwind).
-<p>
-
-It is an error for a package to contains files which are on the system
-in another package, unless <tt/Replaces/ is used (see
-<ref id="replaces">).  Currently the <tt/--force-overwrite/ flag is
-enabled, downgrading it to a warning, but this may not always be the
-case.
-<p>
-
-It is a more serious error for a package to contain a plain file or
-other kind of nondirectory where another package has a directory
-(again, unless <tt/Replaces/ is used).  This error can be overridden
-if desired using <tt/--force-overwrite-dir/, but this is not advisable.
-<p>
-
-Packages which overwrite each other's files produce behaviour which
-though deterministic is hard for the system administrator to
-understand.  It can easily lead to `missing' programs if, for example,
-a package is installed which overwrites a file from another package,
-and is then removed again.<footnote>Part of the problem is due to what
-is arguably a bug in <prgn/dpkg/.</footnote>
-<p>
-
-A directory will never be replaced by a symbolic links to a directory
-or vice versa; instead, the existing state (symlink or not) will be
-left alone and <prgn/dpkg/ will follow the symlink if there is one.
-
-<item>
-
-<enumlist>
-<item>
-If the package is being upgraded, call
-<example>
-<var/old-postrm/ upgrade <var/new-version/
-</example>
-
-<item>
-If this fails, <prgn/dpkg/ will attempt:
-<example>
-<var/new-postrm/ failed-upgrade <var/old-version/
-</example>
-Error unwind, for both cases:
-<example>
-<var/old-preinst/ abort-upgrade <var/new-version/
-</example>
-
-</enumlist>
-
-This is the point of no return - if <prgn/dpkg/ gets this far, it won't
-back off past this point if an error occurs.  This will leave the
-package in a fairly bad state, which will require a successful
-reinstallation to clear up, but it's when <prgn/dpkg/ starts doing
-things that are irreversible.
-
-<item>
-Any files which were in the old version of the package but not in the
-new are removed.
-
-<item>
-The new file list replaces the old.
-
-<item>
-The new maintainer scripts replace the old.
-
-<item>
-Any packages all of whose files have been overwritten during the
-installation, and which aren't required for dependencies, are considered
-to have been removed.  For each such package,
-
-<enumlist>
-<item>
-<prgn/dpkg/ calls:
-<example>
-<var/disappearer's-postrm/ disappear \
-    <var/overwriter/ <var/overwriter-version/
-</example>
-
-<item>
-The package's maintainer scripts are removed.
-
-<item>
-It is noted in the status database as being in a sane state, namely
-not installed (any conffiles it may have are ignored, rather than
-being removed by <prgn/dpkg/).  Note that disappearing packages do not
-have their prerm called, because <prgn/dpkg/ doesn't know in advance
-that the package is going to vanish.
-
-</enumlist>
-
-<item>
-Any files in the package we're unpacking that are also listed in the
-file lists of other packages are removed from those lists.  (This will
-lobotomise the file list of the `conflicting' package if there is one.)
-
-<item>
-The backup files made during installation, above, are deleted.
-
-<item>
-The new package's status is now sane, and recorded as `unpacked'.  Here
-is another point of no return - if the conflicting package's removal
-fails we do not unwind the rest of the installation; the conflicting
-package is left in a half-removed limbo.
-
-<item>
-If there was a conflicting package we go and do the removal actions
-(described below), starting with the removal of the conflicting
-package's files (any that are also in the package being installed
-have already been removed from the conflicting package's file list,
-and so do not get removed now).
-
-</enumlist>
-
-<sect>Details of configuration
-<p>
-
-When we configure a package (this happens with <tt/dpkg --install/, or
-with <tt/--configure/), we first update the conffiles and then call:
-<example>
-<var/postinst/ configure <var/most-recently-configured-version/
+<debiandoc>
+  <book>
+
+    <titlepag><title>Debian Packaging Manual</title>
+      <author>
+	<name>Ian Jackson </name>
+	<email>ijackson@gnu.ai.mit.edu</email>
+      </author>
+      <author>
+	<name>Revised: David A. Morris</name>
+	<email>bweaver@debian.org</email>
+      </author>
+      <author>
+	<name>Maintainer: Christian Schwarz </name>
+	<email>schwarz@debian.org</email>
+      </author>
+      <author>
+	<name>Maintainer: Manoj Srivastava </name>
+	<email>srivasta@debian.org</email>
+      </author>
+      <author>
+	<name>Maintainer: The Debian Policy group </name>
+	<email>debian-policy@lists.debian.org</email>
+      </author>
+      <version>version &version;, &date;</version>
+	
+      <abstract>
+	This manual describes the technical aspects of creating Debian
+	binary and source packages.  It also documents the interface
+	between <prgn>dselect</prgn> and its access method scripts.
+	It does not deal with the Debian Project policy requirements,
+	and it assumes familiarity with <prgn>dpkg</prgn>'s functions
+	from the system administrator's perspective.
+
+      <copyright>
+	<copyrightsummary>Copyright &copy;1996 Ian Jackson.</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
+	  <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
+	  distribution or on the World Wide Web at
+	  <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
+	  obtain it by writing to the Free Software Foundation, Inc.,
+	  59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+	</p>
+      </copyright>
+
+    <toc detail="sect">
+
+    <!-- Describes the technical interface between a package and dpkg.
+
+    How to safely put shared libraries in a package.  Details of
+    dpkg's handling of individual files.  Sections on when to use
+    which feature (eg Replaces vs. Replaces/Conflicts
+    vs. update-alternatives vs. diversions) Cross-references to the
+    policy document (see below) where appropriate.  Description of the
+    interface between dselect and its access methods.  Hints on where
+    to start with a new package (ie, the hello package).  What to do
+    about file aliasing.
+    
+    file aliasing
+    
+    Manpages are required for: update-rc.d, diversions,
+    update-alternatives, install-info in a package.
+
+    -->
+
+    <chapt id="scope">
+      <heading>Introduction and scope of this manual</heading>
+
+      <p>
+	<prgn>dpkg</prgn> is a suite of programs for creating binary
+	package files and installing and removing them on Unix
+	systems.<footnote>
+	  <p>
+	    <prgn>dpkg</prgn> is targetted primarily at Debian
+	    GNU/Linux, but may work on or be ported to other
+	    systems.
+	  </p>
+	</footnote>
+      </p>
+
+      <p>
+	The binary packages are designed for the management of
+	installed executable programs (usually compiled binaries) and
+	their associated data, though source code examples and
+	documentation are provided as part of some packages.</p>
+
+      <p>
+	This manual describes the technical aspects of creating Debian
+	binary packages (<tt>.deb</tt> files).  It documents the
+	behaviour of the package management programs
+	<prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and and the way
+	they interact with packages.</p>
+
+      <p>
+	It also documents the interaction between
+	<prgn>dselect</prgn>'s core and the access method scripts it
+	uses to actually install the selected packages, and describes
+	how to create a new access method.</p>
+	
+      <p>
+	This manual does not go into detail about the options and
+	usage of the package building and installation tools.  It
+	should therefore be read in conjuction with those programs'
+	manpages.
+      </p>	
+
+      <p>
+	The utility programs which are provided with <prgn>dpkg</prgn>
+	for managing various system configuration and similar issues,
+	such as <prgn>update-rc.d</prgn> and
+	<prgn>install-info</prgn>, are not described in detail here -
+	please see their manpages.
+      </p>
+	
+      <p>
+	It does <em>not</em> describe the policy requirements imposed
+	on Debian packages, such as the permissions on files and
+	directories, documentation requirements, upload procedure, and
+	so on.  You should see the Debian packaging policy manual for
+	these details.  (Many of them will probably turn out to be
+	helpful even if you don't plan to upload your package and make
+	it available as part of the distribution.)
+      </p>
+	
+      <p>
+	It is assumed that the reader is reasonably familiar with the
+	<prgn>dpkg</prgn> System Administrators' manual.
+	Unfortunately this manual does not yet exist.
+      </p>
+	
+      <p>
+	The Debian version of the FSF's GNU hello program is provided
+	as an example for people wishing to create Debian
+	packages. The Debian <prgn>debmake</prgn> package is
+	recommended as a very helpful tool in creating and maintaining
+	Debian packages. However, while the tools and examples are
+	helpful, they do not replace the need to read and follow the
+	Policy and Programmer's Manual.</p>
+    </chapt>
+      
+    <chapt id="binarypkg"><heading>Binary packages
+      </heading>
+	
+      <p>
+	The binary package has two main sections.  The first part
+	consists of various control information files and scripts used
+	by <prgn>dpkg</prgn> when installing and removing.  See <ref
+	id="controlarea">.
+      </p>
+	
+      <p>
+	The second part is an archive containing the files and
+	directories to be installed.
+      </p>
+	
+      <p>
+	In the future binary packages may also contain other
+	components, such as checksums and digital signatures. The
+	format for the archive is described in full in the
+	<tt>deb(5)</tt> manpage.
+      </p>
+	
+	
+      <sect id="bincreating"><heading>Creating package files -
+      <prgn>dpkg-deb</prgn>
+	</heading>
+	  
+	<p>
+	  All manipulation of binary package files is done by
+	  <prgn>dpkg-deb</prgn>; it's the only program that has
+	  knowledge of the format.  (<prgn>dpkg-deb</prgn> may be
+	  invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
+	  will spot that the options requested are appropriate to
+	  <prgn>dpkg-deb</prgn> and invoke that instead with the same
+	  arguments.)
+	</p>
+	  
+	<p>
+	  In order to create a binary package you must make a
+	  directory tree which contains all the files and directories
+	  you want to have in the filesystem data part of the package.
+	  In Debian-format source packages this directory is usually
+	  <tt>debian/tmp</tt>, relative to the top of the package's
+	  source tree.
+	</p>
+	  
+	<p>
+	  They should have the locations (relative to the root of the
+	  directory tree you're constructing) ownerships and
+	  permissions which you want them to have on the system when
+	  they are installed.
+	</p>
+	  
+	<p>
+	  With current versions of <prgn>dpkg</prgn> the uid/username
+	  and gid/groupname mappings for the users and groups being
+	  used should be the same on the system where the package is
+	  built and the one where it is installed.
+	</p>
+	  
+	<p>
+	  You need to add one special directory to the root of the
+	  miniature filesystem tree you're creating:
+	  <prgn>DEBIAN</prgn>.  It should contain the control
+	  information files, notably the binary package control file
+	  (see <ref id="controlfile">).
+	</p>
+	  
+	<p>
+	  The <prgn>DEBIAN</prgn> directory will not appear in the
+	  filesystem archive of the package, and so won't be installed
+	  by <prgn>dpkg</prgn> when the package is installed.
+	</p>
+	  
+	<p>
+	  When you've prepared the package, you should invoke:
+	  <example>
+	    dpkg --build <var>directory</var>
+	  </example>
+	</p>
+	  
+	<p>
+	  This will build the package in
+	  <tt><var>directory</var>.deb</tt>.  (<prgn>dpkg</prgn> knows
+	  that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
+	  it invokes <prgn>dpkg-deb</prgn> with the same arguments to
+	  build the package.)
+	</p>
+	  
+	<p>
+	  See the manpage <manref name="dpkg-deb" section="8"> for details of how
+	  to examine the contents of this newly-created file.  You may find the
+	  output of following commands enlightening:
+	  <example>
+dpkg-deb --info <var>filename</var>.deb
+dpkg-deb --contents <var>filename</var>.deb
+dpkg --contents <var>filename</var>.deb
 </example>
-<p>
-
-No attempt is made to unwind after errors during configuration.
-<p>
-
-If there is no most recently configured version <prgn/dpkg/ will pass a
-null argument; older versions of dpkg may pass
-<tt>&lt;unknown&gt;</tt> (including the angle brackets) in this case.
-Even older ones do not pass a second argument at all, under any
-circumstances.
-
-<sect>Details of removal and/or configuration purging
-<p>
-
-<enumlist>
-<item>
+	  To view the copyright file for a package you could use this command:
 <example>
-<var/prerm/ remove
-</example>
+dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
+</example></p>
+	
+      <sect id="controlarea">
+	<heading>
+	  Package control information files
+	</heading>
+	  
+	<p>
+	  The control information portion of a binary package is a
+	  collection of files with names known to <prgn>dpkg</prgn>.
+	  It will treat the contents of these files specially - some
+	  of them contain information used by <prgn>dpkg</prgn> when
+	  installing or removing the package; others are scripts which
+	  the package maintainer wants <prgn>dpkg</prgn> to run.
+	</p>
+	  
+	<p>
+	  It is possible to put other files in the package control
+	  area, but this is not generally a good idea (though they
+	  will largely be ignored).
+	</p>
+	  
+	<p>
+	  Here is a brief list of the control info files supported by
+	  <prgn>dpkg</prgn> and a summary of what they're used for.
+	</p>
+	  
+	<p>
+	  <taglist>
+	    <tag><tt>control</tt>
+	    <item>
+	      
+	      <p>
+		This is the key description file used by
+		<prgn>dpkg</prgn>.  It specifies the package's name
+		and version, gives its description for the user,
+		states its relationships with other packages, and so
+		forth.  See <ref id="controlfile">.
+	      </p>
+		
+	      <p>
+		It is usually generated automatically from information
+		in the source package by the
+		<prgn>dpkg-gencontrol</prgn> program, and with
+		assistance from <prgn>dpkg-shlibdeps</prgn>.  See <ref
+		id="sourcetools">.</p>
+	    </item>
+	      
+	    <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
+	    <tt>prerm</tt>
+	    </tag>
+	    <item>
+	      
+	      <p>
+		These are exectuable files (usually scripts) which
+		<prgn>dpkg</prgn> runs during installation, upgrade
+		and removal of packages.  They allow the package to
+		deal with matters which are particular to that package
+		or require more complicated processing than that
+		provided by <prgn>dpkg</prgn>.  Details of when and
+		how they are called are in <ref
+		id="maintainerscripts">.
+	      </p>
+		
+	      <p>
+		It is very important to make these scripts
+		idempotent.
+		<footnote>
+		  <p>
+		    That means that if it runs successfully or fails
+		    and then you call it again it doesn't bomb out,
+		    but just ensures that everything is the way it
+		    ought to be.
+		  </p>
+		</footnote> This is so that if an error occurs, the
+		user interrupts <prgn>dpkg</prgn> or some other
+		unforeseen circumstance happens you don't leave the
+		user with a badly-broken package.
+	      </p>
+		
+	      <p>
+		The maintainer scripts are guaranteed to run with a
+		controlling terminal and can interact with the user.
+		If they need to prompt for passwords, do full-screen
+		interaction or something similar you should do these
+		things to and from <tt>/dev/tty</tt>, since
+		<prgn>dpkg</prgn> will at some point redirect scripts'
+		standard input and output so that it can log the
+		installation process.  Likewise, because these scripts
+		may be executed with standard output redirected into a
+		pipe for logging purposes, Perl scripts should set
+		unbuffered output by setting <tt>$|=1</tt> so that the
+		output is printed immediately rather than being
+		buffered.
+	      </p>
+		
+	      <p>
+		Each script should return a zero exit status for
+		success, or a nonzero one for failure.</p>
+	    </item>
+	      
+	    <tag><tt>conffiles</tt>
+	    </tag>
+	    <item>
+	      
+	      <p>
+		This file contains a list of configuration files which
+		are to be handled automatically by <prgn>dpkg</prgn>
+		(see <ref id="conffiles">).  Note that not necessarily
+		every configuration file should be listed here.</p>
+	    </item>
+	      
+	    <tag><tt>shlibs</tt>
+	    </tag>
+	    <item>
+	      
+	      <p>
+		This file contains a list of the shared libraries
+		supplied by the package, with dependency details for
+		each.  This is used by <prgn>dpkg-shlibdeps</prgn>
+		when it determines what dependencies are required in a
+		package control file. The <tt>shlibs</tt> file format
+		is described on <ref id="shlibs">.
+	      </p>
+	    </item>
+	  </taglist>
+	</p>
+	
+      <sect id="controlfile">
+	<heading>
+	  The main control information file: <tt>control</tt>
+	</heading>
+	<p>
+	  The most important control information file used by
+	  <prgn>dpkg</prgn> when it installs a package is
+	  <tt>control</tt>.  It contains all the package's `vital
+	  statistics'.
+	</p>
+
+	<p>	  
+	  The binary package control files of packages built from
+	  Debian sources are made by a special tool,
+	  <prgn>dpkg-gencontrol</prgn>, which reads
+	  <tt>debian/control</tt> and <tt>debian/changelog</tt> to
+	  find the information it needs.  See <ref id="sourcepkg"> for
+	  more details.
+	</p>
+
+	<p>	  
+	  The fields in binary package control files are:
+	  <list compact="compact">
+	    <item>
+	      <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
+	    </item>
+	    <item>
+	      <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+	    </item>
+	    <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
+		(mandatory)
+		<footnote>
+		  <p>
+		    This field should appear in all packages, though
+		    <prgn>dpkg</prgn> doesn't require it yet so that
+		    old packages can still be installed.
+		  </p>
+		</footnote>
+	      </p>
+	    </item>
+	    <item>
+	      <p><qref id="relationships"><tt>Depends</tt>,
+		  <tt>Provides</tt> et al.</qref></p>
+	    </item>
+	    <item>
+	      <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
+	    </item>
+	    <item>
+	      <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
+	    </item>
+	    <item>
+	      <p><qref id="f-classification"><tt>Section</tt>,
+		  <tt>Priority</tt></qref></p>
+	    </item>
+	    <item>
+	      <p><qref id="f-Source"><tt>Source</tt></qref></p>
+	    </item>
+	    <item>
+	      <p><qref id="descriptions"><tt>Description</tt></qref></p>
+	    </item>
+	    <item>
+	      <p>
+		<qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
+	      </p>
+	    </item> 
+	  </list>
+	    
+	<p>
+	  A description of the syntax of control files and the purpose
+	  of these fields is available in <ref id="controlfields">.
+	</p>
+      </sect>
+      <sect>
+	<heading>Time Stamps</heading>
+	<p>
+	  Maintainers are encouraged to preserve the modification
+	  times of the upstream source files in a package, as far as
+	  is reasonably possible. 
+	  <footnote>
+	    <p>
+	      The rationale is that there is some information conveyed
+	      by knowing the age of the file, for example, you could
+	      recognize that some documentation is very old by looking
+	      at the modification time, so it would be nice if the
+	      modification time of the upstream source would be
+	      preserved.
+	    </p>
+	  </footnote>
+	</p>
+      </sect>
+      
+    <chapt id="sourcepkg">
+      <heading>Source packages</heading>
+
+      <p>	
+	The Debian binary packages in the distribution are generated
+	from Debian sources, which are in a special format to assist
+	the easy and automatic building of binaries.
+      </p>
+
+      <p>	
+	There was a previous version of the Debian source format,
+	which is now being phased out.  Instructions for converting an
+	old-style package are given in the Debian policy manual.
+      </p>
+	
+      <sect id="sourcetools">
+	<heading>Tools for processing source packages</heading> 
+
+	<p>	  
+	  Various tools are provided for manipulating source packages;
+	  they pack and unpack sources and help build of binary
+	  packages and help manage the distribution of new versions.
+	</p>
+
+	<p>	  
+	  They are introduced and typical uses described here; see
+	  <manref name="dpkg-source" section="1"> for full
+	  documentation about their arguments and operation.
+	</p>
+
+	<p>	  
+	  For examples of how to construct a Debian source package,
+	  and how to use those utilities that are used by Debian
+	  source packages, please see the <prgn>hello</prgn> example
+	  package.
+	</p>
+	  
+	<sect1>
+	  <heading>
+	    <prgn>dpkg-source</prgn> - packs and unpacks Debian source
+	    packages
+	  </heading>
+
+	  <p>	    
+	    This program is frequently used by hand, and is also
+	    called from package-independent automated building scripts
+	    such as <prgn>dpkg-buildpackage</prgn>.
+	  </p>
+
+	  <p>	    
+	    To unpack a package it is typically invoked with
+	    <example>
+	      dpkg-source -x <var>.../path/to/filename</var>.dsc
+	    </example> 
+	  </p>
+
+	   <p>	
+	    with the <tt><var>filename</var>.tar.gz</tt> and
+	    <tt><var>filename</var>.diff.gz</tt> (if applicable) in
+	    the same directory.  It unpacks into
+	    <tt><var>package</var>-<var>version</var></tt>, and if
+	    applicable
+	    <tt><var>package</var>-<var>version</var>.orig</tt>, in
+	    the current directory.
+	  </p>
+
+	  <p>	    
+	    To create a packed source archive it is typically invoked:
+	    <example>
+	      dpkg-source -b <var>package</var>-<var>version</var>
+	  </example>
+	  </p>
+
+	  <p>
+	    This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
+	    <tt>.diff.gz</tt> (if appropriate) in the current
+	    directory.  <prgn>dpkg-source</prgn> does not clean the
+	    source tree first - this must be done separately if it is
+	    required.
+	  </p>
+
+	  <p>	    
+	    See also <ref id="sourcearchives">.</p>
+	</sect1>
+	  
+	  
+	<sect1>
+	  <heading>
+	    <prgn>dpkg-buildpackage</prgn> - overall package-building
+	    control script
+	  </heading>
+
+	  <p>	    
+	    <prgn>dpkg-buildpackage</prgn> is a script which invokes
+	    <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
+	    targets <prgn>clean</prgn>, <prgn>build</prgn> and
+	    <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
+	    <prgn>pgp</prgn> to build a signed source and binary
+	    package upload.
+	  </p>
+
+	  <p>	    
+	    It is usually invoked by hand from the top level of the
+	    built or unbuilt source directory.  It may be invoked with
+	    no arguments; useful arguments include:
+	    <taglist compact="compact">
+	      <tag><tt>-uc</tt>, <tt>-us</tt></tag>
+	      <item>
+		<p>
+		  Do not PGP-sign the <tt>.changes</tt> file or the
+		  source package <tt>.dsc</tt> file, respectively.</p>
+	      </item>
+	      <tag><tt>-p<var>pgp-command</var></tt></tag>
+	      <item>
+		<p>
+		  Invoke <var>pgp-command</var> instead of finding
+		  <tt>pgp</tt> on the <prgn>PATH</prgn>.
+		  <var>pgp-command</var> must behave just like
+		  <prgn>pgp</prgn>.</p>
+	      </item>
+	      <tag><tt>-r<var>root-command</var></tt></tag>
+	      <item>
+		<p>
+		  When root privilege is required, invoke the command
+		  <var>root-command</var>.  <var>root-command</var>
+		  should invoke its first argument as a command, from
+		  the <prgn>PATH</prgn> if necessary, and pass its
+		  second and subsequent arguments to the command it
+		  calls.  If no <var>root-command</var> is supplied
+		  then <var>dpkg-buildpackage</var> will take no
+		  special action to gain root privilege, so that for
+		  most packages it will have to be invoked as root to
+		  start with.</p>
+	      </item>
+	      <tag><tt>-b</tt>, <tt>-B</tt></tag>
+	      <item>
+		<p>
+		  Two types of binary-only build and upload - see
+		  <manref name="dpkg-source" section="1">.
+		</p>
+	      </item>
+	    </taglist>
+	  </p>
+	</sect1>
+	  
+	<sect1>
+	  <heading>
+	    <prgn>dpkg-gencontrol</prgn> - generates binary package
+	    control files
+	  </heading>
+
+	  <p>	    
+	    This program is usually called from <tt>debian/rules</tt>
+	    (see <ref id="sourcetree">) in the top level of the source
+	    tree.
+	  </p>
+
+	  <p>	    
+	    This is usually done just before the files and directories in the
+	    temporary directory tree where the package is being built have their
+	    permissions and ownerships set and the package is constructed using
+	    <prgn>dpkg-deb/</prgn>
+	      <footnote>
+	      <p>
+		This is so that the control file which is produced has
+		the right permissions
+	      </p>
+	    </footnote>.
+	  </p>
+
+	  <p>	    
+	    <prgn>dpkg-gencontrol</prgn> must be called after all the
+	    files which are to go into the package have been placed in
+	    the temporary build directory, so that its calculation of
+	    the installed size of a package is correct.
+	  </p>
+
+	  <p>	    
+	    It is also necessary for <prgn>dpkg-gencontrol</prgn> to
+	    be run after <prgn>dpkg-shlibdeps</prgn> so that the
+	    variable substitutions created by
+	    <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
+	    are available.
+	  </p>
+
+	  <p>	    
+	    For a package which generates only one binary package, and
+	    which builds it in <tt>debian/tmp</tt> relative to the top
+	    of the source package, it is usually sufficient to call:
+	    <example>
+	      dpkg-gencontrol
+	    </example>
+	  </p>
+
+	  <p>	    
+	    Sources which build several binaries will typically need
+	    something like:
+	    <example>
+	      dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
+	    </example> The <tt>-P</tt> tells
+	    <prgn>dpkg-gencontrol</prgn> that the package is being
+	    built in a non-default directory, and the <tt>-p</tt>
+	    tells it which package's control file should be generated.
+	  </p>
+
+	  <p>	    
+	    <prgn>dpkg-gencontrol</prgn> also adds information to the
+	    list of files in <tt>debian/files</tt>, for the benefit of
+	    (for example) a future invocation of
+	    <prgn>dpkg-genchanges</prgn>.</p>
+	</sect1>
+	  
+	<sect1>
+	  <heading>
+	    <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+	    dependencies
+	  </heading>
+
+	  <p>	    
+	    This program is usually called from <tt>debian/rules</tt>
+	    just before <prgn>dpkg-gencontrol</prgn> (see <ref
+	    id="sourcetree">), in the top level of the source tree.
+	  </p>
+
+	  <p>	    
+	    Its arguments are executables
+	    <footnote>
+	      <p>
+		They may be specified either in the locations in the
+		source tree where they are created or in the locations
+		in the temporary build tree where they are installed
+		prior to binary package creation.
+	      </p>
+	    </footnote> for which shared library dependencies should
+	    be included in the binary package's control file.
+	  </p>
+
+	  <p>	    
+	    If some of the executable(s) shared libraries should only
+	    warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
+	    some warrant a <tt>Pre-Depends</tt>, this can be achieved
+	    by using the <tt>-d<var>dependency-field</var></tt> option
+	    before those executable(s).  (Each <tt>-d</tt> option
+	    takes effect until the next <tt>-d</tt>.)
+	  </p>
+
+	  <p>	    
+	    <prgn>dpkg-shlibdeps</prgn> does not directly cause the
+	    output control file to be modified.  Instead by default it
+	    adds to the <tt>debian/substvars</tt> file variable
+	    settings like <tt>shlibs:Depends</tt>.  These variable
+	    settings must be referenced in dependency fields in the
+	    appropriate per-binary-package sections of the source
+	    control file.
+	  </p>
+
+	  <p>	    
+	    For example, the <prgn>procps</prgn> package generates two
+	    kinds of binaries, simple C binaries like <prgn>ps</prgn>
+	    which require a predependency and full-screen ncurses
+	    binaries like <prgn>top</prgn> which require only a
+	    recommendation.  It can say in its <tt>debian/rules</tt>:
+	    <example>
+	      dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+	    </example>
+	    and then in its main control file <tt>debian/control</tt>:
+	    <example>
+	      <var>...</var>
+	      Package: procps
+	      Pre-Depends: ${shlibs:Pre-Depends}
+	      Recommends: ${shlibs:Recommends}
+	      <var>...</var>
+	    </example>
+	  </p>
+
+	  <p>	    
+	    Sources which produce several binary packages with
+	    different shared library dependency requirements can use
+	    the <tt>-p<var>varnameprefix</var></tt> option to override
+	    the default <tt>shlib:</tt> prefix (one invocation of
+	    <prgn>dpkg-shlibdeps</prgn> per setting of this option).
+	    They can thus produce several sets of dependency
+	    variables, each of the form
+	    <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
+	    which can be referred to in the appropriate parts of the
+	    binary package control files.
+	  </p>
+	</sect1>
+	  
+	  
+	<sect1>
+	  <heading>
+	    <prgn>dpkg-distaddfile</prgn> - adds a file to
+	    <tt>debian/files</tt>
+	  </heading>
+
+	  <p>	    
+	    Some packages' uploads need to include files other than
+	    the source and binary package files.
+	  </p>
+
+	  <p>	    
+	    <prgn>dpkg-distaddfile</prgn> adds a file to the
+	    <tt>debian/files</tt> file so that it will be included in
+	    the <tt>.changes</tt> file when
+	    <prgn>dpkg-genchanges</prgn> is run.
+	  </p>
+
+	  <p>	    
+	    It is usually invoked from the <prgn>binary</prgn> target of
+	    <tt>debian/rules</tt>:
+	    <example>
+	      dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
+	    </example>
+	    The <var>filename</var> is relative to the directory where
+	    <prgn>dpkg-genchanges</prgn> will expect to find it - this
+	    is usually the directory above the top level of the source
+	    tree.  The <tt>debian/rules</tt> target should put the
+	    file there just before or just after calling
+	    <prgn>dpkg-distaddfile</prgn>.
+	  </p>
+
+	  <p>	    
+	    The <var>section</var> and <var>priority</var> are passed
+	    unchanged into the resulting <tt>.changes</tt> file.  See
+	    <ref id="f-classification">.
+	  </p>
+	</sect1>
+	  
+	  
+	<sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
+	    control file
+	  </heading>
+
+	  <p>	    
+	    This program is usually called by package-independent
+	    automatic building scripts such as
+	    <prgn>dpkg-buildpackage</prgn>, but it may also be called
+	    by hand.
+	  </p>
+
+	  <p>	    
+	    It is usually called in the top level of a built source
+	    tree, and when invoked with no arguments will print out a
+	    straightforward <tt>.changes</tt> file based on the
+	    information in the source package's changelog and control
+	    file and the binary and source packages which should have
+	    been built.
+	  </p>
+	</sect1>
+	  
+	  
+	<sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
+	    a changelog
+	  </heading>
+
+	  <p>	    
+	    This program is used internally by
+	    <prgn>dpkg-source</prgn> et al.  It may also occasionally
+	    be useful in <tt>debian/rules</tt> and elsewhere.  It
+	    parses a changelog, <tt>debian/changelog</tt> by default,
+	    and prints a control-file format representation of the
+	    information in it to standard output.
+	  </p>
+	</sect1>
+      </sect>
+	
+      <sect id="sourcetree"><heading>The Debianised source tree
+	</heading>
+
+	<p>	  
+	  The source archive scheme described later is intended to
+	  allow a Debianised source tree with some associated control
+	  information to be reproduced and transported easily.  The
+	  Debianised source tree is a version of the original program
+	  with certain files added for the benefit of the
+	  Debianisation process, and with any other changes required
+	  made to the rest of the source code and installation
+	  scripts.
+	</p>
+
+	<p>	  
+	  The extra files created for Debian are in the subdirectory
+	  <tt>debian</tt> of the top level of the Debianised source
+	  tree.  They are described below.
+	</p>
+	  
+	<sect1><heading><tt>debian/rules</tt> - the main building
+	script
+	  </heading>
+
+	  <p>	    
+	    This file is an executable makefile, and contains the
+	    package-specific recipies for compiling the package and
+	    building binary package(s) out of the source.
+	  </p>
+
+	  <p>	    
+	    It must start with the line <tt>#!/usr/bin/make -f</tt>,
+	    so that it can be invoked by saying its name rather than
+	    invoking <prgn>make</prgn> explicitly.
+	  </p>
+
+	  <p>
+	    Since an interactive <tt>debian/rules</tt> script makes it
+	    impossible to autocompile that package and also makes it
+	    hard for other people to reproduce the same binary
+	    package, all <strong>required targets</strong> have to be
+	    non-interactive. At a minimul, required targets are the
+	    ones called by <prgn>dpkg-buildpackage</prgn>, namely,
+	    <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
+	    <em>build</em>. It also follows that any target that these
+	    targets depend on must also be non-interactive.
+	  </p>
+
+	  <p>	    
+	    The targets which are required to be present are:	    
+	    <taglist>
+	      <tag><tt>build</tt></tag>
+	      <item>
+		<p>
+		  This should perform all non-interactive
+		  configuration and compilation of the package.  If a
+		  package has an interactive pre-build configuration
+		  routine, the Debianised source package should be
+		  built after this has taken place, so that it can be
+		  built without rerunning the configuration.
+		</p>
+
+		<p>		  
+		  For some packages, notably ones where the same
+		  source tree is compiled in different ways to produce
+		  two binary packages, the <prgn>build</prgn> target
+		  does not make much sense.  For these packages it is
+		  good enough to provide two (or more) targets
+		  (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
+		  for each of the ways of building the package, and a
+		  <prgn>build</prgn> target that does nothing.  The
+		  <prgn>binary</prgn> target will have to build the
+		  package in each of the possible ways and make the
+		  binary package out of each.
+		</p>
+
+		<p>		  
+		  The <prgn>build</prgn> target must not do anything
+		  that might require root privilege.
+		</p>
+
+		<p>		  
+		  The <prgn>build</prgn> target may need to run
+		  <prgn>clean</prgn> first - see below.
+		</p>
+
+		<p>		  
+		  When a package has a configuration routine that
+		  takes a long time, or when the makefiles are poorly
+		  designed, or when <prgn>build</prgn> needs to run
+		  <prgn>clean</prgn> first, it is a good idea to
+		  <tt>touch build</tt> when the build process is
+		  complete.  This will ensure that if <tt>debian/rules
+		    build</tt> is run again it will not rebuild the
+		    whole program.
+		</p>
+	      </item>
+		
+	      <tag><tt>binary</tt>, <tt>binary-arch</tt>,
+		<tt>binary-indep</tt>
+	      </tag> 
+	      <item>
+		<p>
+		  The <prgn>binary</prgn> target should be all that is
+		  necessary for the user to build the binary
+		  package. All these targets are required to be
+		  non-interactive.  It is split into two parts:
+		  <prgn>binary-arch</prgn> builds the packages' output
+		  files which are specific to a particular
+		  architecture, and <prgn>binary-indep</prgn> builds
+		  those which are not.
+		</p>
+
+		<p>		  
+		  <prgn>binary</prgn> should usually be a target with
+		  no commands which simply depends on
+		  <prgn>binary-arch</prgn> and
+		  <prgn>binary-indep</prgn>.
+		</p>
+
+		<p>		  
+		  Both <prgn>binary-*</prgn> targets should depend on
+		  the <prgn>build</prgn> target, above, so that the
+		  package is built if it has not been already.  It
+		  should then create the relevant binary package(s),
+		  using <prgn>dpkg-gencontrol</prgn> to make their
+		  control files and <prgn>dpkg-deb</prgn> to build
+		  them and place them in the parent of the top level
+		  directory.
+		</p>
+
+		<p>		  
+		  If one of the <prgn>binary-*</prgn> targets has
+		  nothing to do (this will be always be the case if
+		  the source generates only a single binary package,
+		  whether architecture-dependent or not) it
+		  <em>must</em> still exist, but should always
+		  succeed.
+		</p>
+
+		<p>		  
+		  <ref id="binarypkg"> describes how to construct
+		  binary packages.
+		</p>
+
+		<p>		  
+		  The <prgn>binary</prgn> targets must be invoked as
+		  root.
+		</p>
+	      </item>
+		
+	      <tag><tt>clean</tt></tag>
+	      <item>
+		
+		<p>
+		  This should undo any effects that the
+		  <prgn>build</prgn> and <prgn>binary</prgn> targets
+		  may have had, except that it should leave alone any
+		  output files created in the parent directory by a
+		  run of <prgn>binary</prgn>. This target is required
+		  to be non-interactive.
+		</p>
+
+		<p>		  
+		  If a <prgn>build</prgn> file is touched at the end
+		  of the <prgn>build</prgn> target, as suggested
+		  above, it must be removed as the first thing that
+		  <prgn>clean</prgn> does, so that running
+		  <prgn>build</prgn> again after an interrupted
+		  <prgn>clean</prgn> doesn't think that everything is
+		  already done.
+		</p>
+
+		<p>		  
+		  The <prgn>clean</prgn> target must be invoked as
+		  root if <prgn>binary</prgn> has been invoked since
+		  the last <prgn>clean</prgn>, or if
+		  <prgn>build</prgn> has been invoked as root (since
+		  <prgn>build</prgn> may create directories, for
+		  example).
+		</p>
+	      </item>
+		
+	      <tag><tt>get-orig-source</tt> (optional)</tag>
+	      <item>
+		
+		<p>
+		  This target fetches the most recent version of the
+		  original source package from a canonical archive
+		  site (via FTP or WWW, for example), does any
+		  necessary rearrangement to turn it into the original
+		  source tarfile format described below, and leaves it
+		  in the current directory.
+		</p>
+
+		<p>		  
+		  This target may be invoked in any directory, and
+		  should take care to clean up any temporary files it
+		  may have left.
+		</p>
+
+		<p>		  
+		  This target is optional, but providing it if
+		  possible is a good idea.
+		</p>
+	      </item>
+	    </taglist>
+	      
+	  <p>
+	    The <prgn>build</prgn>, <prgn>binary</prgn> and
+	    <prgn>clean</prgn> targets must be invoked with a current
+	    directory of the package's top-level directory.
+	  </p>
+	    
+
+	  <p>	    
+	    Additional targets may exist in <tt>debian/rules</tt>,
+	    either as published or undocumented interfaces or for the
+	    package's internal use.
+	  </p>
+	</sect1>
+	  
+	  
+	<sect1><heading><tt>debian/control</tt>
+	  </heading>
+
+	  <p>	    
+	    This file contains version-independent details about the
+	    source package and about the binary packages it creates.
+	  </p>
+
+	  <p>	    
+	    It is a series of sets of control fields, each
+	    syntactically similar to a binary package control file.
+	    The sets are separated by one or more blank lines.  The
+	    first set is information about the source package in
+	    general; each subsequent set describes one binary package
+	    that the source tree builds.
+	  </p>
+
+	  <p>	    
+	    The syntax and semantics of the fields are described below
+	    in <ref id="controlfields">.
+	  </p>
+
+	  <p>	    
+	    The general (binary-package-independent) fields are:
+	    <list compact="compact">
+	      <item>
+		<p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
+	      </item>
+	      <item>
+		<p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
+	      </item>
+	      <item>
+		<p>
+		  <qref id="f-classification"><tt>Section</tt> and
+		    <tt>Priority</tt></qref> 
+		  (classification, mandatory)
+		</p>
+	      </item>
+	      <item>
+		<p>
+		  <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
+		</p>
+	      </item> 
+	    </list>
+
+	  <p>	    
+	    The per-binary-package fields are:
+	    <list compact="compact">
+	      <item>
+		<p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
+	      </item>
+	      <item>
+		<p>
+		  <qref	id="f-Architecture"><tt>Architecture</tt></qref>
+		  (mandatory)</p>
+	      </item>
+	      <item>
+		<p><qref id="descriptions"><tt>Description</tt></qref></p>
+	      </item>
+	      <item>
+		<p>
+		  <qref id="f-classification"><tt>Section</tt> and
+		    <tt>Priority</tt></qref> (classification)</p>
+	      </item>
+	      <item>
+		<p><qref id="f-Essential"><tt>Essential</tt></qref></p>
+	      </item>
+	      <item>
+		<p>
+		  <qref id="relationships"><tt>Depends</tt> et
+		  al.</qref> (package interrelationships)
+		</p>
+	      </item>
+	    </list>
+
+	  <p>	    
+	    These fields are used by <prgn>dpkg-gencontrol</prgn> to
+	    generate control files for binary packages (see below), by
+	    <prgn>dpkg-genchanges</prgn> to generate the
+	    <tt>.changes</tt> file to accompany the upload, and by
+	    <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
+	    source control file as part of a source archive.
+	  </p>
+
+	  <p>	    
+	    The fields here may contain variable references - their
+	    values will be substituted by
+	    <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
+	    or <prgn>dpkg-source</prgn> when they generate output
+	    control files.  See <ref id="srcsubstvars"> for details.
+	  </p>
+
+	  <p> <sect2><heading>User-defined fields
+	    </heading>
+
+	    <p>	      
+	      Additional user-defined fields may be added to the
+	      source package control file.  Such fields will be
+	      ignored, and not copied to (for example) binary or
+	      source package control files or upload control files.
+	    </p>
+
+	    <p>	      
+	      If you wish to add additional unsupported fields to
+	      these output files you should use the mechanism
+	      described here.
+	    </p>
+
+	    <p>	      
+	      Fields in the main source control information file with
+	      names starting <tt>X</tt>, followed by one or more of
+	      the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
+	      be copied to the output files.  Only the part of the
+	      field name after the hyphen will be used in the output
+	      file.  Where the letter <tt>B</tt> is used the field
+	      will appear in binary package control files, where the
+	      letter <tt>S</tt> is used in source package control
+	      files and where <tt>C</tt> is used in upload control
+	      (<tt>.changes</tt>) files.
+	    </p>
+
+	    <p>	      
+	      For example, if the main source information control file
+	      contains the field
+	      <example>
+		XBS-Comment: I stand between the candle and the star.
+	      </example>
+	      then the binary and source package control files will contain the
+	      field
+	      <example>
+		Comment: I stand between the candle and the star.
+	      </example>
+	    </p>
+	  </sect2>
+	
+	</sect1>
+
+	<sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
+	  </heading>
+
+	  <p>	    
+	    This file records the changes to the Debian-specific parts of the
+	    package
+	    <footnote>
+	      <p>
+		Though there is nothing stopping an author who is also
+		the Debian maintainer from using it for all their
+		changes, it will have to be renamed if the Debian and
+		upstream maintainers become different
+		people.
+	      </p>
+	    </footnote>.
+	  </p>
+
+	  <p>	    
+	    It has a special format which allows the package building
+	    tools to discover which version of the package is being
+	    built and find out other release-specific information.
+	  </p>
+
+	  <p>
+	    That format is a series of entries like this:	
+	    <example>
+	      <var>package</var> (<var>version</var>) <var>distribution(s)</var>;
+	      urgency=<var>urgency</var>
+	      
+	      * <var>change details</var>
+	      <var>more change details</var>
+	      * <var>even more change details</var>
+	      
+	      -- <var>maintainer name and email address</var>  <var>date</var>
+	    </example>
+	  </p>
+
+	  <p>	    
+	    <var>package</var> and <var>version</var> are the source
+	    package name and version number.
+	  </p> 
+
+	  <p>	    
+	    <var>distribution(s)</var> lists the distributions where
+	    this version should be installed when it is uploaded - it
+	    is copied to the <tt>Distribution</tt> field in the
+	    <tt>.changes</tt> file.  See <ref id="f-Distribution">.
+	  </p>
+
+	  <p>	    
+	    <var>urgency</var> is the value for the <tt>Urgency</tt>
+	    field in the <tt>.changes</tt> file for the upload.  See
+	    <ref id="f-Urgency">.  It is not possible to specify an
+	    urgency containing commas; commas are used to separate
+	    <tt><var>keyword</var>=<var>value</var></tt> settings in
+	    the <prgn>dpkg</prgn> changelog format (though there is
+	    currently only one useful <var>keyword</var>,
+	    <tt>urgency</tt>).
+	  </p>
+
+	  <p>	    
+	    The change details may in fact be any series of lines
+	    starting with at least two spaces, but conventionally each
+	    change starts with an asterisk and a separating space and
+	    continuation lines are indented so as to bring them in
+	    line with the start of the text above.  Blank lines may be
+	    used here to separate groups of changes, if desired.
+	  </p>
+
+	  <p>	    
+	    The maintainer name and email address should <em>not</em>
+	    necessarily be those of the usual package maintainer.
+	    They should be the details of the person doing
+	    <em>this</em> version.  The information here will be
+	    copied to the <tt>.changes</tt> file, and then later used
+	    to send an acknowledgement when the upload has been
+	    installed.
+	  </p>
+
+	  <p>	    
+	    The <var>date</var> should be in RFC822 format
+	    <footnote>
+	      <p>
+		This is generated by the <prgn>822-date</prgn>
+		program.
+	      </p>
+	    </footnote>; it should include the timezone specified
+	    numerically, with the timezone name or abbreviation
+	    optionally present as a comment.
+	  </p>
+
+	  <p>	    
+	    The first `title' line with the package name should start
+	    at the left hand margin; the `trailer' line with the
+	    maintainer and date details should be preceded by exactly
+	    one space.  The maintainer details and the date must be
+	    separated by exactly two spaces.
+	  </p>
+
+	  <p>	    
+	    An Emacs mode for editing this format is available: it is
+	    called <tt>debian-changelog-mode</tt>.  You can have this
+	    mode selected automatically when you edit a Debian
+	    changelog by adding a local variables clause to the end of
+	    the changelog.
+	  </p>
+	    
+	  <sect2><heading>Defining alternative changelog formats
+	    </heading>
+
+	    <p>	      
+	      It is possible to use a different format to the standard
+	      one, by providing a parser for the format you wish to
+	      use.
+	    </p>
+
+	    <p>	      
+	      In order to have <tt>dpkg-parsechangelog</tt> run your
+	      parser, you must include a line within the last 40 lines
+	      of your file matching the Perl regular expression:
+	      <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
+	      parentheses should be the name of the format.  For
+	      example, you might say:
+	      <example>
+		@@@ changelog-format: joebloggs @@@
+	      </example>
+	      Changelog format names are non-empty strings of alphanumerics.
+	    </p>
+
+	    <p>	      
+	      If such a line exists then <tt>dpkg-parsechangelog</tt>
+	      will look for the parser as
+	      <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
+	      or
+	      <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
+	      it is an error for it not to find it, or for it not to
+	      be an executable program.  The default changelog format
+	      is <tt>dpkg</tt>, and a parser for it is provided with
+	      the <tt>dpkg</tt> package.
+	    </p>
+
+	    <p>	      
+	      The parser will be invoked with the changelog open on
+	      standard input at the start of the file.  It should read
+	      the file (it may seek if it wishes) to determine the
+	      information required and return the parsed information
+	      to standard output in the form of a series of control
+	      fields in the standard format.  By default it should
+	      return information about only the most recent version in
+	      the changelog; it should accept a
+	      <tt>-v<var>version</var></tt> option to return changes
+	      information from all versions present <em>strictly
+	      after</em> <var>version</var>, and it should then be an
+	      error for <var>version</var> not to be present in the
+	      changelog.
+	    </p>
+
+	    <p>	      
+	      The fields are:
+	      <list compact="compact">
+		<item>
+		  <p><qref id="f-Source"><tt>Source</tt></qref></p>
+		</item>
+		<item>
+		  <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+		</item>
+		<item>
+		  <p>
+		    <qref id="f-Distribution"><tt>Distribution</tt></qref>
+		    (mandatory)
+		  </p> 
+		</item>
+		<item>
+		  <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
+		</item>
+		<item>
+		  <p>
+		    <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
+		    (mandatory)
+		  </p>
+		</item>
+		<item>
+		  <p><qref id="f-Date"><tt>Date</tt></qref></p>
+		</item>
+		<item>
+		  <p>
+		    <qref id="f-Changes"><tt>Changes</tt></qref>
+		    (mandatory)
+		  </p>
+		</item>
+	      </list>
+
+	    <p>	      
+	      If several versions are being returned (due to the use
+	      of <tt>-v</tt>), the urgency value should be of the
+	      highest urgency code listed at the start of any of the
+	      versions requested followed by the concatenated
+	      (space-separated) comments from all the versions
+	      requested; the maintainer, version, distribution and
+	      date should always be from the most recent version.
+	    </p>
+
+	    <p>	      
+	      For the format of the <tt>Changes</tt> field see <ref
+	      id="f-Changes">.
+	    </p>
+
+	    <p>	      
+	      If the changelog format which is being parsed always or
+	      almost always leaves a blank line between individual
+	      change notes these blank lines should be stripped out,
+	      so as to make the resulting output compact.
+	    </p>
+
+	    <p>	      
+	      If the changelog format does not contain date or package
+	      name information this information should be omitted from
+	      the output.  The parser should not attempt to synthesise
+	      it or find it from other sources.
+	    </p>
+
+	    <p>	      
+	      If the changelog does not have the expected format the
+	      parser should exit with a nonzero exit status, rather
+	      than trying to muddle through and possibly generating
+	      incorrect output.
+	    </p>
+
+	    <p>	      
+	      A changelog parser may not interact with the user at
+	      all.</p></sect2>
+	</sect1>
+	  
+	<sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
+	and variable substitutions
+	  </heading>
+
+	  <p>	    
+	    When <prgn>dpkg-gencontrol</prgn>,
+	    <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+	    generate control files they do variable substitutions on
+	    their output just before writing it.  Variable
+	    substitutions have the form
+	    <tt>${<var>variable-name</var>}</tt>.  The optional file
+	    <tt>debian/substvars</tt> contains variable substitutions
+	    to be used; variables can also be set directly from
+	    <tt>debian/rules</tt> using the <tt>-V</tt> option to the
+	    source packaging commands, and certain predefined
+	    variables are available.
+	  </p>
+
+	  <p>	    
+	    The is usually generated and modified dynamically by
+	    <tt>debian/rules</tt> targets; in this case it must be
+	    removed by the <prgn>clean</prgn> target.
+	  </p>
+
+	  <p>
+	    See <manref name="dpkg-source" section="1"> for full
+	    details about source variable substitutions, including the
+	    format of <tt>debian/substvars</tt>.</p>
+	</sect1>
+	  
+	<sect1><heading><tt>debian/files</tt>
+	  </heading>
+
+	  <p>	    
+	    This file is not a permanent part of the source tree; it
+	    is used while building packages to record which files are
+	    being generated.  <prgn>dpkg-genchanges</prgn> uses it
+	    when it generates a <tt>.changes</tt> file.
+	  </p>
+
+	  <p>	    
+	    It should not exist in a shipped source package, and so it
+	    (and any backup files or temporary files such as
+	    <tt>files.new</tt>
+	      <footnote>
+		<p>
+		  <tt>files.new</tt> is used as a temporary file by
+		  <prgn>dpkg-gencontrol</prgn> and
+		  <prgn>dpkg-distaddfile</prgn> - they write a new
+		  version of <tt>files</tt> here before renaming it,
+		  to avoid leaving a corrupted copy if an error
+		  occurs
+		</p>
+	      </footnote>) should be removed by the
+	      <prgn>clean</prgn> target.  It may also be wise to
+	      ensure a fresh start by emptying or removing it at the
+	      start of the <prgn>binary</prgn> target.
+	  </p>
+
+	  <p>	    
+	    <prgn>dpkg-gencontrol</prgn> adds an entry to this file
+	    for the <tt>.deb</tt> file that will be created by
+	    <prgn>dpkg-deb</prgn> from the control file that it
+	    generates, so for most packages all that needs to be done
+	    with this file is to delete it in <prgn>clean</prgn>.
+	  </p>
+
+	  <p>	    
+	    If a package upload includes files besides the source
+	    package and any binary packages whose control files were
+	    made with <prgn>dpkg-gencontrol</prgn> then they should be
+	    placed in the parent of the package's top-level directory
+	    and <prgn>dpkg-distaddfile</prgn> should be called to add
+	    the file to the list in <tt>debian/files</tt>.</p>
+	</sect1>
+	  
+	<sect1><heading><tt>debian/tmp</tt>
+	  </heading>
+
+	  <p>	    
+	    This is the canonical temporary location for the
+	    construction of binary packages by the <prgn>binary</prgn>
+	    target.  The directory <tt>tmp</tt> serves as the root of
+	    the filesystem tree as it is being constructed (for
+	    example, by using the package's upstream makefiles install
+	    targets and redirecting the output there), and it also
+	    contains the <tt>DEBIAN</tt> subdirectory.  See <ref
+	    id="bincreating">.
+	  </p>
+
+	  <p>	    
+	    If several binary packages are generated from the same
+	    source tree it is usual to use several
+	    <tt>debian/tmp<var>something</var></tt> directories, for
+	    example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
+	  </p>
+
+	  <p>	    
+	    Whatever <tt>tmp</tt> directories are created and used by
+	    <prgn>binary</prgn> must of course be removed by the
+	    <prgn>clean</prgn> target.</p></sect1>
+      </sect>
+	
+	
+      <sect id="sourcearchives"><heading>Source packages as archives
+	</heading>
+
+	<p>	  
+	  As it exists on the FTP site, a Debian source package
+	  consists of three related files.  You must have the right
+	  versions of all three to be able to use them.
+	</p>
+
+	<p>	  
+	  <taglist>
+	    <tag>Debian source control file - <tt>.dsc</tt></tag>
+	    <item>
+	      
+	      <p>
+		This file contains a series of fields, identified and
+		separated just like the fields in the control file of
+		a binary package.  The fields are listed below; their
+		syntax is described above, in <ref id="controlfields">.
+		<list compact="compact">
+		  <item>
+		    <p><qref id="f-Source"><tt>Source</tt></qref></p>
+		  </item>
+		  <item>
+		    <p><qref id="versions"><tt>Version</tt></qref></p>
+		  </item>
+		  <item>
+		    <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
+		  </item>
+		  <item>
+		    <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
+		  </item>
+		  <item>
+		    <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
+		  </item>
+		  <item>
+		    <p>
+		      <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
+		  </item>
+		  <item>
+		    <p><qref id="f-Files"><tt>Files</tt></qref></p>
+		  </item>
+		</list>
+
+	      <p>		
+		The source package control file is generated by
+		<prgn>dpkg-source</prgn> when it builds the source
+		archive, from other files in the source package,
+		described above.  When unpacking it is checked against
+		the files and directories in the other parts of the
+		source package, as described below.</p>
+	    </item>
+	      
+	    <tag>
+	      Original source archive -
+	      <tt>
+		<var>package</var>_<var>upstream-version</var>.orig.tar.gz
+	      </tt>
+	    </tag> 
+
+	    <item>
+	      
+	      <p>
+		This is a compressed (with <tt>gzip -9</tt>)
+		<prgn>tar</prgn> file containing the source code from
+		the upstream authors of the program.  The tarfile
+		unpacks into a directory
+		<tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
+		and does not contain files anywhere other than in
+		there or in its subdirectories.</p>
+	    </item>
+	      
+	    <tag>
+	      Debianisation diff -
+	      <tt>
+		<var>package</var>_<var>upstream_version-revision</var>.diff.gz
+	      </tt>
+	    </tag> 
+	    <item>
+	      
+	      <p>
+		This is a unified context diff (<tt>diff -u</tt>)
+		giving the changes which are required to turn the
+		original source into the Debian source.  These changes
+		may only include editing and creating plain files.
+		The permissions of files, the targets of symbolic
+		links and the characteristics of special files or
+		pipes may not be changed and no files may be removed
+		or renamed.
+	      </p>
+
+	      <p>		
+		All the directories in the diff must exist, except the
+		<tt>debian</tt> subdirectory of the top of the source
+		tree, which will be created by
+		<prgn>dpkg-source</prgn> if necessary when unpacking.
+	      </p>
+
+	      <p>		
+		The <prgn>dpkg-source</prgn> program will
+		automatically make the <tt>debian/rules</tt> file
+		executable (see below).</p></item>
+	  </taglist>
+	    
+
+	<p>	  
+	  If there is no original source code - for example, if the
+	  package is specially prepared for Debian or the Debian
+	  maintainer is the same as the upstream maintainer - the
+	  format is slightly different: then there is no diff, and the
+	  tarfile is named
+	  <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
+	  contains a directory
+	  <tt><var>package</var>-<var>version</var></tt>.
+	</p>
+      </sect>
+	
+      <sect><heading>Unpacking a Debian source package without
+      <prgn>dpkg-source</prgn>
+	</heading>
+
+	<p>	  
+	  <tt>dpkg-source -x</tt> is the recommended way to unpack a
+	  Debian source package.  However, if it is not available it
+	  is possible to unpack a Debian source archive as follows:
+	<enumlist compact="compact">
+	  <item> 
+	    <p>
+	      Untar the tarfile, which will create a <tt>.orig</tt>
+	      directory.</p>
+	  </item>
+	  <item>
+	    <p>Rename the <tt>.orig</tt> directory to
+	      <tt><var>package</var>-<var>version</var></tt>.</p>
+	  </item>
+	    <item>
+	    <p>
+	      Create the subdirectory <tt>debian</tt> at the top of
+	      the source tree.</p>
+	  </item>
+	  <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
+	  </item>
+	  <item><p>Untar the tarfile again if you want a copy of the original
+	      source code alongside the Debianised version.</p>
+	  </item>
+	</enumlist>
+	
+	<p>	  
+	  It is not possible to generate a valid Debian source archive
+	  without using <prgn>dpkg-source</prgn>.  In particular,
+	  attempting to use <prgn>diff</prgn> directly to generate the
+	  <tt>.diff.gz</tt> file will not work.
+	</p>
+	  
+	<sect1><heading>Restrictions on objects in source packages
+	  </heading>
+
+	  <p>	    
+	    The source package may not contain any hard links
+	    <footnote>
+	      <p>
+		This is not currently detected when building source
+		packages, but only when extracting
+		them.
+	      </p>
+	    </footnote>
+	    <footnote>
+	      <p>
+		Hard links may be permitted at some point in the
+		future, but would require a fair amount of
+		work.
+	      </p>
+	    </footnote>, device special files, sockets or setuid or
+	    setgid files.
+	    <footnote>
+	      <p>
+		Setgid directories are allowed.
+	      </p>
+	    </footnote>
+	  </p>
+
+	  <p>	    
+	    The source packaging tools manage the changes between the
+	    original and Debianised source using <prgn>diff</prgn> and
+	    <prgn>patch</prgn>.  Turning the original source tree as
+	    included in the <tt>.orig.tar.gz</tt> into the debianised
+	    source must not involve any changes which cannot be
+	    handled by these tools.  Problematic changes which cause
+	    <prgn>dpkg-source</prgn> to halt with an error when
+	    building the source package are:
+	    <list compact="compact">
+	      <item><p>Adding or removing symbolic links, sockets or pipes.</p>
+	      </item>
+	      <item><p>Changing the targets of symbolic links.</p>
+	      </item>
+	      <item><p>Creating directories, other than <tt>debian</tt>.</p>
+	      </item>
+	      <item><p>Changes to the contents of binary files.</p></item>
+	    </list> Changes which cause <prgn>dpkg-source</prgn> to
+	    print a warning but continue anyway are:
+	    <list compact="compact">
+	      <item>
+		<p>
+		  Removing files, directories or symlinks.
+		  <footnote>
+		    <p>
+		      Renaming a file is not treated specially - it is
+		      seen as the removal of the old file (which
+		      generates a warning, but is otherwise ignored),
+		      and the creation of the new
+		      one.</p>
+		  </footnote>
+		</p>
+	      </item>
+	      <item>
+		<p>
+		  Changed text files which are missing the usual final
+		  newline (either in the original or the modified
+		  source tree).
+		</p>
+	      </item>
+	    </list>
+	    Changes which are not represented, but which are not detected by
+	    <prgn>dpkg-source</prgn>, are:
+	    <list compact="compact">
+	      <item><p>Changing the permissions of files (other than
+		  <tt>debian/rules</tt>) and directories.</p></item>
+	    </list>
+	  </p>
+
+	  <p>	    
+	    The <tt>debian</tt> directory and <tt>debian/rules</tt>
+	    are handled specially by <prgn>dpkg-source</prgn> - before
+	    applying the changes it will create the <tt>debian</tt>
+	    directory, and afterwards it will make
+	    <tt>debian/rules</tt> world-exectuable.
+	  </p>
+	</sect1>
+      </sect>
+    </chapt>
+      
+    <chapt id="controlfields"><heading>Control files and their fields
+      </heading>
+
+      <p>	
+	Many of the tools in the <prgn>dpkg</prgn> suite manipulate
+	data in a common format, known as control files.  Binary and
+	source packages have control data as do the <tt>.changes</tt>
+	files which control the installation of uploaded files, and
+	<prgn>dpkg</prgn>'s internal databases are in a similar
+	format.
+      </p>
+	
+      <sect><heading>Syntax of control files
+	</heading>
+
+	<p>	  
+	  A file consists of one or more paragraphs of fields.  The
+	  paragraphs are separated by blank lines.  Some control files
+	  only allow one paragraph; others allow several, in which
+	  case each paragraph often refers to a different package.
+	</p>
+
+	<p>	  
+	  Each paragraph is a series of fields and values; each field
+	  consists of a name, followed by a colon and the value.  It
+	  ends at the end of the line.  Horizontal whitespace (spaces
+	  and tabs) may occur before or after the value and is ignored
+	  there; it is conventional to put a single space after the
+	  colon.
+	</p>
+
+	<p>	  
+	  Some fields' values may span several lines; in this case
+	  each continuation line <em>must</em> start with a space or
+	  tab.  Any trailing spaces or tabs at the end of individual
+	  lines of a field value are ignored.
+	</p>
+
+	<p>	  
+	  Except where otherwise stated only a single line of data is
+	  allowed and whitespace is not significant in a field body.
+	  Whitespace may never appear inside names (of packages,
+	  architectures, files or anything else), version numbers or
+	  in between the characters of multi-character version
+	  relationships.
+	</p>
+
+	<p>	  
+	  Field names are not case-sensitive, but it is usual to
+	  capitalise the fields using mixed case as shown below.
+	</p>
+
+	<p>	  
+	  Blank lines, or lines consisting only of spaces and tabs,
+	  are not allowed within field values or between fields - that
+	  would mean a new paragraph.
+	</p>
+
+	<p>	  
+	  It is important to note that there are several fields which
+	  are optional as far as <prgn>dpkg</prgn> and the related
+	  tools are concerned, but which must appear in every Debian
+	  package, or whose omission may cause problems.  When writing
+	  the control files for Debian packages you <em>must</em> read
+	  the Debian policy manual in conjuction with the details
+	  below and the list of fields for the particular file.</p>
+      </sect>
+	
+      <sect><heading>List of fields
+	</heading>
+	  
+	<sect1 id="f-Package"><heading><tt>Package</tt>
+	  </heading>
+
+	  <p>	    
+	    The name of the binary package.  Package names consist of
+	    the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
+	    (plus, minus and full stop).
+	    <footnote>
+	      <p>
+		The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
+		<tt>t</tt>t> <tt>_</tt> (at, colon, equals, percent
+		and underscore) used to be legal and are still
+		accepted when found in a package file, but may not be
+		used in new packages
+	      </p>
+	    </footnote>
+	  </p>
+
+	  <p>	    
+	    They must be at least two characters and must start with
+	    an alphanumeric.  In current versions of dpkg they are
+	    sort of case-sensitive<footnote><p>This is a
+	    bug.</p></footnote>; use lowercase package names unless
+	    the package you're building (or referring to, in other
+	    fields) is already using uppercase.</p>
+	</sect1>
+	  
+	<sect1 id="f-Version"><heading><tt>Version</tt>
+	  </heading>
+
+	  <p>	    
+	    This lists the source or binary package's version number -
+	    see <ref id="versions">.
+	  </p>
+
+	</sect1>
+	  
+	<sect1 id="f-Architecture"><heading><tt>Architecture</tt>
+	  </heading>
+
+	  <p>	    
+	    This is the architecture string; it is a single word for
+	    the CPU architecture.
+	  </p>
+
+	  <p>	    
+	    <prgn>dpkg</prgn> will check the declared architecture of
+	    a binary package against its own compiled-in value before
+	    it installs it.
+	  </p>
+
+	  <p>	    
+	    The special value <tt>all</tt> indicates that the package
+	    is architecture-independent.
+	  </p>
+
+	  <p>	    
+	    In the main <tt>debian/control</tt> file in the source
+	    package, or in the source package control file
+	    <tt>.dsc</tt>, a list of architectures (separated by
+	    spaces) is also allowed, as is the special value
+	    <tt>any</tt>.  A list indicates that the source will build
+	    an architecture-dependent package, and will only work
+	    correctly on the listed architectures.  <tt>any</tt>
+	    indicates that though the source package isn't dependent
+	    on any particular architecture and should compile fine on
+	    any one, the binary package(s) produced are not
+	    architecture-independent but will instead be specific to
+	    whatever the current build architecture is.
+	  </p>
+
+	  <p>	    
+	    In a <tt>.changes</tt> file the <tt>Architecture</tt>
+	    field lists the architecture(s) of the package(s)
+	    currently being uploaded.  This will be a list; if the
+	    source for the package is being uploaded too the special
+	    entry <tt>source</tt> is also present.
+	  </p>
+
+	  <p>	    
+	    The current build architecture can be determined using <tt>dpkg
+	      --print-architecture</tt>.
+	    <footnote>
+	      <p>
+		This actually invokes
+		<example>
+		  gcc --print-libgcc-file-name
+		</example> and parses and decomposes the output and
+		looks the CPU type from the GCC configuration in a
+		table in <prgn>dpkg</prgn>.  This is so that it will
+		work if you're cross-compiling.
+	      </p>
+	    </footnote> This value is automatically used by
+	    <prgn>dpkg-gencontrol</prgn> when building the control
+	    file for a binary package for which the source control
+	    information doesn't specify architecture <tt>all</tt>.
+	  </p>
+
+	  <p>	    
+	    There is a separate option,
+	    <tt>--print-installation-architecture</tt>, for finding
+	    out what architecture <prgn>dpkg</prgn> is willing to
+	    install.  This information is also in the output of
+	    <tt>dpkg --version</tt>.</p>
+	</sect1>
+	  
+	<sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
+	  </heading>
+
+	  <p>	    
+	    The package maintainer's name and email address.  The name
+	    should come first, then the email address inside angle
+	    brackets <tt>&lt;&gt</tt> (in RFC822 format).
+	  </p>
+
+	  <p>	    
+	    If the maintainer's name contains a full stop then the
+	    whole field will not work directly as an email address due
+	    to a misfeature in the syntax specified in RFC822; a
+	    program using this field as an address must check for this
+	    and correct the problem if necessary (for example by
+	    putting the name in round brackets and moving it to the
+	    end, and bringing the email address forward).
+	  </p>
+
+	  <p>	    
+	    In a <tt>.changes</tt> file or parsed changelog data this
+	    contains the name and email address of the person
+	    responsible for the particular version in question - this
+	    may not be the package's usual maintainer.
+	  </p>
+
+	  <p>	    
+	    This field is usually optional in as far as the
+	    <prgn>dpkg</prgn> are concerned, but its absence when
+	    building packages usually generates a warning.</p>
+	</sect1>
+	  
+	<sect1 id="f-Source"><heading><tt>Source</tt>
+	  </heading>
+
+	  <p>	    
+	    This field identifies the source package name.
+	  </p>
+
+	  <p>	    
+	    In a main source control information or a
+	    <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
+	    changelog data this may contain only the name of the
+	    source package.
+	  </p>
+
+	  <p>	    
+	    In the control file of a binary package (or in a
+	    <tt>Packages</tt> file) it may be followed by a version
+	    number in parentheses.
+	    <footnote>
+	      <p>
+		It is usual to leave a space after the package name if
+		a version number is specified.
+	      </p>
+	    </footnote> This version number may be omitted (and is, by
+	    <prgn>dpkg-gencontrol</prgn>) if it has the same value as
+	    the <tt>Version</tt> field of the binary package in
+	    question.  The field itself may be omitted from a binary
+	    package control file when the source package has the same
+	    name and version as the binary package.
+	  </p>
+	</sect1>
+	  
+	<sect1><heading>Package interrelationship fields:
+	    <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+	    <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
+	    <tt>Provides</tt>, <tt>Replaces</tt>
+	  </heading>
+
+	  <p>	    
+	    These fields describe the package's relationships with
+	    other packages.  Their syntax and semantics are described
+	    in <ref id="relationships">.</p>
+	</sect1>
+	  
+	<sect1 id="f-Description"><heading><tt>Description</tt>
+	  </heading>
+
+	  <p>	    
+	    In a binary package <tt>Packages</tt> file or main source
+	    control file this field contains a description of the
+	    binary package, in a special format.  See <ref
+	    id="descriptions"> for details.
+	  </p>
+
+	  <p>	    
+	    In a <tt>.changes</tt> file it contains a summary of the
+	    descriptions for the packages being uploaded.  The part of
+	    the field before the first newline is empty; thereafter
+	    each line has the name of a binary package and the summary
+	    description line from that binary package.  Each line is
+	    indented by one space.</p>
+	</sect1>
+	  
+	<sect1 id="f-Essential"><heading><tt>Essential</tt>
+	  </heading>
+
+	  <p>	    
+	    This is a boolean field which may occur only in the
+	    control file of a binary package (or in the
+	    <tt>Packages</tt> file) or in a per-package fields
+	    paragraph of a main source control data file.
+	  </p>
+
+	  <p>	    
+	    If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
+	    <prgn>dselect</prgn> will refuse to remove the package
+	    (though it can be upgraded and/or replaced).  The other
+	    possible value is <tt>no</tt>, which is the same as not
+	    having the field at all.</p>
+	</sect1>
+	  
+	<sect1 id="f-classification"><heading><tt>Section</tt> and
+	<tt>Priority</tt>
+	  </heading>
+
+	  <p>	    
+	    These two fields classify the package.  The
+	    <tt>Priority</tt> represents how important that it is that
+	    the user have it installed; the <tt>Section</tt>
+	    represents an application area into which the package has
+	    been classified.
+	  </p>
+
+	  <p>	    
+	    When they appear in the <tt>debian/control</tt> file these
+	    fields give values for the section and priority subfields
+	    of the <tt>Files</tt> field of the <tt>.changes</tt> file,
+	    and give defaults for the section and priority of the
+	    binary packages.
+	  </p>
+
+	  <p>	    
+	    The section and priority are represented, though not as
+	    separate fields, in the information for each file in the
+	    <qref id="f-Files"><tt>-File</tt></qref>field of a
+	    <tt>.changes</tt> file.  The section value in a
+	    <tt>.changes</tt> file is used to decide where to install
+	    a package in the FTP archive.
+	  </p>
+
+	  <p>	    
+	    These fields are not used by by <prgn>dpkg</prgn> proper,
+	    but by <prgn>dselect</prgn> when it sorts packages and
+	    selects defaults.  See the Debian policy manual for the
+	    priorities in use and the criteria for selecting the
+	    priority for a Debian package, and look at the Debian FTP
+	    archive for a list of currently in-use priorities.
+	  </p>
+
+	  <p>	    
+	    These fields may appear in binary package control files,
+	    in which case they provide a default value in case the
+	    <tt>Packages</tt> files are missing the information.
+	    <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
+	    the value from a <tt>.deb</tt> file if they have no other
+	    information; a value listed in a <tt>Packages</tt> file
+	    will always take precedence.  By default
+	    <prgn>dpkg-genchanges</prgn> does not include the section
+	    and priority in the control file of a binary package - use
+	    the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
+	    achieve this effect.</p>
+	</sect1>
+	  
+	<sect1 id="f-Binary"><heading><tt>Binary</tt>
+	  </heading>
+
+	  <p>	    
+	    This field is a list of binary packages.
+	  </p>
+
+	  <p>	    
+	    When it appears in the <tt>.dsc</tt> file it is the list
+	    of binary packages which a source package can produce.  It
+	    does not necessarily produce all of these binary packages
+	    for every architecture.  The source control file doesn't
+	    contain details of which architectures are appropriate for
+	    which of the binary packages.
+	  </p>
+
+	  <p>	    
+	    When it appears in a <tt>.changes</tt> file it lists the
+	    names of the binary packages actually being uploaded.
+	  </p>
+
+	  <p>	    
+	    The syntax is a list of binary packages separated by
+	    commas.
+	    <footnote>
+	      <p>
+		A space after each comma is conventional.
+	      </p>
+	    </footnote> Currently the packages must be separated using
+	    only spaces in the <tt>.changes</tt> file.</p>
+	</sect1>
+	  
+	<sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
+	  </heading>
+
+	  <p>	    
+	    This field appears in the control files of binary
+	    packages, and in the <tt>Packages</tt> files.  It gives
+	    the total amount of disk space required to install the
+	    named package.
+	  </p>
+
+	  <p>	    
+	    The disk space is represented in kilobytes as a simple
+	    decimal number.</p>
+	</sect1>
+	  
+	<sect1 id="f-Files"><heading><tt>Files</tt>
+	  </heading>
+
+	  <p>	    
+	    This field contains a list of files with information about
+	    each one.  The exact information and syntax varies with
+	    the context.  In all cases the the part of the field
+	    contents on the same line as the field name is empty.  The
+	    remainder of the field is one line per file, each line
+	    being indented by one space and containing a number of
+	    sub-fields separated by spaces.
+	  </p>
+
+	  <p>	    
+	    In the <tt>.dsc</tt> (Debian source control) file each
+	    line contains the MD5 checksum, size and filename of the
+	    tarfile and (if applicable) diff file which make up the
+	    remainder of the source package.
+	    <footnote>
+	      <p>
+		That is, the parts which are not the
+		<tt>.dsc</tt>.
+	      </p>
+	    </footnote> The exact forms of the filenames are described
+	    in <ref id="sourcearchives">.
+	  </p>
+
+	  <p>	    
+	    In the <tt>.changes</tt> file this contains one line per
+	    file being uploaded.  Each line contains the MD5 checksum,
+	    size, section and priority and the filename.  The section
+	    and priority are the values of the corresponding fields in
+	    the main source control file - see <ref
+	    id="f-classification">.  If no section or priority is
+	    specified then <tt>-</tt> should be used, though section
+	    and priority values must be specified for new packages to
+	    be installed properly.
+	  </p>
+
+	  <p>	    
+	    The special value <tt>byhand</tt> for the section in a
+	    <tt>.changes</tt> file indicates that the file in question
+	    is not an ordinary package file and must by installed by
+	    hand by the distribution maintainers.  If the section is
+	    <tt>byhand</tt> the priority should be <tt>-</tt>.
+	  </p>
+
+	  <p>	    
+	    If a new Debian revision of a package is being shipped and
+	    no new original source archive is being distributed the
+	    <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+	    entry for the original source archive
+	    <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
+	    but the <tt>.changes</tt> file should leave it out.  In
+	    this case the original source archive on the distribution
+	    site must match exactly, byte-for-byte, the original
+	    source archive which was used to generate the
+	    <tt>.dsc</tt> file and diff which are being uploaded.</p>
+	</sect1>
+	  
+	  
+	<sect1
+	id="f-Standards-Version"><heading><tt>Standards-Version</tt>
+	  </heading>
+
+	  <p>	    
+	    The most recent version of the standards (the
+	    <prgn>dpkg</prgn> programmers' and policy manuals and
+	    associated texts) with which the package complies.  This
+	    is updated manually when editing the source package to
+	    conform to newer standards; it can sometimes be used to
+	    tell when a package needs attention.
+	  </p>
+
+	  <p>	    
+	    Its format is the same as that of a version number except
+	    that no epoch or Debian revision is allowed - see <ref
+	    id="versions">.</p>
+	</sect1>
+	  
+	  
+	<sect1 id="f-Distribution"><heading><tt>Distribution</tt>
+	  </heading>
+
+	  <p>	    
+	    In a <tt>.changes</tt> file or parsed changelog output
+	    this contains the (space-separated) name(s) of the
+	    distribution(s) where this version of the package should
+	    be or was installed.  Distribution names follow the rules
+	    for package names.  (See <ref id="f-Package">).
+	  </p>
+
+	  <p>	    
+	    Current distribution values are:
+	  <taglist>
+	    <tag><em>stable</em></tag>
+	    <item>
+	      <p> 
+		This is the current `released' version of Debian
+		GNU/Linux.  A new version is released approximately
+		every 3 months after the <em>development</em> code has
+		been <em>frozen</em> for a month of testing.  Once the
+		distribution is <em>stable</em> only major bug fixes
+		are allowed. When changes are made to this
+		distribution, the minor version number is increased
+		(for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
+	      </p>
+	    </item>
+		
+	    <tag><em>unstable</em></tag>
+	    <item>
+	      <p>
+		This distribution value refers to the
+		<em>developmental</em> part of the Debian distribution
+		tree. New packages, new upstream versions of packages
+		and bug fixes go into the <em>unstable</em> directory
+		tree. Download from this distribution at your own
+		risk.</p>
+	    </item>
+	    
+	    <tag><em>contrib</em></tag>
+	    <item>
+	      <p>
+		The packages with this distribution value do not meet
+		the criteria for inclusion in the main Debian
+		distribution as defined by the Policy Manual, but meet
+		the criteria for the <em>contrib</em>
+		Distribution. There is currently no distinction
+		between stable and unstable packages in the
+		<em>contrib</em> or <em>non-free</em>
+		distributions. Use your best judgement in downloading
+		from this Distribution.</p>
+	    </item>
+		
+	    <tag><em>non-free</em></tag>
+	    <item>
+	      <p>
+		Like the packages in the <em>contrib</em> seciton,
+		the packages in <em>non-free</em> do not meet the
+		criteria for inclusion in the main Debian distribution
+		as defined by the Policy Manual. Again, use your best
+		judgement in downloading from this Distribution.</p>
+	      
+	    <tag><em>experimental</em></tag>
+	    <item>
+	      <p>
+		The packages with this distribution value are deemed
+		by their maintainers to be high risk. Oftentimes they
+		represent early beta or developmental packages from
+		various sources that the maintainers want people to
+		try, but are not ready to be a part of the other parts
+		of the Debian distribution tree. Download at your own
+		risk.</p>
+	    </item>
+		
+	    <tag><em>frozen</em></tag>
+	    <item>
+	      <p>
+		From time to time, (currently, every 3 months) the
+		<em>unstable</em> distribution enters a state of
+		`code-freeze' in anticipation of release as a
+		<em>stable</em> version. During this period of testing
+		(usually 4 weeks) only fixes for existing or
+		newly-discovered bugs will be allowed.
+	      </p>
+	    </item>
+	  </taglist> You should list <em>all</em> distributions that
+	  the package should be installed into. Except in unusual
+	  circumstances, installations to <em>stable</em> should also
+	  go into <em>frozen</em> (if it exists) and
+	  <em>unstable</em>. Likewise, installations into
+	  <em>frozen</em> should also go into <em>unstable</em>.</p>
+	</sect1>
+	  
+	<sect1 id="f-Urgency"><heading><tt>Urgency</tt>
+	  </heading>
+
+	  <p>	    
+	    This is a description of how important it is to upgrade to
+	    this version from previous ones.  It consists of a single
+	    keyword usually taking one of the values <tt>LOW</tt>,
+	    <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
+	    commentary (separated by a space) which is usually in
+	    parentheses.  For example:
+	    <example>
+	      Urgency: LOW (HIGH for diversions users)
+	    </example>
+	  </p>
+
+	  <p>	    
+	    This field appears in the <tt>.changes</tt> file and in
+	    parsed changelogs; its value appears as the value of the
+	    <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
+	    changelog (see <ref id="dpkgchangelog">).
+	  </p>
+
+	  <p>	    
+	    Urgency keywords are not case-sensitive.</p>
+	</sect1>
+	  
+	<sect1 id="f-Date"><heading><tt>Date</tt>
+	  </heading>
+
+	  <p>	    
+	    In <tt>.changes</tt> files and parsed changelogs, this
+	    gives the date the package was built or last edited.</p>
+	</sect1>
+	  
+	<sect1 id="f-Format"><heading><tt>Format</tt>
+	  </heading>
+
+	  <p>	    
+	    This field occurs in <tt>.changes</tt> files, and
+	    specifies a format revision for the file.  The format
+	    described here is version <tt>1.5</tt>.  The syntax of the
+	    format value is the same as that of a package version
+	    number except that no epoch or Debian revision is allowed
+	    - see <ref id="versions">.</p>
+	</sect1>
+	  
+	<sect1 id="f-Changes"><heading><tt>Changes</tt>
+	  </heading>
+
+	  <p>	    
+	    In a <tt>.changes</tt> file or parsed changelog this field
+	    contains the human-readable changes data, describing the
+	    differences between the last version and the current one.
+	  </p>
+
+	  <p>	    
+	    There should be nothing in this field before the first
+	    newline; all the subsequent lines must be indented by at
+	    least one space; blank lines must be represented by a line
+	    consiting only of a space and a full stop.
+	  </p>
+
+	  <p>	    
+	    Each version's change information should be preceded by a
+	    `title' line giving at least the version, distribution(s)
+	    and urgency, in a human-readable way.
+	  </p>
+
+	  <p>	    
+	    If data from several versions is being returned the entry
+	    for the most recent version should be returned first, and
+	    entries should be separated by the representation of a
+	    blank line (the `title' line may also be followed by the
+	    representation of blank line).</p>
+	</sect1>
+	  
+	<sect1 id="f-Filename"><heading><tt>Filename</tt> and
+	<tt>MSDOS-Filename</tt>
+	  </heading>
+
+	  <p>	    
+	    These fields in <tt>Packages</tt> files give the
+	    filename(s) of (the parts of) a package in the
+	    distribution directories, relative to the root of the
+	    Debian hierarchy.  If the package has been split into
+	    several parts the parts are all listed in order, separated
+	    by spaces.</p>
+	</sect1>
+	  
+	<sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
+	  </heading>
+
+	  <p>	    
+	    These fields in <tt>Packages</tt> files give the size (in
+	    bytes, expressed in decimal) and MD5 checksum of the
+	    file(s) which make(s) up a binary package in the
+	    distribution.  If the package is split into several parts
+	    the values for the parts are listed in order, separated by
+	    spaces.</p>
+	</sect1>
+	  
+	<sect1 id="f-Status"><heading><tt>Status</tt>
+	  </heading>
+
+	  <p>	    
+	    This field in <prgn>dpkg</prgn>'s status file records
+	    whether the user wants a package installed, removed or
+	    left alone, whether it is broken (requiring
+	    reinstallation) or not and what its current state on the
+	    system is.  Each of these pieces of information is a
+	    single word.</p>
+	</sect1>
+	  
+	<sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
+	  </heading>
+
+	  <p>	    
+	    If a package is not installed or not configured, this
+	    field in <prgn>dpkg</prgn>'s status file records the last
+	    version of the package which was successfully
+	    configured.</p>
+	</sect1>
+	  
+	<sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
+	  </heading>
+
+	  <p>	    
+	    This field in <prgn>dpkg</prgn>'s status file contains
+	    information about the automatically-managed configuration
+	    files held by a package.  This field should <em>not</em>
+	    appear anywhere in a package!</p>
+	</sect1>
+	  
+	<sect1><heading>Obsolete fields
+	  </heading>
+
+	  <p>	    
+	    These are still recognised by <prgn>dpkg</prgn> but should
+	    not appear anywhere any more.
+	    <taglist compact="compact">
+	      
+	      <tag><tt>Revision</tt></tag>
+	      <tag><tt>Package-Revision</tt></tag>
+	      <tag><tt>Package_Revision</tt></tag>
+	      <item>
+		<p>
+		  The Debian revision part of the package version was
+		  at one point in a separate control file field.  This
+		  field went through several names.</p>
+	      </item>
+		  
+	      <tag><tt>Recommended</tt></tag>
+	      <item><p>Old name for <tt>Recommends</tt></p>
+	      </item>
+		
+	      <tag><tt>Optional</tt></tag>
+	      <item><p>Old name for <tt>Suggests</tt>.</p>
+	      </item>
+	      <tag><tt>Class</tt></tag>
+	      <item><p>Old name for <tt>Priority</tt>.</p>
+	      </item>
+	    </taglist>
+	  </p>
+	</sect1>
+      </sect>
+    </chapt>
+
+    <chapt id="versions"><heading>Version numbering
+      </heading>
+
+      <p>	
+	Every package has a version number, in its <tt>Version</tt>
+	control file field.
+      </p>
+
+      <p>	
+	<prgn>dpkg</prgn> imposes an ordering on version numbers, so
+	that it can tell whether packages are being up- or downgraded
+	and so that <prgn>dselect</prgn> can tell whether a package it
+	finds available is newer than the one installed on the system.
+	The version number format has the most significant parts (as
+	far as comparison is concerned) at the beginning.
+      </p>
+
+      <p>	
+	The version number format is:
+	&lsqb<var>epoch/<tt>:</tt>&rsqb;<var>upstream-version</var>&lsqb;<tt>-/<var>debian-revision</var>&rsqb;.</tt></var>
+      </p>
+
+      <p>	
+	The three components here are:
+	<taglist>
+	  <tag><var>epoch</var></tag>
+	  <item>
+	    
+	    <p>
+	      This is a single unsigned integer, which should usually
+	      be small.  It may be omitted, in which case zero is
+	      assumed.  If it is omitted then the
+	      <var>upstream-version</var> may not contain any colons.
+	    </p>
+
+	    <p>	      
+	      It is provided to allow mistakes in the version numbers
+	      of older versions of a package, and also a package's
+	      previous version numbering schemes, to be left behind.
+	    </p>
+
+	    <p>	      
+	      <prgn>dpkg</prgn> will not usually display the epoch
+	      unless it is essential (non-zero, or if the
+	      <var>upstream-version</var> contains a colon);
+	      <prgn>dselect</prgn> does not display epochs at all in
+	      the main part of the package selection display.</p>
+	  </item>
+	    
+	  <tag><var>upstream-version</var></tag>
+	  <item>
+	    
+	    <p>
+	      This is the main part of the version.  It is usually
+	      version number of the original (`upstream') package of
+	      which the <tt>.deb</tt> file has been made, if this is
+	      applicable.  Usually this will be in the same format as
+	      that specified by the upstream author(s); however, it
+	      may need to be reformatted to fit into
+	      <prgn>dpkg</prgn>'s format and comparison scheme.
+	    </p>
+
+	    <p>	      
+	      The comparison behaviour of <prgn>dpkg</prgn> with
+	      respect to the <var>upstream-version</var> is described
+	      below.  The <var>upstream-version</var> portion of the
+	      version number is mandatory.
+	    </p>
+
+	    <p>	      
+	      The <var>upstream-version</var> may contain only
+	      alphanumerics and the characters <tt>+</tt> <tt>.</tt>
+	      <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
+	      and should start with a digit.  If there is no
+	      <var>debian-revision</var> then hyphens are not allowed;
+	      if there is no <var>epoch</var> then colons are not
+	      allowed.</p>
+	  </item>
+	    
+	  <tag><var>debian-revision</var></tag>
+	  <item>
+	    
+	    <p>
+	      This part of the version represents the version of the
+	      modifications that were made to the package to make it a
+	      Debian binary package.  It is in the same format as the
+	      <var>upstream-version</var> and <prgn>dpkg</prgn>
+	      compares it in the same way.
+	    </p>
+
+	    <p>	      
+	      It is optional; if it isn't present then the
+	      <var>upstream-version</var> may not contain a hyphen.
+	      This format represents the case where a piece of
+	      software was written specifically to be turned into a
+	      Debian binary package, and so there is only one
+	      `debianization' of it and therefore no revision
+	      indication is required.
+	    </p>
+
+	    <p>	      
+	      It is conventional to restart the
+	      <var>debian-revision</var> at <tt>1</tt> each time the
+	      <var>upstream-version</var> is increased.
+	    </p>
+
+	    <p>	      
+	      <prgn>dpkg</prgn> will break the
+	      <var>upstream-version</var> and
+	      <var>debian-revision</var> apart at the last hyphen in
+	      the string.  The absence of a <var>debian-revision</var>
+	      compares earlier than the presence of one (but note that
+	      the <var>debian-revision</var> is the least significant
+	      part of the version number).
+	    </p>
+
+	    <p>	      
+	      The <var>debian-revision</var> may contain only
+	      alphanumerics and the characters <tt>+</tt> and
+	      <tt>.</tt> (plus and full stop).
+	    </p>
+	  </item>
+	</taglist>
+	The <var>upstream-version</var> and <var>debian-revision</var> parts are
+	compared by <prgn>dpkg</prgn> using the same algorithm:
+      </p>
+
+      <p>	
+	The strings are compared from left to right.
+      </p>
+
+      <p>	
+	First the initial part of each string consisting entirely of
+	non-digit characters is determined.  These two parts (one of
+	which may be empty) are compared lexically.  If a difference
+	is found it is returned.  The lexical comparison is a
+	comparison of ASCII values modified so that all the letters
+	sort earlier than all the non-letters.
+      </p>
+
+      <p>	
+	Then the initial part of the remainder of each string which
+	consists entirely of digit characters is determined.  The
+	numerical values of these two parts are compared, and any
+	difference found is returned as the result of the comparison.
+	For these purposes an empty string (which can only occur at
+	the end of one or both version strings being compared) counts
+	as zero.
+      </p>
+
+      <p>	
+	These two steps are repeated (chopping initial non-digit
+	strings and initial digit strings off from the start) until a
+	difference is found or both strings are exhausted.
+      </p>
+
+      <p>	
+	Note that the purpose of epochs is to allow us to leave behind
+	mistakes in version numbering, and to cope with situations
+	where the version numbering changes.  It is <em>not</em> there
+	to cope with version numbers containing strings of letters
+	which <prgn>dpkg</prgn> cannot interpret (such as
+	<tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
+	author of this manual has heard of a package whose versions
+	went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
+	<tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
+      </p>
+
+      <p>	
+	If an upstream package has problematic version numbers they
+	should be converted to a sane form for use in the
+	<tt>Version</tt> field.
+      </p>
+
+      <p>	
+	If you need to compare version numbers in a script, you may use
+	<tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
+	--help</tt> --> --for details on arguments.
+      </p>
+    </chapt>
+      
+    <chapt id="maintainerscripts"><heading>Package maintainer scripts
+	and installation procedure
+      </heading>
+
+      <sect><heading>Introduction to package maintainer scripts
+	</heading>
+
+	<p>	  
+	  It is possible supply scripts as part of a package which
+	  <prgn>dpkg</prgn> will run for you when your package is
+	  installed, upgraded or removed.
+	</p>
+
+	<p>	  
+	  These scripts should be the files <tt>preinst</tt>,
+	  <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
+	  control area of the package.  They must be proper exectuable
+	  files; if they are scripts (which is recommended) they must
+	  start with the usual <tt>#!</tt> convention.  They should be
+	  readable and executable to anyone, and not world-writeable.
+	</p>
+
+	<p>	  
+	  <prgn>dpkg</prgn> looks at the exit status from these
+	  scripts.  It is important that they exit with a non-zero
+	  status if there is an error, so that <prgn>dpkg</prgn> can
+	  stop its processing.  For shell scripts this means that you
+	  <em>almost always</em> need to use <tt>set -e</tt> (this is
+	  usually true when writing shell scripts, in fact).  It is
+	  also important, of course, that they don't exit with a
+	  non-zero status if everything went well.
+	</p>
+
+	<p>	  
+	  It is necessary for the error recovery procedures that the
+	  scripts be idempotent: ie, invoking the same script several
+	  times in the same situation should do no harm.  If the first
+	  call failed, or aborted half way through for some reason,
+	  the second call should merely do the things that were left
+	  undone the first time, if any, and exit with a success
+	  status.
+	</p>
+
+	<p>	  
+	  When a package is upgraded a combination of the scripts from
+	  the old and new packages is called in amongst the other
+	  steps of the upgrade procedure.  If your scripts are going
+	  to be at all complicated you need to be aware of this, and
+	  may need to check the arguments to your scripts.
+	</p>
+
+	<p>	  
+	  Broadly speaking the <prgn>preinst</prgn> is called before
+	  (a particular version of) a package is installed, and the
+	  <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+	  before (a version of) a package is removed and the
+	  <prgn>postrm</prgn> afterwards.	
+	</p>
+	  <!--
+	  next paragraph by Guy Maor to close bug #2481
+	  -->
+ 
+	  <p> Programs called from maintainer scripts should not
+	  normally have a path prepended to them. Before installation
+	  is started <prgn>dpkg</prgn> checks to see if the programs
+	  <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
+	  <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
+	  be found via the <tt>PATH</tt> environment variable. Those
+	  programs, and any other program that one would expect to on
+	  the <tt>PATH</tt>, should thus be invoked without an
+	  absolute pathname. Maintainer scripts should also not reset
+	  the <tt>PATH</tt>, though they might choose to modify it by
+	  pre- or appending package-specific directories. These
+	  considerations really apply to all shell scripts.</p>
+      </sect>
+	
+      <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+      scripts are called
+	</heading>
+
+	<p>	  
+	  <list compact="compact">
+	    <item>
+	      <p><var>new-preinst</var> <tt>install</tt></p>
+	    </item>
+	    <item>
+	      <p><var>new-preinst</var> <tt>install</tt>
+	      <var>old-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>new-preinst</var> <tt>upgrade</tt>
+	      <var>old-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>old-preinst</var> <tt>abort-upgrade</tt>
+	      <var>new-version</var>
+	      </p>
+	    </item> 
+	  </list>
+
+	<p>	  
+	  <list compact="compact">
+	    <item>
+	      <p><var>postinst</var> <tt>configure</tt>
+		<var>most-recently-configured-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>old-postinst</var> <tt>abort-upgrade</tt>
+	      <var>new version</var></p>
+	    </item>
+	    <item>
+	      <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+		<tt>in-favour</tt> <var>package</var>
+		<var>new-version</var></p>
+	    </item>
+	    <item>
+	      <p>
+		<var>deconfigured's-postinst</var>
+		<tt>abort-deconfigure</tt> <tt>in-favour</tt>
+		<var>failed-install-package</var> <var>version</var>
+		<tt>removing</tt> <var>conflicting-package</var>
+		<var>version</var>
+	      </p>
+	    </item>
+	  </list>
+
+	<p>	  
+	  <list compact="compact">
+	    <item>
+	      <p><var>prerm</var> <tt>remove</tt></p>
+	    </item>
+	    <item>
+	      <p><var>old-prerm</var> <tt>upgrade</tt>
+		<var>new-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>new-prerm</var> <tt>failed-upgrade</tt>
+		<var>old-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>conflictor's-prerm</var> <tt>remove</tt>
+		<tt>in-favour</tt> <var>package</var>
+		<var>new-version</var></p>
+	    </item>
+	    <item>
+	      <p>
+		<var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+		<tt>in-favour</tt> <var>package-being-installed</var>
+		<var>version</var> <tt>removing</tt>
+		<var>conflicting-package</var>
+		<var>version</var>
+	      </p>
+	    </item>
+	  </list>
+
+	<p>	  
+	  <list compact="compact">
+	    <item>
+	      <p><var>postrm</var> <tt>remove</tt></p>
+	    </item>
+	    <item>
+	      <p><var>postrm</var> <tt>purge</tt></p>
+	    </item>
+	    <item>
+	      <p>
+		<var>old-postrm</var> <tt>upgrade</tt>
+		<var>new-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>new-postrm</var> <tt>failed-upgrade</tt>
+		<var>old-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>new-postrm</var> <tt>abort-install</tt></p>
+	    </item>
+	    <item>
+	      <p><var>new-postrm</var> <tt>abort-install</tt>
+		<var>old-version</var></p>
+	    </item>
+	    <item>
+	      <p><var>new-postrm</var> <tt>abort-upgrade</tt>
+		<var>old-version</var></p>
+	    </item>
+	    <item>
+	      <p>
+		<var>disappearer's-postrm</var> <tt>disappear</tt>
+		<var>r>overwrit</var>r>
+		<var>new-version</var></p></item>
+	  </list>
+	</p>
+	
+	
+      <sect id="unpackphase"><heading>Details of unpack phase of
+      installation or upgrade
+	</heading>
+
+	<p>	  
+	  The procedure on installation/upgrade/overwrite/disappear
+	  (ie, when running <tt>dpkg --unpack</tt>, or the unpack
+	  stage of <tt>dpkg
+	    --install</tt>) is as follows.  In each case if an error occurs the
+	  actions in are general run backwards - this means that the maintainer
+	  scripts are run with different arguments in reverse order.  These are
+	  the `error unwind' calls listed below.
+	  
+	  <enumlist>
+	    <item>
+	      <p>
+		<enumlist>
+		  <item>
+		    <p>If a version the package is already
+		      installed, call
+		      <example>
+			<var>old-prerm</var> upgrade <var>new-version</var>
+		      </example></p>
+		  </item>
+		  <item>
+		    <p>
+		      If this gives an error (ie, a non-zero exit
+		      status), dpkg will attempt instead:
+		      <example>
+			<var>new-prerm</var> failed-upgrade <var>old-version</var>
+		      </example>
+		      Error unwind, for both the above cases:
+		      <example>
+			<var>old-postinst</var> abort-upgrade <var>new-version</var>
+		      </example>
+		    </p>
+		  </item>
+		</enumlist>
+	      </p>
+	    </item>
+	    <item>
+	      <p>If a `conflicting' package is being removed at the same time:
+		<enumlist>
+		  <item>
+		    <p>
+		      If any packages depended on that conflicting
+		      package and <tt>--auto-deconfigure</tt> is
+		      specified, call, for each such package:
+		      <example>
+			<var>deconfigured's-prerm</var> deconfigure \
+			in-favour <var>package-being-installed</var> <var>version</var> \
+			removing <var>conflicting-package</var> <var>version</var>
+		      </example>
+		      Error unwind:
+		      <example>
+			<var>deconfigured's-postinst</var> abort-deconfigure \
+			in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+			removing <var>conflicting-package</var> <var>version</var>
+		      </example> 
+		      The deconfigured packages are marked as
+		      requiring configuration, so that if
+		      <tt>--install</tt> is used they will be
+		      configured again if possible.</p>
+		  </item>
+		  <item>
+		    <p>To prepare for removal of the conflicting package, call:
+		      <example>
+			<var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+		      </example>
+		      Error unwind:
+		      <example>
+			<var>conflictor's-postinst</var> abort-remove \
+			in-favour <var>package</var> <var>new-version</var>
+		      </example>
+		    </p>
+		  </item>
+		</enumlist>
+	      </p>
+	    </item>
+	    <item>
+	      <p>
+		<enumlist>
+		  <item>
+		    <p>If the package is being upgraded, call:
+		      <example>
+			<var>new-preinst</var> upgrade <var>old-version</var>
+		      </example></p>
+		  </item>
+		  <item>
+		    <p>
+		      Otherwise, if the package had some configuration
+		      files from a previous version installed (ie, it
+		      is in the `configuration files only' state):
+		      <example>
+			<var>new-preinst</var> install <var>old-version</var>
+		      </example></p>
+		    
+		  <item>
+		    <p>Otherwise (ie, the package was completely purged):
+		      <example>
+			<var>new-preinst</var> install
+		      </example>
+		      Error unwind versions, respectively:
+		      <example>
+			<var>new-postrm</var> abort-upgrade <var>old-version</var>
+			<var>new-postrm</var> abort-install <var>old-version</var>
+			<var>new-postrm</var> abort-install
+		      </example>
+		    </p>
+		  </item>
+		</enumlist>
+	      </p>
+	    </item>
+	    <item>
+
+	      <p>
+		The new package's files are unpacked, overwriting any
+		that may be on the system already, for example any
+		from the old version of the same package or from
+		another package (backups of the old files are left
+		around, and if anything goes wrong dpkg will attempt
+		to put them back as part of the error unwind).
+	      </p>
+
+	      <p>		
+		It is an error for a package to contains files which
+		are on the system in another package, unless
+		<tt>Replaces</tt> is used (see <ref id="replaces">).
+		Currently the <tt>--force-overwrite</tt> flag is
+		enabled, downgrading it to a warning, but this may not
+		always be the case.
+	      </p>
+
+	      <p>		
+		It is a more serious error for a package to contain a
+		plain file or other kind of nondirectory where another
+		package has a directory (again, unless
+		<tt>Replaces</tt> is used).  This error can be
+		overridden if desired using
+		<tt>--force-overwrite-dir</tt>, but this is not
+		advisable.
+	      </p>
+
+	      <p>		
+		Packages which overwrite each other's files produce
+		behaviour which though deterministic is hard for the
+		system administrator to understand.  It can easily
+		lead to `missing' programs if, for example, a package
+		is installed which overwrites a file from another
+		package, and is then removed again.
+		<footnote>
+		  <p>
+		    Part of the problem is due to what is arguably a
+		    bug in <prgn>dpkg</prgn> .
+		  </p>
+		</footnote>
+	      </p>
+
+	      <p>		
+		A directory will never be replaced by a symbolic links
+		to a directory or vice versa; instead, the existing
+		state (symlink or not) will be left alone and
+		<prgn>dpkg</prgn> will follow the symlink if there is
+		one.</p>
+	    </item>
+	      
+	    <item>
+	      
+	      <p><enumlist>
+		  <item>
+		    <p>If the package is being upgraded, call
+		      <example>
+			<var>old-postrm</var> upgrade <var>new-version</var>
+		      </example></p>
+		  </item>
+		  <item>
+		    <p>If this fails, <prgn>dpkg</prgn> will attempt:
+		      <example>
+			<var>new-postrm</var> failed-upgrade <var>old-version</var>
+		      </example>
+		      Error unwind, for both cases:
+		      <example>
+			<var>old-preinst</var> abort-upgrade <var>new-version</var>
+		      </example>
+		    </p>
+		  </item>
+		</enumlist>
+		This is the point of no return - if <prgn>dpkg</prgn>
+		gets this far, it won't back off past this point if an
+		error occurs.  This will leave the package in a fairly
+		bad state, which will require a successful
+		reinstallation to clear up, but it's when
+		<prgn>dpkg</prgn> starts doing things that are
+		irreversible.</p>
+	    </item>
+	    <item>
+	      <p>		
+		Any files which were in the old version of the package
+		but not in the new are removed.</p>
+	    </item>
+	    <item>
+		<p>The new file list replaces the old.</p>
+	    </item>
+	    <item>
+		<p>The new maintainer scripts replace the old.</p>
+	    </item>
+		
+	    <item>
+	      <p>Any packages all of whose files have been overwritten during the
+		installation, and which aren't required for
+		dependencies, are considered to have been removed.
+		For each such package,
+		<enumlist>
+		  <item>
+		    <p><prgn>dpkg</prgn> calls:
+		      <example>
+			<var>disappearer's-postrm</var> disappear \
+			<var>overwriter</var> <var>overwriter-version</var>
+		      </example></p>
+		  </item>
+		  <item>
+		      <p>The package's maintainer scripts are removed.
+		    </p>
+		  </item>
+		  <item>
+		    <p>
+		      It is noted in the status database as being in a
+		      sane state, namely not installed (any conffiles
+		      it may have are ignored, rather than being
+		      removed by <prgn>dpkg</prgn>).  Note that
+		      disappearing packages do not have their prerm
+		      called, because <prgn>dpkg</prgn> doesn't know
+		      in advance that the package is going to
+		      vanish.
+		    </p>
+		  </item>
+		</enumlist>
+	      </p>
+	    </item>
+	    <item>
+	      <p>
+		Any files in the package we're unpacking that are also
+		listed in the file lists of other packages are removed
+		from those lists.  (This will lobotomise the file list
+		of the `conflicting' package if there is one.)
+	      </p>
+	    </item>
+	    <item>
+	      <p>
+		The backup files made during installation, above, are
+		deleted.
+	      </p>
+	    </item>
+		
+	    <item>
+	      <p>
+		The new package's status is now sane, and recorded as
+		`unpacked'.  Here is another point of no return - if
+		the conflicting package's removal fails we do not
+		unwind the rest of the installation; the conflicting
+		package is left in a half-removed limbo.
+	      </p>
+	    </item>
+	    <item>
+	      <p>
+		If there was a conflicting package we go and do the
+		removal actions (described below), starting with the
+		removal of the conflicting package's files (any that
+		are also in the package being installed have already
+		been removed from the conflicting package's file list,
+		and so do not get removed now).
+	      </p>
+	    </item>
+	  </enumlist>
+	</p>
+      </sect>
+
+      <sect><heading>Details of configuration
+	</heading>
+
+	<p>	  
+	  When we configure a package (this happens with <tt>dpkg
+	  --install</tt>, or with <tt>--configure</tt>), we first
+	  update the conffiles and then call:
+	  <example>
+	    <var>postinst</var> configure <var>most-recently-configured-version</var>
+	  </example>
+	</p>
+
+	<p>	  
+	  No attempt is made to unwind after errors during
+	  configuration.
+	</p>
+
+	<p>	  
+	  If there is no most recently configured version
+	  <prgn>dpkg</prgn> will pass a null argument; older versions
+	  of dpkg may pass <tt>&lt;unknown&gt;</tt> (including the
+	  angle brackets) in this case.  Even older ones do not pass a
+	  second argument at all, under any circumstances.
+	</p>
+      </sect>
+	
+      <sect><heading>Details of removal and/or configuration purging
+	</heading>
+
+	<p>	  
+	  <enumlist>
+	    <item>
+	      <p><example>
+		  <var>prerm</var> remove
+		</example></p>
+	    </item>
+	    <item>
+	      <p>
+		The package's files are removed (except conffiles).
+	      </p>
+	    </item>
+	    <item>
+	      <p><example>
+		  <var>postrm</var> remove
+		</example></p>
+	    </item>
+	    <item>
+	      <p>All the maintainer scripts except the postrm are removed.
+	      </p>
+
+	      <p>		
+		If we aren't purging the package we stop here.  Note
+		that packages which have no postrm and no conffiles
+		are automatically purged when removed, as there is no
+		difference except for the <prgn>dpkg</prgn>
+		status.</p>
+	    </item>
+	    <item>
+	      <p>
+		The conffiles and any backup files (<tt>~</tt>-files,
+		<tt>#*#</tt> files, <tt>%</tt>-files,
+		<tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
+	    </item>
+	    <item>
+	      <p><example>
+		  <var>postrm</var> purge
+		</example></p>
+	    </item>
+	    <item>
+		<p>The package's file list is removed.</p>
+	    </item>
+	  </enumlist>
+	  No attempt is made to unwind after errors during
+	  removal.</p>
+      </sect>
+    </chapt>
+      
+    <chapt id="descriptions"><heading>Descriptions of packages - the
+	<tt>Description</tt> field
+      </heading>
+
+      <p>	
+	The <tt>Description</tt> control file field is used by
+	<prgn>dselect</prgn> when the user is selecting which packages
+	to install and by <prgn>dpkg</prgn> when it displays
+	information about the status of packages and so forth.  It is
+	included on the FTP site in the <prgn>Packages</prgn> files,
+	and may also be used by the Debian WWW pages.
+      </p>
+
+      <p>	
+	The description is intended to describe the program to a user
+	who has never met it before so that they know whether they
+	want to install it.  It should also give information about the
+	significant dependencies and conflicts between this package
+	and others, so that the user knows why these dependencies and
+	conflicts have been declared.
+      </p>
+
+      <p>	
+	The field's format is as follows:
+	<example>
+	  Description: <var>single line synopsis</var>
+	  <var>extended description over several lines</var>
+	</example>
+      </p>
+
+      <p>	
+	The synopsis is often printed in lists of packages and so
+	forth, and should be as informative as possible.  Every
+	package should also have an extended description.
+      </p>
+
+      <sect><heading>Types of formatting line in the extended
+	  description
+	</heading>
+
+	<p>	  
+	  <list>
+	    <item>
+	      <p>
+		Those starting with a single space are part of a
+		paragraph.  Successive lines of this form will be
+		word-wrapped when displayed.  The leading space will
+		usually be stripped off.
+	      </p>
+	    </item>
+		
+	    <item>
+	      <p>
+		Those starting with two or more spaces.  These will be
+		displayed verbatim.  If the display cannot be panned
+		horizontally the displaying program will linewrap them
+		`hard' (ie, without taking account of word breaks).
+		If it can they will be allowed to trail off to the
+		right.  None, one or two initial spaces may be
+		deleted, but the number of spaces deleted from each
+		line will be the same (so that you can have indenting
+		work correctly, for example).
+	      </p>
+	    </item>
+		
+	    <item>
+	      <p>Those containing a single space followed by a single full stop
+		character.  These are rendered as blank lines.  This
+		is the <em>only</em> way to get a blank line - see
+		below.</p>
+	    </item>
+	      
+	    <item>
+	      <p>
+		Those containing a space, a full stop and some more
+		characters.  These are for future expansion.  Do not
+		use them.</p>
+	    </item>
+	  </list>
+	</p>
+      </sect>
+
+      <sect><heading>Notes about writing descriptions
+	</heading>
+
+	<p>	  
+	  <em>Always</em> start extended description lines with at least one
+	  whitespace character.  Fields in the control file and in the Packages
+	  file are separated by field names starting in the first column, just
+	  as message header fields are in RFC822.  Forgetting the whitespace
+	  will cause <prgn>dpkg-deb</prgn>
+	  <footnote>
+	    <p>
+	      Version 0.93.23 or later.
+	    </p>
+	  </footnote> to produce a syntax error when trying to build
+	  the package.  If you force it to build anyway
+	  <prgn>dpkg</prgn> will refuse to install the resulting
+	  mess.
+	</p>
+
+	<p>	  
+	  <em>Do not</em> include any completely <em>empty</em>
+	  lines. These separate different records in the Packages file
+	  and different packages in the <tt>debian/control</tt> file,
+	  and are forbidden in package control files.  See the
+	  previous paragraph for what happens if you get this wrong.
+	</p>
+
+	<p>	  
+	  The single line synopsis should be kept brief - certainly
+	  under 80 characters.  <prgn>dselect</prgn> displays between
+	  25 and 49 characters without panning if you're using an
+	  80-column terminal, depending on what display options are in
+	  effect.
+	</p>
+
+	<p>	  
+	  Do not include the package name in the synopsis line.  The
+	  display software knows how to display this already, and you
+	  do not need to state it.  Remember that in many situations
+	  the user may only see the synopsis line - make it as
+	  informative as you can.
+	</p>
+
+	<p>	  
+	  The extended description should describe what the package
+	  does and how it relates to the rest of the system (in terms
+	  of, for example, which subsystem it is which part of).
+	</p>
+
+	<p>	  
+	  The blurb that comes with a program in its announcements
+	  and/or <prgn>README</prgn> files is rarely suitable for use
+	  in a description.  It is usually aimed at people who are
+	  already in the community where the package is used.  The
+	  description field needs to make sense to anyone, even people
+	  who have no idea about any of the things the package deals
+	  with.
+	</p>
+
+	<p>	  
+	  Put important information first, both in the synopis and
+	  extended description.  Sometimes only the first part of the
+	  synopsis or of the description will be displayed.  You can
+	  assume that there will usually be a way to see the whole
+	  extended description.
+	</p>
+
+	<p>	  
+	  You may include information about dependencies and so forth
+	  in the extended description, if you wish.
+	</p>
+
+	<p>	  
+	  Do not use tab characters.  Their effect is not predictable.
+	</p>
+
+	<p>	  
+	  Do not try to linewrap the summary (the part on the same
+	  line as the field name <tt>Description</tt>) into the
+	  extended description.  This will not work correctly when the
+	  full description is displayed, and makes no sense where only
+	  the summary is available.</p>
+      </sect>
+	
+      <sect><heading>Example description in control file for Smail
+	</heading>
+
+	<p>	  
+	  <example>
+	    Package: smail
+	    Version: 3.1.29.1-13
+	    Maintainer: Ian Jackson &lt;iwj10@cus.cam.ac.uk&gt;
+	    Recommends: pine | mailx | elm | emacs | mail-user-agent
+	    Suggests: metamail
+	    Depends: cron, libc5
+	    Conflicts: sendmail
+	    Provides: mail-transport-agent
+	    Description: Electronic mail transport system.
+	    Smail is the recommended mail transport agent (MTA) for Debian.
+	    .
+	    An MTA is the innards of the mail system - it takes messages from
+	    user-friendly mailer programs and arranges for them to be delivered
+	    locally or passed on to other systems as required.
+	    .
+	    In order to make use of it you must have one or more user level
+	    mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
+	    and VM as mailreaders) installed.  If you wish to send messages other
+	    than just to other users of your system you must also have appropriate
+	    networking support, in the form of IP or UUCP.
+	  </example>
+	</p>
+      </sect>
+    </chapt>
+
+    <chapt id="relationships"><heading>Declaring relationships between
+    packages
+      </heading>
+
+      <p>	
+	Packages can declare in their control file that they have
+	certain relationships to other packages - for example, that
+	they may not be installed at the same time as certain other
+	packages, and/or that they depend on the presence of others,
+	or that they should overwrite files in certain other packages
+	if present.
+      </p>
+
+      <p>	
+	This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
+	<tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
+	<tt>Replaces</tt> control file fields.
+      </p>
+
+      <sect id="depsyntax"><heading>Syntax of relationship fields
+	</heading>
+
+	<p>	  
+	  These fields all have a uniform syntax.  They are a list of
+	  package names separated by commas.
+	</p>
+
+	<p>	  
+	  In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>
+	  and <tt>Pre-Depends</tt> (the fields which declare
+	  dependencies of the package in which they occur on other
+	  packages) these package names may also be lists of
+	  alternative package names, separated by vertical bar symbols
+	  <tt>|</tt> (pipe symbols).
+	</p>
+
+	<p>	  
+	  All the fields except <tt>Provides</tt> may restrict their
+	  applicability to particular versions of each named package.
+	  This is done in parentheses after each individual package
+	  name; the parentheses should contain a relation from the
+	  list below followed by a version number, in the format
+	  described in <ref id="versions">.
+	</p>
+
+	<p>	  
+	  The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
+	  <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
+	  strictly earlier, earlier or equal, exactly equal, later or
+	  equal and strictly later, respectively.  The forms
+	  <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
+	  earlier/later or equal, rather than strictly earlier/later,
+	  so they should not appear in new packages (though
+	  <prgn>dpkg</prgn> still supports them).
+	</p>
+
+	<p>	  
+	  Whitespace may appear at any point in the version
+	  specification, and must appear where it's necessary to
+	  disambiguate; it is not otherwise significant.  For
+	  consistency and in case of future changes to
+	  <prgn>dpkg</prgn> it is recommended that a single space be
+	  used after a version relationship and before a version
+	  number; it is usual also to put a single space after each
+	  comma, on either side of each vertical bar, and before each
+	  open parenthesis.
+	</p>
+
+	<p>	  
+	  For example:
+	  <example>
+	    Package: metamail
+	    Version: 2.7-3
+	    Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+	  </example>
+	</p>
+      </sect>
+
+      <sect><heading>Dependencies - <tt>Depends</tt>, <tt>Recommends</tt>,
+	  <tt>tt>Sugge</tt>tt>, <tt>Pre-Depends</tt>
+	</heading>
+
+	<p>	  
+	  These four fields are used to declare a dependency by one
+	  package on another.  They appear in the depending package's
+	  control file.
+	</p>
+
+	<p>	  
+	  All but <tt>Pre-Depends</tt> (discussed below) take effect
+	  <em>only</em> when a package is to be configured.  They do
+	  not prevent a package being on the system in an unconfigured
+	  state while its dependencies are unsatisfied, and it is
+	  possible to replace a package whose dependencies are
+	  satisfied and which is properly installed with a different
+	  version whose dependencies are not and cannot be satisfied;
+	  when this is done the depending package will be left
+	  unconfigured (since attempts to configure it will give
+	  errors) and will not function properly.
+	</p>
+
+	<p>	  
+	  For this reason packages in an installation run are usually
+	  all unpacked first and all configured later; this gives
+	  later versions of packages with dependencies on later
+	  versions of other packages the opportunity to have their
+	  dependencies satisfied.
+	</p>
+
+	<p>	  
+	  Thus <tt>Depends</tt> allows package maintainers to impose
+	  an order in which packages should be configured.
+	  <taglist>
+	    <tag><tt>Depends</tt></tag>
+	    <item>
+	      
+	      <p>This declares an absolute dependency.
+	      </p>
+
+	      <p>		
+		<prgn>dpkg</prgn> will not configure packages whose
+		dependencies aren't satisfied.  If it is asked to make
+		an installation which would cause an installed
+		package's dependencies to become unsatisfied it will
+		complain
+		<footnote>
+		  <p>
+		    Current versions (1.2.4) of <prgn>dpkg</prgn> have
+		    a bug in this area which will cause some of these
+		    problems to be ignored.
+		  </p>
+		</footnote>, unless <tt>--auto-deconfigure</tt> is
+		specified, in which case those packages will be
+		deconfigured before the installation proceeds.
+	      </p>
+
+	      <p>		
+		<prgn>dselect</prgn> makes it hard for the user to
+		select packages for installation, removal or upgrade
+		in a way that would mean that packages'
+		<prgn>Depends</prgn> fields would be unsatisfied.  The
+		user can override this if they wish, for example if
+		they know that <prgn>dselect</prgn> has an out-of-date
+		view of the real package relationships.
+	      </p>
+
+	      <p>		
+		The <tt>Depends</tt> field should be used if the
+		depended-on package is required for the depending
+		package to provide a significant amount of
+		functionality.</p>
+	    </item>
+	      
+	    <tag><tt>Recommends</tt></tag>
+	    <item>
+	      <p>This declares a strong, but not absolute, dependency.
+	      </p>
+
+	      <p>		
+		<tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
+		so that users using the command-line (who are presumed
+		to know what they're doing) will not be impeded.
+	      </p>
+
+	      <p>		
+		It is treated by <prgn>dselect</prgn> exactly as
+		<tt>Depends</tt> is; this makes it hard for the user
+		to select things so as to leave <tt>Recommends</tt>
+		fields unsatisfied, but they are able to do so by
+		being persistent.
+	      </p>
+
+	      <p>		
+		The <tt>Recommends</tt> field should list packages
+		that would be found together with this one in all but
+		unusual installations.</p>
+	    </item>
+	      
+	    <tag><tt>Suggests</tt></tag>
+	    <item>
+	      
+	      <p>
+		This is used to declare that one package may be more
+		useful with one or more others.  Using this field
+		tells the packaging system and the user that the
+		listed packages are be related to this one and can
+		perhaps enhance its usefulness, but that installing
+		this one without them is perfectly reasonable.
+	      </p>
+
+	      <p>		
+		<prgn>dselect</prgn> will offer suggsted packages to
+		the system administrator when they select the
+		suggesting package, but the default is not to install
+		the suggested package.</p>
+	    </item>
+	      
+	    <tag><tt>Pre-Depends</tt></tag>
+	    <item>
+	      
+	      <p>This field is like <tt>Depends</tt>, except that it also forces
+		<prgn>dpkg</prgn> to complete installation of the
+		packages named before even starting the installation
+		of the package which declares the predependency.
+	      </p>
+
+	      <p>		
+		<prgn>dselect</prgn> checks for predependencies when
+		it is doing an installation run, and will attempt to
+		find the packages which are required to be installed
+		first and do so in the right order.
+	      </p>
+
+	      <p>		
+		However, this process is slow (because it requires
+		repeated invocations of <prgn>dpkg</prgn>) and
+		troublesome (because it requires guessing where to
+		find the appropriate files).
+	      </p>
+
+	      <p>		
+		For these reasons, and because this field imposes
+		restrictions on the order in which packages may be
+		unpacked (which can be difficult for installations
+		from multipart media, for example),
+		<tt>Pre-Depends</tt> should be used sparingly,
+		preferably only by packages whose premature upgrade or
+		installation would hamper the ability of the system to
+		continue with any upgrade that might be in progress.
+	      </p>
+
+	      <p>		
+		When the package declaring it is being configured, a
+		<tt>Pre-Dependency</tt> will be considered satisfied
+		only if the depending package has been correctly
+		configured, just as if an ordinary <tt>Depends</tt>
+		had been used.
+	      </p>
+
+	      <p>		
+		However, when a package declaring a predependency is
+		being unpacked the predependency can be satisfied even
+		if the depended-on package(s) are only unpacked or
+		half-configured, provided that they have been
+		configured correctly at some point in the past (and
+		not removed or partially removed since).  In this case
+		both the previously-configured and currently unpacked
+		or half-configured versions must satisfy any version
+		clause in the <tt>Pre-Depends</tt> field.
+	      </p>
+	    </item>
+	  </taglist>
+	</p>
+	<p> 
+	  When selecting which level of dependency to use you should
+	  consider how important the depended-on package is to the
+	  functionality of the one declaring the dependency.  Some
+	  packages are composed of components of varying degrees of
+	  importance.  Such a package should list using
+	  <tt>Depends</tt> the package(s) which are required by the
+	  more important components.  The other components'
+	  requirements may be mentioned as Suggestions or
+	  Recommendations, as appropriate to the components' relative
+	  importance.
+	</p>
+
+      <sect1><heading>Dependencies on shared libraries
+	</heading>
+	
+	<p>	    
+	    The dependency fields listed above are used by packages
+	    which need shared libraries to declare dependencies on the
+	    appropriate packages.
+	</p>
+
+	<p>	    
+	  These dependencies are usually determined automatically
+	  using <prgn>dpkg-shlibdeps</prgn> and inserted in the
+	  package control file using the control file substitution
+	  variables mechanism; see <ref id="srcsubstvars"> and 
+	  <ref id="sourcetools">.
+	</p>
+      </sect1>
+	  
+      <sect1><heading>Deconfiguration due to removal during bulk
+      installations
+	</heading>
+	  
+	<p>	    
+	  If <prgn>dpkg</prgn> would like to remove a package due to a
+	  conflict, as described above, but this would violate a
+	  dependency of some other package on the system,
+	  <prgn>dpkg</prgn> will usually not remove the conflicting
+	  package and halt with an error.
+	</p>
+	  
+	<p>	    
+	  However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
+	  option is used <prgn>dpkg</prgn> will automatically
+	  `deconfigure' the package with the problematic dependency,
+	  so that the conflicting package can be removed and the
+	  package we're trying to install can be installed.  If
+	  <prgn>dpkg</prgn> is being asked to install packages (rather
+	  than just unpacking them) it will try to reconfigure the
+	  package when it has unpacked all its arguments, in the hope
+	  that one of the other packages it is installing will satisfy
+	  the problematic dependency.
+	</p>
+
+	  <p>	    
+	    <prgn>dselect</prgn> supplies this argument to
+	    <prgn>dpkg</prgn> when it invokes it, so that bulk
+	    installations proceed smoothly.
+	</p>
+      </sect1>
+
+      <sect id="conflicts"><heading>Alternative packages -
+	  <tt>tt>Confli</tt>tt> and <tt>Replaces</tt>
+	</heading>
+
+	<p>	  
+	  When one package declares a conflict with another
+	  <prgn>dpkg</prgn> will refuse to allow them to be installed
+	  on the system at the same time.
+	</p>
+
+	<p>	  
+	  If one package is to be installed, the other must be removed first -
+	  if the package being installed is marked as replacing (<ref
+								      id="replaces">) the one on the system, or the one on the system is
+	  marked as deselected, or both packages are marked
+	  <tt>Essential</tt>, then <prgn>dpkg</prgn> will
+	  automatically remove the package which is causing the
+	  conflict, otherwise it will halt the installation of the new
+	  package with an error.
+	</p>
+
+	<p>	  
+	  <prgn>dselect</prgn> makes it hard to select conflicting
+	  packages, though the user can override this if they wish.
+	  If they do not override it then <prgn>dselect</prgn> will
+	  select one of the packages for removal, and the user must
+	  make sure it is the right one.  In the future
+	  <prgn>dselect</prgn> will look for the presence of a
+	  <tt>Replaces</tt> field to help decide which package should
+	  be installed and which removed.
+	</p>
+
+	<p>	  
+	  A package will not cause a conflict merely because its
+	  configuration files are still installed; it must be at least
+	  half-installed.
+	</p>
+
+	<p>	  
+	  A special exception is made for packages which declare a
+	  conflict with their own package name, or with a virtual
+	  package which they provide (see below): this does not
+	  prevent their installation, and allows a package to conflict
+	  with others providing a replacement for it.  You use this
+	  feature when you want the package in question to be the only
+	  package providing something.
+	</p>
+
+	<p>	  
+	  A <tt>Conflicts</tt> entry should almost never have an
+	  `earlier than' version clause.  This would prevent
+	  <prgn>dpkg</prgn> from upgrading or installing the package
+	  which declared such a conflict until the upgrade or removal
+	  of the conflicted-with package had been completed.  This
+	  aspect of installation ordering is not handled by
+	  <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
+	  this way is likely to cause problems for `bulk run' upgrades
+	  and installations.
+	</p>
+      </sect>
+	
+      <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
+	</heading>
+
+	<p>	  
+	  As well as the names of actual (`concrete') packages, the
+	  package relationship fields <tt>Depends</tt>,
+	  <tt>Recommends</tt>, <tt>Suggests</tt> and
+	  <tt>Conflicts</tt> may mention virtual packages.
+	</p>
+
+	<p>	  
+	  A virtual package is one which appears in the
+	  <tt>Provides</tt> control file field of another package.
+	  The effect is as if the package(s) which provide a
+	  particular virtual package name had been listed by name
+	  everywhere were the virtual package name appears.
+	</p>
+
+	<p>	  
+	  If there are both a real and a virtual package of the same
+	  name then the dependency may be satisfied (or the conflict
+	  caused) by either the real package or any of the virtual
+	  packages which provide it.  This is so that, for example,
+	  supposing we have
+	  <example>
+	    Package: vm
+	    Depends: emacs
+	  </example>
+	  and someone else releases an xemacs package they can say
+	  <example>
+	    Package: xemacs
+	    Provides: emacs
+	  </example> and all will work in the interim (until a purely
+	  virtual package name is decided on and the <tt>emacs</tt>
+	  and <tt>vm</tt> packages are changed to use it).
+	</p>
+
+	<p>	  
+	  If a dependency or a conflict has a version number attached
+	  then only real packages will be considered to see whether
+	  the relationship is satisfied (or the prohibition violated,
+	  for a conflict) - it is assumed that a real package which
+	  provides virtual package is not of the `right' version.  So,
+	  a <tt>Provides</tt> field may not contain version numbers,
+	  and the version number of the concrete package which
+	  provides a particular virtual package will not be looked at
+	  when considering a dependency on or conflict with the
+	  virtual package name.
+	</p>
+
+	<p>	  
+	  It is likely that the ability will be added in a future
+	  release of <prgn>dpkg</prgn> to specify a version number for
+	  each virtual package it provides.  This feature is not yet
+	  present, however, and is expected to be used only
+	  infrequently.
+	</p>
+
+	<p>	  
+	  If you want to specify which of a set of real packages should be the
+	  default to satisfy a particular dependency on a virtual package, you
+	  should list the real package as alternative before the virtual.
+	</p>
+      </sect>
+	
+	
+      <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
+      files and replacing packages
+	</heading>
+
+	<p>	  
+	  The <tt>Replaces</tt> control file field has two purposes,
+	  which come into play in different situations.
+	</p>
+
+	<p>	  
+	  Virtual packages (<ref id="virtual">) are not considered
+	  when looking at a <tt>Replaces</tt> field - the packages
+	  declared as being replaced must be mentioned by their real
+	  names.
+	</p>
+	  
+	<sect1><heading>Overwriting files in other packages
+	  </heading>
+
+	  <p>	    
+	    Firstly, as mentioned before, it is usually an error for a
+	    package to contains files which are on the system in
+	    another package, though currently the
+	    <tt>--force-overwrite</tt> flag is enabled by default,
+	    downgrading the error to a warning,
+	  </p>
+
+	  <p>	    
+	    If the overwriting package declares that it replaces the
+	    one containing the file being overwritten then
+	    <prgn>dpkg</prgn> will proceed, and replace the file from
+	    the old package with that from the new.  The file will no
+	    longer be listed as `owned' by the old package.
+	  </p>
+
+	  <p>	    
+	    If a package is completely replaced in this way, so that
+	    <prgn>dpkg</prgn> does not know of any files it still
+	    contains, it is considered to have disappeared.  It will
+	    be marked as not wanted on the system (selected for
+	    removal) and not installed.  Any conffiles details noted
+	    in the package will be ignored, as they will have been
+	    taken over by the replacing package(s).  The package's
+	    <prgn>postrm</prgn> script will be run to allow the
+	    package to do any final cleanup required.  See <ref
+	    id="mscriptsinstact">.
+	  </p>
+
+	  <p>	    
+	    In the future <prgn>dpkg</prgn> will discard files which
+	    overwrite those from another package which declares that
+	    it replaces the one being installed (so that you can
+	    install an older version of a package without problems).
+	  </p>
+
+	  <p>	    
+	    This usage of <tt>Replaces</tt> only takes effect when
+	    both packages are at least partially on the system at
+	    once, so that it can only happen if they do not conflict
+	    or if the conflict has been overridden.</p>
+	</sect1>
+	  
+	<sect1><heading>Replacing whole packages, forcing their
+	removal
+	  </heading>
+
+	  <p>	    
+	    Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
+	    <prgn>dselect</prgn> to resolve which package should be
+	    removed when a conflict - see <ref id="conflicts">.  This
+	    usage only takes effect when the two packages <em>do</em>
+	    conflict, so that the two effects do not interfere with
+	    each other.
+	  </p>
+	</sect1>
+      </sect>
+	
+      <sect><heading>Defaults for satisfying dependencies - ordering
+	</heading>
+
+	<p>	  
+	  Ordering is significant in dependency fields.
+	</p>
+
+	<p>	  
+	  Usually dselect will suggest to the user that they select
+	  the package with the most `fundamental' class (eg, it will
+	  prefer Base packages to Optional ones), or the one that they
+	  `most wanted' to select in some sense.
+	</p>
+
+	<p>	  
+	  In the absence of other information <prgn>dselect</prgn>
+	  will offer a default selection of the first named package in
+	  a list of alternatives.
+	</p>
+
+	<p>	  
+	  However, there is no way to specify the `order' of several
+	  packages which all provide the same thing, when that thing
+	  is listed as a dependency.
+	</p>
+
+	<p>	  
+	  Therefore a dependency on a virtual package should contain a
+	  concrete package name as the first alternative, so that this
+	  is the default.
+	</p>
+
+	<p>	  
+	  For example, consider the set of packages:
+	  <example>
+	    Package: glibcdoc
+	    Recommends: info-browser
+	    
+	    Package: info
+	    Provides: info-browser
+	    
+	    Package: emacs
+	    Provides: info-browser
+	  </example>
+	</p>
+
+	<p>	  
+	  If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
+	  same priority then <prgn>dselect</prgn>'s choice is
+	  essentially random.  Better would be
+	  <example>
+	    Package: glibcdoc
+	    Recommends: info | info-browser
+	  </example>
+	  so that <prgn>dselect</prgn> defaults to selecting the
+	  lightweight standalone info browser.
+	</p>
+      </sect>
+    </chapt>
+      
+    <chapt id="conffiles"><heading>Configuration file handling
+      </heading>
+
+      <p>	
+	<prgn>dpkg</prgn> can do a certain amount of automatic
+	handling of package configuration files.
+      </p>
+
+      <p>	
+	Whether this mechanism is appropriate depends on a number of
+	factors, but basically there are two approaches to any
+	particular configuration file.
+      </p>
+
+      <p>	
+	The easy method is to ship a best-effort configuration in the
+	package, and use <prgn>dpkg</prgn>'s conffile mechanism to
+	handle updates.  If the user is unlikely to want to edit the
+	file, but you need them to be able to without losing their
+	changes, and a new package with a changed version of the file
+	is only released infrequently, this is a good approach.
+      </p>
+
+      <p>	
+	The hard method is to build the configuration file from
+	scratch in the <prgn>postinst</prgn> script, and to take the
+	responsibility for fixing any mistakes made in earlier
+	versions of the package automatically.  This will be
+	appropriate if the file is likely to need to be different on
+	each system.
+      </p>
+	
+      <sect><heading>Automatic handling of configuration files by
+      <prgn>dpkg</prgn>
+	</heading>
+
+	<p>	  
+	  A package may contain a control area file called
+	  <tt>conffiles</tt>.  This file should be a list of filenames
+	  of configuration files needing automatic handling, separated
+	  by newlines.  The filenames should be absolute pathnames,
+	  and the files referred to should actually exist in the
+	  package.
+	</p>
+
+	<p>	  
+	  When a package is upgraded <prgn>dpkg</prgn> will process
+	  the configuration files during the configuration stage,
+	  shortly before it runs the package's <prgn>postinst</prgn>
+	  script,
+	</p>
+
+	<p>	  
+	  For each file it checks to see whether the version of the
+	  file included in the package is the same as the one that was
+	  included in the last version of the package (the one that is
+	  being upgraded from); it also compares the version currently
+	  installed on the system with the one shipped with the last
+	  version.
+	</p>
+
+	<p>	  
+	  If neither the user nor the package maintainer has changed
+	  the file, it is left alone.  If one or the other has changed
+	  their version, then the changed version is preferred - ie,
+	  if the user edits their file, but the package maintainer
+	  doesn't ship a different version, the user's changes will
+	  stay, silently, but if the maintainer ships a new version
+	  and the user hasn't edited it the new version will be
+	  installed (with an informative message).  If both have
+	  changed their version the user is prompted about the problem
+	  and must resolve the differences themselves.
+	</p>
+
+	<p>	  
+	  The comparisons are done by calculating the MD5 message
+	  digests of the files, and storing the MD5 of the file as it
+	  was included in the most recent version of the package.
+	</p>
+
+	<p>	  
+	  When a package is installed for the first time
+	  <prgn>dpkg</prgn> will install the file that comes with it,
+	  unless that would mean overwriting a file already on the
+	  filesystem.
+	</p>
+
+	<p>	  
+	  However, note that <prgn>dpkg</prgn> will <em>not</em>
+	  replace a conffile that was removed by the user (or by a
+	  script).  This is necessary because with some programs a
+	  missing file produces an effect hard or impossible to
+	  achieve in another way, so that a missing file needs to be
+	  kept that way if the user did it.
+	</p>
+
+	<p>	  
+	  Note that a package should <em>not</em> modify a
+	  <prgn>dpkg</prgn>-handled conffile in its maintainer
+	  scripts.  Doing this will lead to <prgn>dpkg</prgn> giving
+	  the user confusing and possibly dangerous options for
+	  conffile update when the package is upgraded.</p>
+      </sect>
+	
+      <sect><heading>Fully-featured maintainer script configuration
+      handling
+	</heading>
+
+	<p>	  
+	  For files which contain site-specific information such as
+	  the hostname and networking details and so forth, it is
+	  better to create the file in the package's
+	  <prgn>postinst</prgn> script.
+	</p>
+
+	<p>	  
+	  This will typically involve examining the state of the rest
+	  of the system to determine values and other information, and
+	  may involve prompting the user for some information which
+	  can't be obtained some other way.
+	</p>
+
+	<p>	  
+	  When using this method there are a couple of important
+	  issues which should be considered:
+	</p>
+
+	<p>	  
+	  If you discover a bug in the program which generates the
+	  configuration file, or if the format of the file changes
+	  from one version to the next, you will have to arrange for
+	  the postinst script to do something sensible - usually this
+	  will mean editing the installed configuration file to remove
+	  the problem or change the syntax.  You will have to do this
+	  very carefully, since the user may have changed the file,
+	  perhaps to fix the very problem that your script is trying
+	  to deal with - you will have to detect these situations and
+	  deal with them correctly.
+	</p>
+
+	<p>	  
+	  If you do go down this route it's probably a good idea to
+	  make the program that generates the configuration file(s) a
+	  separate program in <tt>/usr/sbin</tt>, by convention called
+	  <tt><var>package</var>config</tt> and then run that if
+	  appropriate from the post-installation script.  The
+	  <tt><var>package</var>config</tt> program should not
+	  unquestioningly overwrite an existing configuration - if its
+	  mode of operation is geared towards setting up a package for
+	  the first time (rather than any arbitrary reconfiguration
+	  later) you should have it check whether the configuration
+	  already exists, and require a <tt>--force</tt> flag to
+	  overwrite it.</p></sect>
+    </chapt>
+      
+      
+      
+    <chapt id="alternatives"><heading>Alternative versions of an interface -
+	<prgn>update-alternatives</prgn>
+      </heading>
+
+      <p>	
+	When several packages all provide different versions of the
+	same program or file it is useful to have the system select a
+	default, but to allow the system administrator to change it
+	and have their decisions respected.
+      </p>
+
+      <p>	
+	For example, there are several versions of the <prgn>vi</prgn>
+	editor, and there is no reason to prevent all of them from
+	being installed at once, each under their own name
+	(<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
+	Nevertheless it is desirable to have the name <tt>vi</tt>
+	refer to something, at least by default.
+      </p>
+
+      <p>	
+	If all the packages involved cooperate, this can be done with
+	<prgn>update-alternatives</prgn>.
+      </p>
+
+      <p>	
+	Each package provides its own version under its own name, and
+	calls <prgn>update-alternatives</prgn> in its postinst to
+	register its version (and again in its prerm to deregister
+	it).
+      </p>
+
+      <p>	
+	See the manpage <manref name="update-alternatives"
+	section="8"> for details.
+      </p>
+
+      <p>	
+	If <prgn>update-alternatives</prgn> does not seem appropriate
+	you may wish to consider using diversions instead.</p>
+    </chapt>
+      
+      
+    <chapt id="diversions"><heading>Diversions - overriding a
+    package's version of a file
+      </heading>
+
+      <p>	
+	It is possible to have <prgn>dpkg</prgn> not overwrite a file
+	when it reinstalls the package it belongs to, and to have it
+	put the file from the package somewhere else instead.
+      </p>
+
+      <p>	
+	This can be used locally to override a package's version of a
+	file, or by one package to override another's version (or
+	provide a wrapper for it).
+      </p>
+
+      <p>	
+	Before deciding to use a diversion, read <ref
+	id="alternatives"> to see if you really want a diversion
+	rather than several alternative versions of a program.
+      </p>
+
+      <p>	
+	There is a diversion list, which is read by <prgn>dpkg</prgn>,
+	and updated by a special program <prgn>dpkg-divert</prgn>.
+	Please see <manref name="dpkg-divert" section="8"> for full
+	details of its operation.
+      </p>
+
+      <p>	
+	When a package wishes to divert a file from another, it should
+	call <prgn>dpkg-divert</prgn> in its preinst to add the
+	diversion and rename the existing file.  For example,
+	supposing that a <prgn>smailwrapper</prgn> package wishes to
+	install a wrapper around <tt>/usr/sbin/smail</tt>:
+	<example>
+	  if [ install = "$1" ]; then
+	  dpkg-divert --package smailwrapper --add --rename \
+	  --divert /usr/sbin/smail.real /usr/sbin/smail
+	  fi
+	</example> Testing <tt>$1</tt> is necessary so that the script
+	doesn't try to add the diversion again when
+	<prgn>smailwrapper</prgn> is upgraded.  The <tt>--package
+	smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
+	copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
+	get installed as the true version.
+      </p>
+
+      <p>	
+	The postrm has to do the reverse:
+	<example>
+	  if [ remove = "$1" ]; then
+	  dpkg-divert --package smailwrapper --remove --rename \
+	  --divert /usr/sbin/smail.real /usr/sbin/smail
+	  fi
+	</example>
+      </p>
+
+      <p>	
+	Do not attempt to divert a file which is vitally important for
+	the system's operation - when using <prgn>dpkg-divert</prgn>
+	there is a time, after it has been diverted but before
+	<prgn>dpkg</prgn> has installed the new version, when the file
+	does not exist.</p>
+    </chapt>
+      
+      
+    <chapt id="sharedlibs"><heading>Shared libraries
+      </heading>
+
+      <p>	
+	Packages containing shared libraries must be constructed with
+	a little care to make sure that the shared library is always
+	available.  This is especially important for packages whose
+	shared libraries are vitally important, such as the libc.
+      </p>
+
+      <p>	
+	Firstly, your package should install the shared libraries
+	under their normal names.  For example, the
+	<prgn>libgdbm1</prgn> package should install
+	<tt>libgdbm.so.1.7.3</tt> as
+	<tt>/usr/lib/libgdbm.so.1.7.3</tt>.  The files should not be
+	renamed or relinked by any prerm or postrm scripts;
+	<prgn>dpkg</prgn> will take care of renaming things safely
+	without affecting running programs, and attempts to interfere
+	with this are likely to lead to problems.
+      </p>
+
+      <p>	
+	Secondly, your package should include the symlink that
+	<prgn>ldconfig</prgn> would create for the shared libraries.
+	For example, the <prgn>libgdbm1</prgn> package should include
+	a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
+	<tt>libgdbm.so.1.7.3</tt>.  This is needed so that
+	<prgn>ld.so</prgn> can find the library in between the time
+	<prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
+	in the <prgn>postinst</prgn> script.  Futhermore, and <em>this
+	is very important</em>, the library must be placed before the
+	symlink pointing to it in the <tt>.deb</tt> file.  This is so
+	that by the time <prgn>dpkg</prgn> comes to install the
+	symlink (overwriting the previous symlink pointing at an older
+	version of the library) the new shared library is already in
+	place.  Currently the way to ensure the ordering is done
+	properly is to install the library in the appropriate
+	<tt>debian/tmp/.../lib</tt> directory before creating the
+	symlink, by putting the commands in the <tt>debian/rules</tt>
+	in the appropriate order.
+      </p>
+
+	<!--
+	next Paragraph added to close Bug #5299, Guy Maor
+	-->
+	
+      <p>	
+	Thirdly, the development package should contain a symlink for
+	the shared library without a version number.  For example, the
+	<tt>libgdbm1-dev</tt> package should include a symlink from
+	<tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>.  This
+	symlink is needed by <prgn>ld</prgn> when compiling packages
+	as it will only look for <tt>libgdm.so</tt> and
+	<tt>libgdm.a</tt> when compiling dynamically or statically,
+	respectively.
+      </p>
+
+	<!--
+	next paragraph changed by Christian Schwarz (see policy weekly #6)
+	-->
+	
+      <p>	
+	Any package installing shared libraries in a directory that's listed
+	in <tt>/etc/ld.so.conf</tt> or in one of the default library
+	directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
+	and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
+	script if and only if the first argument is `configure'. However, it
+	is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
+	scripts in the case where the package is being upgraded (see <ref
+									  id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
+	that <prgn>dpkg</prgn> uses for the files while it is
+	installing them and will make the shared library links point
+	to them, just before <prgn>dpkg</prgn> continues the
+	installation and removes the links!
+      </p>
+
+	<!-- 
+	moved from section 2.2 , DMorris 
+	-->
+	
+      <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+	</heading>
+
+	<p>	  
+	  This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
+	  required when your package provides shared libraries.
+	</p>
+
+	<p>	  
+	  Each line is of the form:
+	  <example>
+	    <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
+	  </example>
+	</p>
+
+	<p>	  
+	  <var>library-name</var> is the name of the shared library,
+	  for example <tt>libc5</tt>.
+	</p>
+
+	<p>	  
+	  <var>version-or-soname</var> is the soname of the library -
+	  ie, the thing that must exactly match for the library to be
+	  recognised by <prgn>ld.so</prgn>.  Usually this is major
+	  version number of the library.
+	</p>
+
+	<p>	  
+	  <var>dependencies</var> has the same syntax as a dependency
+	  field in a binary package control file.  It should give
+	  details of which package(s) are required to satisfy a binary
+	  built against the version of the library contained in the
+	  package.  See <ref id="depsyntax">.
+	</p>
+
+	<p>	  
+	  For example, if the package <tt>foo</tt> contains
+	  <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
+	  <tt>libfoo.so.1</tt>, and the first version of the package
+	  which contained a minor number of at least <tt>2.3</tt> was
+	  <var>1.2.3-1</var>, then the package's <var>shlibs</var>
+	  could say:
+	  <example>
+	    libfoo 1	foo (>= 1.2.3-1)
+	  </example>
+	</p>
+
+	<p>	  
+	  The version-specific dependency is to avoid warnings from
+	  <prgn>ld.so</prgn> about using older shared libraries with
+	  newer binaries.</p>
+      </sect>
+	
+      <sect><heading>Further Technical information on
+	  <tt>shlibs</tt></heading>
+
+	
+	<!-- 
+	following section mostly provided by Heiko Schlittermann
+	edited by DMorris
+	-->
+	
+	<sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
+	  </heading>
+
+	  <p>	    
+	    The <tt>debian/shlibs</tt> file provides a way of checking
+	    for shared library dependencies on packaged binaries.
+	    They are intended to be used by package maintainers to
+	    make their lives easier.
+	  </p>
+
+	  <p>	    
+	    Other <tt>shlibs</tt> files that exist on a Debian system are
+	    <list>
+	      <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+	      <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+	      <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+	      <item> <p><tt>debian/shlibs.local</tt></p></item>
+	    </list> 
+	    These files are used by <prgn>dpkg-shlibdeps</prgn> when
+	    creating a binary package.</p>
+	</sect1>
+	  
+	<sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
+	work?
+	  </heading>
+
+	  <p>	    
+	    <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
+	    determine the shared libraries used by the compiled
+	    binaries passed through its command line.
+	  </p>
+
+	  <p>	    
+	    For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know 
+	    <list compact="compact">
+	      <item><p>the package containing the library, and</p></item>
+	      <item><p>the library version number,</p></item>
+
+	    </list>	  <p>
+	    it scans the following files in this order.
+	    <enumlist compact="compact">
+	      <item><p><tt>debian/shlibs.local</tt></p></item>
+	      <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+	      <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+	      <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+	    </enumlist></p>
+	</sect1>
+	  
+	<sect1><heading><em>Who</em> maintains the various
+	<tt>shlibs</tt> files?
+	  </heading>
+
+	  <p>	    
+	    <list compact="compact">
+	      <item>
+		<p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
+		  of dpkg</p>
+	      </item>
+	      <item>
+		<p>
+		  <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
+		  - the maintainer of each package</p>
+	      </item>
+	      <item>
+		<p>
+		  <tt>/etc/dpkg/shlibs.override</tt> - the local
+		  system administrator</p>
+	      </item>
+	      <item>
+		<p><tt>debian/shlibs.local</tt> - the maintainer of
+		the package
+		</p>
+	      </item> 
+	    </list> 
+	    The <tt>shlibs.default</tt> file is managed by
+	    <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
+	    that are provided by <prgn>dpkg</prgn> are just there to
+	    fix things until the shared library packages all have
+	    <tt>shlibs</tt> files.
+	  </p>
+	</sect1>
+
+	<sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
+	    the <tt>shlibs</tt> files?
+	  </heading>
+	    
+	  <sect2><heading>If your package doesn't provide a shared
+	  library
+	    </heading>
+
+	    <p>	      
+	      Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+	      <tt>debian/rules</tt> file.  If your package contains
+	      only binaries (e.g. no scripts) use:
+	      <example>
+		dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
+	      </example>
+	      If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+	      done. If it does complain you might need to create your
+	      own <tt>debian/shlibs.local</tt> file.</p>
+	  </sect2>
+
+	  <sect2><heading>If your package provides a shared library
+	    </heading>
+
+	    <p>	      
+	      Create a <tt>debian/shlibs</tt> file and let
+	      <tt>debian/rules</tt> install it in the control area:	      
+	      <example>
+		install -m644 debian/shlibs debian/tmp/DEBIAN
+	      </example>
+	      If your package contains additional binaries see above.
+	    </p>
+	  </sect2>
+	</sect1>
+
+	<sect1><heading><em>How</em> to write
+	<tt>debian/shlibs.local</tt>
+	  </heading>
+
+	  <p>	    
+	    This file is intended only as a <em>temporary</em> fix if
+	    your binaries depend on a library which doesn't provide
+	    its own <tt>/var/lib/dpkg/*.shlibs</tt> file yet.
+	  </p>
+
+	  <p>	    
+	    Let's assume you are packaging a binary <tt>foo</tt>. Your
+	    output in building the package might look like this.	    
+	    <example>
+	      $ ldd foo
+	      libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
+	      libc.so.5 => /lib/libc.so.5.2.18
+	      libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
+	    </example>
+	    And when you ran <prgn>dpkg-shlibdeps</prgn>
+	    <example>
+	      $ dpkg-shlibdeps -o foo
+	      dpkg-shlibdeps: warning: unable to find dependency information 
+	      for shared library libbar 
+	      (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
+	      shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
+	    </example>
+	    The <prgn>foo</prgn> binary depends on the
+	    <prgn>libbar</prgn> shared library, but no package seems
+	    to provide a <tt>*.shlibs</tt> file in
+	    <tt></tt>var/lib/dpkg/info/.  Let's determine the package
+	    responsible:
+	  </p>
+
+	  <p>
+	    <example>
+	      $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
+	      bar1: /usr/X11R6/lib/libbar.so.1.0
+	      $ dpkg -s bar1 | grep Version
+	      Version: 1.0-1
+	    </example>
+	    This tells us that the <prgn>bar1</prgn> package, version
+	    1.0-1 is the one we are using. Now we can create our own
+	    <tt>debian/shlibs.local</tt> to temporarly fix the above
+	    problem. Include the following line into your
+	    <tt>debian/shlibs.local</tt> file.
+	    <example>
+	      libbar 1 bar1 (>= 1.0-1)
+	    </example>
+	    Now your package build should work. As soon as the
+	    maintainer of <prgn>libbar1</prgn> provides a
+	    <tt>shlibs</tt> file, you can remove your
+	    <tt>debian/shlibs.local</tt> file.
+	  </p>
+	</sect1>
+      </sect>
+    </chapt>
+
+    <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
+    its installation methods
+      </heading>
+
+      <p>	
+	<prgn>dselect</prgn> calls scripts from its installation
+	methods when it needs to actually access data from the
+	distribution.  The core program <prgn>dselect</prgn> itself
+	just calls these scripts and provides the package and access
+	method selection interfaces.  The installation methods are
+	responsible for invoking <prgn>dpkg</prgn> as appropriate.
+      </p>
+
+      <p>	
+	Each installation method has three scripts:
+	<list compact="compact">
+	  <item><p>Setup installation parameters.</p></item>
+	  <item><p>Update list of available packages.</p></item>
+	  <item><p>Install.</p></item>
+	</list>
+
+      <p>	
+	<prgn>dselect</prgn> searches for methods in
+	<tt>/usr/lib/dpkg/methods</tt> and
+	<tt>/usr/local/lib/dpkg/methods</tt>.
+      </p>
+	
+      <sect><heading>Functions of the method scripts
+	</heading>
+
+	<p>	  
+	  The setup script is run just after the user has chosen an
+	  installation method.  It should prompt the user for
+	  parameters like the site to NFS-mount or FTP from, the
+	  directory to use, or the directory or filesystem where the
+	  <tt>.deb</tt> files can be found, or the tape or floppy
+	  device to install from.  It should store the responses under
+	  <tt>/var/lib/dpkg/methods</tt> - see below.  If no available
+	  packages list is available it should perhaps offer to scan
+	  the available packages.
+	</p>
+
+	<p>	  
+	  The update script should obtain a list of available packages
+	  if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
+	  --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
+	  to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
+	  database of available packages.  If no packages list was
+	  available and the user was offered and accepted the option
+	  of scanning the actual files available this scan should be
+	  done here, using <tt>dpkg --record-avail</tt>.
+	</p>
+
+	<p>	  
+	  The install script should feed all the available
+	  <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
+	  equivalent to <tt>dpkg --install
+	    --refuse-downgrade --selected-only --skip-same-version
+	    --auto-deconfigure</tt>).  The <tt>-R</tt>
+	  (<tt>--recursive</tt>) option for traversing subdirectories
+	  may also be useful here).
+	</p>
+
+	<p>	  
+	  If any of these scripts needs to display a message for the
+	  user, it should wait for the user to hit `return' before
+	  exiting so that dselect doesn't immediately rewrite the
+	  screen.
+	</p>
+
+	<p>	  
+	  If a method script succeeds (returns a zero exit status)
+	  <prgn>dselect</prgn> will return immediately to the main
+	  menu, with the `next' option highlighted ready for the user
+	  to select it.  If it fails <prgn>dselect</prgn> will display
+	  a message and wait for the user to hit return.</p>
+      </sect>
+	
+      <sect><heading>Location and arguments of the method scripts
+	</heading>
+
+	<p>	  
+	  A set of scripts (henceforth known as a group) may provide
+	  several methods on the `main menu' with different behaviour.
+	  For example, there might be a generic get-packages-by-FTP
+	  group which might provide methods in the main menu for
+	  installation directly from one of the Debian mirror sites as
+	  well as for installation from a user-specified site.
+	</p>
+
+	<p>	  
+	  Each group of methods implemented by the same set of scripts
+	  should have a subdirectory
+	  <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
+	  <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
+	  containing:
+	  <taglist compact="compact">
+	    <tag><tt>names</tt></tag>
+	    <item><p>a list of user-visible methods provided by these scripts.</p>
+	    </item>
+	    <tag><tt>setup</tt></tag>
+	    <tag><tt>update</tt></tag>
+	    <tag><tt>install</tt></tag>
+	    <item><p>executable programs, the scripts themselves.</p>
+	    </item>
+	    <tag><tt>desc.<var>option</var></tt></tag>
+	    <item><p>description file.</p></item>
+	  </taglist>
+	</p>
+
+	<p>	  
+	  <tt>names</tt> will be formatted as a list of lines, each containing:
+	  <example>
+	    <var>sequence</var> <var>method</var> <var>summary</var>
+	  </example>
+	</p>
+	<p>	  
+	  <var>sequence</var> is a two-digit number that will be used
+	  much like <tt>rc.d</tt> prefixes to control the order in the
+	  main menu.  If in doubt use 50.
+	</p>
+
+	<p>	  
+	  <var>method</var> is a name which is displayed by
+	  <prgn>dselect</prgn> as the name of the method, and which
+	  will be passed to <tt>setup</tt>, <tt>update</tt> and
+	  <tt>unpack</tt> as their first argument.
+	</p>
+
+	<p>	  
+	  <var>summary</var> is the brief description string for
+	  <prgn>dselect</prgn>'s menu.
+	</p>
+
+	<p>	  
+	  Each of the three scripts gets the same three arguments:
+	  <var>vardir</var>, <var>group</var> and <var>method</var>.
+	  <var>vardir</var> is the base directory for storing
+	  <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
+	  <tt>/var/lib/dpkg</tt>; this is passed in so that the
+	  <tt>--admindir</tt> option to <prgn>dselect</prgn> is
+	  honoured).
+	</p>
+
+	<p>	  
+	  Each option may have an extended description in
+	  <tt>desc.<var>option</var></tt>.  This should be formatted
+	  like the extended description part of a <tt>Description</tt>
+	  field entry <em>shifted one character to the left</em>.
+	</p>
+
+	<p>	  
+	  <tt><var>vardir</var>/methods</tt> will exist, and a method
+	  group may use a
+	  <tt><var>vardir</var>/methods/<var>group</var></tt>
+	  directory to store its state.
+	</p>
+
+	<p>	  
+	  The group name and method name must follow the rules for C
+	  identifiers.
+	</p>
+      </sect>
+    </chapt>
+      
+    <chapt id="conversion"><heading>Conversion procedure from old
+    source packages
+      </heading>
+
+      <p>	
+	This is a brief summary of the procedure for converting a
+	pre-2.0.0.0-format source package into the new format.
+      </p>
+
+      <p>	
+	You are strongly advised to download and examine the <prgn>hello</prgn>
+	package, and to read the section in the <prgn>dpkg</prgn> programmers'
+	manual describing the source packaging tools.  More detail about the
+	exact functionality of these tools is available in 
+	<manref name="dpkg-source"  section="1">.
+      </p>
+
+      <p>	
+	<list>
+	  <item>
+	    <p>
+	      Download the original source code from wherever it can
+	      be found and do any rearrangement required to make it
+	      look like the original tree of the Debian source.  Put
+	      it in
+	      <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
+	      or
+	      <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
+	    </p>
+	  </item>
+	  
+	  <item>
+	    <p>
+	      Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
+	      There may be some exceptions to this, but this is a good
+	      start.</p>
+	  </item>
+
+	  <item>
+	    <p>
+	      Edit the <tt>debian/changelog</tt> - create or rename it
+	      if necessary.  Add a new revision to the top with the
+	      appropriate details, and a local variables entry to the
+	      bottom to set Emacs to the right mode:
+	      <example>
+		Local variables:
+		mode: debian-changelog
+		End:
+	      </example>
+	    </p>
+	  </item>
+	  
+	  <item>
+	    <p>
+	      Edit/create <tt>debian/control</tt>:
+	      <list compact="compact">
+		<item>
+		  <p>
+		    Remove the <tt>Version</tt> field.  If it is
+		    generated unusually (not equal to the source
+		    version) you must use the -v option to
+		    dpkg-gencontrol (see below).  <tt>Section</tt>,
+		    <tt>Priority</tt>, <tt>Maintainer</tt> go above
+		    the first blank line, most of the rest
+		    below.
+		  </p>
+		</item>
+		
+		<item>
+		  <p>
+		    Reorder the fields and add a blank line at an
+		    appropriate point, separating the source package
+		    fields from the binary package fields.
+		  </p>
+		</item>
+		
+		<item>
+		  <p>Add the <tt>Source</tt> field.</p></item>
+		
+		<item>
+		  <p>
+		    Add the <tt>Standards-Version</tt> field.  (Please
+		    check out the Debian Policy Manual for details
+		    about this field.)</p>
+		</item>
+		
+		<item>
+		  <p>
+		    Change the <tt>Architecture</tt> field for each
+		    package to <tt>any</tt>, <tt>all</tt> or whatever.
+		    If there isn't an <tt>Architecture</tt> field add
+		    one.</p>
+		</item>
+		
+		<item>
+		  <p>
+		    If any other use of sed or things used to happen
+		    to make the binary control files use
+		    <prgn>dpkg-gencontrol</prgn>'s variable
+		    substitution features to achieve the same effect.
+		    Use <tt>debian/substvars</tt> if you need to put
+		    unusally-generated information (apart from details
+		    of <tt>.deb</tt> files) in the <tt>.changes</tt>
+		    file too.</p>
+		</item>
+	      </list>
+	    </p>
+	  </item>
+	  
+	  <item>
+	    <p>Edit the <tt>debian/rules</tt>:
+	      <list compact="compact">
+		<item>
+		  <p>
+		    Remove the <prgn>source</prgn> and
+		    <prgn>diff</prgn> and any <prgn>changes</prgn> and
+		    <prgn>dist</prgn> targets.  These things now
+		    happen in a package-independent way and are not
+		    done by <tt>debian/rules</tt>.</p>
+		</item>
+		<item>
+		  <p>
+		    Split the <prgn>binary</prgn> target into
+		    <prgn>binary-arch</prgn> and
+		    <prgn>binary-indep</prgn>; in many cases all of
+		    <prgn>binary</prgn> should go into
+		    <prgn>binary-arch</prgn>.  Create the
+		    <prgn>binary</prgn> target and the unused of the
+		    two other <prgn>binary-*</prgn> targets if there
+		    is one - you can copy the ones from the
+		    <prgn>hello</prgn> package.</p>
+		</item>
+		<item>
+		  <p>
+		    Change the <prgn>binary</prgn> target to use
+		    <prgn>dpkg-gencontrol</prgn> to make the package
+		    control file(s).  Move it to after all the files
+		    have been installed but just before the last
+		    <prgn>chown</prgn> and <prgn>chmod</prgn> in the
+		    target.</p>
+		</item>
+		<item>
+		  <p>
+		    Change occurrences of <tt>debian-tmp</tt> to
+		    <tt>debian/tmp</tt>.</p>
+		</item>
+		<item>
+		  <p>
+		    Change occurrences of
+		    <tt>debian.{post,pre}{inst,rm}</tt> to
+		    <tt>debian/*</tt>.</p>
+		</item>
+		<item>
+		  <p>
+		    Remove the version number setting at the top, if
+		    there is one.</p>
+		</item>
+		<item>
+		  <p>
+		    Ensure that the package's Debian-specific and
+		    upstream changelogs are installed.</p>
+		</item>
+	      </list>
+	    </p>
+	  </item>
+	  
+	  <item>
+	    <p>
+	      Change the package to use <prgn>dpkg-shlibdeps</prgn> to
+	      determine its shared library dependencies and substitute
+	      them in.  Shared library dependencies should no longer
+	      be hardwired in the source package.</p>
+	  </item>
+	  
+	  <item>
+	    <p>
+	      Check that the <tt>debian/README</tt> is really the
+	      copyright file, and if so rename it to
+	      <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
+	      to cope with this and to change the installation of the
+	      copyright file from
+	      <tt>/usr/doc/<var>package</var>/copyright</tt> to
+	      <tt>/usr/doc/copyright/<var>package</var></tt>.  If it
+	      isn't then find <tt>debian/copyright</tt> and decide
+	      what to do with the <tt>README</tt>.</p>
+	  </item>
+	  
+	  <item>
+	    <p>Check for various other anachronisms and problems:
+	      <list compact="compact">
+		<item>
+		  <p>
+		    Remove any <tt>Package_Revision</tt>,
+		    <tt>Package-Revision</tt> or <tt>Revision</tt>
+		    fields.</p>
+		</item>
+		<item>
+		  <p>
+		    Rename <tt>Optional</tt> to <tt>Suggests</tt>,
+		    <tt>Recommended</tt> to
+		    <tt>Recommends</tt>.</p>
+		</item>
+		<item>
+		  <p>
+		    Change
+		    <tt>/usr/doc/examples/<var>package</var></tt> to
+		    <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
+		</item>
+		<item>
+		  <p>
+		    Make sure that manpages are installed
+		    compressed.</p>
+		</item>
+		<item>
+		  <p>
+		    Check that the description has an extended
+		    description, is well-formatted and meaningful and
+		    helpful to people wanting to know whether to
+		    install a package.</p>
+		</item>
+	      </list>
+	    </p>
+	  </item>
+	  
+	  <item>
+	    <p>Look everything over.</p></item>
+	  
+	  <item>
+	    <p>
+	      Do a test build using <tt>dpkg-buildpackage -us -uc -sa
+		-r<var>whatever</var></tt>.  Check the permissions and
+	      locations of files in the resulting package by examining
+	      the output of <tt>dpkg-deb --contents</tt>, and check
+	      that the source build happened OK.  Test install the
+	      binary package(s) and test extract the source
+	      package(s).</p>
+	  </item>
+	  
+	  <item>
+	    <p>
+	      Sign the release: either rebuild everything with
+	      <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
+	      <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
+	      <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
+	      <tt>.changes</tt>.</p>
+	  </item>
+	  
+	</list>
+      </p>
+
+      <p>	
+	The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
+	<prgn>dpkg-genchanges</prgn> is important when doing the first
+	build/uploading of a new-format source package.  Unless this
+	happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
+	default the original source tarfile will not be included in
+	the uploaded files listed in the <tt>.changes</tt> file, and
+	so it won't be installed on the FTP site.  <tt>-sa</tt>
+	requests that the original source be included
+	regardless.</p>
+    </chapt>
+    
+  </book>
+</debiandoc>
 
-<item>
-The package's files are removed (except conffiles).
 
-<item>
-<example>
-<var/postrm/ remove
-</example>
 
-<item>
-All the maintainer scripts except the postrm are removed.
-<p>
 
-If we aren't purging the package we stop here.  Note that packages
-which have no postrm and no conffiles are automatically purged when
-removed, as there is no difference except for the <prgn/dpkg/ status.
 
-<item>
-The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files,
-<tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed.
 
-<item>
-<example>
-<var/postrm/ purge
-</example>
 
-<item>
-The package's file list is removed.
 
-</enumlist>
 
-No attempt is made to unwind after errors during removal.
 
 
-<chapt id="descriptions">Descriptions of packages - the
-<tt/Description/ field
-<p>
 
-The <tt/Description/ control file field is used by <prgn/dselect/ when
-the user is selecting which packages to install and by <prgn/dpkg/
-when it displays information about the status of packages and so
-forth.  It is included on the FTP site in the <prgn/Packages/ files,
-and may also be used by the Debian WWW pages.
-<p>
 
-The description is intended to describe the program to a user who has
-never met it before so that they know whether they want to install it.
-It should also give information about the significant dependencies and
-conflicts between this package and others, so that the user knows why
-these dependencies and conflicts have been declared.
-<p>
 
-The field's format is as follows:
-<example>
-Description: <var/single line synopsis/
- <var/extended description over several lines/
-</example>
-<p>
-
-The synopsis is often printed in lists of packages and so forth, and
-should be as informative as possible.  Every package should also have
-an extended description.
-<p>
-
-<sect>Types of formatting line in the extended description
-<p>
-
-<list>
-<item>
-Those starting with a single space are part of a paragraph.
-Successive lines of this form will be word-wrapped when displayed.
-The leading space will usually be stripped off.
-
-<item>
-Those starting with two or more spaces.  These will be displayed
-verbatim.  If the display cannot be panned horizontally the
-displaying program will linewrap them `hard' (ie, without taking
-account of word breaks).  If it can they will be allowed to trail
-off to the right.  None, one or two initial spaces may be deleted,
-but the number of spaces deleted from each line will be the same
-(so that you can have indenting work correctly, for example).
-
-<item>
-Those containing a single space followed by a single full stop
-character.  These are rendered as blank lines.  This is the <em/only/
-way to get a blank line - see below.
-
-<item>
-Those containing a space, a full stop and some more characters.  These
-are for future expansion.  Do not use them.
-</list>
-
-<sect>Notes about writing descriptions
-<p>
-
-<em/Always/ start extended description lines with at least one
-whitespace character.  Fields in the control file and in the Packages
-file are separated by field names starting in the first column, just
-as message header fields are in RFC822.  Forgetting the whitespace
-will cause <prgn/dpkg-deb/<footnote>Version 0.93.23 or
-later.</footnote> to produce a syntax error when trying to build the
-package.  If you force it to build anyway <prgn/dpkg/ will refuse to
-install the resulting mess.
-<p>
-
-<em/Do not/ include any completely <em/empty/ lines. These separate
-different records in the Packages file and different packages in the
-<tt>debian/control</> file, and are forbidden in package control
-files.  See the previous paragraph for what happens if you get this
-wrong.
-<p>
-
-The single line synopsis should be kept brief - certainly under 80
-characters.  <prgn/dselect/ displays between 25 and 49 characters
-without panning if you're using an 80-column terminal, depending on
-what display options are in effect.
-<p>
-
-Do not include the package name in the synopsis line.  The display
-software knows how to display this already, and you do not need to
-state it.  Remember that in many situations the user may only see
-the synopsis line - make it as informative as you can.
-<p>
-
-The extended description should describe what the package does and
-how it relates to the rest of the system (in terms of, for
-example, which subsystem it is which part of).
-<p>
-
-The blurb that comes with a program in its announcements and/or
-<prgn/README/ files is rarely suitable for use in a description.  It
-is usually aimed at people who are already in the community where the
-package is used.  The description field needs to make sense to anyone,
-even people who have no idea about any of the
-things the package deals with.
-<p>
-
-Put important information first, both in the synopis and extended
-description.  Sometimes only the first part of the synopsis or of
-the description will be displayed.  You can assume that there will
-usually be a way to see the whole extended description.
-<p>
-
-You may include information about dependencies and so forth in the
-extended description, if you wish.
-<p>
-
-Do not use tab characters.  Their effect is not predictable.
-<p>
-
-Do not try to linewrap the summary (the part on the same line as the
-field name <tt/Description/) into the extended description.  This will
-not work correctly when the full description is displayed, and makes
-no sense where only the summary is available.
-
-<sect>Example description in control file for Smail
-<p>
 
-<example>
-Package: smail
-Version: 3.1.29.1-13
-Maintainer: Ian Jackson &lt;iwj10@cus.cam.ac.uk&gt;
-Recommends: pine | mailx | elm | emacs | mail-user-agent
-Suggests: metamail
-Depends: cron, libc5
-Conflicts: sendmail
-Provides: mail-transport-agent
-Description: Electronic mail transport system.
- Smail is the recommended mail transport agent (MTA) for Debian.
- .
- An MTA is the innards of the mail system - it takes messages from
- user-friendly mailer programs and arranges for them to be delivered
- locally or passed on to other systems as required.
- .
- In order to make use of it you must have one or more user level
- mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
- and VM as mailreaders) installed.  If you wish to send messages other
- than just to other users of your system you must also have appropriate
- networking support, in the form of IP or UUCP.
-</example>
 
-<chapt id="relationships">Declaring relationships between packages
-<p>
-
-Packages can declare in their control file that they have certain
-relationships to other packages - for example, that they may not be
-installed at the same time as certain other packages, and/or that they
-depend on the presence of others, or that they should overwrite files
-in certain other packages if present.
-<p>
-
-This is done using the <tt/Depends/, <tt/Recommends/, <tt/Suggests/,
-<tt/Conflicts/, <tt/Provides/ and <tt/Replaces/ control file fields.
-<p>
-
-<sect id="depsyntax">Syntax of relationship fields
-<p>
-
-These fields all have a uniform syntax.  They are a list of package
-names separated by commas.
-<p>
-
-In <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Pre-Depends/
-(the fields which declare dependencies of the package in which they
-occur on other packages) these package names may also be lists of
-alternative package names, separated by vertical bar symbols <tt/|/
-(pipe symbols).
-<p>
-
-All the fields except <tt/Provides/ may restrict their applicability
-to particular versions of each named package.  This is done in
-parentheses after each individual package name; the parentheses should
-contain a relation from the list below followed by a version number,
-in the format described in <ref id="versions">.
-<p>
-
-The relations allowed are
-<tt/&lt;&lt;/,
-<tt/&lt;=/,
-<tt/=/,
-<tt/&gt;=/ and
-<tt/&gt;&gt;/
-for strictly earlier, earlier or equal, exactly equal, later or equal
-and strictly later, respectively.  The forms <tt/&lt;/ and <tt/&gt;/
-were used to mean earlier/later or equal, rather than strictly
-earlier/later, so they should not appear in new packages (though
-<prgn/dpkg/ still supports them).
-<p>
-
-Whitespace may appear at any point in the version specification, and
-must appear where it's necessary to disambiguate; it is not otherwise
-significant.  For consistency and in case of future changes to
-<prgn/dpkg/ it is recommended that a single space be used after a
-version relationship and before a version number; it is usual also to
-put a single space after each comma, on either side of each vertical
-bar, and before each open parenthesis.
-<p>
-
-For example:
-<example>
-Package: metamail
-Version: 2.7-3
-Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
-</example>
 
-<sect>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/
-<p>
-
-These four fields are used to declare a dependency by one package on
-another.  They appear in the depending package's control file.
-<p>
-
-All but <tt/Pre-Depends/ (discussed below) take effect <em/only/ when
-a package is to be configured.  They do not prevent a package being on
-the system in an unconfigured state while its dependencies are
-unsatisfied, and it is possible to replace a package whose
-dependencies are satisfied and which is properly installed with a
-different version whose dependencies are not and cannot be satisfied;
-when this is done the depending package will be left unconfigured
-(since attempts to configure it will give errors) and will not
-function properly.
-<p>
-
-For this reason packages in an installation run are usually all
-unpacked first and all configured later; this gives later versions of
-packages with dependencies on later versions of other packages the
-opportunity to have their dependencies satisfied.
-<p>
-
-Thus <tt/Depends/ allows package maintainers to impose an order in
-which packages should be configured.
-
-<taglist>
-<tag><tt/Depends/
-<item>
-
-This declares an absolute dependency.
-<p>
-
-<prgn/dpkg/ will not configure
-packages whose dependencies aren't satisfied.  If it is asked to make
-an installation which would cause an installed package's dependencies
-to become unsatisfied it will complain<footnote>Current versions
-(1.2.4) of <prgn/dpkg/ have a bug in this area which will cause some of
-these problems to be ignored.</footnote>, unless
-<tt/--auto-deconfigure/ is specified, in which case those packages
-will be deconfigured before the installation proceeds.
-<p>
-
-<prgn/dselect/ makes it hard for the user to select packages for
-installation, removal or upgrade in a way that would mean that
-packages' <prgn/Depends/ fields would be unsatisfied.  The user can
-override this if they wish, for example if they know that <prgn/dselect/
-has an out-of-date view of the real package relationships.
-<p>
-
-The <tt/Depends/ field should be used if the depended-on package is
-required for the depending package to provide a significant amount of
-functionality.
-
-<tag><tt/Recommends/
-<item>
-This declares a strong, but not absolute, dependency.
-<p>
-
-<tt/Recommends/ is ignored by <prgn/dpkg/, so that users using the
-command-line (who are presumed to know what they're doing) will not be
-impeded.
-<p>
-
-It is treated by <prgn/dselect/ exactly as <tt/Depends/ is; this makes
-it hard for the user to select things so as to leave <tt/Recommends/
-fields unsatisfied, but they are able to do so by being persistent.
-<p>
-
-The <tt/Recommends/ field should list packages that would be found
-together with this one in all but unusual installations.
-
-<tag><tt/Suggests/
-<item>
-
-This is used to declare that one package may be more useful with one
-or more others.  Using this field tells the packaging system and the
-user that the listed packages are be related to this one and can
-perhaps enhance its usefulness, but that installing this one without
-them is perfectly reasonable.
-<p>
-
-<prgn/dselect/ will offer suggsted packages to the system administrator
-when they select the suggesting package, but the default is not to
-install the suggested package.
-
-<tag><tt/Pre-Depends/
-<item>
-
-This field is like <tt/Depends/, except that it also forces <prgn/dpkg/
-to complete installation of the packages named before even starting
-the installation of the package which declares the predependency.
-<p>
-
-<prgn/dselect/ checks for predependencies when it is doing an
-installation run, and will attempt to find the packages which are
-required to be installed first and do so in the right order.
-<p>
-
-However, this process is slow (because it requires repeated
-invocations of <prgn/dpkg/) and troublesome (because it requires
-guessing where to find the appropriate files).
-<p>
-
-For these reasons, and because this field imposes restrictions on the
-order in which packages may be unpacked (which can be difficult for
-installations from multipart media, for example), <tt/Pre-Depends/
-should be used sparingly, preferably only by packages whose premature
-upgrade or installation would hamper the ability of the system to
-continue with any upgrade that might be in progress.
-<p>
-
-When the package declaring it is being configured, a
-<tt/Pre-Dependency/ will be considered satisfied only if the depending
-package has been correctly configured, just as if an ordinary
-<tt/Depends/ had been used.
-<p>
-
-However, when a package declaring a predependency is being unpacked
-the predependency can be satisfied even if the depended-on package(s)
-are only unpacked or half-configured, provided that they have been
-configured correctly at some point in the past (and not removed or
-partially removed since).  In this case both the previously-configured
-and currently unpacked or half-configured versions must satisfy any
-version clause in the <tt/Pre-Depends/ field.
-
-</taglist>
-
-When selecting which level of dependency to use you should consider
-how important the depended-on package is to the functionality of the
-one declaring the dependency.  Some packages are composed of
-components of varying degrees of importance.  Such a package should
-list using <tt/Depends/ the package(s) which are required by the more
-important components.  The other components' requirements may be
-mentioned as Suggestions or Recommendations, as appropriate to the
-components' relative importance.
-
-<sect1>Dependencies on shared libraries
-<p>
-
-The dependency fields listed above are used by packages which need
-shared libraries to declare dependencies on the appropriate packages.
-<p>
-
-These dependencies are usually determined automatically using
-<prgn/dpkg-shlibdeps/ and inserted in the package control file using
-the control file substitution variables mechanism; see <ref
-id="srcsubstvars"> and <ref id="sourcetools">.
-
-<sect1>Deconfiguration due to removal during bulk installations
-<p>
-
-If <prgn/dpkg/ would like to remove a package due to a conflict, as
-described above, but this would violate a dependency of some other
-package on the system, <prgn/dpkg/ will usually not remove the
-conflicting package and halt with an error.
-<p>
-
-However, if the <tt/--auto-deconfigure/ (<tt/-B/) option is used
-<prgn/dpkg/ will automatically `deconfigure' the package with the
-problematic dependency, so that the conflicting package can be removed
-and the package we're trying to install can be installed.  If
-<prgn/dpkg/ is being asked to install packages (rather than just
-unpacking them) it will try to reconfigure the package when it has
-unpacked all its arguments, in the hope that one of the other packages
-it is installing will satisfy the problematic dependency.
-<p>
-
-<prgn/dselect/ supplies this argument to <prgn/dpkg/ when it invokes it,
-so that bulk installations proceed smoothly.
-
-<sect id="conflicts">Alternative packages - <tt/Conflicts/ and <tt/Replaces/
-<p>
-
-When one package declares a conflict with another <prgn/dpkg/ will
-refuse to allow them to be installed on the system at the same time.
-<p>
-
-If one package is to be installed, the other must be removed first -
-if the package being installed is marked as replacing (<ref
-id="replaces">) the one on the system, or the one on the system is
-marked as deselected, or both packages are marked <tt/Essential/, then
-<prgn/dpkg/ will automatically remove the package which is causing the
-conflict, otherwise it will halt the installation of the new package
-with an error.
-<p>
-
-<prgn/dselect/ makes it hard to select conflicting packages, though the
-user can override this if they wish.  If they do not override it then
-<prgn/dselect/ will select one of the packages for removal, and the user
-must make sure it is the right one.  In the future <prgn/dselect/ will
-look for the presence of a <tt/Replaces/ field to help decide which
-package should be installed and which removed.
-<p>
-
-A package will not cause a conflict merely because its configuration
-files are still installed; it must be at least half-installed.
-<p>
-
-A special exception is made for packages which declare a conflict with
-their own package name, or with a virtual package which they provide
-(see below): this does not prevent their installation, and allows a
-package to conflict with others providing a replacement for it.  You
-use this feature when you want the package in question to be the only
-package providing something.
-<p>
-
-A <tt/Conflicts/ entry should almost never have an `earlier than'
-version clause.  This would prevent <prgn/dpkg/ from upgrading or
-installing the package which declared such a conflict until the
-upgrade or removal of the conflicted-with package had been completed.
-This aspect of installation ordering is not handled by <prgn/dselect/,
-so that the use <tt/Conflicts/ in this way is likely to cause problems
-for `bulk run' upgrades and installations.
-<p>
-
-
-<sect id="virtual">Virtual packages - <tt/Provides/
-<p>
-
-As well as the names of actual (`concrete') packages, the package
-relationship fields <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and
-<tt/Conflicts/ may mention virtual packages.
-<p>
-
-A virtual package is one which appears in the <tt/Provides/ control
-file field of another package.  The effect is as if the package(s)
-which provide a particular virtual package name had been listed by
-name everywhere were the virtual package name appears.
-<p>
-
-If there are both a real and a virtual package of the same name then
-the dependency may be satisfied (or the conflict caused) by either the
-real package or any of the virtual packages which provide it.  This is
-so that, for example, supposing we have
-<example>
-Package: vm
-Depends: emacs
-</example>
-and someone else releases an xemacs package they can say
-<example>
-Package: xemacs
-Provides: emacs
-</example>
-and all will work in the interim (until a purely virtual package name
-is decided on and the <tt/emacs/ and <tt/vm/ packages are changed to
-use it).
-<p>
-
-If a dependency or a conflict has a version number attached then only
-real packages will be considered to see whether the relationship is
-satisfied (or the prohibition violated, for a conflict) - it is
-assumed that a real package which provides virtual package is not of
-the `right' version.  So, a <tt/Provides/ field may not contain
-version numbers, and the version number of the concrete package which
-provides a particular virtual package will not be looked at when
-considering a dependency on or conflict with the virtual package name.
-<p>
-
-It is likely that the ability will be added in a future release of
-<prgn/dpkg/ to specify a version number for each virtual package it
-provides.  This feature is not yet present, however, and is expected
-to be used only infrequently.
-<p>
-
-If you want to specify which of a set of real packages should be the
-default to satisfy a particular dependency on a virtual package, you
-should list the real package as alternative before the virtual.
-<p>
-
-
-<sect id="replaces"><tt/Replaces/ - overwriting files and replacing packages
-<p>
-
-The <tt/Replaces/ control file field has two purposes, which come into
-play in different situations.
-<p>
-
-Virtual packages (<ref id="virtual">) are not considered when looking
-at a <tt/Replaces/ field - the packages declared as being replaced
-must be mentioned by their real names.
-
-<sect1>Overwriting files in other packages
-<p>
-
-Firstly, as mentioned before, it is usually an error for a package to
-contains files which are on the system in another package, though
-currently the <tt/--force-overwrite/ flag is enabled by default,
-downgrading the error to a warning,
-<p>
-
-If the overwriting package declares that it replaces the one
-containing the file being overwritten then <prgn/dpkg/ will proceed, and
-replace the file from the old package with that from the new.  The
-file will no longer be listed as `owned' by the old package.
-<p>
-
-If a package is completely replaced in this way, so that <prgn/dpkg/
-does not know of any files it still contains, it is considered to have
-disappeared.  It will be marked as not wanted on the system (selected
-for removal) and not installed.  Any conffiles details noted in the
-package will be ignored, as they will have been taken over by the
-replacing package(s).  The package's <prgn/postrm/ script will be run to
-allow the package to do any final cleanup required.
-See <ref id="mscriptsinstact">.
-<p>
-
-In the future <prgn/dpkg/ will discard files which overwrite those from
-another package which declares that it replaces the one being
-installed (so that you can install an older version of a package
-without problems).
-<p>
-
-This usage of <tt/Replaces/ only takes effect when both packages are
-at least partially on the system at once, so that it can only happen
-if they do not conflict or if the conflict has been overridden.
-
-<sect1>Replacing whole packages, forcing their removal
-<p>
-
-Secondly, <tt/Replaces/ allows <prgn/dpkg/ and <prgn/dselect/ to resolve
-which package should be removed when a conflict - see
-<ref id="conflicts">.  This usage only takes effect when the two
-packages <em/do/ conflict, so that the two effects do not interfere
-with each other.
-<p>
-
-<sect>Defaults for satisfying dependencies - ordering
-<p>
-
-Ordering is significant in dependency fields.
-<p>
-
-Usually dselect will suggest to the user that they select the package
-with the most `fundamental' class (eg, it will prefer Base packages to
-Optional ones), or the one that they `most wanted' to select in some
-sense.
-<p>
-
-In the absence of other information <prgn/dselect/ will offer a
-default selection of the first named package in a list of
-alternatives.
-<p>
-
-However, there is no way to specify the `order' of several packages
-which all provide the same thing, when that thing is listed as a
-dependency.
-<p>
-
-Therefore a dependency on a virtual package should contain a concrete
-package name as the first alternative, so that this is the default.
-<p>
-
-For example, consider the set of packages:
 
-<example>
-Package: glibcdoc
-Recommends: info-browser
 
-Package: info
-Provides: info-browser
 
-Package: emacs
-Provides: info-browser
-</example>
-<p>
 
-If <prgn/emacs/ and <prgn/info/ both have the same priority then
-<prgn/dselect/'s choice is essentially random.  Better would be
-<example>
-Package: glibcdoc
-Recommends: info | info-browser
-</example>
-so that <prgn/dselect/ defaults to selecting the lightweight standalone
-info browser.
-
-
-
-<chapt id="conffiles">Configuration file handling
-<p>
-
-<prgn/dpkg/ can do a certain amount of automatic handling of package
-configuration files.
-<p>
-
-Whether this mechanism is appropriate depends on a number of factors,
-but basically there are two approaches to any particular configuration
-file.
-<p>
-
-The easy method is to ship a best-effort configuration in the package,
-and use <prgn/dpkg/'s conffile mechanism to handle updates.  If the user
-is unlikely to want to edit the file, but you need them to be able to
-without losing their changes, and a new package with a changed version
-of the file is only released infrequently, this is a good approach.
-<p>
-
-The hard method is to build the configuration file from scratch in the
-<prgn/postinst/ script, and to take the responsibility for fixing any
-mistakes made in earlier versions of the package automatically.  This
-will be appropriate if the file is likely to need to be different on
-each system.
-
-<sect>Automatic handling of configuration files by <prgn/dpkg/
-<p>
-
-A package may contain a control area file called <tt/conffiles/.  This
-file should be a list of filenames of configuration files needing
-automatic handling, separated by newlines.  The filenames should be
-absolute pathnames, and the files referred to should actually exist in
-the package.
-<p>
-
-When a package is upgraded <prgn/dpkg/ will process the configuration
-files during the configuration stage, shortly before it runs the
-package's <prgn/postinst/ script,
-<p>
-
-For each file it checks to see whether the version of the file
-included in the package is the same as the one that was included in
-the last version of the package (the one that is being upgraded
-from); it also compares the version currently installed on the system
-with the one shipped with the last version.
-<p>
-
-If neither the user nor the package maintainer has changed the file,
-it is left alone.  If one or the other has changed their version, then
-the changed version is preferred - ie, if the user edits their file,
-but the package maintainer doesn't ship a different version, the
-user's changes will stay, silently, but if the maintainer ships a new
-version and the user hasn't edited it the new version will be
-installed (with an informative message).  If both have changed their
-version the user is prompted about the problem and must resolve the
-differences themselves.
-<p>
-
-The comparisons are done by calculating the MD5 message digests of the
-files, and storing the MD5 of the file as it was included in the most
-recent version of the package.
-<p>
-
-When a package is installed for the first time <prgn/dpkg/ will install
-the file that comes with it, unless that would mean overwriting a file
-already on the filesystem.
-<p>
-
-However, note that <prgn/dpkg/ will <em/not/ replace a conffile that
-was removed by the user (or by a script).  This is necessary because
-with some programs a missing file produces an effect hard or
-impossible to achieve in another way, so that a missing file needs to
-be kept that way if the user did it.
-<p>
-
-Note that a package should <em/not/ modify a <prgn/dpkg/-handled
-conffile in its maintainer scripts.  Doing this will lead to
-<prgn/dpkg/ giving the user confusing and possibly dangerous options
-for conffile update when the package is upgraded.
-
-<sect>Fully-featured maintainer script configuration handling
-<p>
-
-For files which contain site-specific information such as the hostname
-and networking details and so forth, it is better to create the file
-in the package's <prgn/postinst/ script.
-<p>
-
-This will typically involve examining the state of the rest of the
-system to determine values and other information, and may involve
-prompting the user for some information which can't be obtained some
-other way.
-<p>
-
-When using this method there are a couple of important issues which
-should be considered:
-<p>
-
-If you discover a bug in the program which generates the configuration
-file, or if the format of the file changes from one version to the
-next, you will have to arrange for the postinst script to do something
-sensible - usually this will mean editing the installed configuration
-file to remove the problem or change the syntax.  You will have to do
-this very carefully, since the user may have changed the file, perhaps
-to fix the very problem that your script is trying to deal with - you
-will have to detect these situations and deal with them correctly.
-<p>
-
-If you do go down this route it's probably a good idea to make the
-program that generates the configuration file(s) a separate program in
-<tt>/usr/sbin</>, by convention called <tt/<var/package/config/ and
-then run that if appropriate from the post-installation script.  The
-<tt/<var/package/config/ program should not unquestioningly overwrite
-an existing configuration - if its mode of operation is geared towards
-setting up a package for the first time (rather than any arbitrary
-reconfiguration later) you should have it check whether the
-configuration already exists, and require a <tt/--force/ flag to
-overwrite it.
-
-
-
-<chapt id="alternatives">Alternative versions of an interface -
-<prgn/update-alternatives/
-<p>
-
-When several packages all provide different versions of the same
-program or file it is useful to have the system select a default, but
-to allow the system administrator to change it and have their
-decisions respected.
-<p>
-
-For example, there are several versions of the <prgn/vi/ editor, and
-there is no reason to prevent all of them from being installed at
-once, each under their own name (<prgn/nvi/, <prgn/vim/ or whatever).
-Nevertheless it is desirable to have the name <tt/vi/ refer to
-something, at least by default.
-<p>
-
-If all the packages involved cooperate, this can be done with
-<prgn/update-alternatives/.
-<p>
-
-Each package provides its own version under its own name, and calls
-<prgn/update-alternatives/ in its postinst to register its version
-(and again in its prerm to deregister it).
-<p>
-
-See the manpage <manref name=update-alternatives section=8> for
-details.
-<p>
-
-If <prgn/update-alternatives/ does not seem appropriate you may wish
-to consider using diversions instead.
-
-
-<chapt id="diversions">Diversions - overriding a package's version of a file
-<p>
-
-It is possible to have <prgn/dpkg/ not overwrite a file when it
-reinstalls the package it belongs to, and to have it put the file from
-the package somewhere else instead.
-<p>
-
-This can be used locally to override a package's version of a file, or
-by one package to override another's version (or provide a wrapper for
-it).
-<p>
-
-Before deciding to use a diversion, read <ref id="alternatives"> to
-see if you really want a diversion rather than several alternative
-versions of a program.
-<p>
-
-There is a diversion list, which is read by <prgn/dpkg/, and updated
-by a special program <prgn/dpkg-divert/.  Please see <manref
-name=dpkg-divert section=8> for full details of its operation.
-<p>
-
-When a package wishes to divert a file from another, it should call
-<prgn/dpkg-divert/ in its preinst to add the diversion and rename the
-existing file.  For example, supposing that a <prgn/smailwrapper/
-package wishes to install a wrapper around <tt>/usr/sbin/smail</>:
-<example>
-if [ install = "$1" ]; then
-    dpkg-divert --package smailwrapper --add --rename \
-		--divert /usr/sbin/smail.real /usr/sbin/smail
-fi
-</example>
-Testing <tt/$1/ is necessary so that the script doesn't try to add the
-diversion again when <prgn/smailwrapper/ is upgraded.  The
-<tt/--package smailwrapper/ ensures that <prgn/smailwrapper/'s copy of
-<tt>/usr/sbin/smail</> can bypass the diversion and get installed as
-the true version.
-<p>
-
-The postrm has to do the reverse:
-<example>
-if [ remove = "$1" ]; then
-    dpkg-divert --package smailwrapper --remove --rename \
-                --divert /usr/sbin/smail.real /usr/sbin/smail
-fi
-</example>
-<p>
-
-Do not attempt to divert a file which is vitally important for the
-system's operation - when using <prgn/dpkg-divert/ there is a time,
-after it has been diverted but before <prgn/dpkg/ has installed the
-new version, when the file does not exist.
-
-
-<chapt id="sharedlibs">Shared libraries
-<p>
-
-Packages containing shared libraries must be constructed with a little
-care to make sure that the shared library is always available.  This
-is especially important for packages whose shared libraries are
-vitally important, such as the libc.
-<p>
-
-Firstly, your package should install the shared libraries under their
-normal names.  For example, the <prgn/libgdbm1/ package should install
-<tt/libgdbm.so.1.7.3/ as <tt>/usr/lib/libgdbm.so.1.7.3</tt>.  The
-files should not be renamed or relinked by any prerm or postrm
-scripts; <prgn/dpkg/ will take care of renaming things safely without
-affecting running programs, and attempts to interfere with this are
-likely to lead to problems.
-<p>
-
-Secondly, your package should include the symlink that <prgn/ldconfig/
-would create for the shared libraries.  For example, the
-<prgn/libgdbm1/ package should include a symlink from
-<tt>/usr/lib/libgdbm.so.1</tt> to <tt/libgdbm.so.1.7.3/.  This is
-needed so that <prgn/ld.so/ can find the library in between the time
-<prgn/dpkg/ installs it and <prgn/ldconfig/ is run in the
-<prgn/postinst/ script.  Futhermore, and <em/this is very important/,
-the library must be placed before the symlink pointing to it in the
-<tt/.deb/ file.  This is so that by the time <prgn/dpkg/ comes to
-install the symlink (overwriting the previous symlink pointing at an
-older version of the library) the new shared library is already in
-place.  Currently the way to ensure the ordering is done properly is
-to install the library in the appropriate <tt>debian/tmp/.../lib</>
-directory before creating the symlink, by putting the commands in the
-<tt>debian/rules</> in the appropriate order.
-<p>
-
-<!--
- next Paragraph added to close Bug #5299, Guy Maor
- -->
-
-Thirdly, the development package should contain a symlink for the
-shared library without a version number.  For example, the
-<tt/libgdbm1-dev/ package should include a symlink from
-<tt>/usr/lib/libgdm.so</> to <tt/libgdm.so.1.7.3/.  This symlink is
-needed by <prgn/ld/ when compiling packages as it will only look for
-<tt/libgdm.so/ and <tt/libgdm.a/ when compiling dynamically or
-statically, respectively.
-<p>
-
-<!--
- next paragraph changed by Christian Schwarz (see policy weekly #6)
- -->
-
-Any package installing shared libraries in a directory that's listed
-in <tt>/etc/ld.so.conf</tt> or in one of the default library
-directories of <prgn/ld.so/ (currently, these are <tt>/usr/lib</tt>
-and <tt>/lib</tt>) must call <prgn/ldconfig/ in its <prgn/postinst/
-script if and only if the first argument is `configure'. However, it
-is important not to call <prgn/ldconfig/ in the postrm or preinst
-scripts in the case where the package is being upgraded (see <ref
-id="unpackphase">), as <prgn/ldconfig/ will see the temporary names
-that <prgn/dpkg/ uses for the files while it is installing them and
-will make the shared library links point to them, just before
-<prgn/dpkg/ continues the installation and removes the links!
-<p>
-
-<!-- 
- moved from section 2.2 , DMorris 
- -->
-
-<sect id="shlibs">The <tt/shlibs/ File Format
-<p>
-
-This file is for use by <prgn/dpkg-shlibdeps/ and is required when
-your package provides shared libraries.
-<p>
-
-Each line is of the form:
-<example>
-<var/library-name/ <var/version-or-soname/ <var/dependencies .../
-</example>
-<p>
-
-<var/library-name/ is the name of the shared library, for example
-<tt/libc5/.
-<p>
-
-<var/version-or-soname/ is the soname of the library - ie, the thing
-that must exactly match for the library to be recognised by
-<prgn/ld.so/.  Usually this is major version number of the library.
-<p>
-
-<var/dependencies/ has the same syntax as a dependency field in a
-binary package control file.  It should give details of which
-package(s) are required to satisfy a binary built against the version
-of the library contained in the package.  See <ref id="depsyntax">.
-<p>
-
-For example, if the package <tt/foo/ contains <tt/libfoo.so.1.2.3/,
-where the soname of the library is <tt/libfoo.so.1/, and the first
-version of the package which contained a minor number of at least
-<tt/2.3/ was <var/1.2.3-1/, then the package's <var/shlibs/ could
-say:
-<example>
-libfoo 1	foo (>= 1.2.3-1)
-</example>
-<p>
-
-The version-specific dependency is to avoid warnings from <prgn/ld.so/
-about using older shared libraries with newer binaries.
-
-<sect>Further Technical information on <tt/shlibs/</>
-
-<!-- 
-  following section mostly provided by Heiko Schlittermann
-  edited by DMorris
- -->
-
-<sect1><em/What/ are the <tt/shlibs/ files?
-<p>
-
-The <tt>debian/shlibs</> file provides a way of checking
-for shared library dependencies on packaged binaries.  They are
-intended to be used by package maintainers to make their lives easier.
-<p>
-
-Other <tt/shlibs/ files that exist on a Debian system are
-<list>
-<item> <tt>/etc/dpkg/shlibs.default</>
-<item> <tt>/etc/dpkg/shlibs.override</>
-<item> <tt>/var/lib/dpkg/info/*.shlibs</>
-<item> <tt>debian/shlibs.local</>
-</list>
-
-These files are used by <prgn/dpkg-shlibdeps/ when creating a binary
-package.
-
-<sect1><em/How/ does <prgn/dpkg-shlibdeps/ work?
-<p>
-
-<prgn/dpkg-shlibdeps/ calls <prgn/ldd/ to determine the shared libraries
-used by the compiled binaries passed through its command line.
-<p>
-
-For each shared library, <prgn/dpkg-shlibdeps/ needs to know 
-<list compact>
-<item>the package containing the library, and
-<item>the library version number,
-</list>
-<p>
-it scans the following files in this order.
-<enumlist compact>
-<item><tt>debian/shlibs.local</>
-<item><tt>/etc/dpkg/shlibs.override</>
-<item><tt>/var/lib/dpkg/info/*.shlibs</>
-<item><tt>/etc/dpkg/shlibs.default</>
-</enumlist>
-
-<sect1><em/Who/ maintains the various <tt/shlibs/ files?
-<p>
-
-<list compact>
-<item><tt>/etc/dpkg/shlibs.default</> - the maintainer of dpkg
-<item><tt>/var/lib/dpkg/info/<var/package/.shlibs</> - the maintainer of each 
-package
-<item><tt>/etc/dpkg/shlibs.override</> - the local system administrator
-<item><tt>debian/shlibs.local</> - the maintainer of the package
-</list>
-
-The <tt/shlibs.default/ file is managed by <prgn/dpkg/. The entries in
-<tt/shlibs.default/ that are provided by <prgn/dpkg/ are just there to
-fix things until the shared library packages all have <tt/shlibs/
-files.
-
-<sect1><em/How/ to use <prgn/dpkg-shlibdeps/ and the <tt/shlibs/ files?
-
-<sect2>If your package doesn't provide a shared library
-<p>
-
-Put a call to <prgn/dpkg-shlibs/ into your <tt>debian/rules</> file.
-If your package contains only binaries (e.g. no scripts) use:
-<example>
-dpkg-shlibdeps debian/tmp/usr/{bin,sbin}/*
-</example>
-
-If <prgn/dpkg-shlibdeps/ doesn't complain, you're done. If it does
-complain you might need to create your own <tt>debian/shlibs.local</>
-file.
-
-<sect2>If your package provides a shared library
-<p>
-
-Create a <tt>debian/shlibs</> file and let <tt>debian/rules</> install
-it in the control area:
-
-<example>
-install -m644 debian/shlibs debian/tmp/DEBIAN
-</example>
-
-If your package contains additional binaries see above.
-
-<sect1><em/How/ to write <tt>debian/shlibs.local</>
-<p>
-
-This file is intended only as a <em/temporary/ fix if your binaries
-depend on a library which doesn't provide its own
-<tt>/var/lib/dpkg/*.shlibs</> file yet.
-<p>
-
-Let's assume you are packaging a binary <tt/foo/. Your output in
-building the package might look like this.
-
-<example>
-$ ldd foo
-libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
-libc.so.5 => /lib/libc.so.5.2.18
-libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
-</example>
-
-And when you ran <prgn/dpkg-shlibdeps/
-
-<example>
-$ dpkg-shlibdeps -o foo
-dpkg-shlibdeps: warning: unable to find dependency information 
-for shared library libbar 
-(soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
-shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
-</example>
-
-The <prgn/foo/ binary depends on the <prgn/libbar/ shared library, but
-no package seems to provide a <tt/*.shlibs/ file in
-<tt//var/lib/dpkg/info/.  Let's determine the package responsible:
-<p>
-
-<example>
-$ dpkg -S /usr/X11R6/lib/libbar.so.1.0
-bar1: /usr/X11R6/lib/libbar.so.1.0
-$ dpkg -s bar1 | grep Version
-Version: 1.0-1
-</example>
-
-This tells us that the <prgn/bar1/ package, version 1.0-1 is the one
-we are using. Now we can create our own <tt>debian/shlibs.local</> to
-temporarly fix the above problem. Include the following line into your
-<tt>debian/shlibs.local</> file.
-
-<example>
-    libbar 1 bar1 (>= 1.0-1)
-</example>
-
-Now your package build should work. As soon as the maintainer of
-<prgn/libbar1/ provides a <tt/shlibs/ file, you can remove your
-<tt>debian/shlibs.local</> file.
-
-<chapt id="methif"><prgn/dselect/'s interface to its installation methods
-<p>
-
-<prgn/dselect/ calls scripts from its installation methods when it
-needs to actually access data from the distribution.  The core program
-<prgn/dselect/ itself just calls these scripts and provides the
-package and access method selection interfaces.  The installation
-methods are responsible for invoking <prgn/dpkg/ as appropriate.
-<p>
-
-Each installation method has three scripts:
-<list compact>
-<item>Setup installation parameters.
-<item>Update list of available packages.
-<item>Install.
-</list>
-<p>
-
-<prgn/dselect/ searches for methods in <tt>/usr/lib/dpkg/methods</>
-and <tt>/usr/local/lib/dpkg/methods</>.
-
-<sect>Functions of the method scripts
-<p>
-
-The setup script is run just after the user has chosen an installation
-method.  It should prompt the user for parameters like the site to
-NFS-mount or FTP from, the directory to use, or the directory or
-filesystem where the <tt/.deb/ files can be found, or the tape or
-floppy device to install from.  It should store the responses under
-<tt>/var/lib/dpkg/methods</> - see below.  If no available
-packages list is available it should perhaps offer to scan the
-available packages.
-<p>
-
-The update script should obtain a list of available packages if
-possible, and run <tt/dpkg --update-avail/, <tt/dpkg --merge-avail/
-and/or <tt/dpkg --forget-old-unavail/ to load it into <prgn/dpkg/ and
-<prgn/dselect/'s database of available packages.  If no packages list
-was available and the user was offered and accepted the option of
-scanning the actual files available this scan should be done here,
-using <tt/dpkg --record-avail/.
-<p>
-
-The install script should feed all the available <tt/.deb/ files to
-<tt/dpkg --iGOEB/ (this is equivalent to <tt/dpkg --install
---refuse-downgrade --selected-only --skip-same-version
---auto-deconfigure/).  The <tt/-R/ (<tt/--recursive/) option for
-traversing subdirectories may also be useful here).
-<p>
-
-If any of these scripts needs to display a message for the user, it
-should wait for the user to hit `return' before exiting so that
-dselect doesn't immediately rewrite the screen.
-<p>
-
-If a method script succeeds (returns a zero exit status)
-<prgn/dselect/ will return immediately to the main menu, with the
-`next' option highlighted ready for the user to select it.  If it
-fails <prgn/dselect/ will display a message and wait for the user to
-hit return.
-
-<sect>Location and arguments of the method scripts
-<p>
-
-A set of scripts (henceforth known as a group) may provide several
-methods on the `main menu' with different behaviour.  For example,
-there might be a generic get-packages-by-FTP group which might provide
-methods in the main menu for installation directly from one of the
-Debian mirror sites as well as for installation from a user-specified
-site.
-<p>
-
-Each group of methods implemented by the same set of scripts should
-have a subdirectory <tt>/usr/lib/dpkg/methods/<var/group/</> or
-<tt>/usr/local/lib/dpkg/methods/<var/group/</>, containing:
-<taglist compact>
-<tag><tt/names/
-<item>a list of user-visible methods provided by these scripts.
-<tag><tt/setup/
-<tag><tt/update/
-<tag><tt/install/
-<item>executable programs, the scripts themselves.
-<tag><tt/desc.<var/option//
-<item>description file.
-</taglist>
-<p>
-
-<tt/names/ will be formatted as a list of lines, each containing:
-<example>
-<var/sequence/ <var/method/ <var/summary/
-</example>
-<p>
-
-<var/sequence/ is a two-digit number that will be used much like
-<tt/rc.d/ prefixes to control the order in the main menu.  If in doubt
-use 50.
-<p>
-
-<var/method/ is a name which is displayed by <prgn/dselect/ as the
-name of the method, and which will be passed to <tt/setup/,
-<tt/update/ and <tt/unpack/ as their first argument.
-<p>
-
-<var/summary/ is the brief description string for <prgn/dselect/'s menu.
-<p>
-
-Each of the three scripts gets the same three arguments: <var/vardir/,
-<var/group/ and <var/method/.  <var/vardir/ is the base directory for
-storing <prgn/dpkg/ and <prgn/dselect/'s state, usually
-<tt>/var/lib/dpkg</>; this is passed in so that the <tt/--admindir/
-option to <prgn/dselect/ is honoured).
-<p>
-
-Each option may have an extended description in
-<tt/desc.<var/option//.  This should be formatted like the extended
-description part of a <tt/Description/ field entry <em/shifted one
-character to the left/.
-<p>
-
-<tt><var/vardir//methods</> will exist, and a method group may use a
-<tt><var/vardir//methods/<var/group/</> directory to store its state.
-<p>
-
-The group name and method name must follow the rules for C identifiers.
-
-<chapt id="conversion">Conversion procedure from old source packages
-<p>
-
-This is a brief summary of the procedure for converting a
-pre-2.0.0.0-format source package into the new format.
-<p>
-
-You are strongly advised to download and examine the <prgn/hello/
-package, and to read the section in the <prgn/dpkg/ programmers'
-manual describing the source packaging tools.  More detail about the
-exact functionality of these tools is available in <manref
-name=dpkg-source section=1>.
-<p>
-
-<list>
-
-<item>
-Download the original source code from wherever it can be found and do
-any rearrangement required to make it look like the original tree of
-the Debian source.  Put it in
-<tt><var/package/-<var/upstream-version/.orig/</> or
-<tt/<var/package/_<var/upstream-version/.orig.tar.gz/.
-
-<item>
-Rename all files <tt/debian.*/ to <tt>debian/*</>.  There may be some
-exceptions to this, but this is a good start.
-
-<item>
-Edit the <tt>debian/changelog</> - create or rename it if necessary.
-Add a new revision to the top with the appropriate details, and a
-local variables entry to the bottom to set Emacs to the right mode:
-<example>
-Local variables:
-mode: debian-changelog
-End:
-</example>
 
-<item>
-Edit/create <tt>debian/control</>:
-<list compact>
-<item>
-Remove the <tt/Version/ field.  If it is generated unusually (not
-equal to the source version) you must use the -v option to
-dpkg-gencontrol (see below).  <tt/Section/, <tt/Priority/,
-<tt/Maintainer/ go above the first blank line, most of the rest below.
-
-<item>
-Reorder the fields and add a blank line at an appropriate point,
-separating the source package fields from the binary package
-fields.
-
-<item>
-Add the <tt/Source/ field.
-
-<item>
-Add the <tt/Standards-Version/ field.  (Please check out the Debian
-Policy Manual for details about this field.)
-
-<item>
-Change the <tt/Architecture/ field for each package to <tt/any/,
-<tt/all/ or whatever.  If there isn't an <tt/Architecture/ field add
-one.
-
-<item>
-If any other use of sed or things used to happen to make the binary
-control files use <prgn/dpkg-gencontrol/'s variable substitution
-features to achieve the same effect.  Use <tt>debian/substvars</> if
-you need to put unusally-generated information (apart from details of
-<tt/.deb/ files) in the <tt/.changes/ file too.
-</list>
-
-<item>
-Edit the <tt>debian/rules</>:
-<list compact>
-<item>
-Remove the <prgn/source/ and <prgn/diff/ and any <prgn/changes/ and
-<prgn/dist/ targets.  These things now happen in a package-independent
-way and are not done by <tt>debian/rules</>.
-<item>
-Split the <prgn/binary/ target into <prgn/binary-arch/ and
-<prgn/binary-indep/; in many cases all of <prgn/binary/ should go into
-<prgn/binary-arch/.  Create the <prgn/binary/ target and the unused of
-the two other <prgn/binary-*/ targets if there is one - you can copy
-the ones from the <prgn/hello/ package.
-<item>
-Change the <prgn/binary/ target to use <prgn/dpkg-gencontrol/ to make
-the package control file(s).  Move it to after all the files have been
-installed but just before the last <prgn/chown/ and <prgn/chmod/ in
-the target.
-<item>
-Change occurrences of <tt/debian-tmp/ to <tt>debian/tmp</>.
-<item>
-Change occurrences of <tt/debian.{post,pre}{inst,rm}/ to
-<tt>debian/*</>.
-<item>
-Remove the version number setting at the top, if there is one.
-<item>
-Ensure that the package's Debian-specific and upstream changelogs are
-installed.
-</list>
-
-<item>
-Change the package to use <prgn/dpkg-shlibdeps/ to determine its
-shared library dependencies and substitute them in.  Shared library
-dependencies should no longer be hardwired in the source package.
-
-<item>
-Check that the <tt>debian/README</> is really the copyright file, and
-if so rename it to <tt>debian/copyright</> and edit
-<tt>debian/rules</> to cope with this and to change the installation
-of the copyright file from <tt>/usr/doc/<var/package//copyright</>
-to <tt>/usr/doc/copyright/<var/package/</>.  If it isn't then
-find <tt>debian/copyright</> and decide what to do with the
-<tt>README</>.
-
-<item>
-Check for various other anachronisms and problems:
-<list compact>
-<item>
-Remove any <tt/Package_Revision/, <tt/Package-Revision/ or
-<tt/Revision/ fields.
-<item>
-Rename <tt/Optional/ to <tt/Suggests/, <tt/Recommended/ to
-<tt/Recommends/.
-<item>
-Change <tt>/usr/doc/examples/<var/package/</> to
-<tt>/usr/doc/<var/package//examples</>.
-<item>
-Make sure that manpages are installed compressed.
-<item>
-Check that the description has an extended description, is
-well-formatted and meaningful and helpful to people wanting to know
-whether to install a package.
-</list>
-
-<item>
-Look everything over.
-
-<item>
-Do a test build using <tt/dpkg-buildpackage -us -uc -sa
--r<var/whatever//.  Check the permissions and locations of files in
-the resulting package by examining the output of <tt/dpkg-deb
---contents/, and check that the source build happened OK.  Test
-install the binary package(s) and test extract the source package(s).
-
-<item>
-Sign the release: either rebuild everything with <tt/dpkg-buildpackage
--sa/, or PGP-sign the <tt/.dsc/, rebuild the <tt/.changes/ using
-<tt/dpkg-genchanges -sa/, and then PGP-sign the <tt/.changes/.
-
-</list>
-<p>
-
-The use of <tt/-sa/ on <prgn/dpkg-buildpackage/ and
-<prgn/dpkg-genchanges/ is important when doing the first
-build/uploading of a new-format source package.  Unless this happens
-to be Debian revision <tt/0/ or <tt/1/ by default the original source
-tarfile will not be included in the uploaded files listed in the
-<tt/.changes/ file, and so it won't be installed on the FTP site.
-<tt/-sa/ requests that the original source be included regardless.
-
-</book>