dpkg (1.3.3) experimental; urgency=low

  * Programmers' & policy manuals in source tree; HTML in /usr/doc/dpkg.
  * Old guidelines.info and text files in /usr/doc/dpkg removed.

  * dpkg-source sets permissions on extracted debianised source tree
    and does not copy ownerships out of archive even if running as root.

  * Emacs mode `dpkg changelog' renamed to `Debian changelog'.
  * Default changelog format renamed from `dpkg' to `debian'.

  * debian-changelog-mode sets fill-prefix correctly.
  * debian-changelog-mode urgencies except HIGH lowercase by default.
  * debian-changelog-mode displays keymap in doc string and so mode help.

  * More maintainers' PGP keys.

  * Remove built changelog parsers with `clean' target in source.

 -- Ian Jackson <ian@chiark.chu.cam.ac.uk>  Sat, 10 Aug 1996 23:35:51 +0100

19 files changed, 4231 insertions, 1487 deletions

diff --git a/doc/Makefile.in b/doc/Makefile.in
index 3c0afeb95..a64b312a7 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -35,15 +35,22 @@ INSTALL_DATA = @INSTALL_DATA@
 MAKEINFO = makeinfo
 TEXI2DVI = texi2dvi
 
-DPKGDOCS= auto-deconfiguration.txt dependency-ordering.txt \
- disappear-replace.txt diversions.text \
- essential-flag.txt version-ordering.txt developer-keys.pgp
+DPKGDOCS= developer-keys.pgp
+
+SGMLDOCS= programmer policy
 
-# Files folded into main guidelines document
+# Files folded into manuals
 OBSOLETEDOCS= descriptions.txt upgrades+errors.txt \
- maintainer-script-args.txt virtual-dependencies.txt
+ maintainer-script-args.txt virtual-dependencies.txt \
+ auto-deconfiguration.txt dependency-ordering.txt \
+ disappear-replace.txt diversions.text \
+ essential-flag.txt version-ordering.txt
+
+all:		$(DPKGDOCS) $(SGMLDOCS)
 
-all:		$(DPKGDOCS) guidelines.info
+$(SGMLDOCS):
+		debiandoc2html $@.sgml
+		touch $@
 
 guidelines.info: guidelines.texi
 		$(MAKEINFO) $(srcdir)/guidelines.texi
@@ -57,16 +64,12 @@ database-structure.monops: database-structure.ps
  bind def$$:/$$1 {} bind def:' database-structure.ps >ps
 		mv ps database-structure.monops
 
-#dpkg.dvi:
-#		$(TEXI2DVI) $(srcdir)/dpkg.texi
-#
-#dpkg.info:
-#		$(MAKEINFO) $(srcdir)/dpkg.texi
-
 clean:
+		rm -f $(SGMLDOCS)
 		rm -f database-structure.ps database-structure.monops ps
 		rm -f *.{aux,cp,dvi,fn,ky,log,pg,toc,tp,vr,bak}
-		rm -f guidelines.info*
+		rm -f guidelines.info* *.sasp*
+		rm -rf {programmer,policy}.html
 
 distclean:
 		rm -f Makefile *.orig *~ *.~* ./#*#
@@ -75,8 +78,9 @@ install:	all
 		$(INSTALL_DATA) deb.5 $(man5dir)/deb.$(man5)
 		$(INSTALL_DATA) deb-old.5 $(man5dir)/deb-old.$(man5)
 		$(INSTALL_DATA) deb-control.5 $(man5dir)/deb-control.$(man5)
-		$(INSTALL_DATA) guidelines.info guidelines.info-*[0-9] \
-			$(infodir)/.
+		set -e; for f in $(SGMLDOCS) ; do \
+			cp -r $$f.html $(dpkgdocdir)/$$f.html ; \
+		done
 		set -e; for d in $(DPKGDOCS) ; do \
 			$(INSTALL_DATA) $$d $(dpkgdocdir)/$$d ; \
 		done
diff --git a/doc/developer-keys.pgp b/doc/developer-keys.pgp
index e3073bbc6..3877423a6 100644
--- a/doc/developer-keys.pgp
+++ b/doc/developer-keys.pgp
diff --git a/doc/junk b/doc/junk
deleted file mode 100644
index 46c358738..000000000
--- a/doc/junk
+++ /dev/null
@@ -1,29 +0,0 @@
-
-@table @file
-@item virtual-package-names-list.text
-The list of virtual package names currently in use, together with the
-procedure for getting new virtual package names allocated.
-@item (obsolete) README.etc-skel
-A description of @file{/etc/skel} and @file{/usr/doc/examples}
-(@pxref{Skeleton and examples}).
-@item (obsolete) descriptions.txt
-The description of the package. How to write an extended and more useful
-description field (@pxref{Package description}).
-@item (obsolete) README.init
-How to use the features of Init under Debian GNU/Linux in packages
-(@pxref{Configuration of init}).
-@item (obsolete) mailers.txt
-How to properly configure packages to use the Debian GNU/Linux mail
-nnsystem (@pxref{Mail processing packages}).
-@item (obsolete) maintainer-script-args.txt
-All the ways that the package maintainer scripts inside a package can be
-called by dpkg (@pxref{Maintainer script arguments}).
-@item (obsolete) dpkg-upgrades+errors.txt
-What order things happen in during a package upgrade (@pxref{What
-happends during a package upgrade?}).
-@item (obsolete) virtual-dependencies.txt
-How to use ``virtual dependencies'' in packages (@pxref{Virtual
-dependencies}).
-@item (obsolete) dependency-ordering.txt
-How to properly order package names in the @file{DEPENDS} field.
-@end table
diff --git a/doc/auto-deconfiguration.txt b/doc/obsolete/auto-deconfiguration.txt
index 5cc0ef55b..5cc0ef55b 100644
--- a/doc/auto-deconfiguration.txt
+++ b/doc/obsolete/auto-deconfiguration.txt
diff --git a/doc/dependency-ordering.txt b/doc/obsolete/dependency-ordering.txt
index f3f679408..f3f679408 100644
--- a/doc/dependency-ordering.txt
+++ b/doc/obsolete/dependency-ordering.txt
diff --git a/doc/descriptions.txt b/doc/obsolete/descriptions.txt
index fdc302b1a..fdc302b1a 100644
--- a/doc/descriptions.txt
+++ b/doc/obsolete/descriptions.txt
diff --git a/doc/disappear-replace.txt b/doc/obsolete/disappear-replace.txt
index 8335a0ea4..8335a0ea4 100644
--- a/doc/disappear-replace.txt
+++ b/doc/obsolete/disappear-replace.txt
diff --git a/doc/diversions.text b/doc/obsolete/diversions.text
index ade33af5f..ade33af5f 100644
--- a/doc/diversions.text
+++ b/doc/obsolete/diversions.text
diff --git a/doc/dpkg.texi b/doc/obsolete/dpkg.texi
index b9530d6a5..b9530d6a5 100644
--- a/doc/dpkg.texi
+++ b/doc/obsolete/dpkg.texi
diff --git a/doc/dselect-methods.txt b/doc/obsolete/dselect-methods.txt
index d90e73058..d90e73058 100644
--- a/doc/dselect-methods.txt
+++ b/doc/obsolete/dselect-methods.txt
diff --git a/doc/essential-flag.txt b/doc/obsolete/essential-flag.txt
index 34e821135..34e821135 100644
--- a/doc/essential-flag.txt
+++ b/doc/obsolete/essential-flag.txt
diff --git a/doc/guidelines.texi b/doc/obsolete/guidelines.texi
index f537b81b1..f537b81b1 100644
--- a/doc/guidelines.texi
+++ b/doc/obsolete/guidelines.texi
diff --git a/doc/maintainer-script-args.txt b/doc/obsolete/maintainer-script-args.txt
index a1cd3c75c..a1cd3c75c 100644
--- a/doc/maintainer-script-args.txt
+++ b/doc/obsolete/maintainer-script-args.txt
diff --git a/doc/upgrades+errors.txt b/doc/obsolete/upgrades+errors.txt
index 09b5bd5ee..09b5bd5ee 100644
--- a/doc/upgrades+errors.txt
+++ b/doc/obsolete/upgrades+errors.txt
diff --git a/doc/version-ordering.txt b/doc/obsolete/version-ordering.txt
index 7bbda6304..7bbda6304 100644
--- a/doc/version-ordering.txt
+++ b/doc/obsolete/version-ordering.txt
diff --git a/doc/virtual-dependencies.txt b/doc/obsolete/virtual-dependencies.txt
index 1f45eb7a0..1f45eb7a0 100644
--- a/doc/virtual-dependencies.txt
+++ b/doc/obsolete/virtual-dependencies.txt
diff --git a/doc/policy.sgml b/doc/policy.sgml
new file mode 100644
index 000000000..e15c9394e
--- /dev/null
+++ b/doc/policy.sgml
@@ -0,0 +1,1222 @@
+<!doctype debiandoc system>
+
+<!--
+ Debian Linux package policy manual.
+ Copyright (C)1996 Ian Jackson; released under the terms of the GNU
+ General Public License, version 2 or (at your option) any later.
+ -->
+
+<book>
+
+<title>Debian policy manual
+<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
+<version>version 0.1, <date>
+
+<abstract>
+This manual describes the policy requirements which must be satisfied
+for a package to be included in the Debian distribution.  This
+includes details of the permissions and ownerships of files in
+packages and other technical requirements as well as information like
+the upload procedure.
+</abstract>
+
+<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>
+
+You should have received a copy of the GNU General Public License with
+your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or
+with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>.  If
+not, write to the Free Software Foundation, Inc., 675 Mass Ave,
+Cambridge, MA 02139, USA.
+
+<toc sect>
+
+<chapt id="scope">Introduction and scope of this manual
+<p>
+
+This manual describes the criteria that a Debian-format package must
+satisfy to be included in the Debian distribution.
+<p>
+
+Much of this information will be useful even when building a package
+which is to be distributed in some other way or is for local use.
+<p>
+
+This manual does <em/not/ describe the technical mechanisms involved
+in package creation, installation and removal.  This information can
+be found in the <prgn/dpkg/ programmers' manual and the <prgn/dpkg/ system
+administrators' manual.
+<p>
+
+This document assumes familiarity with these other two manuals.
+<p>
+
+The Debian version of the FSF's GNU <prgn/hello/ program is provided
+as an example for people wishing to create Debian packages.
+<p>
+
+<em>Note that this document is still a draft!</em>
+
+<chapt id="pkgcopyright">Package copyright
+<p>
+
+Please study the copyright of your submission <em/carefully/ and
+understand it before proceeding.  If you have doubts or questions,
+please ask.
+<p>
+
+All packages in the Debian distribution proper must be freely useable,
+modifiable and redistributable in both source and binary form.  It
+must be possible for anyone to distribute and use modified source code
+and their own own compiled binaries, at least when they do so as part
+of a Debian distribution.
+<p>
+
+Packages whose copyright permission notices (or patent problems) do
+not allow distribution and copying for profit, without restriction on
+the amount charged, or where distribution is restricted according to
+the medium used, or where the distributor must ask any kind of special
+permission of the authors, or with other onerous conditions, may only
+be placed in the semi-supported non-free section of the Debian FTP
+archives.  This is important so that CDROM manufacturers can
+distribute Debian without having to check the copyright of each
+package individually, simply by leaving out the contents of the
+non-free area; CDROM distributors are encouraged, though, to check the
+copyrights on programs in non-free individually and include as many as
+they can.
+<p>
+
+Packages whose copyright permission notices (or patent problems) allow
+only distribution of compiled binaries (and thus of which only
+binaries are available), or where the source code which may be
+distributed is not the complete source code required to compile the
+program (ie, the program cannot be compiled using only packages in the
+main Debian distribution), or which depend for their use on non-free
+or contrib packages, or allow free use only for a trial period
+(shareware), or are demonstration programs lacking vital functionality
+(crippleware), or are only installer-packages which require the user
+to supply a separate file to be installed, or which fail to meet some
+other policy requirements, may only be placed in the semi-supported
+contrib section of the Debian FTP archives (unless they need to be in
+non-free - see above).
+<p>
+
+Programs whose authors encourage the user to make donations are fine
+for the main distribution, provided that the authors do not claim that
+not donating is immoral, unethical, illegal or something similar;
+otherwise they must go in contrib (or non-free, if even distribution
+is restricted by such statements).
+<p>
+
+Packages whose copyright permission notices (or patent problems) do
+not allow redistribution even of only binaries, and where no special
+permission has been obtained, cannot placed on the Debian FTP site and
+its mirrors at all.
+<p>
+
+Note that under international copyright law<footnote>This applies in
+the United States, too.</footnote> <em/no/ distribution or modification
+of a work is allowed without an explicit notice saying so.  Therefore
+a program without a copyright notice <em/is/ copyrighted and you may
+not do anything to it without risking being sued!  Likewise if a
+program has a copyright notice but no statement saying what is
+permitted then nothing is permitted.
+<p>
+
+Many authors are unaware of the problems that restrictive copyrights
+(or lack of copyright notices) can cause for the users of their
+supposedly-free software.  It is often worthwhile contacting such
+authors diplomatically to ask them to modify their terms generally, or
+specially for Debian.  However, this is a politically difficult thing
+to do and you should ask for advice on <prgn/debian-devel/ first.
+<p>
+
+When in doubt, send mail to <email/debian-devel@lists.debian.org/.  Be
+prepared to provide us with the copyright statement.  Software covered
+by the GPL, public domain software and BSD-like copyrights are safe;
+be wary of the phrases `commercial use prohibited' and `distribution
+restricted'.
+<p>
+
+Every package submission <em/must/ be accompanied by verbatim copy of
+its copyright (with the exceptions of public domain packages and those
+covered by the UCB BSD licence or the GNU GPL or LGPL; in these cases
+simply indicate which is appropriate).  This information must be
+included in a file installed by the binary package - see <ref
+id="copyrightfile">.
+
+<chapt id="binarypkg">Contents of the binary package
+
+<sect>Control file requirements
+
+<sect1><tt/Maintainer/ information
+<p>
+
+All packages must have a <tt/Maintainer/ field with the correct name
+and a working email address for the Debian maintainer of the package.
+If one person maintains several packages they should try to avoid
+having different forms of their name and address in different
+<tt/Maintainer/ fields.
+
+<sect1>Dependencies and virtual packages
+<p>
+
+Add a dependency for any shared libraries required by
+dynamically-linked executable binaries in your package.  Almost every
+package containing compiled C code should therefore include a
+<tt/Depends/ field which mentions the shared C library required for
+the program to run.  For ELF binaries linked against <tt/libc.so.5/
+the relevant package name is <tt/libc5/.
+<p>
+
+All packages must use virtual package names where appropriate, and
+arrange to create new ones if necessary.  They must not use virtual
+package names (except privately, amongst a cooperating group of
+packages) unless they have been agreed upon and appear in the list of
+virtual package names.
+<p>
+
+The latest version of the authoritative list of virtual package names
+can be found on <ftpsite>ftp.debian.org</> in
+<ftppath>/debian/doc/package-developer/virtual-package-names-list.text</>
+or your local mirror.  The procedure for updating it is described at
+the top of the file.
+
+<sect1><tt/Section/ and <tt/Priority/
+<p>
+
+Decide whether your package can go in <tt/non-free/, <tt/contrib/ or
+the main distribution - see <ref id="pkgcopyright">, and put
+an appropriate value for the distribution in the
+<tt>debian/changelog</> file.
+<p>
+
+The <tt/Priority/ and <tt/Section/ control file fields give
+information for classifying the package in <prgn/dselect/ and say
+which directory to place it in the FTP archive.
+<p>
+
+They are ultimately the responsibility of the distribution
+maintainers; however, you should suggest values for them in your
+<tt/.changes/ information when you upload a package.  You do this by
+including appropriate information in the <tt>debian/control</tt> file
+before building the packages.
+<p>
+
+For a list of the currently in-use sections, please see the FTP
+archive.  Packages in the non-free and contrib areas should have
+section <tt/non-free/ and <tt/contrib/, respectively.
+
+<sect2><tt/Priority/ values
+<p>
+
+<taglist>
+<tag><tt/required/
+<item>
+<tt/required/ packages are necessary for the proper functioning of the
+system.  You must not remove these packages or your system may become
+totally broken and you may probably not even be able to use
+<prgn/dpkg/ to put things back.  Systems with only the <tt/required/
+packages are probably unuseable, but they do have enough functionality
+to allow the sysadmin to boot and install more software.
+
+<tag><tt/important/
+<item>
+Important programs, including those which one would expect to find on
+any Unix-like system.  If the expectation is that an experienced Unix
+person who found it missing would go `What the F*!@&lt;+ is going on,
+where is <prgn/foo/', it should be in <tt/important/.  This is an
+important criterion because we are trying to produce, amongst other
+things, a free Unix.  Other packages without which the system will not
+run well or be useable should also be here.  This does <em/not/
+include Emacs or X11 or TeX or any other large applications.  The
+<tt/important/ packages are just a bare minimum of commonly-expected
+and necessary tools.
+
+<tag><tt/standard/
+<item>
+These packages provide a reasonably small but not too limited
+character-mode system.  This is what will install by default if the
+user doesn't select anything else.  It doesn't include many large
+applications, but it does include Emacs (this is more of a piece of
+infrastructure than an application) and a reasonable subset of TeX and
+LaTeX (if this is possible without X).
+
+<tag><tt/optional/<footnote>In a sense everything is optional that
+isn't required, but that's not what is meant here.</footnote>
+<item>
+This is all the software that you might reasonably want to install if
+you didn't know what it was or don't have specialised requirements.
+This is a much larger system and includes X11, a full TeX
+distribution, and lots of applications.
+
+<tag><tt/extra/
+<item>
+This contains packages that conflict with others with higher
+priorities, or are only likely to be useful if you already know what
+they are or have specialised requirements.
+
+</taglist>
+<p>
+
+Priority values are not case-sensitive.
+
+<sect2>Base packages
+<p>
+
+Some packages have <tt/Section: base/ and are in the <tt/base/
+subdirectory on the FTP archives.  These are the packages that are
+supplied on the base disks.  They are the minimum sensible set for
+installing new packages (perhaps via a network).
+<p>
+
+Most of these packages should have <tt/Priority: required/ or at least
+<tt/Priority: important/.
+
+<sect1>The <tt/Essential/ flag
+<p>
+
+The <tt/Essential: yes/ control file field should not be used unless
+removing a package really will completely hose the system; nor should
+it be used for a shared library package - the dependencies will
+prevent its premature removal, and we need to be able to remove it
+when it has been superseded.
+
+<sect1>Including <tt/Priority/ and <tt/Section/ in the <tt/.deb/
+control file
+<p>
+
+If a user installs a package which is not part of the standard
+distribution, or without downloading and updating from a new
+<prgn/Packages/ file, the information about the priority and section
+of a package will be absent, and the <prgn/dselect/ package listing
+will have the package listed under `unclassified'.  In order to
+improve this it is permissible to use the <tt/-is/, <tt/-isp/ or
+<tt/-ip/ option to <prgn/dpkg-gencontrol/, so that the <tt/Section/
+and/or <tt/Priority/ is copied into the actual control information in
+the <tt/.deb/ file.  However, if you do this you should make sure you
+keep the information up to date so that users are not shown
+conflicting information.
+
+
+<sect1>Formatting of the <tt/Description/ control file field
+<p>
+
+Every Debian package should have an extended description.
+<p>
+
+The description should be written so that it tells the user what they
+need to know to decide whether to install the package.  This
+description should not just be copied from the blurb for the program.
+Instructions for configuring or using the package should not be
+included - that is what installation scripts, manpages, Info files and
+<tt>/usr/doc/<var/package/</> are for.  Copyright statements and other
+administrivia should not be included - that is what
+<tt>/usr/doc/copyright</> is for.
+<p>
+
+If you wish to include a list in your extended with entries which are
+a line or more each you must indent each entry by one space to make
+sure that it doesn't get wordwrapped.  The start of each list entry
+should be marked with an asterisk, followed by a single space.  You
+must wrap the list entries yourself to 75 columns, and should start
+continuation lines indented by three spaces so that they line up with
+the start of the text on the first line of each list entry.
+<p>
+
+See the programmers' manual for further requirements and pitfalls.
+
+<sect>Locations of files
+<p>
+
+The location of all installed files and directories must comply fully
+with the Linux File System Standard (FSSTND).  The latest version of
+this document can be found alongside this manual or on
+<ftpsite/tsx-11.mit.edu/ in
+<ftppath>/pub/linux/docs/linux-standards/fsstnd/</>.  Specific questions
+about following the standard may be asked on <prgn/debian-devel/, or
+referred to Daniel Quinlan, the FSSTND coordinator, at
+<email/quinlan@yggdrasil.com/.
+<p>
+
+<sect1>Manpages
+<p>
+
+You must install manpages in <prgn/nroff/ source form, in appropriate
+places under <tt>/usr/man</tt>.  You should only use sections 1 to 9
+(see the FSSTND for more details).  You must <em/not/ install a
+preformatted `cat page'.
+<p>
+
+If no manual page is available for a particular program, utility or
+function and this is reported as a bug on debian-bugs, a symbolic link
+from the requested manual page to the <manref name=undocumented
+section=7> manual page should be provided.  This symbolic link can be
+created from <tt>debian/rules</> like this:
+<example>
+ln -s ../man7/undocumented.7 \
+ debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]
+</example>
+This manpage claims that the lack of a manpage has been reported as a
+bug, so you may only do this if it really has (you can report it
+yourself, if you like).  Do not close the bug report until a proper
+manpage is available.
+<p>
+
+You may forward a complaint about a missing manpage to the upstream
+authors, and mark the bug as forwarded in the Debian bug tracking
+system.  Even though the GNU Project do not in general consider the
+lack of a manpage to be a bug, we do - if they tell you that they
+don't consider it a bug you should leave the bug in our bug tracking
+system open anyway.
+<p>
+
+Manpages should be installed uncompressed.
+<p>
+
+If one manpage needs to be accesssible via several names it is better
+to use a symbolic link than the <tt/.so/ feature, but there is no need
+to fiddle with the relevant parts of the upstream source to change
+from <tt/.so/ to symlinks - don't do it unless it's easy.  Do not
+create hard links in the manual page directories, and do not put
+absolute filenames in <tt/.so/ directives.  The filename in a
+<tt/.so/ in a manpage should be relative to the base of the manpage
+tree (usually <tt>/usr/man</tt>).
+
+<sect1>Info documents
+<p>
+
+Info documents should be installed in <tt>/usr/info</tt>.  They should
+be compressed with <tt/gzip -9/.
+<p>
+
+Your package must call <prgn/install-info/ to update the Info <tt/dir/
+file, in its post-installation script:
+<example>
+install-info --quiet --section Development Development \
+  /usr/info/foobar.info
+</example>
+<p>
+
+It is a good idea to specify a section for the location of your
+program; this is done with the <tt/--section/ switch.  To determine
+which section to use, you should use look at <tt>/usr/info/dir</> on
+your system and choose the most relevant (or create a new section if
+none of the current sections are relevant).  Note that the
+<tt/--section/ flag takes two arguments; the first is a regular
+expression to match (case-insensitively) against an existing section,
+the second is used when creating a new one.
+<p>
+
+You must remove the entries in the pre-removal script:
+<example>
+install-info --quiet --remove /usr/info/foobar.info
+</example>
+<p>
+
+If <prgn/install-info/ cannot find a description entry in the Info file
+you will have to supply one.  See <manref name=install-info section=8>
+for details.
+
+<sect1>Additional documentation
+<p>
+
+Any additional documentation that comes with the package can be
+installed at the discretion of the package maintainer.  Text
+documentation should be installed in a directory
+<tt>/usr/doc/<var/package/</tt><footnote>Where <var/package/ is the
+name of the package.</footnote> and compressed with <tt/gzip -9/
+unless it is small.
+<p>
+
+If a package comes with large amounts of documentation which many
+users of the package will not require you should create a separate
+binary package to contain it, so that it does not take up disk space
+on the machines of users who do not need or want it installed.
+<p>
+
+It is often a good idea to put text information files that come with
+the source package in <tt>/usr/doc/<var/package/</> in the binary
+package.  However, don't install the instructions for building and
+installing the package, of course!
+
+<sect1>Preferred documentation formats
+<p>
+
+The unification of Debian documentation is being carried out via HTML.
+<p>
+
+If your package comes with extensive documentation in a markup format
+that can be converted to various other formats you should if possible
+ship HTML versions in the binary package, in the directory
+<tt>/usr/doc/<var/package/</> or its subdirectories.
+<p>
+
+Other formats such as PostScript may be provided at your option.
+
+<sect2>Examples
+<p>
+
+Any examples (configurations, source files, whatever), should be
+installed in a directory <tt>/usr/doc/<var/package//examples</tt>.
+These files should not be referenced by any program - they're there
+for the benefit of the system administrator and users, as
+documentation only.
+
+<sect1 id="copyrightfile"><tt>/usr/doc/copyright/<var/package/</tt>
+<p>
+
+This file must contain details of the authorship and copyright of the
+package.  It must say where the upstream sources (if any) were
+obtained, and explain briefly what modifications were made in the
+Debian version of the package compared to the upstream one.  It must
+name the original authors of the package and the Debian maintainer(s)
+who were involved with its creation.
+<p>
+
+It must contain the full text of the copyright notice and any
+acknowledgements for the program and the licence terms under which the
+program is distributed.  If the package is distributed under the GNU
+General Public Licence, the GNU Library General Public Licence, the
+Regents of the University of California at Berkeley (BSD) licence or
+Larry Wall's Artistic Licence please say so instead of including a
+copy of the licence.  The files <tt/BSD/, <tt/GPL/, <tt/LGPL/ and
+<tt/Artistic/ are be available in <tt>/usr/doc/copyright</tt> for you
+to refer to.  The package's copyright file should not be compressed.
+<p>
+
+Do not use the copyright file as a general <tt/README/ file.  If your
+package has such a file it should be installed in
+<tt>/usr/doc/<var/package//README</> or <tt/README.Debian/ or some
+other appropriate place.  Do not make links between
+<tt>/usr/doc/<var/package/</> and the <tt/copyright/ directory.
+
+<sect1>Symbolic links
+<p>
+
+Most symbolic links should be relative, not absolute.  Absolute links,
+in general, cause problems when a file system is not mounted where it
+"normally" resides (for example, when mounted via NFS).
+<p>
+
+In particular, symlinks from one part of <tt>/usr</tt> to another
+should be relative.
+<p>
+
+In certain cases, however, relative links may cause more problems.
+For example, links into <tt>/etc</tt> and <tt>/var</tt> should be
+absolute.
+<p>
+
+Note that when creating a relative link using <prgn/ln/ it is not
+necessary for the target of the link to exist relative to the working
+directory you're running <prgn/ln/ from; nor is it necessary to change
+directory to the directory where the link is to be made.  Simply
+include the string that should appear as the target of the link (this
+will be a pathname relative to the directory in which the link
+resides) as the first argument to <prgn/ln/.
+<p>
+
+For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things
+like:
+<example>
+ln -fs gcc $(prefix)/bin/cc
+ln -fs gcc debian/tmp/usr/bin/cc
+ln -fs ../sbin/sendmail $(prefix)/bin/runq
+ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+</example>
+
+<sect1>Logfiles
+<p>
+
+Logfiles should usually be named
+<tt>/var/log/<var/package/.log</tt>.  If you have many logfiles,
+or need a separate directory for permissions reasons
+(<tt>/var/log</tt> is writeable only by <tt/root/), you should usually
+create a directory named <tt>/var/log/<var/package/</tt>.
+<p>
+
+Make sure that any logfiles are rotated occasionally using so that
+they don't grow indefinitely; the best way to do this is to use
+<prgn/savelog/ program in an <tt>/etc/cron.daily</>,
+<tt>/etc/cron.weekly</> or <tt>/etc/cron.monthly</> script.
+<p>
+
+Make sure that any logfiles are removed when the package is purged
+(but not when it is only removed), by checking the argument to the
+postrm script (see the programmer's manual for details).
+
+<sect1><tt>/usr/local</> - for the use of the system administrator
+<p>
+
+As mandated by the FSSTND no package should place any files in
+<tt>/usr/local</>, either by putting them in the filesystem archive to
+be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer
+scripts.
+<p>
+
+Every package that searches a number of directories or files for
+something (for example, looking for shared libraries in <tt>/lib</> or
+<tt>/usr/lib</>) should search an appropriate directory in
+<tt>/usr/local</> too.
+<p>
+
+In order that the system administrator may know where to place
+additional files a package should create an empty directory in the
+appropriate place in <tt>/usr/local</> by supplying it in the
+filesystem archive for unpacking by <prgn/dpkg/.  The
+<tt>/usr/local</> directory itself and all the subdirectories created
+by the package should have permissions 2775 (group-writeable and
+set-group-id) and be owned by <tt/root.staff/.
+<p>
+
+In the future it will be possible to tell <prgn/dpkg/ not to unpack
+files matching certain patterns, so that system administrators who do
+not wish these directories in <tt>/usr/local</> do not need to have
+them.
+
+<sect>Permissions and ownerships
+<p>
+
+The rules in this section are guidelines for general use.  If
+necessary you may deviate from the details below.  However, if you do
+so you must make sure that what is done is secure and you must try to
+be as consistent as possible with the rest of the system.  You should
+probably also discuss it on <prgn/debian-devel/ first.
+<p>
+
+Files should be owned by <tt/root.root/, and made writeable only by
+the owner and universally readable (and executable, if appropriate).
+<p>
+
+Directories should be mode 755 or (for group-writability) mode 2775.
+The ownership of the directory should be consistent with its mode -
+if a directory is mode 2775, it should be owned by the group that
+needs write access to it.
+<p>
+
+Setuid and setgid executables should be mode 4755 or 2755
+respectively, and owned by the appropriate user or group.  They should
+not be made unreadable (modes like 4711 or 2711 or even 4111); doing
+so achieves no extra security, because anyone can find the binary in
+the freely available Debian package - it is merely inconvenient.  For
+the same reason you should not restrict read or execute permissions on
+non-set-id executables.
+<p>
+
+Some setuid programs need to be restricted to particular sets of
+users, using file permissions.  In this case they should be owned by
+the uid to which they are set-id, and by the group which should be
+allowed to execute them.  They should have mode 4754; there is no
+point in making them unreadable to those users who must not be allowed
+to execute them.
+<p>
+
+Do not arrange that the system administrator can only reconfigure the
+package to correspond to their local security policy by changing the
+permissions on a binary.  Ordinary files installed by <prgn/dpkg/ (as
+opposed to conffiles and other similar objects) have their permissions
+reset to the distributed permissions when the package is reinstalled.
+Instead you should consider (for example) creating a group for people
+allowed to use the program(s) and making any setuid executables
+executable only by that group.
+<p>
+
+Shared libraries should be installed executable.
+
+<sect>Configuration files
+<p>
+
+Any configuration files created or used by your package should reside
+in <tt>/etc</tt>.  If there are several you should consider creating a
+subdirectory named after your package.
+<p>
+
+It is almost certain that any file in <tt>/etc</tt> that is in your
+package's filesystem archive should be listed in <prgn/dpkg/'s
+<tt/conffiles/ control area file.  (See the <prgn/dpkg/ programmers'
+manual).
+
+<sect>Maintainer scripts
+<p>
+
+The package installation scripts should avoid producing output which
+it is unnecessary for the user to see and should rely on <prgn/dpkg/ to
+stave off boredom on the part of a user installing many packages.
+This means, amongst other things, using the <tt/--quiet/ option on
+<prgn/install-info/.
+<p>
+
+Packages should try to minimise the amount of prompting they need to
+do, and they should ensure that the user will only every be asked each
+question once.  This means that packages should try to use appropriate
+shared configuration files (such as <tt>/etc/papersize</> and
+<tt>/etc/news/server</>, rather than each prompting for their own
+list of required pieces of information.
+<p>
+
+It also means that an upgrade should not ask the same questions again,
+unless the user has used <tt/dpkg --purge/ to remove the package's
+configuration.  The answers to configuration questions should be
+stored in an appropriate place in <tt>/etc</> so that the user can
+modify them, and how this has been done should be documented.
+<p>
+
+If a package has a vitally important piece of information to pass to
+the user (such as "don't run me as I am, you must edit the following
+configuration files first or you risk your system emitting
+badly-formatted messages"), it should display this in the
+<prgn/postinst/ script and prompt the user to hit return to
+acknowledge the message.  Copyright messages do not count as vitally
+important (they belong in <tt>/usr/doc/copyright</>); neither do
+instructions on how to use a program (these should be in on line
+documentation, where all the users can see them).
+<p>
+
+Any necessary prompting should almost always be confined to the
+post-installation script, and should be protected with a conditional
+so that unnecssary prompting doesn't happen if a package's
+installation fails and the <prgn/postinst/ is called with
+<tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/.
+<p>
+
+Errors which occur during the execution of an installation script
+<em/must/ be checked and the installation <em/must not/ continue after
+an error.
+<p>
+
+The section below on scripts in general applies to package maintainer
+scripts too.
+
+<sect>Scripts in general
+<p>
+
+All command scripts, including the package maintainer scripts inside
+the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming
+the shell to be used to interpret them.
+<p>
+
+In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>.
+<p>
+
+Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly
+start with <tt>set -e</> so that errors are detected.  Every script
+<em/must/ use <tt/set -e/ or check the exit status of <em/every/
+command.
+<p>
+
+Perl scripts should check for errors when making any system calls,
+including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and
+<tt/system/.
+<p>
+
+<prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages.  See
+Csh Programming Considered Harmful, one of the <tt/comp.unix.*/ FAQs.
+If an upstream package comes with <prgn/csh/ scripts then you must make
+sure that they start with <tt>#!/bin/csh</tt> and make your package
+depend on <prgn/csh/.
+<p>
+
+<sect>Compilation options
+<p>
+
+Generally the following compilation parameters should be used:
+<example>
+CC = gcc
+CFLAGS = -O2 -g -Wall # sane warning options vary between programs
+LDFLAGS = # none
+install -s # (or use strip on the files in debian/tmp)
+</example>
+<p>
+
+Note that all installed binaries should be stripped, either by using
+the <tt/-s/ flag to <prgn/install/, or by calling <prgn/strip/ on the
+binaries after they have been copied into <tt>debian/tmp</> but
+before the tree is made into a package.
+<p>
+
+Make sure that you do not link with <tt/-g/, as this makes a.out
+compilers produce huge statically linked binaries.  The <tt/-g/ flag
+is useful on compilation so that you have available a full set of
+debugging symbols in your built source tree, in case anyone should
+file a bug report involving (for example) a core dump.
+<p>
+
+The <tt/-N/ flag should not be used.  On a.out systems it may have
+been useful for some very small binaries, but for ELF it has no good
+effect.
+<p>
+
+It is up to the package maintainer to decide what compilation options
+are best for the package.  Certain binaries (such as
+computationally-intensive programs) may function better with certain
+flags (<tt/-O3/, for example); feel free to use them.  Please use good
+judgment here.  Don't use flags for the sake of it; only use them if
+there is good reason to do so.  Feel free to override the upstream
+author's ideas about which compilation options are best - they are
+often inappropriate for our environment.
+<p>
+
+Please make sure that you use only released versions of shared
+libraries to build your packages; otherwise other users will not be
+able to run your binaries properly.  Producing source packages that
+depend on unreleased compilers is also usually a bad idea.
+
+<sect>Shared library packages
+<p>
+
+Packages involving shared libraries should be split up into several
+binary packages.
+<p>
+
+For a straightforward library which has a development environment and
+a runtime kit including just shared libraries you need to create two
+packages: <tt/<var/libraryname/<var/soname//<footnote><var/soname/ is
+the shared object name of the shared library - it's the thing that has
+to match exactly between building an executable and running it for the
+dynamic linker to be able run the program.  Usually the <var/soname/
+is the major number of the library.</footnote> and
+<tt/<var/libraryname/<var/soname/-dev/.
+<p>
+
+If you prefer only to support one development version time you may
+name the development package <tt/<var/libraryname/-dev/; otherwise you
+may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that the
+user only installs one development version at a time (after all,
+different development versions are likely to have the same header
+files in them, causing a filename clash if both are installed).
+Typically the development version will also need an exact version
+dependency on the runtime library, to make sure that compilation and
+linking happens correctly.
+<p>
+
+Packages which use the shared library should have a dependency on the
+name of the shared library package,
+<tt/<var/libraryname/<var/soname//.  When the <var/soname/ changes you
+can have both versions of the library installed while moving from the
+old library to the new.
+<p>
+
+If your package has some run-time support programs which use the
+shared library you must <em/not/ put them in the shared library
+package.  If you do that then you won't be able to install several
+versions of the shared library without getting filename clashes.
+Instead, either create a third package for the runtime binaries (this
+package might typically be named <tt/<var/libraryname/-runtime/ - note
+the absence of the <var/soname/ in the package name) or if the
+development package is small include them in there.
+<p>
+
+If you have several shared libraries built from the same source tree
+you can lump them all togther into a single shared library package,
+provided that you change all their <var/soname/s at once (so that you
+don't get filename clashes if you try to install different versions of
+the combined shared libraries package).
+<p>
+
+Follow the directions in the <prgn/dpkg/ programmers' manual for
+putting the shared library in its package.
+
+<sect>Application configuration files, dotfiles and <tt>/etc/skel</>
+<p>
+
+Files in <tt>/etc/skel</> will automatically be copied into new user
+accounts by <prgn/adduser/.  They should not be referenced there by
+any program.
+<p>
+
+Therefore, if a program needs a dotfile to exist in advance in
+<tt/$HOME/ to work sensibly that dotfile should be installed in
+<tt>/etc/skel</> (and listed in conffiles, if it is not generated and
+modified dynamically by the package's installation scripts).
+<p>
+
+However, programs that require dotfiles in order to operate sensibly
+(dotfiles that they do not create themselves automatically, that is)
+are a bad thing, and programs should be configured by the Debian
+default installation as close to normal as possible.
+<p>
+
+Therefore, if a program in a Debian package needs to be configured in
+some way in order to operate sensibly that configuration should be
+done in a site-wide global configuration file elsewhere in
+<tt>/etc</>.  Only if the program doesn't support a site-wide default
+configuration and the package maintainer doesn't have time to add it
+should a default per-user file be placed in <tt>/etc/skel</>.
+<p>
+
+<tt>/etc/skel</> should be as empty as we can make it.  This is
+particularly true because there is no easy mechanism for ensuring that
+the appropriate dotfiles are copied into the accounts of existing
+users when a package is installed.
+<p>
+
+Ideally the sysadmin should ideally not have to do any configuration
+other than that done (semi-)automatically by the postinst script.
+
+<sect id="mail">Mail processing on Debian systems
+<p>
+
+Debian packages which process electronic mail, whether
+mail-user-agents (MUAs) or mail-transport-agents (MTAs), <em/must/
+make sure that they are compatible with the configuration decisions
+below.  Failure to do this may result in lost mail, broken <tt/From:/
+lines, and other serious brain damage!
+<p>
+
+The mail spool is <tt>/var/spool/mail</> and the interface to send a
+mail message is <tt>/usr/sbin/sendmail</> (as per the FSSTND).  The
+mail spool is part of the base system and not part of the MTA package.
+<p>
+
+Mailboxes are locked using the <tt/<var/username/.lock/ lockfile
+convention, rather than <prgn/fcntl/, <prgn/flock/ or <prgn/lockf/.
+<p>
+
+Mailboxes are generally 660 <tt/<var/user/.mail/ unless the user has
+chosen otherwise.  A MUA may remove a mailbox (unless it has
+nonstandard permissions) in which case the MTA or another MUA must
+recreate it if needed.  Mailboxes must be writeable by group mail.
+<p>
+
+The mail spool is 2775 <tt/mail.mail/, and MUA's need to be setgid
+mail to do the locking mentioned above (and obviously need to avoid
+accessing other users' mailboxes using this privilege).
+<p>
+
+<tt>/etc/aliases</> is the source file for the system mail aliases
+(e.g.  postmaster, usenet, etc.) - it is the one which the sysadmin
+and postinst scripts may edit.  After <tt>/etc/aliases</> is edited
+the program or human editing it must call <prgn/newaliases/.  All MTA
+packages should come with a <prgn/newaliases/ program, even if it does
+nothing, but older MTA packages do not do this so programs should not
+fail if <prgn/newaliases/ cannot be found.
+<p>
+
+The convention of writing <tt/forward to <var/address// in the mailbox
+itself is not supported.  Use a <tt/.forward/ file instead.
+<p>
+
+The location for the <prgn/rmail/ program used by UUCP for incoming
+mail is <tt>/usr/sbin/rmail</>, as per the FSSTND.  Likewise,
+<prgn/rsmtp/, for receiving batch-SMTP-over-UUCP, is in
+<tt>/usr/sbin/rsmtp</> if it is supported.
+<p>
+
+Smail is not using HoneyDanBer UUCP, whose <prgn/uux/ apparently
+accepts <tt/-a/ and <tt/-g/ options.
+<p>
+
+If you need to know what name to use (for example) on outgoing news
+and mail messages which are generated locally, you should use the file
+<tt>/etc/mailname</>.  It will contain the portion after the username
+and <tt/@/ (at) sign for email addresses of users on the machine
+(followed by a newline).
+<p>
+
+A package should check for the existence of this file.  If it exists
+it should use it without comment.<footnote>An MTA's prompting
+configuration script may wish to prompt the user even if it finds this
+file exists.</footnote> If it does not exist it should prompt the user
+for the value and store it in <tt>/etc/mailname</> as well as using it
+in the package's configuration.  The prompt should make it clear that
+the name will not just be used by that package.  E.g., in this
+situation the INN package says:
+<example>
+Please enter the `mail name' of your system.  This is the hostname
+portion of the address to be shown on outgoing news and mail messages.
+The default is <var/syshostname/, your system's host name.
+Mail name [`<var/syshostname/']:
+</example>
+where <var/syshostname/ is the output of <tt/hostname -fqdn/.
+
+
+<sect>Packages which can use the X shared libraries
+<p>
+
+Some programs can be configured with or without support for X Windows.
+Typically these binaries produced when configured for X will need the
+X shared libraries to run.
+<p>
+
+Such programs should be configured <em/with/ X support, and should
+declare a dependency on <tt/elf-x11r6lib/ (for the X11R6 libraries).
+Users who wish to use the program can install just the relatively
+small <tt/xlib/ package, and do not need to install the whole of X.
+<p>
+
+Do not create two versions (one with X support and one without) of
+your package.
+
+
+<sect>Games
+<p>
+
+The permissions on /var/lib/games are 755 <tt/root.root/.
+<p>
+
+Each game decides on its own security policy.
+<p>
+
+Games which require protected, privileged access to high-score files,
+savegames, &amp;c, must be made set-<em/group/-id (mode 2755) and
+owned by <tt/root.games/, and use files and directories with
+appropriate permissions (770 <tt/root.games/, for example).  They must
+<em/not/ be made set-<em/user/-id, as this causes security
+problems.<footnote>If an attacker can subvert any set-user-id game
+they can overwrite the executable of any other, causing other players
+of these cames to run a trojan.  With a set-group-id game the attacker
+only gets access to less important game data, and if they can get at
+the other players' accounts at all it will take considerably more
+effort.</footnote>
+<p>
+
+Some packages, for example some fortune cookie programs, are
+configured by the upstream authors to install with their data files or
+other static information made unreadable so that they can only be
+accessed through set-id programs provided.  Do not do this in a Debian
+package: anyone can download the <tt/.deb/ file and read the data from
+it, so there is no point making the files unreadable.  Not making the
+files unreadable also means that you don't have to make so many
+programs set-id, which reduces the risk of a security hole.
+
+<sect>Allocating package-specific users and groups
+<p>
+
+If you need to create a new user or group for your package there are
+two possibilities.  Firstly, you may need to make some files in the
+binary package be owned by this user or group, or you may need to
+compile the user or group id (rather than just the name) into the
+binary (though this latter should be avoided if possible).  In this
+case you need a statically allocated id.
+<p>
+
+You must ask for a user or group id from the base system maintainer,
+and must not release the package until you have been allocated one.
+Once you have been allocated one you must make the package depend
+on a version of the base system with the id present in
+<tt>/etc/passwd</tt> or <tt>/etc/group</tt>, or alternatively arrange
+for your package to create the user or group itself with the correct
+id (using <tt/adduser/) in its pre- or post-installation script (the
+latter is to be preferred if it is possible).
+<p>
+
+On the other hand, the program may able to determine the uid or gid
+from the group name at runtime, so that a dynamic id can be used.  In
+this case you must choose an appropriate user or group name,
+discussing this on <prgn/debian-devel/ and checking with the base system
+maintainer that it is unique and that they do not wish you to use a
+statically allocated id instead.  When this has been checked you must
+arrange for your package to create the user or group if necessary
+using <prgn/adduser/ in the pre- or post-installation script (again, the
+latter is to be preferred if it is possible).
+<p>
+
+Note that changing the numeric value of an id associated with a name
+is very difficult, and involves searching the filesystem for all
+appropriate files.  You need to think carefully whether a static or
+dynamic id is required, since changing your mind later will cause
+problems.
+
+<chapt id="sourcepkg">Source package
+
+<sect>Documentation and the <tt/changelog/
+<p>
+
+Document your changes and updates to the source package properly in
+the <tt>debian/changelog</tt> file.
+<p>
+
+A copy of the file which will be installed in
+<tt>/usr/doc/copyright/<var/package/</tt> should be in
+<tt>debian/copyright</tt>.
+<p>
+
+In non-experimental packages you may only use a format for
+<tt>debian/changelog</> which is supported by the most recent released
+version of <prgn/dpkg/.  If your format is not supported and there is
+general support for it you should contact the <prgn/dpkg/ maintainer
+to have the parser script for your format included in the <prgn/dpkg/
+package.<footnote>You will need to agree that the parser and its
+manpage may be distributed under the GNU GPL, just as the rest of
+<prgn/dpkg/ is.</footnote>
+
+<sect>Changes to the upstream sources
+<p>
+
+If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/
+scripts are used, you should edit the <tt/.in/ files rather than
+editing the <prgn/Makefile/ directly.  This allows the user to
+reconfigure the package if necessary.  You should <em/not/ configure
+the package and edit the generated <prgn/Makefile/!  This makes it
+impossible for someone else to later reconfigure the package.
+<p>
+
+If changes to the source code are made that are generally applicable
+please try to get them included in the upstream version of the package
+by supplying the upstream authors with the changes in whatever form
+they prefer.
+<p>
+
+If you need to configure the package differently for Debian or for
+Linux, and the upstream source doesn't provide a way to configure it
+the way you need to, please add such configuration facilities (for
+example, a new <prgn/autoconf/ test or <tt/#define/) and send the
+patch to the upstream authors, with the default set to the way they
+originally had it.  You can then easily override the default in your
+<tt>debian/rules</tt> or wherever is appropriate.
+
+<sect>Error trapping in makefiles
+<p>
+
+When <prgn/make/ invokes a command in a makefile (including your
+package's upstream makefiles and the <tt>debian/rules</>) it does so
+using <tt/sh/.  This means that <tt/sh/'s usual bad error handling
+properties apply: if you include a miniature script as one of the
+commands in your makefile you'll find that if you don't do anything
+about it then errors are not detected and <prgn/make/ will blithely
+continue after problems.
+<p>
+
+Every time you put more than one shell command (this includes using a
+loop) in a makefile command you <em/must/ make sure that errors are
+trapped.  For simple compound commands, such as changing directory and
+then running a program, using <tt/&amp;&amp;/ rather than semicolon as
+a command separator is sufficient.  For more complex commands
+including most loops and conditionals you must include a separate
+<tt/set -e/ command at the start of every makefile command that's
+actually one of these miniature shellscripts.
+
+<sect>Permissions
+<p>
+
+All the files in the source package should be world-readable and
+user-writeable.  Directories and executable programs should be
+world-exectuable.  None of the files should be world-writeable.  The
+files may or may not be group-writeable, and directories may or may
+not be setgid.  Pipes should not be world-readable and should be
+either both group readable and writeable or neither (and they should
+not be executable).
+<p>
+
+In summary: data files may be <tt/664/, <tt/644/.  Executable files
+may be <tt/775/ or <tt/755/.  Directories may be <tt/775/, <tt/755/,
+<tt/2775/ or <tt/2755/.  Pipes may be <tt/660/ or <tt/600/.
+
+<chapt id="developer">How to become a Debian developer
+
+<sect>Before you start work
+<p>
+
+So, you've read all the documentation, you understand what everything
+in the <prgn/hello/ example package is for, and you're about to
+Debianise your favourite package.  How do you actually become a Debian
+developer so that your work can be incorporated into the Project?
+<p>
+
+Firstly, subscribe to <prgn/debian-devel/ if you haven't already.
+Send the word <tt/subscribe/ in the <em/Subject/ of a mail to
+<email/debian-devel-REQUEST@lists.debian.org/.  In case of problems
+contact the list administrator, Anders Chrigstrom <email/ac@netg.se/.
+<p>
+
+You should to subscribe and lurk for a bit before doing any coding,
+and you should post about your intentions to work on something to
+avoid duplicated effort.
+<p>
+
+If you do not have a PGP key yet generate one.  You should probably
+read the PGP manual, as it has much important information which is
+critical to its security.  Many more security failures are due to
+human error than to software failure or high-powered spy techniques.
+
+<sect>When you have a package to upload
+<p>
+
+When you have your package ready to be uploaded you must send a
+message to the project leader, Bruce Perens <email/bruce@pixar.com/,
+the administrator of <tt/master.debian.org/, Simon Shapiro
+<email/shimon@i-connect.net/, the mailing list administrator, Anders
+Chrigstrom <email/ac@netg.se/ and the <prgn/dpkg/ maintainer, Ian
+Jackson <email/ijackson@gnu.ai.mit.edu/.
+<p>
+
+The message should say what you've done and who you are, and should
+ask for an account on <prgn/master/ and to be subscribed to
+<prgn/debian-private/ (the developers-only mailing list).  It should
+contain your PGP key (extracted using <tt/pgp -kxa/) for the database
+of keys which is shipped with <prgn/dpkg/.
+
+When you have your personal account on <prgn/master/ log in and
+transfer the files to
+<tt>/home/Debian/ftp/private/project/Incoming</>.  You cannot upload
+to <prgn/Incoming/ on <prgn/master/ using anonymous FTP.
+<p>
+
+You can also upload files to <prgn/Incoming/ via a <prgn/cron/-driven
+upload queue in Europe on <ftpsite/chiark.chu.cam.ac.uk/.  For details
+connect to <prgn/chiark/ using anonymous FTP and read
+<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
+
+<sect id="changesfiles">Upload handling - <tt/.changes/ files
+<p>
+
+When a package is uploaded to the Debian FTP archive, it must be
+accompanied by a <tt/.changes/ file which gives directions for its
+handling.  This is usually generated by <prgn/dpkg-genchanges/.
+<p>
+
+This file is a control file with the following fields:
+<list compact>
+<item><tt/Format/
+<item><tt/Date/
+<item><tt/Source/
+<item><tt/Binary/
+<item><tt/Architecture/
+<item><tt/Version/
+<item><tt/Distribution/
+<item><tt/Urgency/
+<item><tt/Maintainer/
+<item><tt/Description/
+<item><tt/Changes/
+<item><tt/Files/
+</list>
+<p>
+
+All of them are mandatory for a Debian upload.  See the list of
+control fields in the <prgn/dpkg/ programmers' manual for the contents
+of these fields.
+
+
+<chapt id="mailinglists">The Debian mailing lists
+<p>
+
+The mailing list server is at <tt/lists.debian.org/.  Mail
+<tt/debian-<var/foo/-REQUEST@lists.debian.org/<footnote>where
+<tt/debian-<var/foo// is the name of the list</footnote> with the word
+<tt/subscribe/ in the Subject to subscribe or <tt/unsubscribe/ to
+unsubscribe.
+<p>
+
+When replying to messages on the mailing list, please do not send a
+carbon copy (<tt/CC/ - this does not mean `courtesy copy') to the
+original poster.  Anyone who posts to a mailing list should read it to
+see the responses.
+<p>
+
+As ever on the net, please trim down the quoting of articles you're
+replying to.
+
+</book>
diff --git a/doc/programmer.sgml b/doc/programmer.sgml
new file mode 100644
index 000000000..6360d245c
--- /dev/null
+++ b/doc/programmer.sgml
@@ -0,0 +1,2990 @@
+<!doctype debiandoc system>
+
+<!--
+ Debian Linux dpkg package installation tool.
+ programmers' manual.
+ Copyright (C)1996 Ian Jackson; released under the terms of the GNU
+ General Public License, version 2 or (at your option) any later.
+ -->
+
+<book>
+
+<title><prgn/dpkg/ programmers' manual
+<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
+<version><date>
+
+<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>
+
+You should have received a copy of the GNU General Public License with
+your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or
+with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>.  If
+not, write to the Free Software Foundation, Inc., 675 Mass Ave,
+Cambridge, MA 02139, USA.
+
+<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.
+<p>
+
+The Debian version of the FSF's GNU hello program is provided as an
+example for people wishing to create Debian packages.
+<p>
+
+<em>Note that this document is still a draft!</em>
+
+<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 (currently a <prgn/tar/ archive)
+containing files and directories to be installed.
+<p>
+
+In the future binary packages may also contain other components, such
+as checksums and digital signatures.
+
+
+<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
+</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">.
+
+<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 itempotent.<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.
+
+</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/</>
+
+</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>
+
+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.  See <manref name=dpkg-source section=1>
+for details.
+
+<sect>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//
+<item>
+
+This target should be all that is necessary for the user to build the
+binary package.  It 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 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>
+
+<ref id="binarypkg"> describes how to construct binary packages.
+<p>
+
+The <prgn/binary/ target 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//
+<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:
+<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.  <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; 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:
+<example>
+\schangelog-format:\s+([0-9a-z]+)\W
+</example>
+The part in parentheses should be the name of the format.
+<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 file may be a static part of the source archive, or generated and
+modified dynamically by <tt>debian/rules</> targets.  In the latter
+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/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 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>
+</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-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 (optionally) 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 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/-/.
+
+
+<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 <tt/stable/, <tt/unstable/,
+<tt/contrib/, <tt/non-free/ and <tt/experimental/.
+
+<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.
+
+
+<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.
+
+
+<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>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>
+
+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>
+
+<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/
+</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>
+<example>
+<var/prerm/ remove
+</example>
+
+<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
+ 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>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>
+
+<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>
+
+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 symlink must be placed before the library it
+points to in the <tt/.deb/ file.  Currently the way to ensure the
+ordering is done properly is to create the symlink in the appropriate
+<tt>debian/tmp/.../lib</tt> directory before installing the library
+when you build the package.
+<p>
+
+If you do the above your package does not need to call <prgn/ldconfig/
+in its maintainer scripts.  It is especially important not to call
+<prgn/ldconfig/ in the postrm or preinst scripts in the case where the
+package is being upgraded (see the programmer's manual), 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!
+
+
+
+<chapt id="sysvinit">Configuration of <prgn/init/
+<p>
+
+<sect>Introduction to the <tt/init.d/ scheme
+<p>
+
+The <tt>/etc/init.d</> directory contains the scripts executed by
+<prgn/init/ when init state (or `runlevel') is changed (see <manref
+name=init section=8>).
+<p>
+
+These scripts are be referenced by symbolic links in the
+<tt>/etc/rc<var/n/.d</> directories.  When changing runlevels, init
+looks in the directory <tt>/etc/rc<var/n/.d</> for the scripts it
+should execute, where <var/n/ is the runlevel that is being changed
+to.
+<p>
+
+The names of the links all have the form <tt/S<var/mm/<var/script// or
+<tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and
+<var/script/ is the name of the script (this should be the same as the
+name of the actual script in <tt>/etc/init.d</>.
+
+When <prgn/init/ changes runlevel first the targets of the links whose
+names starting with a <tt/K/ are executed, each with the single
+argument <tt/stop/, followed by the scripts prefixed with an <tt/S/,
+each with the single argument <tt/start/.  The <tt/K/ links are
+responsible for killing services and the <tt/S/ link for starting
+services upon entering the runlevel.
+<p>
+
+For example, if we are changing from runlevel 2 to runlevel 3, init
+will first execute all of the <tt/K/ prefixed scripts it finds in
+<tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts.  The
+links starting with <tt/K/ will cause the referred-to file to be
+executed with an argument of <tt/stop/, and the <tt/S/ links with an
+argument of <tt/start/.
+<p>
+
+The two-digit number <var/mm/ is used to decide which order to start
+and stop things in - low-numbered links have their scripts run first.
+For example, the <tt/K20/ scripts will be executed before the <tt/K30/
+scripts.  This is used when a certain service must be started before
+another.  For example, the name server <prgn/bind/ might need to be
+started before the news server <prgn/inn/ so that <prgn/inn/ can set
+up its access lists.  In this case, the script that starts <prgn/bind/
+should have a lower number than the script that starts <prgn/inn/ so
+that it runs first:
+<example>
+/etc/rc2.d/S17bind
+/etc/rc2.d/S70inn
+</example>
+
+<sect>Writing <tt/init.d/ scripts
+<p>
+
+Packages can and should place scripts in <tt>/etc/init.d</> to start
+or stop services at boot time or during a change of runlevel.  These
+scripts should be named <tt>/etc/init.d/<var/package/</>, and they
+should accept one argument, saying what to do: <tt/start/, meaning to
+starts the service, or <tt/stop/, to stop the service.  Optionally
+they can support <tt/reload/ which causes the configuration to be
+reloaded.
+<p>
+
+The <tt/init.d/ scripts should ensure that they will behave sensibly
+if invoked with <tt/start/ when the service is already running, or
+with <tt/stop/ when it isn't, and that they don't kill
+unfortunately-named user processes.  The best way to achieve this is
+usually to use <prgn/start-stop-daemon/.
+<p>
+
+These scripts should not fail obscurely when the configuration files
+remain but the package has been removed, as the default in <prgn/dpkg/
+is to leave configuration files on the system after the package has
+been removed.  Only when it is executed with the <tt/--purge/ option
+will dpkg remove configuration files.  Therefore, you should include a
+<tt/test/ statement at the top of the script, like this:
+<example>
+test -f <var/program-executed-later-in-script/ || exit 0
+</example>
+
+<sect>Managing the <tt/rc<var/n/.d/ links - <prgn/update-rc.d/
+<p>
+
+A program is provided, <prgn/update-rc.d/, to make it easier for
+package maintainers to arrange for the proper creation and removal of
+<tt>/etc/rc<var/n/.d</> symbolic links from their postinst and postrm
+scripts.
+<p>
+
+You should use this script to make changes to <tt>/etc/rc<var/n/.d</>
+and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in
+the actual archive.
+<p>
+
+By default <prgn/update-rc.d/ will start services in each of the
+multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt
+runlevel (0), the single-user runlevel (1) and the reboot runlevel
+(6).  The system administrator will have the opportunity to customize
+runlevels by simply adding, moving, or removing the symbolic links in
+<tt>/etc/rc<var/n/.d</>.
+<p>
+
+To get the default behaviour for your package, put in your postinst
+script
+<example>
+update-rc.d <var/package/ default &gt;/dev/null
+</example>
+and in your postrm
+<example>
+if [ purge = "$1" ]; then
+    update-rc.d <var/package/ remove &gt;/dev/null
+fi
+</example>
+<p>
+
+This will use a default sequence number of 20.  If it does not matter
+when or in which order the script is run, use this default.  If it
+does, then you should talk to the maintainer of the <prgn/sysvinit/
+package or post to <tt>debian-devel</>, and they will help you choose
+a number.
+<p>
+
+For more information about using <tt/update-rc.d/, please consult its
+manpage <manref name=update-rc.d section=8>.
+
+<sect>Boot-time initialisation - <tt/rc.boot/
+<p>
+
+There is another directory, <tt>/etc/rc.boot</>, which contains
+scripts which are run once per machine boot.  This facility is
+provided for initialisation of hardware devices, cleaning up of
+leftover files, and so forth.
+<p>
+
+For example, the <prgn/kbd/ package provides a script here for
+initialising the keyboard layout and console font and mode.
+<p>
+
+The files in <tt>/etc/rc.boot</> should <em/not/ be links into
+<tt>/etc/init.d</> - they should be the scripts themselves.
+<p>
+
+<tt/rc.boot/ should <em/not/ be used for starting general-purpose
+daemons and similar activities.  This should be done using the
+<tt/rc<var/n/.d/ scheme, above, so that the services can be started
+and stopped cleanly when the runlevel changes or the machine is to be
+shut down or rebooted.
+
+<sect>Notes
+<p>
+
+<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
+the <tt/.deb/ filesystem archive!  <em/This will cause problems!/
+You should create them with <prgn/update-rc.d/, as above.
+<p>
+
+<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
+<prgn/dpkg/'s conffiles list!  <em/This will cause problems!/
+<em/Do/, however, include the <tt>/etc/init.d</> scripts in conffiles.
+
+<sect>Example
+<p>
+
+The <prgn/bind/ DNS (nameserver) package wants to make sure that the
+nameserver is running in multiuser runlevels, and is properly shut
+down with the system.  It puts a script in <tt>/etc/init.d</>, naming
+the script appropriately <tt/bind/.  As you can see, the script
+interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/
+signal (causing it to reload its configuration); this way the user can
+say <tt>/etc/init.d/bind reload</> to reload the nameserver.
+<p>
+
+<example>
+#!/bin/sh
+# Original version by Robert Leslie &lt;rob@mars.org&gt;, edited by iwj
+test -x /usr/sbin/named || exit 0
+case "$1" in
+  start)
+    test -f /etc/named.boot -a -f /var/named/boot.options || exit 0
+    start-stop-daemon --start --verbose --exec /usr/sbin/named
+    ;;
+  stop)
+    start-stop-daemon --stop --verbose  \
+        --pidfile /var/run/named.pid --exec /usr/sbin/named
+    ;;
+  reload)
+    start-stop-daemon --stop --signal 1 --verbose  \
+        --pidfile /var/run/named.pid --exec /usr/sbin/named
+    ;;
+  *)
+    echo "Usage: /etc/init.d/bind {start|stop|reload}" >&2
+    exit 1
+    ;;
+esac
+exit 0
+</example>
+<p>
+
+Another example on which to base your <tt>/etc/init.d</> scripts is in
+<tt>/etc/init.d/skeleton</>.
+<p>
+
+If this package is happy with the default setup from
+<prgn/update-rc.d/, namely an ordering number of 20 and having named
+running in all runlevels, it can say in its postinst:
+<example>
+update-rc.d bind default >/dev/null
+</example>
+And in its postrm, to remove the links when the package is purged:
+<example>
+if [ purge = "$1" ]; then
+     update-rc.d acct remove >/dev/null
+fi
+</example>
+
+
+
+<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.
+
+</book>
diff --git a/doc/sgml/programmer.sgml b/doc/sgml/programmer.sgml
deleted file mode 100644
index e6f27ae9d..000000000
--- a/doc/sgml/programmer.sgml
+++ /dev/null
@@ -1,1443 +0,0 @@
-<!doctype linuxdoc system "./linuxdoc.dtd" >
-
-<!--
- Debian Linux dpkg package installation tool.
- Programmers' manual.
- Copyright (C)1996 Ian Jackson; released under the terms of the GNU
- General Public License, version 2 or (at your option) any later.
- -->
-
-<article>
-
-<title><tt/dpkg/ Programmers' manual
-<author>Ian Jackson, <tt/ijackson@gnu.ai.mit.edu/
-<date>1st June 1996
-<abstract>
-This manual describes the technical aspects of creating Debian binary
-packages.  It describes how to use utilities like <tt/install-info/.
-It also documents the interface between <tt/dselect/ and its access
-method scripts.  It does not deal with the Debian Project policy
-requirements, and it assumes familiarity with <tt/dpkg/'s functions
-from the system administrator's perspective.
-</abstract>
-
-<toc>
-
-<!-- Describes the technical interface between a package and dpkg.
-How to use
-update-rc.d, diversions, update-alternatives, install-info in a
-package.  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.
--->
-
-<sect>Scope of this manual
-<p>
-
-This manual describes the technical aspects of creating Debian binary
-packages (<tt/.deb/ files.).  It documents the behaviour of the
-package management programs <tt/dpkg/, <tt/dselect/ et al and and the
-way they interact with packages.
-<p>
-
-It documents the utility programs which are provided with <tt/dpkg/
-for managing various system configuration and similar issues (such as
-<tt/update-rc.d/ and <tt/install-info/.
-
-It also documents the interaction between <tt/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>
-
-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
-<tt/dpkg/ System Administrators' manual.
-<p>
-
-The Debian version of the FSF's GNU hello program is provided as an
-example for people wishing to create Debian packages.
-<p>
-
-<em>Note that this document is not yet complete !</em>
-
-<sect>Binary package format
-<p>
-
-<tt/dpkg/ is a suite of programs for creating binary package files and
-installing and removing them on Unix systems.<footnote><tt/dpkg/ is
-targetted primarily at Debian Linux, but may work or be ported to
-other systems.</footnote>
-<p>
-
-The binary package files' contents may be architecture-independent,
-but they usually aren't.  They aren't designed for the management of
-program source code (though examples of this are provided as part of
-some packages by way of documentation).
-<p>
-
-The binary package has two main sections: the first part consists of
-various control information files and scripts used by <tt/dpkg/ when
-installing and removing.
-<p>
-
-The second part is an archive (currently a <tt/tar/ archive)
-containing files and directories to be installed.  See <ref
-id="controlarea">.
-<p>
-
-In the future binary packages may also contain other components, such
-as checksums and digital signatures.
-<p>
-
-
-<sect1>Creating package files -- <tt/dpkg-deb/
-<p>
-
-All manipulation of binary package files is done by <tt/dpkg-deb/;
-it's the only program that has knowledge of the format.
-(<tt/dpkg-deb/ may be invoked by calling <tt/dpkg/, as <tt/dpkg/ will
-spot that the options requested are appropriate to <tt/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.
-<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 <tt/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: <tt/DEBIAN/.  It should contain the
-control information files, notably the main package control file (see
-<ref id="controlarea">).
-<p>
-
-The <tt/DEBIAN/ directory will not appear in the filesystem archive of
-the package, and so won't be installed by <tt/dpkg/ when the package
-is installed.
-<p>
-
-When you've prepared the package, you should invoke:<!--var-->
-<example>
-dpkg --build <it/directory/
-</example>
-<p>
-
-This will build the package in <var/directory/<tt/.deb/.
-(<tt/dpkg/ knows that <tt/--build/ is a <tt/dpkg-deb/ option, so it
-invokes <tt/dpkg-deb/ with the same arguments to build the package.)
-<p>
-
-See the manpage for <tt/dpkg-deb/ 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/<tt/.deb/
-dpkg-deb --contents <var/filename/<tt/.deb/
-</example>
-
-<sect1>Package control information files<label id="controlarea">
-<p>
-
-The control information portion of a binary package is a collection of
-files with names known to <tt/dpkg/.  It will treat the contents of
-these files specially - some of them contain information used by
-<tt/dpkg/ when installing or removing the package; others are scripts
-which the package maintainer wants <tt/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 <tt/dpkg/
-and a summary of what they're used for.
-
-<descrip>
-
-<tag/<tt/control//
-
-This is the key description file used by <tt/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">.
-
-<tag><tt/postinst/, <tt/preinst/, <tt/postrm/, <tt/prerm/</tag>
-
-These are exectuable files (usually scripts) which <tt/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 <tt/dpkg/.
-Details of when and how they are called are in
-<ref id="maintainerscripts">.
-
-<tag/<tt/conffiles//
-
-This file contains a list of configuration files which are to be
-handled automatically by <tt/dpkg/ (see <ref id="conffiles">).  Note
-that not necessarily every configuration file should be listed here.
-
-</descrip>
-
-<sect1>The main control information file: <tt/control/<label id="controlfile">
-<p>
-
-The most important control information file used by <tt/dpkg/ when it
-installs a package is <tt/control/.  It contains all the package's
-`vital statistics'.
-<p>
-
-It 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.  Many of the fields have a syntax where whitespace is
-not significant.
-<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>
-
-Field names are not case-sensitive, but it is usual to capitalise the
-fields as shown below (usually using a form of mixed case).
-<p>
-
-Blank lines, or lines consisting only of spaces and tabs, are not allowed.
-<p>
-
-
-Here is a list of the fields which are permitted in packages, together
-with a description of the purposes and syntax of each and or a pointer
-to further information if appropriate.
-<p>
-
-It is important to note that there are several fields which are
-optional as far as <tt/dpkg/ is concerned, but which must appear in
-every Debian package, or whose omission may cause problems.  When
-writing the control file for a Debian package you <em/must/ read the
-Debian policy manual in conjuction with the list below.
-
-<sect2>List of package control file fields
-<p>
-
-<descrip>
-
-<tag/<tt/Package//
-
-The name of the package.  Package names consist of the alphanumerics,
-plus, minus and dot.  They must be at least two characters and must
-start with an alphanumeric.  In current versions of dpkg they are sort
-of case-sensitive; use lowercase package names unless the package
-you're building (or referring to, in other fields) is already using
-uppercase.
-<p>
-
-This field is mandatory.
-
-<tag/<tt/Version//
-
-This lists the package's version number - see <ref id="versions">.
-
-This field is mandatory.
-
-<tag/<tt/Architecture//
-
-This is the architecture string; it is a single word for the CPU
-architecture, and <tt/dpkg/ will check it against its own compiled-in
-value before it installs a package.  The special value <tt/all/
-indicates that the package is architecture-independent.
-<p>
-
-The value for this field can be obtained using
-<example>
-dpkg --print-architecture
-</example>
-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 <tt/dpkg/.  This is so that it will
-work if you're cross-compiling.
-<p>
-
-There is a separate option, <tt/--print-installation-architecture/,
-for finding out what architecture <tt/dpkg/ is willing to install.
-This information is also in the output of <tt/dpkg --version/.
-<p>
-
-This field should appear in all packages, though <tt/dpkg/ doesn't
-require it yet so that old packages can still be installed.
-
-<tag/<tt/Maintainer//
-
-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 for addresses; a program using this field as an address must
-check for this and reverse the components if necessary (for example by
-putting the name in round brackets or quotes, and perhaps moving it to
-the end).
-
-This feature is optional as far as <tt/dpkg/ is concerned, but
-<tt/dpkg-deb/ will warn if it is missing.
-
-<tag><tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/, <tt/Suggests/
-<tt/Conflicts/, <tt/Provides/, <tt/Replaces/</tag>
-
-These fields describe the package's relationships with other packages.
-Their syntax and semantics are described in <ref id="depconoverwr">.
-
-<tag/<tt/Source//
-
-This field identifies the source package name, primarily for the
-benefit of humans reading the control file rather than <tt/dpkg/.  It
-consists solely of the source package name; it may be omitted when the
-source package has the same name as the binary package.
-
-This field is optional as far as <tt/dpkg/ is concerned.
-
-<tag/<tt/Description//
-
-This field contains a description of the package, in a special format.
-<p>
-
-It is very important that you read <ref id="descriptions">.
-
-<tag/<tt/Essential//
-
-This is a boolean field.  If set to <tt/yes/ then <tt/dpkg/ and
-<tt/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.
-<p>
-
-This field is optional.
-
-<tag/<tt/Priority//
-
-This specifies the `priority' of the package; this represents how
-important that it is that the user have it installed.
-<p>
-
-This value isn't used by <tt/dpkg/, but only by <tt/dselect/ when it
-sorts packages and selects defaults.  See the <tt/dpkg/ System
-Administrator's Manual for details of the values it can take, and the
-Debian Policy Manual for the criteria for selecting the priority for a
-Debian package.
-<p>
-
-<tt/dpkg/ and <tt/dselect/ will only use the value from a <tt/.deb/
-file if they have no other information; a priority value listed in a
-<tt/Packages/ file will always take precedence.  This field is
-optional as far as <tt/dpkg/ is concerned.
-
-<tag/<tt/Section//
-
-This specifies the `section' of the package, namely the application
-area or group of packages which contain it.  The value is a simple
-string, usually from a set chosen by the distribution maintainers.
-<p>
-
-The section isn't used at all except by <tt/dselect/, which only uses
-it for sorting packages in the selection display and not even for
-choosing defaults.
-<p>
-
-Just as with <tt/Priority/, this field is optional as far as <tt/dpkg/
-is concerned, and the value from a package file is used only as a last
-resort.
-
-</descrip>
-
-<sect2>List of other control fields
-<p>
-
-There are several other fields which are used elsewhere by parts of
-the system.  These should not appear in package control files.
-
-<sect3>Status fields
-<p>
-
-These fields appear in <tt/dpkg/'s internal status file; they are also
-printed by <tt/dpkg --status/ and can be seen in <tt/dselect/ by
-selecting the installed control info display.
-
-<p>
-
-<descrip>
-
-<tag/<tt/Status//
-
-This field in <tt/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.
-
-<tag/<tt/Config-Version//
-
-If a package is not installed or not configured, this field in
-<tt/dpkg/'s status file records the last version of the package which
-was successfully configured.
-
-<tag/<tt/Conffiles//
-
-This field in <tt/dpkg/'s status file contains information about the
-automatically-managed configuration files held by a package.  Let me
-emphasise that this field should <em/not/ appear in a package !
-
-</descrip>
-
-<sect4><tt/Packages/ file (available package) fields
-<p>
-
-These fields are found in <tt/Packages/ files (lists of packages
-available for installation, which are generated by the distribution
-maintainers and used principally by <tt/dselect/) and in <tt/dpkg/'s
-database of available packages (which can be inspected using
-<tt/dpkg --print-avail/ or by selecting the `available control
-information' in <tt/dselect/.
-
-<p>
-
-<descrip>
-
-<tag><tt/Filename/, <tt/MSDOS-Filename/</tag>
-
-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.
-
-<tag><tt/Size/, <tt/MD5sum/</tag>
-
-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.
-
-</descrip>
-
-<sect4>Obsolete fields
-<p>
-
-These are still recognised by <tt/dpkg/ but should not appear anywhere
-any more.
-
-<descrip>
-
-<tag><tt/Revision/, <tt/Package-Revision/, <tt/Package_Revision/</tag>
-
-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/Recommended/ Old name for <tt/Recommends/.
-<tag/Optional/ Old name for <tt/Suggests/.
-<tag/Class/ Old name for <tt/Priority/.
-
-</descrip>
-
-<sect1>Version numbering<label id="versions">
-<p>
-
-Every package has a version number, in its <tt/Version/ control file
-field.
-<p>
-
-<tt/dpkg/ imposes an ordering on version numbers, so that it can tell
-whether packages are being up- or downgraded and so that <tt/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:
-
-<descrip>
-
-<tag/<var/epoch//
-
-This is a single unsigned integer, which should usually be small.  It
-may be omitted, in which case it defaults to zero.  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>
-
-<tt/dpkg/ will not usually display the epoch unless it is essential
-(non-zero, or if the <var/upstream-version/ contains a colon);
-<tt/dselect/ does not display epochs at all in the main part of the
-package selection display.
-
-<tag/<var/upstream-version//
-
-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 <tt/dpkg/'s format and comparison scheme.
-<p>
-
-The comparison behaviour of <tt/dpkg/ with respect to the
-<var/upstream-version/ is described below.  The <var/upstream-version/
-portion of the version number is mandatory.
-
-<tag/<var/debian-revision//
-
-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 <tt/dpkg/
-compares it in the same way.
-<p>
-
-It is optional; if it isn't present then the <var/upstream-version/
-should 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 version indication is require there.
-<p>
-
-It is conventional to restart the <var/debian-revision/ at <tt/1/ each
-time the <var/upstream-version/ is increased.
-<p>
-
-<tt/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).
-
-</descrip>
-
-The <var/upstream-version/ and <var/debian-revision/ parts are
-compared by <tt/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 <tt/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.
-
-<sect1>Package maintainer scripts run by <tt/dpkg/<label id="maintainerscripts">
-<p>
-
-It is possible supply scripts as part of a package which <tt/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
-should be proper exectuable files, so that if they are scripts (which
-is to be recommended) they must start with the usual <tt/#!/
-convention.  They should be readable and executable to anyone, and not
-world-writeable.
-<p>
-
-<tt/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 <tt/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 <tt/preinst/ is called before (a particular
-version of) a package is installed, and the <tt/postinst/ afterwards;
-the <tt/prerm/ before (a version of) a package is removed and the
-<tt/postrm/ afterwards.
-<p>
-
-See <ref id="maintscripts-instact"> for details of exactly when and
-how these scripts are called and with what arguments.
-
-<sect>Declaring relationships between packages<label id="depconoverwr">
-<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>
-
-<sect1>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
-<tt/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
-<tt/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.
-
-<sect1>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.
-
-<descrip>
-<tag/<tt/Depends//
-This declares an absolute dependency.
-<p>
-
-<tt/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 <tt/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>
-
-<tt/dselect/ makes it hard for the user to select packages for
-installation, removal or upgrade in a way that would mean that
-packages' <tt/Depends/ fields would be unsatisfied.  The user can
-override this if they wish, for example if they know that <tt/dselect/
-has an out-of-date view of the real package relationships.
-
-**** WHEN TO USE -- POLICY STATEMENT HERE ?
-
-<tag/<tt/Recommends//
-This declares a strong, but not absolute, dependency.
-<p>
-
-<tt/Recommends/ is ignored by <tt/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 <tt/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.
-
-**** WHEN TO USE -- POLICY STATEMENT HERE ?
-
-<tag/<tt/Suggests//
-
-This is used to declare that one package may be more useful with one
-or more others.
-<p>
-
-<tt/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.
-
-**** WHEN TO USE -- POLICY STATEMENT HERE ?
-
-<tag/<tt/Pre-Depends//
-
-This field is like <tt/Depends/, except that it also forces <tt/dpkg/
-to complete installation of the packages named before even starting
-the installation of the package which declares the predependency.
-<p>
-
-<tt/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 <tt/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.
-
-</descrip>
-
-<sect2>Deconfiguration due to removal during bulk installations
-<p>
-
-If <tt/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, <tt/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
-<tt/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
-<tt/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>
-
-<tt/dselect/ supplies this argument to <tt/dpkg/ when it invokes it,
-so that bulk installations proceed smoothly.
-
-<sect1>Alternative packages - <tt/Conflicts/ and <tt/Replaces/<label id="conflicts">
-<p>
-
-When one package declares a conflict with another <tt/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
-<tt/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>
-
-<tt/dselect/ makes it hard to select conflicting packages, though the
-user can override this if they wish.  If they do not override it then
-<tt/dselect/ will select one of the packages for removal, and the user
-must make sure it is the right one.  In the future <tt/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.
-<p>
-
-A <tt/Conflicts/ entry should almost never have an `earlier than'
-version clause.  This would prevent <tt/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 <tt/dselect/,
-so that the use <tt/Conflicts/ in this way is likely to cause problems
-for `bulk run' upgrades and installations.
-<p>
-
-
-
-<sect1>Virtual packages - <tt/Provides/<label id="virtual">
-<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
-<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 prohibited, 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>
-
-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>
-
-<sect1>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>
-
-However, in the absence of other information <tt/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>
-
-If <tt/emacs/ and <tt/info/ both have the same priority then
-<tt/dselect/'s choice is essentially random.  Better would be
-<example>
-Package: glibcdoc
-Recommends: info | info-browser
-</example>
-so that <tt/dselect/ defaults to selecting the lightweight standalone
-info browser.
-
-<sect1><tt/Replaces/ - overwriting files and replacing packages<label id="replaces">
-<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.
-
-<sect2>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 <tt/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 <tt/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 <tt/postrm/ script will be run to
-allow the package to do any final cleanup required.
-See <ref id="maintscripts-instact">.
-<p>
-
-In the future <tt/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.
-
-<sect2>Replacing whole packages, forcing their removal
-<p>
-
-Secondly, <tt/Replaces/ allows <tt/dpkg/ and <tt/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>Order of processing steps and maintainer script arguments<label id="maintscripts-instact">
-<p>
-
-<sect1>Summary of ways maintainer scripts are called
-<p>
-
-<itemize>
-<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/
-</itemize>
-
-<itemize>
-<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/
- 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/
-</itemize>
-
-<itemize>
-<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/
-</itemize>
-
-<itemize>
-<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/
-</itemize>
-
-<sect1>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.
-
-<enum>
-<item>
-
-<enum>
-<item>
-If a version the package is already
-installed, call
-<example>
-<var/old-prerm/ <tt/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/ <tt/failed-upgrade/ <var/old-version/
-</example>
-Error unwind, for both the above cases:
-<example>
-<var/old-postinst/ <tt/abort-upgrade/ <var/new-version/
-</example>
-
-</enum>
-
-<item>
-If a `conflicting' package is being removed at the same time:
-<enum>
-
-<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/ <tt/deconfigure/
- <tt/in-favour/ <var/package-being-installed/ <var/version/
- <tt/removing/ <var/conflicting-package/ <var/version/
-</example>
-Error unwind:
-<example>
-<var/deconfigured's-postinst/ <tt/abort-deconfigure/
- <tt/in-favour/ <var/package-being-installed-but-failed/ <var/version/
- <tt/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/ <tt/remove/
- <tt/in-favour/ <var/package/ <var/new-version/
-</example>
-Error unwind:
-<example>
-<var/conflictor's-postinst/ <tt/abort-remove/
- <tt/in-favour/ <var/package/ <var/new-version/
-</example>
-
-</enum>
-
-<item>
-<enum>
-<item>
-If the package is being upgraded, call:
-<example>
-<var/new-preinst/ <tt/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/ <tt/install/ <var/old-version/
-</example>
-
-<item>
-Otherwise (ie, the package was completely purged):
-<example>
-<var/new-preinst/ <tt/install/
-</example>
-Error unwind versions, respectively:
-<example>
-<var/new-postrm/ <tt/abort-upgrade/ <var/old-version/
-<var/new-postrm/ <tt/abort-install/ <var/old-version/
-<var/new-postrm/ <tt/abort-install/
-</example>
-
-</enum>
-
-<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 will not always be
-the case.
-<p>
-
-Packages which overwrite each other's files produce behaviour which
-(though deterministic) is hard for the system administrator to
-understand and can easily lead to `missing' programs (for example, if
-a package is installed which overwrites a file from another package,
-and then it is removed again).
-
-<item>
-
-<enum>
-<item>
-If the package is being upgraded, call
-<example>
-<var/old-postrm/ <tt/upgrade/ <var/new-version/
-</example>
-
-<item>
-If this fails, <tt/dpkg/ will attempt:
-<example>
-<var/new-postrm/ <tt/failed-upgrade/ <var/old-version/
-</example>
-Error unwind, for both cases:
-<example>
-<var/old-preinst/ <tt/abort-upgrade/ <var/new-version/
-</example>
-
-</enum>
-
-This is the point of no return - if <tt/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 <tt/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,
-
-<enum>
-<item>
-<tt/dpkg/ calls:
-<example>
-<var/disappearer's-postrm/ <tt/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 <tt/dpkg/).  Note that disappearing packages do not
-have their prerm called, because <tt/dpkg/ doesn't know in advance
-that the package is going to vanish.
-
-</enum>
-
-<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).
-
-</enum>
-
-<sect1>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/ <tt/configure/ <var/most-recently-configured-version/
-</example>
-<p>
-
-No attempt is made to unwind after errors during configuration.
-<p>
-
-If there is no most recently configured version <tt/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.
-
-<sect1>Details of removal and/or configration purging
-<p>
-
-<enum>
-<item>
-<example>
-<var/prerm/ <tt/remove/
-</example>
-
-<item>
-The package's files are removed (except conffiles).
-
-<item>
-<example>
-<var/postrm/ <tt/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 <tt/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/ <tt/purge/
-</example>
-
-<item>
-The package's file list is removed.
-
-</enum>
-
-No attempt is made to unwind after errors during removal.
-
-
-<sect>Configuration file handling<label id="conffiles">
-
-<tt/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 <tt/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
-<tt/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.
-
-<sect1>Automatic handling of configuration files by <tt/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, during the configuration state shortly
-before <tt/dpkg/ runs the package's <tt/postinst/ script, it will
-process the configuration files.
-<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 <tt/dpkg/ will install
-the file that comes with it, unless that would mean overwriting a file
-already on the filesystem.
-<p>
-
-However, note that <tt/dpkg/ will <em/not/ replace a conffile file
-that was removed by the user (or by a script).  This is necessary
-because for some programs' configuration files 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 <tt/dpkg/-handled
-conffile in its maintainer scripts.  Doing this will lead to <tt/dpkg/
-asking the user confusing and possibly dangerous questions when the
-package is upgraded.
-
-<sect2>Fully-featured maintainer script configuration handling
-<p>
-
-For files which contain site-specific information such as thep
-hostname and networking details and so forth, it is better to create
-the file in the package's <tt/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 number of important issues which
-should be considered:
-<p>
-
-The package's <tt/postinst/ should be written so that 
-
-
-<sect>Dangling references
-<p>
-
-<sect1>Would dangle to conffiles<label id="conffiles">
-<p>
-
-There would be a dangling xref here.  Instead I've just put this dummy
-text in.
-
-<sect1>Would dangle to descriptions<label id="descriptions">
-<p>
-
-There would be a dangling xref here.  Instead I've just put this dummy
-text in.
-
-</article>