From 25b4839e000bc696827519518a4c7d27ae76dcb9 Mon Sep 17 00:00:00 2001
From: Brian Ryans <BrianLRyans@gmail.com>
Date: Thu, 30 Sep 2010 12:46:54 -0500
Subject: [PATCH] policy cleanup: remove entire pkgman and refs

* Remove the Packaging Manual
* Remove references to the above
* Reformat paragraphs altered by reference removal
---
 policy.sgml | 1450 +---------------------------------------------------------
 1 files changed, 25 insertions(+), 1425 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index 642f672..bfb79cd 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -117,11 +117,6 @@
 	</p>
 
 	<p>
-	  The appendices to this manual are not necessarily normative,
-	  either. Please see <ref id="pkg-scope"> for more information.
-	</p>
-
-	<p>
 	  In the normative part of this manual,
 	  the words <em>must</em>, <em>should</em> and
 	  <em>may</em>, and the adjectives <em>required</em>,
@@ -2117,7 +2112,7 @@
 	<p>
 	  The architectures we build on and build for are determined
 	  by <prgn>make</prgn> variables using the
-	  utility <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
+	  utility <prgn>dpkg-architecture</prgn>.
 	  You can determine the Debian architecture and the GNU style
 	  architecture specification string for the build architecture as
 	  well as for the host architecture.  The build architecture is
@@ -5641,12 +5636,11 @@ Replaces: mail-transport-agent
 
 	<p>
 	  When a package is built which contains any shared libraries, it
-	  must provide a <file>shlibs</file> file for other packages to
-	  use.  When a package is built which contains any shared
-	  libraries or compiled binaries, it must run
-	  <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
-	  on these to determine the libraries used and hence the
-	  dependencies needed by this package.<footnote>
+	  must provide a <file>shlibs</file> file for other packages to use.
+	  When a package is built which contains any shared libraries or
+	  compiled binaries, it must run <prgn>dpkg-shlibdeps</prgn> on
+	  these to determine the libraries used and hence the dependencies
+	  needed by this package.<footnote>
 	    <p>
 	      <prgn>dpkg-shlibdeps</prgn> will use a program
 	      like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find
@@ -5699,11 +5693,10 @@ Replaces: mail-transport-agent
 	<heading>The <tt>shlibs</tt> files present on the system</heading>
 
 	<p>
-	  There are several places where <tt>shlibs</tt> files are
-	  found.  The following list gives them in the order in which
-	  they are read by
-	  <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
-	  (The first one which gives the required information is used.)
+	  There are several places where <tt>shlibs</tt> files are found.
+	  The following list gives them in the order in which they are read
+	  by <prgn>dpkg-shlibdeps</prgn>. (The first one which gives the
+	  required information is used.)
 	</p>
 
 	<p>
@@ -5743,27 +5736,26 @@ Replaces: mail-transport-agent
 		files give details of any shared libraries included in the
 		same package.<footnote>
 		  An example may help here.  Let us say that the source
-		  package <tt>foo</tt> generates two binary
-		  packages, <tt>libfoo2</tt> and <tt>foo-runtime</tt>.
-		  When building the binary packages, the two packages are
-		  created in the directories <file>debian/libfoo2</file>
-		  and <file>debian/foo-runtime</file> respectively.
+		  package <tt>foo</tt> generates two binary packages,
+		  <tt>libfoo2</tt> and <tt>foo-runtime</tt>. When building
+		  the binary packages, the two packages are created in the
+		  directories <file>debian/libfoo2</file> and
+		  <file>debian/foo-runtime</file> respectively.
 		  (<file>debian/tmp</file> could be used instead of one of
 		  these.)  Since <tt>libfoo2</tt> provides the
 		  <tt>libfoo</tt> shared library, it will require a
 		  <tt>shlibs</tt> file, which will be installed in
 		  <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually to
 		  become <file>/var/lib/dpkg/info/libfoo2.shlibs</file>.
-		  When <prgn>dpkg-shlibdeps</prgn> is run on the
-		  executable <file>debian/foo-runtime/usr/bin/foo-prog</file>,
-		  it will examine
-		  the <file>debian/libfoo2/DEBIAN/shlibs</file> file to
-		  determine whether <tt>foo-prog</tt>'s library
+		  When <prgn>dpkg-shlibdeps</prgn> is run on the executable
+		  <file>debian/foo-runtime/usr/bin/foo-prog</file>, it will
+		  examine the <file>debian/libfoo2/DEBIAN/shlibs</file> file
+		  to determine whether <tt>foo-prog</tt>'s library
 		  dependencies are satisfied by any of the libraries
 		  provided by <tt>libfoo2</tt>.  For this reason,
 		  <prgn>dpkg-shlibdeps</prgn> must only be run once all of
-		  the individual binary packages' <tt>shlibs</tt> files
-		  have been installed into the build directory.
+		  the individual binary packages' <tt>shlibs</tt> files have
+		  been installed into the build directory.
 		</footnote>
 	      </p>
 	    </item>
@@ -5798,11 +5790,10 @@ Replaces: mail-transport-agent
 	    <file>shlibs</file> files</heading>
 
 	<p>
-	  Put a call to
-	  <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
-	  into your <file>debian/rules</file> file.  If your package
-	  contains only compiled binaries and libraries (but no scripts),
-	  you can use a command such as:
+	  Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+	  <file>debian/rules</file> file.  If your package contains only
+	  compiled binaries and libraries (but no scripts), you can use a
+	  command such as:
 	  <example compact="compact">
 dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
   debian/tmp/usr/lib/*
@@ -9751,1397 +9742,6 @@ END-INFO-DIR-ENTRY
       </sect>
     </chapt>
 
-    <appendix id="pkg-scope">
-      <heading>Introduction and scope of these appendices</heading>
-
-      <p>
-	These appendices are taken essentially verbatim from the
-	now-deprecated Packaging Manual, version 3.2.1.0.  They are
-	the chapters which are likely to be of use to package
-	maintainers and which have not already been included in the
-	policy document itself. Most of these sections are very likely
-	not relevant to policy; they should be treated as
-	documentation for the packaging system. Please note that these
-	appendices are included for convenience, and for historical
-	reasons: they used to be part of policy package, and they have
-	not yet been incorporated into dpkg documentation. However,
-	they still have value, and hence they are presented here.
-      </p>
-
-      <p>
-	They have not yet been checked to ensure that they are
-	compatible with the contents of policy, and if there are any
-	contradictions, the version in the main policy document takes
-	precedence.  The remaining chapters of the old Packaging
-	Manual have also not been read in detail to ensure that there
-	are not parts which have been left out.  Both of these will be
-	done in due course.
-      </p>
-
-      <p>
-	Certain parts of the Packaging manual were integrated into the
-	Policy Manual proper, and removed from the appendices. Links
-	have been placed from the old locations to the new ones.
-      </p>
-
-      <p>
-	<prgn>dpkg</prgn> is a suite of programs for creating binary
-	package files and installing and removing them on Unix
-	systems.<footnote>
-	    <prgn>dpkg</prgn> is targeted primarily at Debian, but may
-	    work on or be ported to other systems.
-	</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 (<file>.deb</file> files).  It documents the
-	behavior of the package management programs
-	<prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. 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 conjunction with those programs'
-	man pages.
-      </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 man pages.
-      </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. However,
-	while the examples are helpful, they do not replace the need to
-	read and follow the Policy and Programmer's Manual.</p>
-    </appendix>
-
-    <appendix id="pkg-binarypkg">
-      <heading>Binary packages (from old Packaging Manual)</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="pkg-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
-	<file>deb(5)</file> man page.
-      </p>
-
-
-      <sect id="pkg-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 file system data part of the package.
-	  In Debian-format source packages this directory is usually
-	  <file>debian/tmp</file>, 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 file system tree you're creating:
-	  <prgn>DEBIAN</prgn>.  It should contain the control
-	  information files, notably the binary package control file
-	  (see <ref id="pkg-controlfile">).
-	</p>
-
-	<p>
-	  The <prgn>DEBIAN</prgn> directory will not appear in the
-	  file system 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
-	  <file><var>directory</var>.deb</file>.  (<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 man page <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>
-	  To view the copyright file for a package you could use this command:
-	  <example>
-  dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - --wildcards \*/copyright | pager
-	  </example>
-	</p>
-      </sect>
-
-      <sect id="pkg-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
-	  information file 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 information 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="sourcecontrolfiles"> and
-		<ref id="binarycontrolfiles">.
-	      </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="pkg-sourcetools">.
-	      </p>
-	    </item>
-
-	    <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
-		 <tt>prerm</tt>
-	    </tag>
-	    <item>
-	      <p>
-		These are executable 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.
-		See <ref id="idempotency">.
-	      </p>
-
-	      <p>
-		The maintainer scripts are not guaranteed to run with a
-		controlling terminal and may not be able to interact with
-		the user.  See <ref id="controllingterminal">.
-	      </p>
-	    </item>
-
-	    <tag><tt>conffiles</tt>
-	    </tag>
-	    <item>
-		This file contains a list of configuration files which
-		are to be handled automatically by <prgn>dpkg</prgn>
-		(see <ref id="pkg-conffiles">).  Note that not necessarily
-		every configuration file should be listed here.
-	    </item>
-
-	    <tag><tt>shlibs</tt>
-	    </tag>
-	    <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</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">.
-	    </item>
-	  </taglist>
-	</p>
-
-      <sect id="pkg-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
-	  <file>debian/control</file> and <file>debian/changelog</file> to
-	  find the information it needs.  See <ref id="pkg-sourcepkg"> for
-	  more details.
-	</p>
-
-	<p>
-	  The fields in binary package control files are listed in
-	  <ref id="binarycontrolfiles">.
-	</p>
-
-	<p>
-	  A description of the syntax of control files and the purpose
-	  of the fields is available in <ref id="controlfields">.
-	</p>
-      </sect>
-
-      <sect>
-	<heading>Time Stamps</heading>
-
-	<p>
-	  See <ref id="timestamps">.
-	</p>
-      </sect>
-    </appendix>
-
-    <appendix id="pkg-sourcepkg">
-      <heading>Source packages (from old Packaging Manual) </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>
-
-      <sect id="pkg-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 id="pkg-dpkg-source">
-	  <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 <file><var>filename</var>.tar.gz</file> and
-	    <file><var>filename</var>.diff.gz</file> (if applicable) in
-	    the same directory.  It unpacks into
-	    <file><var>package</var>-<var>version</var></file>, and if
-	    applicable
-	    <file><var>package</var>-<var>version</var>.orig</file>, 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 <file>.dsc</file>, <file>.tar.gz</file> and
-	    <file>.diff.gz</file> (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="pkg-sourcearchives">.</p>
-	</sect1>
-
-
-	<sect1 id="pkg-dpkg-buildpackage">
-	  <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 <file>debian/rules</file>
-	    targets <tt>clean</tt>, <tt>build</tt> and
-	    <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
-	    <prgn>gpg</prgn> (or <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 sign the <tt>.changes</tt> file or the
-		  source package <tt>.dsc</tt> file, respectively.</p>
-	      </item>
-	      <tag><tt>-p<var>sign-command</var></tt></tag>
-	      <item>
-		<p>
-		  Invoke <var>sign-command</var> instead of finding
-		  <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
-		  <var>sign-command</var> must behave just like
-		  <prgn>gpg</prgn> or <tt>pgp</tt>.</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 id="pkg-dpkg-gencontrol">
-	  <heading>
-	    <prgn>dpkg-gencontrol</prgn> - generates binary package
-	    control files
-	  </heading>
-
-	  <p>
-	    This program is usually called from <file>debian/rules</file>
-	    (see <ref id="pkg-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>
-		This is so that the control file which is produced has
-		the right permissions
-	    </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 <file>debian/substvars</file>
-	    are available.
-	  </p>
-
-	  <p>
-	    For a package which generates only one binary package, and
-	    which builds it in <file>debian/tmp</file> relative to the top
-	    of the source package, it is usually sufficient to call
-	    <prgn>dpkg-gencontrol</prgn>.
-	  </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 <file>debian/files</file>, for the benefit of
-	    (for example) a future invocation of
-	    <prgn>dpkg-genchanges</prgn>.</p>
-	</sect1>
-
-	<sect1 id="pkg-dpkg-shlibdeps">
-	  <heading>
-	    <prgn>dpkg-shlibdeps</prgn> - calculates shared library
-	    dependencies
-	  </heading>
-
-	  <p>
-	    This program is usually called from <file>debian/rules</file>
-	    just before <prgn>dpkg-gencontrol</prgn> (see <ref
-	    id="pkg-sourcetree">), in the top level of the source tree.
-	  </p>
-
-	  <p>
-	    Its arguments are executables and shared libraries
-	    <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 found 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 <file>debian/substvars</file> 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, a package that generates an essential part
-	    which requires dependencies, and optional parts that 
-	    which only require a recommendation, would separate those
-	    two sets of dependencies into two different fields.<footnote>
-		At the time of writing, an example for this was the
-		<package/xmms/ package, with Depends used for the xmms
-		executable, Recommends for the plug-ins and Suggests for
-		even more optional features provided by unzip.
-	    </footnote>
-            It can say in its <file>debian/rules</file>:
-	    <example>
-  dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
-                 -dRecommends <var>optionalpart anotheroptionalpart</var>
-	    </example>
-	    and then in its main control file <file>debian/control</file>:
-	    <example>
-  <var>...</var>
-  Depends: ${shlibs: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>shlibs:</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 id="pkg-dpkg-distaddfile">
-	  <heading>
-	    <prgn>dpkg-distaddfile</prgn> - adds a file to
-	    <file>debian/files</file>
-	  </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
-	    <file>debian/files</file> file so that it will be included in
-	    the <file>.changes</file> file when
-	    <prgn>dpkg-genchanges</prgn> is run.
-	  </p>
-
-	  <p>
-	    It is usually invoked from the <tt>binary</tt> target of
-	    <file>debian/rules</file>:
-	    <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 <file>debian/rules</file> 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 <file>.changes</file> file.
-	  </p>
-	</sect1>
-
-
-	<sect1 id="pkg-dpkg-genchanges">
-	  <heading>
-	    <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
-	    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 <file>.changes</file> 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 id="pkg-dpkg-parsechangelog">
-          <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 <file>debian/rules</file> and elsewhere.  It
-	    parses a changelog, <file>debian/changelog</file> by default,
-	    and prints a control-file format representation of the
-	    information in it to standard output.
-	  </p>
-	</sect1>
-
-        <sect1 id="pkg-dpkg-architecture">
-	  <heading>
-	    <prgn>dpkg-architecture</prgn> - information about the build and
-	    host system
-          </heading>
-
-          <p>
-            This program can be used manually, but is also invoked by
-            <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
-            environment or make variables which specify the build and host
-            architecture for the package building process.
-          </p>
-        </sect1>
-      </sect>
-
-      <sect id="pkg-sourcetree">
-	<heading>The Debian package source tree</heading>
-
-	<p>
-	  The source archive scheme described later is intended to
-	  allow a Debian package source tree with some associated
-	  control information to be reproduced and transported easily.
-	  The Debian package source tree is a version of the original
-	  program with certain files added for the benefit of the
-	  packaging 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
-	  <file>debian</file> of the top level of the Debian package
-	  source tree. They are described below.
-	</p>
-
-	<sect1 id="pkg-debianrules">
-	  <heading><file>debian/rules</file> - the main building script</heading>
-
-	  <p>
-	    See <ref id="debianrules">.
-	  </p>
-	</sect1>
-
-	<sect1 id="pkg-srcsubstvars">
-	  <heading><file>debian/substvars</file> and variable substitutions</heading>
-
-	  <p>
-	    See <ref id="substvars">.
-	  </p>
-
-	</sect1>
-
-	<sect1>
-	  <heading><file>debian/files</file></heading>
-
-	  <p>
-	    See <ref id="debianfiles">.
-	  </p>
-	</sect1>
-
-	<sect1><heading><file>debian/tmp</file>
-	  </heading>
-
-	  <p>
-	    This is the canonical temporary location for the
-	    construction of binary packages by the <tt>binary</tt>
-	    target.  The directory <file>tmp</file> serves as the root of
-	    the file system 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="pkg-bincreating">.
-	  </p>
-
-	  <p>
-	    If several binary packages are generated from the same
-	    source tree it is usual to use several
-	    <file>debian/tmp<var>something</var></file> directories, for
-	    example <file>tmp-a</file> or <file>tmp-doc</file>.
-	  </p>
-
-	  <p>
-	    Whatever <file>tmp</file> directories are created and used by
-	    <tt>binary</tt> must of course be removed by the
-	    <tt>clean</tt> target.</p></sect1>
-      </sect>
-
-
-      <sect id="pkg-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>
-		This file is a control file used by <prgn>dpkg-source</prgn>
-		to extract a source package.
-		See <ref id="debiansourcecontrolfiles">.
-	    </item>
-
-	    <tag>
-	      Original source archive -
-	      <file>
-		<var>package</var>_<var>upstream-version</var>.orig.tar.gz
-	      </file>
-	    </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.
-	      </p>
-	    </item>
-
-	    <tag>
-	      Debian package diff -
-	      <file>
-		<var>package</var>_<var>upstream_version-revision</var>.diff.gz
-	      </file>
-	    </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
-		<file>debian</file> 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 <file>debian/rules</file> file
-		executable (see below).</p></item>
-	  </taglist>
-	</p>
-
-	<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
-	  <file><var>package</var>_<var>version</var>.tar.gz</file>,
-	  and preferably contains a directory named
-	  <file><var>package</var>-<var>version</var></file>.
-	</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 <file>.orig</file>
-	      directory.</p>
-	  </item>
-	  <item>
-	    <p>Rename the <file>.orig</file> directory to
-	      <file><var>package</var>-<var>version</var></file>.</p>
-	  </item>
-	    <item>
-	    <p>
-	      Create the subdirectory <file>debian</file> 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 Debian 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
-	  <file>.diff.gz</file> 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>
-		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>
-
-	  <p>
-	    The source packaging tools manage the changes between the
-	    original and Debian source using <prgn>diff</prgn> and
-	    <prgn>patch</prgn>.  Turning the original source tree as
-	    included in the <file>.orig.tar.gz</file> into the Debian
-	    package 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 <file>debian</file>.</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>
-		      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>
-		</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
-		  <file>debian/rules</file>) and directories.</p></item>
-	    </list>
-	  </p>
-
-	  <p>
-	    The <file>debian</file> directory and <file>debian/rules</file>
-	    are handled specially by <prgn>dpkg-source</prgn> - before
-	    applying the changes it will create the <file>debian</file>
-	    directory, and afterwards it will make
-	    <file>debian/rules</file> world-executable.
-	  </p>
-	</sect1>
-      </sect>
-    </appendix>
-
-    <appendix id="pkg-controlfields">
-      <heading>Control files and their fields (from old Packaging Manual)</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 <file>.changes</file>
-	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>
-	  See <ref id="controlsyntax">.
-	</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.
-	</p>
-      </sect>
-
-      <sect>
-	<heading>List of fields</heading>
-
-	<p>
-	  See <ref id="controlfieldslist">.
-	</p>
-
-	<p>
-	  This section now contains only the fields that didn't belong
-	  to the Policy manual.
-	</p>
-
-	<sect1 id="pkg-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="pkg-f-Size">
-	  <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
-
-	  <p>
-	    These fields in <file>Packages</file> 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="pkg-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
-	    re-installation) 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="pkg-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="pkg-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 recognized 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>
-		  The Debian revision part of the package version was
-		  at one point in a separate control field.  This
-		  field went through several names.
-	      </item>
-
-	      <tag><tt>Recommended</tt></tag>
-	      <item>Old name for <tt>Recommends</tt>.</item>
-
-	      <tag><tt>Optional</tt></tag>
-	      <item>Old name for <tt>Suggests</tt>.</item>
-
-	      <tag><tt>Class</tt></tag>
-	      <item>Old name for <tt>Priority</tt>.</item>
-
-	    </taglist>
-	  </p>
-	</sect1>
-      </sect>
-
-    </appendix>
-
-    <appendix id="pkg-conffiles">
-      <heading>Configuration file handling (from old Packaging Manual)</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 information 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 - i.e.,
-	  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
-	  file system.
-	</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 <file>/usr/sbin</file>, by convention called
-	  <file><var>package</var>config</file> 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>
-    </appendix>
-
-    <appendix id="pkg-alternatives"><heading>Alternative versions of
-	an interface - <prgn>update-alternatives</prgn> (from old
-    Packaging Manual)
-      </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 man page <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>
-    </appendix>
-
-    <appendix id="pkg-diversions"><heading>Diversions - overriding a
-    package's version of a file (from old Packaging Manual)
-      </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="pkg-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 <file>/usr/sbin/smail</file>:
-	<example>
-   dpkg-divert --package smailwrapper --add --rename \
-      --divert /usr/sbin/smail.real /usr/sbin/smail
-	</example> The <tt>--package smailwrapper</tt> ensures that
-	<prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
-	can bypass the diversion and get installed as the true version.
-	It's safe to add the diversion unconditionally on upgrades since
-	it will be left unchanged if it already exists, but
-	<prgn>dpkg-divert</prgn> will display a message.  To suppress that
-	message, make the command conditional on the version from which
-	the package is being upgraded:
-	<example>
-   if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
-      dpkg-divert --package smailwrapper --add --rename \
-         --divert /usr/sbin/smail.real /usr/sbin/smail
-   fi
-	</example> where <tt>1.0-2</tt> is the version at which the
-	diversion was first added to the package.  Running the command
-	during abort-upgrade is pointless but harmless.
-      </p>
-
-      <p>
-	The postrm has to do the reverse:
-	<example>
-  if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
-     dpkg-divert --package smailwrapper --remove --rename \
-        --divert /usr/sbin/smail.real /usr/sbin/smail
-  fi
-	</example> If the diversion was added at a particular version, the
-	postrm should also handle the failure case of upgrading from an
-	older version (unless the older version is so old that direct
-	upgrades are no longer supported):
-	<example>
-  if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then
-     dpkg-divert --package smailwrapper --remove --rename \
-        --divert /usr/sbin/smail.real /usr/sbin/smail
-  fi
-	</example> where <tt>1.02-2</tt> is the version at which the
-	diversion was first added to the package.  The postrm should not
-	remove the diversion on upgrades both because there's no reason to
-	remove the diversion only to immediately re-add it and since the
-	postrm of the old package is run after unpacking so the removal of
-	the diversion will fail.
-      </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>
-    </appendix>
-
   </book>
 </debiandoc>
 <!-- Local variables: -->
-- 
1.5.6.5

