doc: Convert from DebianDoc SGML to DocBook XML

doc/design.dbk

@@ -0,0 +1,438 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+]>
+
+<book lang="en">
+
+<title>The APT project design document</title>
+
+<bookinfo>
+
+<authorgroup>
+  <author>
+    <personname>Manoj Srivastava</personname><email>srivasta@debian.org</email>
+  </author>
+</authorgroup>
+
+<releaseinfo>Version &apt-product-version;</releaseinfo>
+
+<abstract>
+<para>
+This document is an overview of the specifications and design goals of the APT
+project. It also attempts to give a broad description of the implementation
+as well.
+</para>
+</abstract>
+
+<copyright><year>1997</year><holder>Manoj Srivastava</holder></copyright>
+
+<legalnotice>
+<title>License Notice</title>
+<para>
+APT, including this document, is free software; you may redistribute it and/or
+modify it under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any later
+version.
+</para>
+<para>
+This is distributed in the hope that it will be useful, but <emphasis>without
+any warranty</emphasis>; without even the implied warranty of merchantability
+or fitness for a particular purpose. See the GNU General Public License for
+more details.
+</para>
+<para>
+You should have received a copy of the GNU General Public License with your
+Debian system, in <literal>/usr/share/common-licenses/GPL</literal>, or with
+the <command>debiandoc-sgml</command> source package as the file
+<literal>COPYING</literal>. If not, write to the Free Software Foundation,
+Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+<chapter id="introduction"><title>Introduction</title>
+<para>
+APT is supposed to be a replacement for dselect, and not a replacement for
+dpkg. However, since addition functionality has been required for APT, and
+given the fact that this is very closely related to dpkg, it is not
+unreasonable to expect that additional functionality in the underlying dpkg
+would also be requested.
+</para>
+<para>
+Deity/dselect are the first introduction that people have to Debian, and
+unfortunately this first impression contributes greatly to the public
+perception of the distribution. It is imperative that this be a showcase for
+Debian, rather than frighten novices away (which has been an accusation often
+levelled at the current system)
+</para>
+</chapter>
+
+<chapter id="ch2"><title>Requirements</title>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+APT should be a replacement for dselect. Therefore it should have all the
+functionality that dselect has currently. This is the primary means of
+interaction between the user and the package management system, and it should
+be able to handle all tasks involved in installing, upgrading, and routine
+management without having the users take recourse to the underlying management
+system.
+</para>
+</listitem>
+<listitem>
+<para>
+It should be easier to use and less confusing for novice users. The primary
+stimulus for the creation of APT was the perceived intractability, complexity,
+and non-intuitive behavior of the existing user interface, and as such, human
+factors must be a primary mandate of APT.
+</para>
+</listitem>
+<listitem>
+<para>
+It should be able to group packages more flexibly, and possibly allow
+operations based on a group. One should be able to select, or deselect,
+a coherent group of related packages simultaneously, allowing one to add,
+remove, or upgrade functionality to a machine as one step.
+</para>
+</listitem>
+<listitem>
+<para>
+This would allow APT to handle <emphasis>standard installations</emphasis>,
+namely, one could then install a set of packages to enable a machine to
+fulfill specific tasks. Define a few standard installations, and which
+packages are included therein. The packages should be internally consistent.
+</para>
+</listitem>
+<listitem>
+<para>
+Make use of a keywords field in package headers; provide a standard list of
+keywords for people to use. This could be the underpinning to allow the
+previous two requirements to work (though the developers are not constrained
+to implement the previous requirements using keywords)
+</para>
+</listitem>
+<listitem>
+<para>
+Use dependencies, conflicts, and reverse dependencies to properly order
+packages for installation and removal. This has been a complaint in the past
+that the installation methods do not really understand dependencies, causing
+the upgrade process to break, or allowing the removal of packages that left the
+system in an untenable state by breaking the dependencies on packages that were
+dependent on the package being removed. A special emphasis is placed on
+handling pre-dependencies correctly; the target of a predependency has to be
+fully configured before attempting to install the pre-dependent package. Also,
+<emphasis>configure immediately</emphasis> requests mentioned below should be
+handled.
+</para>
+</listitem>
+<listitem>
+<para>
+Handle replacement of a package providing a virtual package with another (for
+example, it has been very difficult replacing <command>sendmail</command> with
+<command>smail</command>, or vice versa), making sure that the dependencies are
+still satisfied.
+</para>
+</listitem>
+<listitem>
+<para>
+Handle source lists for updates from multiple sources. APT should also be able
+to handle diverse methods of acquiring new packages; local filesystem,
+mountable CD-ROM drives, FTP accessible repositories are some of the methods
+that come to mind. Also, the source lists can be separated into categories,
+such as main, contrib, non-us, non-local, non-free, my-very-own, etc. APT
+should be set up to retrieve the Packages files from these multiple source
+lists, as well as retrieving the packages themselves.
+</para>
+</listitem>
+<listitem>
+<para>
+Handle base of source and acquire all Packages files underneath. (possibly
+select based on architecture), this should be a simple extension of the
+previous requirement.
+</para>
+</listitem>
+<listitem>
+<para>
+Handle remote installation (to be implemented maybe in a future version, it
+still needs to be designed). This would ease the burden of maintaining
+multiple Debian machines on a site. In the authors opinion this is a killer
+difference for the distribution, though it may be too hard a problem to be
+implemented with the initial version of APT. However, some thought must be
+given to this to enable APT to retain hooks for future functionality, or at
+least to refrain from methods that may preclude remote activity. It is
+desirable that adding remote installation not require a redesign of APT from
+the ground up.
+</para>
+</listitem>
+<listitem>
+<para>
+Be scalable. Dselect worked a lot better with 400 packages, but at last count
+the number of packages was around twelve hundred and climbing. This also
+requires APT to pay attention to the needs of small machines which are low on
+memory (though this requirement shall diminish as we move towards bigger
+machines, it would still be nice if Debian worked on all old machines where
+Linux itself would work).
+</para>
+</listitem>
+<listitem>
+<para>
+Handle install immediately requests. Some packages, like watchdog, are
+required to be working for the stability of the machine itself. There are
+others which may be required for the correct functioning of a production
+machine, or which are mission critical applications. APT should, in these
+cases, upgrade the packages with minimal downtime; allowing these packages to
+be one of potentially hundreds of packages being upgraded concurrently may
+not satisfy the requirements of the package or the site. (Watchdog, for
+example, if not restarted quickly, may cause the machine to reboot in the
+midst of installation, which may cause havoc on the machine)
+</para>
+</listitem>
+</orderedlist>
+</chapter>
+
+<chapter id="ch3"><title>Procedural description</title>
+<variablelist>
+<varlistentry>
+<term>Set Options</term>
+<listitem>
+<para>
+This process handles setting of user or site options, and configuration of all
+aspects of APT. It allows the user to set the location and order of package
+sources, allowing them to set up source list details, like ftp site locations,
+passwords, etc. Display options may also be set.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Updates</term>
+<listitem>
+<para>
+Build a list of available packages, using source lists or a base location and
+trawling for Packages files (needs to be aware of architecture). This may
+involve finding and retrieving Packages files, storing them locally for
+efficiency, and parsing the data for later use. This would entail contacting
+various underlying access modules (ftp, cdrom mounts, etc) Use a backing store
+for speed. This may also require downloading the actual package files locally
+for speed.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Local status</term>
+<listitem>
+<para>
+Build up a list of packages already installed. This requires reading and
+writing the local??  status file. For remote installation, this should
+probably use similar mechanisms as the Packages file retrieval does. Use
+the backing store for speed. One should consider multiple backing stores,
+one for each machine.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Relationship determination</term>
+<listitem>
+<para>
+Determine forward and reverse dependencies. All known dependency fields should
+be acted upon, since it is fairly cheap to do so. Update the backing store
+with this information.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Selection</term>
+<listitem>
+<para>
+Present the data to the user. Look at Behan Webster's documentation for the
+user interface procedures. (Note: In the authors opinion deletions and reverse
+dependencies should also be presented to the user, in a strictly symmetric
+fashion; this may make it easier to prevent a package being removed that breaks
+dependencies)
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Ordering of package installations and configuration</term>
+<listitem>
+<para>
+Build a list of events. Simple topological sorting gives order of packages
+in dependency order. At certain points in this ordering,
+predependencies/immediate configure directives cause an break in normal
+ordering. We need to insert the uninstall/purge directive in the stream
+(default: as early as possible).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Action</term>
+<listitem>
+<para>
+Take the order of installations and removals and build up a stream of events
+to send to the packaging system (dpkg). Execute the list of events if
+successful. Do not partially install packages and leave system in broken
+state. Go to The Selection step as needed.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</chapter>
+
+<chapter id="ch4"><title>Modules and interfaces</title>
+<variablelist>
+<varlistentry>
+<term>The user interface module</term>
+<listitem>
+<para>
+Look at Behan Webster's documentation.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Widget set</term>
+<listitem>
+<para>
+Related closely to above Could some one present design decisions of the widget
+set here?
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>pdate Module</term>
+<listitem>
+<para>
+Distinct versions of the same package are recorded separately, but if multiple
+Packages files contain the same version of a package, then only the first one
+is recorded. For this reason, the least expensive update source should be
+listed first (local file system is better than a remote ftp site)
+</para>
+<para>
+This module should interact with the user interface module to set and change
+configuration parameters for the modules listed below. It needs to record that
+information in an on disk data file, to be read on future invocations.
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+FTP methods
+</para>
+</listitem>
+<listitem>
+<para>
+mount and file traversal module(s)?
+</para>
+</listitem>
+<listitem>
+<para>
+Other methods ???
+</para>
+</listitem>
+</orderedlist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Status file parser/generator</term>
+<listitem>
+<para>
+The status file records the current state of the system, listing the packages
+installed, etc. The status file is also one method of communicating with dpkg,
+since it is perfectly permissible for the user to use APT to request packages
+be updated, put others on hold, mark other for removal, etc, and then run
+<literal>dpkg -BORGiE</literal> on a file system.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Package file parser/generator</term>
+<listitem>
+<para>
+Related to above. Handle multiple Packages files, from different
+sources. Each package contains a link back to the packages file structure
+that contains details about the origin of the data.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Dependency module</term>
+<listitem>
+<itemizedlist>
+<listitem>
+<para>
+dependency/conflict determination and linking
+</para>
+</listitem>
+<listitem>
+<para>
+reverse dependency generator. Maybe merged with above
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Package ordering Module</term>
+<listitem>
+<para>
+Create an ordering of the actions to be taken.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Event generator</term>
+<listitem>
+<para>
+module to interact with dpkg
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</chapter>
+
+<chapter id="ch5"><title>Data flow and conversions analysis.</title>
+<screen>
+                                                          ____________
+                                                       __\|ftp modules|
+                                                      /  /|___________|
+                                    _ ____________   /     ________________
+                                    |    update   | /     |mount/local file|
+        |==========================&gt;|   module    |/_____\|  traversals    |
+        |                           |_____________|      /|________________|
+        |                             ^        ^
+        |                             |        |               ______________
+  ______|_______    _ _____ ______    |   _____v________      \|            |
+ |Configuration |   |configuration|   |   |Packages Files|  ===|Status file |
+ |  module      |&lt;=&gt;|    data     |   |   |______________| /  /|____________|
+ |______________|   |_____________|   |        ^          /
+         ^                            |        |         /
+         |                            | _______v_______|/_
+         |                            | |              |    ________________
+         |                            | |              |/_\|   Dependency  |
+         |                            | |backing store |\ /|     Module    |
+         |                            | |______________|  _|_______________|
+         |                             \       ^          /|       ^
+         |                              \      |         /         |
+         |                              _\|____v_______|/__    ____v_______
+         |_____________________________\| User interaction|    |    dpkg   |
+                                       /|_________________|&lt;==&gt;  Invoker  |
+                                                               |___________|
+</screen>
+<para>
+dpkg also interacts with status and available files.
+</para>
+<para>
+The backing store and the associated data structures are the core of APT. All
+modules essentially revolve around the backing store, feeding it data, adding
+and manipulating links and relationships between data in the backing store,
+allowing the user to interact with and modify the data in the backing store,
+and finally writing it out as the status file and possibly issuing directives
+to dpkg.
+</para>
+<para>
+The other focal point for APT is the user interface.
+</para>
+</chapter>
+
+</book>

doc/design.sgml

@@ -1,411 +0,0 @@
-<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
-<debiandoc>
-  <book>
-    <titlepag>
-      <title> The APT project design document</title>
-      <author>
-	<name>Manoj Srivastava</name>
-	<email>srivasta@debian.org</email>
-      </author>
-      <version>$Id: design.sgml,v 1.4 2003/02/12 15:05:45 doogie Exp $</version>
-      <abstract>
-	This document is an overview of the specifications and design
-	goals of the APT project. It also attempts to give a broad
-	description of the implementation as well.
-      </abstract>
-      <copyright>
-	<copyrightsummary>Copyright &copy;1997 Manoj Srivastava
-	</copyrightsummary>
-	<p>
-	  APT, including this document, is free software; you may
-	  redistribute it and/or modify it under the terms of the GNU
-	  General Public License as published by the Free Software
-	  Foundation; either version 2, or (at your option) any later
-	  version.</p>
-	<p>
-	  This is distributed in the hope that it will be useful, but
-	  <em>without any warranty</em>; without even the implied
-	  warranty of merchantability or fitness for a particular
-	  purpose.  See the GNU General Public License for more
-	  details.</p>
-
-	<p>
-	  You should have received a copy of the GNU General Public
-	  License with your Debian system, in
-	  <tt>/usr/share/common-licenses/GPL</tt>, or with the
-	  <prgn/debiandoc-sgml/ source package as the file
-	  <tt>COPYING</tt>.  If not, write to the Free Software
-	  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
-	  USA.</p>
-      </copyright>
-    </titlepag>
-    <chapt id="introduction">
-      <heading>Introduction</heading>
-      <p>APT is supposed to be a replacement for dselect, and not a 
-	replacement for dpkg. However, since addition functionality
-	has been required for APT, and given the fact that this is
-	very closely related to dpkg, it is not unreasonable to expect
-	that additional functionality in the underlying dpkg would
-	also be requested.</p>
-
-      <p> Deity/dselect are the first introduction that people have to
-	Debian, and unfortunately this first impression contributes
-	greatly to the public perception of the distribution. It is
-	imperative that this be a showcase for Debian, rather than
-	frighten novices away (which has been an accusation often
-	levelled at the current system)</p>
-    </chapt>
-    <chapt>
-      <heading>Requirements</heading>
-      <p>
-	<enumlist compact="compact">
-	  <item>
-	    <p>
-	      APT should be a replacement for dselect. Therefore it
-	      should have all the functionality that dselect has
-	      currently. This is the primary means of interaction
-	      between the user and the package management system, and
-	      it should be able to handle all tasks involved in
-	      installing, upgrading, and routine management without
-	      having the users take recourse to the underlying
-	      management system.</p>
-	  </item>
-	  <item>
-	    <p>
-	      It should be easier to use and less confusing for novice
-	      users. The primary stimulus for the creation of APT
-	      was the perceived intractability, complexity, and
-	      non-intuitive behavior of the existing user interface,
-	      and as such, human factors must be a primary mandate of
-	      APT.</p>
-	  </item>
-	  <item>
-	    <p>
-	      It should be able to group packages more flexibly, and
-	      possibly allow operations based on a group. One should
-	      be able to select, or deselect, a coherent group of
-	      related packages simultaneously, allowing one to add,
-	      remove, or upgrade functionality to a machine as one
-	      step.
-	    </p>
-	  </item>
-	  <item>
-	    <p>
-	      This would allow APT to handle <em>standard
-		installations</em>, namely, one could then install a
-	      set of packages to enable a machine to fulfill specific
-	      tasks.  Define a few standard installations, and which
-	      packages are included therein. The packages should be
-	      internally consistent.</p>
-	  </item>
-	  <item>
-	    <p>
-	      Make use of a keywords field in package headers; provide
-	      a standard list of keywords for people to use. This
-	      could be the underpinning to allow the previous two
-	      requirements to work (though the developers are not
-	      constrained to implement the previous requirements using
-	      keywords)
-	    </p>
-	  </item>
-	  <item>
-	    <p>
-	      Use dependencies, conflicts, and reverse dependencies to
-	      properly order packages for installation and
-	      removal. This has been a complaint in the past that the
-	      installation methods do not really understand
-	      dependencies, causing the upgrade process to break, or
-	      allowing the removal of packages that left the system in
-	      an untenable state by breaking the dependencies on
-	      packages that were dependent on the package being
-	      removed. A special emphasis is placed on handling
-	      pre-dependencies correctly; the target of a
-	      predependency has to be fully configured before
-	      attempting to install the pre-dependent package. Also,
-	      <em>configure immediately</em> requests mentioned below
-	      should be handled.</p>
-	  </item>
-	  <item>
-	    <p>
-	      Handle replacement of a package providing a virtual
-	      package with another (for example, it has been very
-	      difficult replacing <prgn>sendmail</prgn> with
-	      <prgn>smail</prgn>, or vice versa), making sure that the
-	      dependencies are still satisfied. </p>
-	  </item>
-	  <item>
-	    <p>
-	      Handle source lists for updates from multiple
-	      sources. APT should also be able to handle diverse
-	      methods of acquiring new packages; local filesystem,
-	      mountable CD-ROM drives, FTP accessible repositories are
-	      some of the methods that come to mind.  Also, the source
-	      lists can be separated into categories, such as main,
-	      contrib, non-us, non-local, non-free, my-very-own,
-	      etc. APT should be set up to retrieve the Packages
-	      files from these multiple source lists, as well as
-	      retrieving the packages themselves. </p>
-	  </item>
-	  <item>
-	    <p>
-	      Handle base of source and acquire all Packages files
-	      underneath.  (possibly select based on architecture),
-	      this should be a simple extension of the previous
-	      requirement.</p>
-	  </item>
-	  <item>
-	    <p>
-	      Handle remote installation (to be implemented maybe in a
-	      future version, it still needs to be designed). This
-	      would ease the burden of maintaining multiple Debian
-	      machines on a site. In the authors opinion this is a
-	      killer difference for the distribution, though it may be
-	      too hard a problem to be implemented with the initial
-	      version of APT. However, some thought must be given to
-	      this to enable APT to retain hooks for future
-	      functionality, or at least to refrain from methods that
-	      may preclude remote activity. It is desirable that
-	      adding remote installation not require a redesign of
-	      APT from the ground up.</p>
-	  </item>
-	  <item>
-	    <p>
-	      Be scalable. Dselect worked a lot better with 400
-	      packages, but at last count the number of packages was
-	      around twelve hundred and climbing. This also requires
-	      APT to pay attention to the needs of small machines
-	      which are low on memory (though this requirement shall
-	      diminish as we move towards bigger machines, it would
-	      still be nice if Debian worked on all old machines where
-	      Linux itself would work).</p>
-	  </item>
-	  <item>
-	    <p>
-	      Handle install immediately requests. Some packages, like
-	      watchdog, are required to be working for the stability
-	      of the machine itself. There are others which may be
-	      required for the correct functioning of a production
-	      machine, or which are mission critical
-	      applications. APT should, in these cases, upgrade the
-	      packages with minimal downtime; allowing these packages
-	      to be one of potentially hundreds of packages being
-	      upgraded concurrently may not satisfy the requirements
-	      of the package or the site. (Watchdog, for example, if
-	      not restarted quickly, may cause the machine to reboot
-	      in the midst of installation, which may cause havoc on
-	      the machine)</p>
-	  </item>
-	</enumlist> 
-      </p>
-    </chapt>
-    <chapt>
-      <heading>Procedural description</heading>
-      <p><taglist>
-	  <tag>Set Options</tag>
-	  <item>
-	    <p>
-	      This process handles setting of user or
-	      site options, and configuration of all aspects of
-	      APT. It allows the user to set the location and order
-	      of package sources, allowing them to set up source list
-	      details, like ftp site locations, passwords,
-	      etc. Display options may also be set.</p>
-	  </item>
-	  <tag>Updates</tag>
-	  <item>
-	    <p>
-	      Build a list of available packages, using
-	      source lists or a base location and trawling for
-	      Packages files (needs to be aware of architecture). This
-	      may involve finding and retrieving Packages files,
-	      storing them locally for efficiency, and parsing the
-	      data for later use. This would entail contacting various
-	      underlying access modules (ftp, cdrom mounts, etc) Use a
-	      backing store for speed. This may also require
-	      downloading the actual package files locally for
-	      speed.</p>
-	  </item>
-	  <tag>Local status</tag>
-	  <item>
-	    <p>
-	      Build up a list of packages already
-	      installed. This requires reading and writing the local??
-	      status file. For remote installation, this should
-	      probably use similar mechanisms as the Packages file
-	      retrieval does. Use the backing store for speed. One
-	      should consider multiple backing stores, one for each
-	      machine.
-	    </p>
-	  </item>
-	  <tag>Relationship determination</tag>
-	  <item>
-	    <p>
-	      Determine forward and reverse dependencies. All known
-	      dependency fields should be acted upon, since it is
-	      fairly cheap to do so. Update the backing store with
-	      this information.</p>
-	  </item>
-	  <tag>Selection</tag>
-	  <item>
-	    <p>
-	      Present the data to the user. Look at Behan Webster's
-	      documentation for the user interface procedures. (Note:
-	      In the authors opinion deletions and reverse
-	      dependencies should also be presented to the user, in a
-	      strictly symmetric fashion; this may make it easier to
-	      prevent a package being removed that breaks
-	      dependencies)
-	    </p>
-	  </item>
-	  <tag>Ordering of package installations and configuration </tag>
-	  <item>
-	    <p>
-	      Build a list of events. Simple topological sorting gives
-	      order of packages in dependency order. At certain points
-	      in this ordering, predependencies/immediate configure
-	      directives cause an break in normal ordering. We need to
-	      insert the uninstall/purge directive in the stream
-	      (default: as early as possible).</p>
-	  </item>
-	  <tag>Action</tag>
-	  <item>
-	    <p>
-	      Take the order of installations and removals and build
-	      up a stream of events to send to the packaging system
-	      (dpkg). Execute the list of events if successful. Do not
-	      partially install packages and leave system in broken
-	      state. Go to The Selection step as needed.</p>
-	  </item>
-
-	</taglist>
-      </p>
-    </chapt>
-    <chapt>
-      <heading>Modules and interfaces</heading>
-      <p><taglist>
-	  <tag>The user interface module</tag>
-	  <item>
-	    <p> Look at Behan Webster's documentation.</p> 
-	  </item>
-	  <tag>Widget set</tag>
-	  <item>
-	    <p>
-	      Related closely to above Could some one present design
-	      decisions of the widget set here?</p>
-	  </item>
-	  <tag>pdate Module</tag>
-	  <item>
-	    <p>	    
-	      Distinct versions of the same package are recorded
-	      separately, but if multiple Packages files contain the
-	      same version of a package, then only the first one is
-	      recorded. For this reason, the least expensive update
-	      source should be listed first (local file system is
-	      better than a remote ftp site)</p>
-	    <p>
-	      This module should interact with the user interface
-	      module to set and change configuration parameters for
-	      the modules listed below. It needs to record that
-	      information in an on disk data file, to be read on
-	      future invocations. </p>
-	    <p><enumlist>
-		<item>
-		  <p>FTP methods</p>
-		</item>
-		<item>
-		  <p>mount and file traversal module(s)?</p>
-		</item>
-		<item>
-		  <p>Other methods ???</p>
-		</item>
-	      </enumlist>
-	    </p>
-	  </item>
-	  <tag>Status file parser/generator</tag>
-	  <item>
-	    <p> 
-	      The status file records the current state of the system,
-	      listing the packages installed, etc. The status file is
-	      also one method of communicating with dpkg, since it is
-	      perfectly permissible for the user to use APT to
-	      request packages be updated, put others on hold, mark
-	      other for removal, etc, and then run <tt>dpkg
-		-BORGiE</tt> on a file system.</p>
-	  </item>
-	  <tag>Package file parser/generator</tag>
-	  <item>
-	    <p>
-	      Related to above. Handle multiple Packages files, from
-	      different sources. Each package contains a link back to
-	      the packages file structure that contains details about
-	      the origin of the data. </p>
-	  </item>
-	  <tag>Dependency module</tag>
-	  <item>
-	    <p><list>
-		<item>
-		  <p>dependency/conflict determination and linking</p>
-		</item>
-		<item>
-		  <p>reverse dependency generator. Maybe merged with above</p>
-		</item>
-	      </list>
-	    </p>
-	  </item>
-	  <tag>Package ordering Module</tag>
-	  <item>
-	    <p>Create an ordering of the actions to be taken.</p>
-	  </item>
-	  <tag>Event generator</tag>
-	  <item>
-	    <p>module to interact with dpkg</p>
-	  </item>
-	</taglist>
-    </chapt>
-    <chapt>
-      <heading>Data flow and conversions analysis.</heading>
-      <p> 
-	<example>
-                                                          ____________
-                                                       __\|ftp modules|
-                                                      /  /|___________|
-                                    _ ____________   /     ________________
-                                    |    update   | /     |mount/local file|
-        |==========================>|   module    |/_____\|  traversals    |
-        |                           |_____________|      /|________________|
-        |                             ^        ^
-        |                             |        |               ______________
-  ______|_______    _ _____ ______    |   _____v________      \|            |
- |Configuration |   |configuration|   |   |Packages Files|  ===|Status file |
- |  module      |<=>|    data     |   |   |______________| /  /|____________|
- |______________|   |_____________|   |        ^          /
-         ^                            |        |         /
-         |                            | _______v_______|/_
-         |                            | |              |    ________________
-         |                            | |              |/_\|   Dependency  |
-         |                            | |backing store |\ /|     Module    |
-         |                            | |______________|  _|_______________|
-         |                             \       ^          /|       ^
-         |                              \      |         /         |
-         |                              _\|____v_______|/__    ____v_______
-         |_____________________________\| User interaction|    |    dpkg   |
-                                       /|_________________|<==>|  Invoker  |
-                                                               |___________|
-
-	</example>
-      <p> dpkg also interacts with status and available files.</p>
-
-
-      <p>
-	The backing store and the associated data structures are the
-	core of APT. All modules essentially revolve around the
-	backing store, feeding it data, adding and manipulating links
-	and relationships between data in the backing store, allowing
-	the user to interact with and modify the data in the backing
-	store, and finally writing it out as the status file and
-	possibly issuing directives to dpkg.</p>
-
-      <p>The other focal point for APT is the user interface.</p> 
-    </chapt>
-  </book>
-</debiandoc>

doc/dpkg-tech.dbk

@@ -0,0 +1,895 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+]>
+
+<book lang="en">
+
+<title>dpkg technical manual</title>
+
+<bookinfo>
+
+<authorgroup>
+  <author>
+    <personname>Tom Lees</personname><email>tom@lpsg.demon.co.uk</email>
+  </author>
+</authorgroup>
+
+<releaseinfo>Version &apt-product-version;</releaseinfo>
+
+<abstract>
+<para>
+This document describes the minimum necessary workings for the APT dselect
+replacement. It gives an overall specification of what its external interface
+must look like for compatibility, and also gives details of some internal
+quirks.
+</para>
+</abstract>
+
+<copyright><year>1997</year><holder>Tom Lees</holder></copyright>
+
+<legalnotice>
+<title>License Notice</title>
+<para>
+APT and this document are free software; you can redistribute them and/or
+modify them under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or (at your
+option) any later version.
+</para>
+<para>
+For more details, on Debian systems, see the file
+/usr/share/common-licenses/GPL for the full license.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+<chapter id="ch1"><title>Quick summary of dpkg's external interface</title>
+
+<section id="control"><title>Control files</title>
+<para>
+The basic dpkg package control file supports the following major features:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+5 types of dependencies:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Pre-Depends, which must be satisfied before a package may be unpacked
+</para>
+</listitem>
+<listitem>
+<para>
+Depends, which must be satisfied before a package may be configured
+</para>
+</listitem>
+<listitem>
+<para>
+Recommends, to specify a package which if not installed may severely limit the
+usefulness of the package
+</para>
+</listitem>
+<listitem>
+<para>
+Suggests, to specify a package which may increase the productivity of the
+package
+</para>
+</listitem>
+<listitem>
+<para>
+Conflicts, to specify a package which must NOT be installed in order for the
+package to be configured
+</para>
+</listitem>
+<listitem>
+<para>
+Breaks, to specify a package which is broken by the package and which should
+therefore not be configured while broken
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Each of these dependencies can specify a version and a depedency on that
+version, for example "&lt;= 0.5-1", "== 2.7.2-1", etc. The comparators
+available are:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+"&lt;&lt;" - less than
+</para>
+</listitem>
+<listitem>
+<para>
+"&lt;=" - less than or equal to
+</para>
+</listitem>
+<listitem>
+<para>
+"&gt;&gt;" - greater than
+</para>
+</listitem>
+<listitem>
+<para>
+"&gt;=" - greater than or equal to
+</para>
+</listitem>
+<listitem>
+<para>
+"==" - equal to
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+<listitem>
+<para>
+The concept of "virtual packages", which many other packages may provide,
+using the Provides mechanism. An example of this is the "httpd" virtual
+package, which all web servers should provide. Virtual package names may be
+used in dependency headers. However, current policy is that virtual packages
+do not support version numbers, so dependencies on virtual packages with
+versions will always fail.
+</para>
+</listitem>
+<listitem>
+<para>
+Several other control fields, such as Package, Version, Description, Section,
+Priority, etc., which are mainly for classification purposes. The package
+name must consist entirely of lowercase characters, plus the characters '+',
+'-', and '.'. Fields can extend across multiple lines - on the second and
+subsequent lines, there is a space at the beginning instead of a field name
+and a ':'. Empty lines must consist of the text " .", which will be ignored,
+as will the initial space for other continuation lines. This feature is
+usually only used in the Description field.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s1.2"><title>The dpkg status area</title>
+<para>
+The "dpkg status area" is the term used to refer to the directory where dpkg
+keeps its various status files (GNU would have you call it the dpkg shared
+state directory). This is always, on Debian systems, /var/lib/dpkg. However,
+the default directory name should not be hard-coded, but #define'd, so that
+alteration is possible (it is available via configure in dpkg 1.4.0.9 and
+above). Of course, in a library, code should be allowed to override the
+default directory, but the default should be part of the library (so that
+the user may change the dpkg admin dir simply by replacing the library).
+</para>
+<para>
+Dpkg keeps a variety of files in its status area. These are discussed later
+on in this document, but a quick summary of the files is here:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+available - this file contains a concatenation of control information from all
+the packages which dpkg knows about. This is updated using the dpkg commands
+"--update-avail &lt;file&gt;", "--merge-avail &lt;file&gt;", and
+"--clear-avail".
+</para>
+</listitem>
+<listitem>
+<para>
+status - this file contains information on the following things for every
+package:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Whether it is installed, not installed, unpacked, removed, failed
+configuration, or half-installed (deconfigured in favour of another package).
+</para>
+</listitem>
+<listitem>
+<para>
+Whether it is selected as install, hold, remove, or purge.
+</para>
+</listitem>
+<listitem>
+<para>
+If it is "ok" (no installation problems), or "not-ok".
+</para>
+</listitem>
+<listitem>
+<para>
+It usually also contains the section and priority (so that dselect may classify
+packages not in available)
+</para>
+</listitem>
+<listitem>
+<para>
+For packages which did not initially appear in the "available" file when they
+were installed, the other control information for them.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+The exact format for the "Status:" field is:
+</para>
+<screen>
+      Status: Want Flag Status
+</screen>
+<para>
+Where <replaceable>Want</replaceable> may be one of
+<emphasis>unknown</emphasis>, <emphasis>install</emphasis>,
+<emphasis>hold</emphasis>, <emphasis>deinstall</emphasis>,
+<emphasis>purge</emphasis>. <replaceable>Flag</replaceable> may
+be one of <emphasis>ok</emphasis>, <emphasis>reinstreq</emphasis>,
+<emphasis>hold</emphasis>,
+<emphasis>hold-reinstreq</emphasis>. <replaceable>Status</replaceable> may
+be one of <emphasis>not-installed</emphasis>, <emphasis>unpacked</emphasis>,
+<emphasis>half-configured</emphasis>, <emphasis>installed</emphasis>,
+<emphasis>half-installed</emphasis> <emphasis>config-files</emphasis>,
+<emphasis>post-inst-failed</emphasis>, <emphasis>removal-failed</emphasis>.
+The states are as follows:-
+</para>
+<variablelist>
+<varlistentry>
+<term>not-installed</term>
+<listitem>
+<para>
+No files are installed from the package, it has no config files left, it
+uninstalled cleanly if it ever was installed.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>unpacked</term>
+<listitem>
+<para>
+The basic files have been unpacked (and are listed in
+/var/lib/dpkg/info/[package].list. There are config files present, but the
+postinst script has _NOT_ been run.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>half-configured</term>
+<listitem>
+<para>
+The package was installed and unpacked, but the postinst script failed in some
+way.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>installed</term>
+<listitem>
+<para>
+All files for the package are installed, and the configuration was also
+successful.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>half-installed</term>
+<listitem>
+<para>
+An attempt was made to remove the packagem but there was a failure in the
+prerm script.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>config-files</term>
+<listitem>
+<para>
+The package was "removed", not "purged". The config files are left, but
+nothing else.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>post-inst-failed</term>
+<listitem>
+<para>
+Old name for half-configured. Do not use.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>removal-failed</term>
+<listitem>
+<para>
+Old name for half-installed. Do not use.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+The two last items are only left in dpkg for compatibility - they are
+understood by it, but never written out in this form.
+</para>
+<para>
+Please see the dpkg source code, <literal>lib/parshelp.c</literal>,
+<emphasis>statusinfos</emphasis>, <emphasis>eflaginfos</emphasis> and
+<emphasis>wantinfos</emphasis> for more details.
+</para>
+</listitem>
+<listitem>
+<para>
+info - this directory contains files from the control archive of every
+package currently installed. They are installed with a prefix of
+"&lt;packagename&gt;.". In addition to this, it also contains a file
+called &lt;package&gt;.list for every package, which contains a list
+of files. Note also that the control file is not copied into here; it
+is instead found as part of status or available.
+</para>
+</listitem>
+<listitem>
+<para>
+methods - this directory is reserved for "method"-specific files - each
+"method" has a subdirectory underneath this directory (or at least,
+it can have). In addition, there is another subdirectory "mnt", where
+misc. filesystems (floppies, CD-ROMs, etc.) are mounted.
+</para>
+</listitem>
+<listitem>
+<para>
+alternatives - directory used by the "update-alternatives" program. It
+contains one file for each "alternatives" interface, which contains
+information about all the needed symlinked files for each alternative.
+</para>
+</listitem>
+<listitem>
+<para>
+diversions - file used by the "dpkg-divert" program. Each diversion takes
+three lines. The first is the package name (or ":" for user diversion), the
+second the original filename, and the third the diverted filename.
+</para>
+</listitem>
+<listitem>
+<para>
+updates - directory used internally by dpkg. This is discussed later, in the
+section <xref linkend="updates"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+parts - temporary directory used by dpkg-split
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s1.3"><title>The dpkg library files</title>
+<para>
+These files are installed under /usr/lib/dpkg (usually), but
+/usr/local/lib/dpkg is also a possibility (as Debian policy dictates). Under
+this directory, there is a "methods" subdirectory. The methods subdirectory in
+turn contains any number of subdirectories for each general method processor
+(note that one set of method scripts can, and is, used for more than one of
+the methods listed under dselect).
+</para>
+<para>
+The following files may be found in each of these subdirectories:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+names - One line per method, two-digit priority to appear on menu at
+beginning, followed by a space, the name, and then another space and
+the short description.
+</para>
+</listitem>
+<listitem>
+<para>
+desc.&lt;name&gt; - Contains the long description displayed by dselect
+when the cursor is put over the &lt;name&gt; method.
+</para>
+</listitem>
+<listitem>
+<para>
+setup - Script or program which sets up the initial values to be used
+by this method. Called with first argument as the status area directory
+(/var/lib/dpkg), second argument as the name of the method (as in the
+directory name), and the third argument as the option (as in the names file).
+</para>
+</listitem>
+<listitem>
+<para>
+install - Script/program called when the "install" option of dselect is run
+with this method. Same arguments as for setup.
+</para>
+</listitem>
+<listitem>
+<para>
+update - Script/program called when the "update" option of dselect is
+run. Same arguments as for setup/install.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s1.4"><title>The "dpkg" command-line utility</title>
+
+<section id="s1.4.1"><title>"Documented" command-line interfaces</title>
+<para>
+As yet unwritten. You can refer to the other manuals for now. See
+<citerefentry><refentrytitle>dpkg</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+</para>
+</section>
+
+<section id="s1.4.2"><title>Environment variables which dpkg responds to</title>
+<itemizedlist>
+<listitem>
+<para>
+DPKG_NO_TSTP - if set to a non-null value, this variable causes dpkg to run a
+child shell process instead of sending itself a SIGTSTP, when the user selects
+to background the dpkg process when it asks about conffiles.
+</para>
+</listitem>
+<listitem>
+<para>
+SHELL - used to determine which shell to run in the case when DPKG_NO_TSTP
+is set.
+</para>
+</listitem>
+<listitem>
+<para>
+CC - used as the C compiler to call to determine the target architecture. The
+default is "gcc".
+</para>
+</listitem>
+<listitem>
+<para>
+PATH - dpkg checks that it can find at least the following files in the path
+when it wants to run package installation scripts, and gives an error if it
+cannot find all of them:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+ldconfig
+</para>
+</listitem>
+<listitem>
+<para>
+start-stop-daemon
+</para>
+</listitem>
+<listitem>
+<para>
+install-info
+</para>
+</listitem>
+<listitem>
+<para>
+update-rc.d
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s1.4.3"><title>Assertions</title>
+<para>
+The dpkg utility itself is required for quite a number of packages, even if
+they have been installed with a tool totally separate from dpkg. The reason
+for this is that some packages, in their pre-installation scripts, check that
+your version of dpkg supports certain features. This was broken from the
+start, and it should have actually been a control file header "Dpkg-requires",
+or similar. What happens is that the configuration scripts will abort or
+continue according to the exit code of a call to dpkg, which will stop them
+from being wrongly configured.
+</para>
+<para>
+These special command-line options, which simply return as true or false are
+all prefixed with "--assert-". Here is a list of them (without the prefix):-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+support-predepends - Returns success or failure according to whether a version
+of dpkg which supports predepends properly (1.1.0 or above) is installed,
+according to the database.
+</para>
+</listitem>
+<listitem>
+<para>
+working-epoch - Return success or failure according to whether a version of
+dpkg which supports epochs in version properly (1.4.0.7 or above) is installed,
+according to the database.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Both these options check the status database to see what version of the
+"dpkg" package is installed, and check it against a known working version.
+</para>
+</section>
+
+<section id="s1.4.4"><title>--predep-package</title>
+<para>
+This strange option is described as follows in the source code:
+</para>
+<screen>
+/* Print a single package which:
+ *  (a) is the target of one or more relevant predependencies.
+ *  (b) has itself no unsatisfied pre-dependencies.
+ * If such a package is present output is the Packages file entry,
+ *  which can be massaged as appropriate.
+ * Exit status:
+ *  0 = a package printed, OK
+ *  1 = no suitable package available
+ *  2 = error
+ */
+</screen>
+<para>
+On further inspection of the source code, it appears that what is does is
+this:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Looks at the packages in the database which are selected as "install",
+and are installed.
+</para>
+</listitem>
+<listitem>
+<para>
+It then looks at the Pre-Depends information for each of these packages
+from the available file. When it find a package for which any of the
+pre-dependencies are not satisfied, it breaks from the loop through the
+packages.
+</para>
+</listitem>
+<listitem>
+<para>
+It then looks through the unsatisfied pre-dependencies, and looks for
+packages which would satisfy this pre-dependency, stopping on the first
+it finds. If it finds none, it bombs out with an error.
+</para>
+</listitem>
+<listitem>
+<para>
+It then continues this for every dependency of the initial package.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Eventually, it writes out the record of all the packages to satisfy the
+pre-dependencies. This is used by the disk method to make sure that its
+dependency ordering is correct. What happens is that all pre-depending
+packages are first installed, then it runs dpkg -iGROEB on the directory,
+which installs in the order package files are found. Since pre-dependencies
+mean that a package may not even be unpacked unless they are satisfied, it
+is necessary to do this (usually, since all the package files are unpacked
+in one phase, the configured in another, this is not needed).
+</para>
+</section>
+
+</section>
+
+</chapter>
+
+<chapter id="ch2"><title>dpkg-deb and .deb file internals</title>
+<para>
+This chapter describes the internals to the "dpkg-deb" tool, which is used by
+"dpkg" as a back-end. dpkg-deb has its own tar extraction functions, which is
+the source of many problems, as it does not support long filenames, using
+extension blocks.
+</para>
+
+<section id="s2.1"><title>The .deb archive format</title>
+<para>
+The main principal of the new-format Debian archive (I won't describe the old
+format - for that have a look at deb-old.5), is that the archive really is an
+archive - as used by "ar" and friends. However, dpkg-deb uses this format
+internally, rather than calling "ar". Inside this archive, there are usually
+the following members:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+debian-binary
+</para>
+</listitem>
+<listitem>
+<para>
+control.tar.gz
+</para>
+</listitem>
+<listitem>
+<para>
+data.tar.gz
+</para>
+</listitem>
+</itemizedlist>
+<para>
+The debian-binary member consists simply of the string "2.0", indicating
+the format version. control.tar.gz contains the control files (and scripts),
+and the data.tar.gz contains the actual files to populate the filesystem
+with. Both tarfiles extract straight into the current directory. Information
+on the tar formats can be found in the GNU tar info page. Since dpkg-deb
+calls "tar -cf" to build packages, the Debian packages use the GNU extensions.
+</para>
+</section>
+
+<section id="s2.2"><title>The dpkg-deb command-line</title>
+<para>
+dpkg-deb documents itself thoroughly with its '--help' command-line
+option. However, I am including a reference to these for
+completeness. dpkg-deb supports the following options:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+--build (-b) &lt;dir&gt; - builds a .deb archive, takes a directory which
+contains all the files as an argument. Note that the directory
+&lt;dir&gt;/DEBIAN will be packed separately into the control archive.
+</para>
+</listitem>
+<listitem>
+<para>
+--contents (-c) &lt;debfile&gt; - Lists the contents of the "data.tar.gz"
+member.
+</para>
+</listitem>
+<listitem>
+<para>
+--control (-e) &lt;debfile&gt; - Extracts the control archive into a directory
+called DEBIAN. Alternatively, with another argument, it will extract it into a
+different directory.
+</para>
+</listitem>
+<listitem>
+<para>
+--info (-I) &lt;debfile&gt; - Prints the contents of the "control" file in the
+control archive to stdout. Alternatively, giving it other arguments will cause
+it to print the contents of those files instead.
+</para>
+</listitem>
+<listitem>
+<para>
+--field (-f) &lt;debfile&gt; &lt;field&gt; ... - Prints any number of fields
+from the "control" file. Giving it extra arguments limits the fields it prints
+to only those specified. With no command-line arguments other than a filename,
+it is equivalent to -I and just the .deb filename.
+</para>
+</listitem>
+<listitem>
+<para>
+--extract (-x) &lt;debfile&gt; &lt;dir&gt; - Extracts the data archive of a
+debian package under the directory &lt;dir&gt;.
+</para>
+</listitem>
+<listitem>
+<para>
+--vextract (-X) &lt;debfile&gt; &lt;dir&gt; - Same as --extract, except it
+is equivalent of giving tar the '-v' option - it prints the filenames as it
+extracts them.
+</para>
+</listitem>
+<listitem>
+<para>
+--fsys-tarfile &lt;debfile&gt; - This option outputs a gunzip'd version of
+data.tar.gz to stdout.
+</para>
+</listitem>
+<listitem>
+<para>
+--new - sets the archive format to be used to the new Debian format
+</para>
+</listitem>
+<listitem>
+<para>
+--old - sets the archive format to be used to the old Debian format
+</para>
+</listitem>
+<listitem>
+<para>
+--debug - Tells dpkg-deb to produce debugging output
+</para>
+</listitem>
+<listitem>
+<para>
+--nocheck - Tells dpkg-deb not to check the sanity of the control file
+</para>
+</listitem>
+<listitem>
+<para>
+--help (-h) - Gives a help message
+</para>
+</listitem>
+<listitem>
+<para>
+--version - Shows the version number
+</para>
+</listitem>
+<listitem>
+<para>
+--licence/--license (UK/US spellings) - Shows a brief outline of the GPL
+</para>
+</listitem>
+</itemizedlist>
+
+<section id="s2.2.1"><title>Internal checks used by dpkg-deb when building packages</title>
+<para>
+Here is a list of the internal checks used by dpkg-deb when building
+packages. It is in the order they are done.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+First, the output Debian archive argument, if it is given, is checked using
+stat. If it is a directory, an internal flag is set. This check is only made
+if the archive name is specified explicitly on the command-line. If the
+argument was not given, the default is the directory name, with ".deb"
+appended.
+</para>
+</listitem>
+<listitem>
+<para>
+Next, the control file is checked, unless the --nocheck flag was specified on
+the command-line. dpkg-deb will bomb out if the second argument to --build was
+a directory, and --nocheck was specified. Note that dpkg-deb will not be able
+to determine the name of the package in this case. In the control file, the
+following things are checked:-
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The package name is checked to see if it contains any invalid characters (see
+<xref linkend="control"/> for this).
+</para>
+</listitem>
+<listitem>
+<para>
+The priority field is checked to see if it uses standard values, and
+user-defined values are warned against. However, note that this check is now
+redundant, since the control file no longer contains the priority - the
+changes file now does this.
+</para>
+</listitem>
+<listitem>
+<para>
+The control file fields are then checked against the standard list of fields
+which appear in control files, and any "user-defined" fields are reported as
+warnings.
+</para>
+</listitem>
+<listitem>
+<para>
+dpkg-deb then checks that the control file contains a valid version number.
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+<listitem>
+<para>
+After this, in the case where a directory was specified to build the .deb file
+in, the filename is created as "directory/pkg_ver.deb" or
+"directory/pkg_ver_arch.deb", depending on whether the control file contains
+an architecture field.
+</para>
+</listitem>
+<listitem>
+<para>
+Next, dpkg-deb checks for the &lt;dir&gt;/DEBIAN directory. It complains if it
+doesn't exist, or if it has permissions &lt; 0755, or &gt; 0775.
+</para>
+</listitem>
+<listitem>
+<para>
+It then checks that all the files in this subdir are either symlinks or plain
+files, and have permissions between 0555 and 0775.
+</para>
+</listitem>
+<listitem>
+<para>
+The conffiles file is then checked to see if the filenames are too
+long. Warnings are produced for each that is. After this, it checks
+that the package provides initial copies of each of these conffiles,
+and that they are all plain files.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+</section>
+
+</chapter>
+
+<chapter id="ch3"><title>dpkg internals</title>
+<para>
+This chapter describes the internals of dpkg itself. Although the low-level
+formats are quite simple, what dpkg does in certain cases often does not make
+sense.
+</para>
+
+<section id="updates"><title>Updates</title>
+<para>
+This describes the /var/lib/dpkg/updates directory. The function of this
+directory is somewhat strange, and seems only to be used internally. A
+function called cleanupdates is called whenever the database is scanned. This
+function in turn uses
+<citerefentry><refentrytitle>scandir</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+to sort the files in this directory. Files who names do not consist entirely
+of digits are discarded. dpkg also causes a fatal error if any of the
+filenames are different lengths.
+</para>
+<para>
+After having scanned the directory, dpkg in turn parses each file the same way
+it parses the status file (they are sorted by the scandir to be in numerical
+order). After having done this, it then writes the status information back to
+the "status" file, and removes all the "updates" files.
+</para>
+<para>
+These files are created internally by dpkg's "checkpoint" function, and are
+cleaned up when dpkg exits cleanly.
+</para>
+<para>
+Juding by the use of the updates directory I would call it a Journal. Inorder
+to efficiently ensure the complete integrity of the status file dpkg will
+"checkpoint" or journal all of it's activities in the updates directory. By
+merging the contents of the updates directory (in order!!) against the original
+status file it can get the precise current state of the system, even in the
+event of a system failure while dpkg is running.
+</para>
+<para>
+The other option would be to sync-rewrite the status file after each operation,
+which would kill performance.
+</para>
+<para>
+It is very important that any program that uses the status file abort if the
+updates directory is not empty!  The user should be informed to run dpkg
+manually (what options though??) to correct the situation.
+</para>
+</section>
+
+<section id="s3.2"><title>What happens when dpkg reads the database</title>
+<para>
+First, the status file is read. This gives dpkg an initial idea of the
+packages that are there. Next, the updates files are read in, overriding the
+status file, and if necessary, the status file is re-written, and updates files
+are removed. Finally, the available file is read. The available file is read
+with flags which preclude dpkg from updating any status information from it,
+though - installed version, etc., and is also told to record that the packages
+it reads this time are available, not installed.
+</para>
+<para>
+More information on updates is given above.
+</para>
+</section>
+
+<section id="s3.3"><title>How dpkg compares version numbers</title>
+<para>
+Version numbers consist of three parts: the epoch, the upstream version, and
+the Debian revision. Dpkg compares these parts in that order. If the epochs
+are different, it returns immediately, and so on.
+</para>
+<para>
+However, the important part is how it compares the versions which are
+essentially stored as just strings. These are compared in two distinct
+parts: those consisting of numerical characters (which are evaluated, and
+then compared), and those consisting of other characters. When comparing
+non-numerical parts, they are compared as the character values (ASCII),
+but non-alphabetical characters are considered "greater than" alphabetical
+ones. Also note that longer strings (after excluding differences where
+numerical values are equal) are considered "greater than" shorter ones.
+</para>
+<para>
+Here are a few examples of how these rules apply:-
+</para>
+<screen>
+15 &gt; 10
+0010 == 10
+
+d.r &gt; dsr
+32.d.r == 0032.d.r
+d.rnr &lt; d.rnrn
+</screen>
+</section>
+
+</chapter>
+
+</book>

doc/dpkg-tech.sgml

@@ -1,511 +0,0 @@
-<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
-<book>
-<title>dpkg technical manual</title>
-
-<author>Tom Lees <email>tom@lpsg.demon.co.uk</email></author>
-<version>$Id: dpkg-tech.sgml,v 1.3 2003/02/12 15:05:45 doogie Exp $</version>
-
-<abstract>
-This document describes the minimum necessary workings for the APT dselect
-replacement. It gives an overall specification of what its external interface
-must look like for compatibility, and also gives details of some internal
-quirks.
-</abstract>
-
-<copyright>
-Copyright &copy; Tom Lees, 1997.
-<p>
-APT and this document are free software; you can redistribute them and/or
-modify them under the terms of the GNU General Public License as published
-by the Free Software Foundation; either version 2 of the License, or (at your
-option) any later version.
-
-<p>
-For more details, on Debian systems, see the file
-/usr/share/common-licenses/GPL for the full license.
-</copyright>
-
-<toc sect>
-
-<chapt>Quick summary of dpkg's external interface
-<sect id="control">Control files
-
-<p>
-The basic dpkg package control file supports the following major features:-
-
-<list>
-<item>5 types of dependencies:-
-	<list>
-	<item>Pre-Depends, which must be satisfied before a package may be
-	unpacked
-	<item>Depends, which must be satisfied before a package may be
-	configured
-	<item>Recommends, to specify a package which if not installed may
-	severely limit the usefulness of the package
-	<item>Suggests, to specify a package which may increase the
-	productivity of the package
-	<item>Conflicts, to specify a package which must NOT be installed
-	in order for the package to be configured
-	<item>Breaks, to specify a package which is broken by the
-	package and which should therefore not be configured while broken
-	</list>
-Each of these dependencies can specify a version and a depedency on that
-version, for example "<= 0.5-1", "== 2.7.2-1", etc. The comparators available
-are:-
-	<list>
-	<item>"&lt;&lt;" - less than
-	<item>"&lt;=" - less than or equal to
-	<item>"&gt;&gt;" - greater than
-	<item>"&gt;=" - greater than or equal to
-	<item>"==" - equal to
-	</list>
-<item>The concept of "virtual packages", which many other packages may provide,
-using the Provides mechanism. An example of this is the "httpd" virtual package,
-which all web servers should provide. Virtual package names may be used in
-dependency headers. However, current policy is that virtual packages do not
-support version numbers, so dependencies on virtual packages with versions
-will always fail.
-<item>Several other control fields, such as Package, Version, Description,
-Section, Priority, etc., which are mainly for classification purposes. The
-package name must consist entirely of lowercase characters, plus the characters
-'+', '-', and '.'. Fields can extend across multiple lines - on the second
-and subsequent lines, there is a space at the beginning instead of a field
-name and a ':'. Empty lines must consist of the text " .", which will be
-ignored, as will the initial space for other continuation lines. This feature
-is usually only used in the Description field.
-</list>
-
-<sect>The dpkg status area
-
-<p>
-The "dpkg status area" is the term used to refer to the directory where dpkg
-keeps its various status files (GNU would have you call it the dpkg shared
-state directory). This is always, on Debian systems, /var/lib/dpkg. However,
-the default directory name should not be hard-coded, but #define'd, so that
-alteration is possible (it is available via configure in dpkg 1.4.0.9 and
-above). Of course, in a library, code should be allowed to override the
-default directory, but the default should be part of the library (so that
-the user may change the dpkg admin dir simply by replacing the library).
-
-<p>
-Dpkg keeps a variety of files in its status area. These are discussed later
-on in this document, but a quick summary of the files is here:-
-
-<list>
-<item>available - this file contains a concatenation of control information
-from all the packages which dpkg knows about. This is updated using the dpkg
-commands "--update-avail &lt;file&gt;", "--merge-avail &lt;file&gt;", and
-"--clear-avail".
-<item>status - this file contains information on the following things for
-every package:-
-	<list>
-	<item>Whether it is installed, not installed, unpacked, removed,
-		failed configuration, or half-installed (deconfigured in
-		favour of another package).
-	<item>Whether it is selected as install, hold, remove, or purge.
-	<item>If it is "ok" (no installation problems), or "not-ok".
-	<item>It usually also contains the section and priority (so that
-		dselect may classify packages not in available)
-	<item>For packages which did not initially appear in the "available"
-		file when they were installed, the other control information
-		for them.
-	</list>
-   <p>
-   The exact format for the "Status:" field is:
-   <example>
-      Status: Want Flag Status
-   </example>
-   Where <var>Want</> may be one of <em>unknown</>, <em>install</>,
-   <em>hold</>, <em>deinstall</>, <em>purge</>. <var>Flag</>
-   may be one of <em>ok</>, <em>reinstreq</>, <em>hold</>,
-   <em>hold-reinstreq</>.
-   <var>Status</> may be one of <em>not-installed</>, <em>unpacked</>, 
-   <em>half-configured</>, <em>installed</>, <em>half-installed</>
-   <em>config-files</>, <em>post-inst-failed</>, <em>removal-failed</>.
-   The states are as follows:-
-   <taglist>
-     <tag>not-installed
-     <item>No files are installed from the package, it has no config files
-        left, it uninstalled cleanly if it ever was installed.
-     <tag>unpacked
-     <item>The basic files have been unpacked (and are listed in
-        /var/lib/dpkg/info/[package].list. There are config files present,
-        but the postinst script has _NOT_ been run.
-     <tag>half-configured
-     <item>The package was installed and unpacked, but the postinst script
-        failed in some way.
-     <tag>installed
-     <item>All files for the package are installed, and the configuration
-        was also successful.
-     <tag>half-installed
-     <item>An attempt was made to remove the packagem but there was a failure
-        in the prerm script.
-     <tag>config-files
-     <item>The package was "removed", not "purged". The config files are left,
-        but nothing else.
-     <tag>post-inst-failed
-     <item>Old name for half-configured. Do not use.
-     <tag>removal-failed
-     <item>Old name for half-installed. Do not use.
-   </taglist>
-   The two last items are only left in dpkg for compatibility - they are
-   understood by it, but never written out in this form.
-
-   <p>
-   Please see the dpkg source code, <tt>lib/parshelp.c</tt>, 
-   <em>statusinfos</>, <em>eflaginfos</> and <em>wantinfos</> for more 
-   details.
-   
-<item>info - this directory contains files from the control archive of every
-package currently installed. They are installed with a prefix of "&lt;packagename&gt;.".
-In addition to this, it also contains a file called &lt;package&gt;.list for every
-package, which contains a list of files. Note also that the control file is
-not copied into here; it is instead found as part of status or available.
-<item>methods - this directory is reserved for "method"-specific files - each
-"method" has a subdirectory underneath this directory (or at least, it can
-have). In addition, there is another subdirectory "mnt", where misc.
-filesystems (floppies, CD-ROMs, etc.) are mounted.
-<item>alternatives - directory used by the "update-alternatives" program. It
-contains one file for each "alternatives" interface, which contains information
-about all the needed symlinked files for each alternative.
-<item>diversions - file used by the "dpkg-divert" program. Each diversion takes
-three lines. The first is the package name (or ":" for user diversion), the
-second the original filename, and the third the diverted filename.
-<item>updates - directory used internally by dpkg. This is discussed later,
-in the section <ref id="updates">.
-<item>parts - temporary directory used by dpkg-split
-</list>
-
-<sect>The dpkg library files
-
-<p>
-These files are installed under /usr/lib/dpkg (usually), but
-/usr/local/lib/dpkg is also a possibility (as Debian policy dictates). Under
-this directory, there is a "methods" subdirectory. The methods subdirectory
-in turn contains any number of subdirectories for each general method
-processor (note that one set of method scripts can, and is, used for more than
-one of the methods listed under dselect).
-
-<p>
-The following files may be found in each of these subdirectories:-
-
-<list>
-<item>names - One line per method, two-digit priority to appear on menu
-at beginning, followed by a space, the name, and then another space and the
-short description.
-<item>desc.&lt;name&gt; - Contains the long description displayed by dselect
-when the cursor is put over the &lt;name&gt; method.
-<item>setup - Script or program which sets up the initial values to be used
-by this method. Called with first argument as the status area directory
-(/var/lib/dpkg), second argument as the name of the method (as in the directory
-name), and the third argument as the option (as in the names file).
-<item>install - Script/program called when the "install" option of dselect is
-run with this method. Same arguments as for setup.
-<item>update - Script/program called when the "update" option of dselect is
-run. Same arguments as for setup/install.
-</list>
-
-<sect>The "dpkg" command-line utility
-
-<sect1>"Documented" command-line interfaces
-
-<p>
-As yet unwritten. You can refer to the other manuals for now. See
-<manref name="dpkg" section="8">.
-
-<sect1>Environment variables which dpkg responds to
-
-<p>
-<list>
-<item>DPKG_NO_TSTP - if set to a non-null value, this variable causes dpkg to
-run a child shell process instead of sending itself a SIGTSTP, when the user
-selects to background the dpkg process when it asks about conffiles.
-<item>SHELL - used to determine which shell to run in the case when
-DPKG_NO_TSTP is set.
-<item>CC - used as the C compiler to call to determine the target architecture.
-The default is "gcc".
-<item>PATH - dpkg checks that it can find at least the following files in the
-path when it wants to run package installation scripts, and gives an error if
-it cannot find all of them:-
-	<list>
-	<item>ldconfig
-	<item>start-stop-daemon
-	<item>install-info
-	<item>update-rc.d
-	</list>
-</list>
-
-<sect1>Assertions
-
-<p>
-The dpkg utility itself is required for quite a number of packages, even if
-they have been installed with a tool totally separate from dpkg. The reason for
-this is that some packages, in their pre-installation scripts, check that your
-version of dpkg supports certain features. This was broken from the start, and
-it should have actually been a control file header "Dpkg-requires", or similar.
-What happens is that the configuration scripts will abort or continue according
-to the exit code of a call to dpkg, which will stop them from being wrongly
-configured.
-
-<p>
-These special command-line options, which simply return as true or false are
-all prefixed with "--assert-". Here is a list of them (without the prefix):-
-
-<list>
-<item>support-predepends - Returns success or failure according to whether
-a version of dpkg which supports predepends properly (1.1.0 or above) is
-installed, according to the database.
-<item>working-epoch - Return success or failure according to whether a version
-of dpkg which supports epochs in version properly (1.4.0.7 or above) is
-installed, according to the database.
-</list>
-
-<p>
-Both these options check the status database to see what version of the "dpkg"
-package is installed, and check it against a known working version.
-
-<sect1>--predep-package
-
-<p>
-This strange option is described as follows in the source code:
-
-<example>
-/* Print a single package which:
- *  (a) is the target of one or more relevant predependencies.
- *  (b) has itself no unsatisfied pre-dependencies.
- * If such a package is present output is the Packages file entry,
- *  which can be massaged as appropriate.
- * Exit status:
- *  0 = a package printed, OK
- *  1 = no suitable package available
- *  2 = error
- */
-</example>
-
-<p>
-On further inspection of the source code, it appears that what is does is
-this:-
-
-<list>
-<item>Looks at the packages in the database which are selected as "install",
-and are installed.
-<item>It then looks at the Pre-Depends information for each of these packages
-from the available file. When it find a package for which any of the
-pre-dependencies are not satisfied, it breaks from the loop through the packages.
-<item>It then looks through the unsatisfied pre-dependencies, and looks for
-packages which would satisfy this pre-dependency, stopping on the first it
-finds. If it finds none, it bombs out with an error.
-<item>It then continues this for every dependency of the initial package.
-</list>
-
-Eventually, it writes out the record of all the packages to satisfy the
-pre-dependencies. This is used by the disk method to make sure that its
-dependency ordering is correct. What happens is that all pre-depending
-packages are first installed, then it runs dpkg -iGROEB on the directory,
-which installs in the order package files are found. Since pre-dependencies
-mean that a package may not even be unpacked unless they are satisfied, it is
-necessary to do this (usually, since all the package files are unpacked in one
-phase, the configured in another, this is not needed).
-
-<chapt>dpkg-deb and .deb file internals
-
-<p>
-This chapter describes the internals to the "dpkg-deb" tool, which is used
-by "dpkg" as a back-end. dpkg-deb has its own tar extraction functions, which
-is the source of many problems, as it does not support long filenames, using
-extension blocks.
-
-<sect>The .deb archive format
-
-<p>
-The main principal of the new-format Debian archive (I won't describe the old
-format - for that have a look at deb-old.5), is that the archive really is
-an archive - as used by "ar" and friends. However, dpkg-deb uses this format
-internally, rather than calling "ar". Inside this archive, there are usually
-the following members:-
-
-<list>
-<item>debian-binary
-<item>control.tar.gz
-<item>data.tar.gz
-</list>
-
-<p>
-The debian-binary member consists simply of the string "2.0", indicating the
-format version. control.tar.gz contains the control files (and scripts), and
-the data.tar.gz contains the actual files to populate the filesystem with.
-Both tarfiles extract straight into the current directory. Information on the
-tar formats can be found in the GNU tar info page. Since dpkg-deb calls
-"tar -cf" to build packages, the Debian packages use the GNU extensions.
-
-<sect>The dpkg-deb command-line 
-
-<p>
-dpkg-deb documents itself thoroughly with its '--help' command-line option.
-However, I am including a reference to these for completeness. dpkg-deb
-supports the following options:-
-
-<list>
-<item>--build (-b) &lt;dir&gt; - builds a .deb archive, takes a directory which
-contains all the files as an argument. Note that the directory
-&lt;dir&gt;/DEBIAN will be packed separately into the control archive.
-<item>--contents (-c) &lt;debfile&gt; - Lists the contents of the "data.tar.gz"
-member.
-<item>--control (-e) &lt;debfile&gt; - Extracts the control archive into a
-directory called DEBIAN. Alternatively, with another argument, it will extract
-it into a different directory.
-<item>--info (-I) &lt;debfile&gt; - Prints the contents of the "control" file
-in the control archive to stdout. Alternatively, giving it other arguments will
-cause it to print the contents of those files instead.
-<item>--field (-f) &lt;debfile&gt; &lt;field&gt; ... - Prints any number of
-fields from the "control" file. Giving it extra arguments limits the fields it
-prints to only those specified. With no command-line arguments other than a
-filename, it is equivalent to -I and just the .deb filename.
-<item>--extract (-x) &lt;debfile&gt; &lt;dir&gt; - Extracts the data archive
-of a debian package under the directory &lt;dir&gt;.
-<item>--vextract (-X) &lt;debfile&gt; &lt;dir&gt; - Same as --extract, except
-it is equivalent of giving tar the '-v' option - it prints the filenames as
-it extracts them.
-<item>--fsys-tarfile &lt;debfile&gt; - This option outputs a gunzip'd version
-of data.tar.gz to stdout.
-<item>--new - sets the archive format to be used to the new Debian format
-<item>--old - sets the archive format to be used to the old Debian format
-<item>--debug - Tells dpkg-deb to produce debugging output
-<item>--nocheck - Tells dpkg-deb not to check the sanity of the control file
-<item>--help (-h) - Gives a help message
-<item>--version - Shows the version number
-<item>--licence/--license (UK/US spellings) - Shows a brief outline of the GPL
-</list>
-
-<sect1>Internal checks used by dpkg-deb when building packages
-
-<p>
-Here is a list of the internal checks used by dpkg-deb when building packages.
-It is in the order they are done.
-
-<list>
-<item>First, the output Debian archive argument, if it is given, is checked
-using stat. If it is a directory, an internal flag is set. This check is only
-made if the archive name is specified explicitly on the command-line. If the
-argument was not given, the default is the directory name, with ".deb"
-appended.
-<item>Next, the control file is checked, unless the --nocheck flag was
-specified on the command-line. dpkg-deb will bomb out if the second argument
-to --build was a directory, and --nocheck was specified. Note that dpkg-deb
-will not be able to determine the name of the package in this case. In the
-control file, the following things are checked:-
-	<list>
-	<item>The package name is checked to see if it contains any invalid
-	characters (see <ref id="control"> for this).
-	<item>The priority field is checked to see if it uses standard values,
-	and user-defined values are warned against. However, note that this
-	check is now redundant, since the control file no longer contains
-	the priority - the changes file now does this.
-	<item>The control file fields are then checked against the standard
-	list of fields which appear in control files, and any "user-defined"
-	fields are reported as warnings.
-	<item>dpkg-deb then checks that the control file contains a valid
-	version number.
-	</list>
-<item>After this, in the case where a directory was specified to build the
-.deb file in, the filename is created as "directory/pkg_ver.deb" or
-"directory/pkg_ver_arch.deb", depending on whether the control file contains
-an architecture field.
-<item>Next, dpkg-deb checks for the &lt;dir&gt;/DEBIAN directory. It complains
-if it doesn't exist, or if it has permissions &lt; 0755, or &gt; 0775.
-<item>It then checks that all the files in this subdir are either symlinks
-or plain files, and have permissions between 0555 and 0775.
-<item>The conffiles file is then checked to see if the filenames are too
-long. Warnings are produced for each that is. After this, it checks that
-the package provides initial copies of each of these conffiles, and that
-they are all plain files.
-</list>
-
-<chapt>dpkg internals
-
-<p>
-This chapter describes the internals of dpkg itself. Although the low-level
-formats are quite simple, what dpkg does in certain cases often does not
-make sense.
-
-<sect id="updates">Updates
-
-<p>
-This describes the /var/lib/dpkg/updates directory. The function of this
-directory is somewhat strange, and seems only to be used internally. A function
-called cleanupdates is called whenever the database is scanned. This function
-in turn uses <manref name="scandir" section="3">, to sort the files in this
-directory. Files who names do not consist entirely of digits are discarded.
-dpkg also causes a fatal error if any of the filenames are different lengths.
-
-<p>
-After having scanned the directory, dpkg in turn parses each file the same way
-it parses the status file (they are sorted by the scandir to be in numerical
-order). After having done this, it then writes the status information back
-to the "status" file, and removes all the "updates" files.
-
-<p>
-These files are created internally by dpkg's "checkpoint" function, and are
-cleaned up when dpkg exits cleanly.
-
-<p>
-Juding by the use of the updates directory I would call it a Journal. Inorder
-to efficiently ensure the complete integrity of the status file dpkg will
-"checkpoint" or journal all of it's activities in the updates directory. By
-merging the contents of the updates directory (in order!!) against the 
-original status file it can get the precise current state of the system,
-even in the event of a system failure while dpkg is running.
-
-<p> 
-The other option would be to sync-rewrite the status file after each 
-operation, which would kill performance.
-
-<p>
-It is very important that any program that uses the status file abort if
-the updates directory is not empty! The user should be informed to run dpkg
-manually (what options though??) to correct the situation.
-
-<sect>What happens when dpkg reads the database
-
-<p>
-First, the status file is read. This gives dpkg an initial idea of the packages
-that are there. Next, the updates files are read in, overriding the status
-file, and if necessary, the status file is re-written, and updates files are
-removed. Finally, the available file is read. The available file is read
-with flags which preclude dpkg from updating any status information from it,
-though - installed version, etc., and is also told to record that the packages
-it reads this time are available, not installed.
-
-<p>
-More information on updates is given above.
-
-<sect>How dpkg compares version numbers
-
-<p>
-Version numbers consist of three parts: the epoch, the upstream version, and
-the Debian revision. Dpkg compares these parts in that order. If the epochs
-are different, it returns immediately, and so on.
-
-<p>
-However, the important part is how it compares the versions which are
-essentially stored as just strings. These are compared in two distinct parts:
-those consisting of numerical characters (which are evaluated, and then
-compared), and those consisting of other characters. When comparing
-non-numerical parts, they are compared as the character values (ASCII), but
-non-alphabetical characters are considered "greater than" alphabetical ones.
-Also note that longer strings (after excluding differences where numerical
-values are equal) are considered "greater than" shorter ones.
-
-<p>
-Here are a few examples of how these rules apply:-
-
-<example>
-15 > 10
-0010 == 10
-
-d.r > dsr
-32.d.r == 0032.d.r
-d.rnr < d.rnrn
-</example>
-
-</book>

doc/files.dbk

@@ -0,0 +1,392 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+]>
+
+<book lang="en">
+
+<title>APT Files</title>
+
+<bookinfo>
+
+<authorgroup>
+  <author>
+    <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email>
+  </author>
+</authorgroup>
+
+<releaseinfo>Version &apt-product-version;</releaseinfo>
+
+<abstract>
+<para>
+This document describes the complete implementation and format of the installed
+APT directory structure. It also serves as guide to how APT views the Debian
+archive.
+</para>
+</abstract>
+
+<copyright><year>1998-1999</year><holder>Jason Gunthorpe</holder></copyright>
+
+<legalnotice>
+<title>License Notice</title>
+<para>
+"APT" and this document are free software; you can redistribute them and/or
+modify them under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or (at your
+option) any later version.
+</para>
+<para>
+For more details, on Debian systems, see the file
+/usr/share/common-licenses/GPL for the full license.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+<chapter id="ch1"><title>Introduction</title>
+
+<section id="s1.1"><title>General</title>
+<para>
+This document serves two purposes. The first is to document the installed
+directory structure and the format and purpose of each file. The second
+purpose is to document how APT views the Debian archive and deals with multiple
+package files.
+</para>
+<para>
+The var directory structure is as follows:
+</para>
+<screen>
+  /var/lib/apt/
+		lists/
+		       partial/
+		periodic/
+		extended_states
+		cdroms.list
+  /var/cache/apt/
+		  archives/
+		          partial/
+		  pkgcache.bin
+		  srcpkgcache.bin
+  /etc/apt/
+	    sources.list.d/
+	    apt.conf.d/
+	    preferences.d/
+	    trusted.gpg.d/
+	    sources.list
+	    apt.conf
+	    apt_preferences
+	    trusted.gpg
+  /usr/lib/apt/
+	        methods/
+			 bzip2
+			 cdrom
+			 copy
+			 file
+			 ftp
+			 gpgv
+			 gzip
+			 http
+			 https
+			 lzma
+			 rred
+			 rsh
+			 ssh
+</screen>
+<para>
+As is specified in the FHS 2.1 /var/lib/apt is used for application data that
+is not expected to be user modified. /var/cache/apt is used for regeneratable
+data and is where the package cache and downloaded .debs go. /etc/apt is the
+place where configuration should happen and /usr/lib/apt is the place where the
+apt and other packages can place binaries which can be used by the acquire
+system of APT.
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch2"><title>Files</title>
+
+<section id="s2.1"><title>Files and fragment directories in /etc/apt</title>
+<para>
+All files in /etc/apt are used to modify specific aspects of APT. To enable
+other packages to ship needed configuration herself all these files have a
+fragment directory packages can place their files in instead of mangling with
+the main files. The main files are therefore considered to be only used by the
+user and not by a package. The documentation omits this directories most of
+the time to be easier readable, so every time the documentation includes a
+reference to a main file it really means the file or the fragment directories.
+</para>
+</section>
+
+<section id="s2.2"><title>Distribution Source list (sources.list)</title>
+<para>
+The distribution source list is used to locate archives of the debian
+distribution. It is designed to support any number of active sources and to
+support a mix of source media. The file lists one source per line, with the
+fastest source listed first. The format of each line is:
+</para>
+<para>
+<replaceable>type uri args</replaceable>
+</para>
+<para>
+The first item, <replaceable>type</replaceable>, indicates the format for the
+remainder of the line. It is designed to indicate the structure of the
+distribution the line is talking about. Currently the only defined values are
+<emphasis>deb</emphasis> and <emphasis>deb-src</emphasis> which indicate a
+standard debian (source) archive with a dists directory. More about these
+types and the URI specification can be found in the sources.list manpage.
+</para>
+
+<section id="s2.2.1"><title>Hashing the URI</title>
+<para>
+All permanent information acquired from any of the sources is stored in the
+lists directory. Thus, there must be a way to relate the filename in the lists
+directory to a line in the sourcelist. To simplify things this is done by
+quoting the URI and treating _'s as quoteable characters and converting /
+to _. The URI spec says this is done by converting a sensitive character
+into %xx where xx is the hexadecimal representation from the ASCII character
+set. Examples:
+</para>
+<screen>
+http://www.debian.org/archive/dists/stable/binary-i386/Packages
+/var/lib/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages
+
+cdrom:Debian 1.3/debian/Packages
+/var/lib/apt/info/Debian%201.3_debian_Packages
+</screen>
+<para>
+The other alternative that was considered was to use a deep directory structure
+but this poses two problems, it makes it very difficult to prune directories
+back when sources are no longer used and complicates the handling of the
+partial directory. This gives a very simple way to deal with all of the
+situations that can arise. Also note that the same rules described in the
+<emphasis>Archive Directory</emphasis> section regarding the partial sub dir
+apply here as well.
+</para>
+</section>
+
+</section>
+
+<section id="s2.3"><title>Extended States File (extended_states)</title>
+<para>
+The extended_states file serves the same purpose as the normal dpkg status
+file (/var/lib/dpkg/status) except that it stores information unique to
+apt. This includes currently only the autoflag but is open to store more
+unique data that come up over time. It duplicates nothing from the normal
+dpkg status file. Please see other APT documentation for a discussion of
+the exact internal behavior of these fields. The Package and the Architecture
+field are placed directly before the new fields to indicate which package
+they apply to. The new fields are as follows:
+</para>
+<variablelist>
+<varlistentry>
+<term>Auto-Installed</term>
+<listitem>
+<para>
+The Auto flag can be 1 (Yes) or 0 (No) and controls whether the package was
+automatical installed to satisfy a dependency or if the user requested the
+installation
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+
+<section id="s2.4"><title>Binary Package Cache (srcpkgcache.bin and pkgcache.bin)</title>
+<para>
+Please see cache.sgml for a complete description of what this file
+is. The cache file is updated whenever the contents of the lists
+directory changes. If the cache is erased, corrupted or of a non-matching
+version it will be automatically rebuilt by all of the tools that need
+it. <emphasis>srcpkgcache.bin</emphasis> contains a cache of all of the
+package files in the source list. This allows regeneration of the cache
+when the status files change to use a prebuilt version for greater speed.
+</para>
+</section>
+
+<section id="s2.5"><title>Downloads Directory (archives)</title>
+<para>
+The archives directory is where all downloaded .deb archives go. When the file
+transfer is initiated the deb is placed in partial. Once the file is fully
+downloaded and its MD5 hash and size are verified it is moved from partial
+into archives/. Any files found in archives/ can be assumed to be verified.
+</para>
+<para>
+No directory structure is transferred from the receiving site and all .deb file
+names conform to debian conventions. No short (msdos) filename should be
+placed in archives. If the need arises .debs should be unpacked, scanned and
+renamed to their correct internal names. This is mostly to prevent file name
+conflicts but other programs may depend on this if convenient. A conforming
+.deb is one of the form, name_version_arch.deb. Our archive scripts do not
+handle epochs, but they are necessary and should be re-inserted. If necessary
+_'s and :'s in the fields should be quoted using the % convention. It must be
+possible to extract all 3 fields by examining the file name. Downloaded .debs
+must be found in one of the package lists with an exact name + version match..
+</para>
+</section>
+
+<section id="s2.6"><title>The Methods Directory (/usr/lib/apt/methods)</title>
+<para>
+The Methods directory is more fully described in the APT Methods interface
+document.
+</para>
+</section>
+
+<section id="s2.7"><title>The Configuration File (/etc/apt/apt.conf)</title>
+<para>
+The configuration file (and the associated fragments directory
+/etc/apt/apt.conf.d/) is described in the apt.conf manpage.
+</para>
+</section>
+
+<section id="s2.8"><title>The trusted.gpg File (/etc/apt/trusted.gpg)</title>
+<para>
+The trusted.gpg file (and the files in the associated fragments directory
+/etc/apt/trusted.gpg.d/) is a binary file including the keyring used by apt to
+validate that the information (e.g. the Release file) it downloads are really
+from the distributor it clams to be and is unmodified and is therefore the last
+step in the chain of trust between the archive and the end user. This security
+system is described in the apt-secure manpage.
+</para>
+</section>
+
+<section id="s2.9"><title>The Release File</title>
+<para>
+This file plays an important role in how APT presents the archive to the
+user. Its main purpose is to present a descriptive name for the source of
+each version of each package. It also is used to detect when new versions
+of debian are released. It augments the package file it is associated with
+by providing meta information about the entire archive which the Packages
+file describes.
+</para>
+<para>
+The full name of the distribution for presentation to the user is formed as
+'label version archive', with a possible extended name being 'label version
+archive component'.
+</para>
+<para>
+The file is formed as the package file (RFC-822) with the following tags
+defined:
+</para>
+<variablelist>
+<varlistentry>
+<term>Archive</term>
+<listitem>
+<para>
+This is the common name we give our archives, such as
+<emphasis>stable</emphasis> or <emphasis>unstable</emphasis>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Component</term>
+<listitem>
+<para>
+Refers to the sub-component of the archive, <emphasis>main</emphasis>,
+<emphasis>contrib</emphasis> etc. Component may be omitted if there are no
+components for this archive.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Version</term>
+<listitem>
+<para>
+This is a version string with the same properties as in the Packages file. It
+represents the release level of the archive.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Origin</term>
+<listitem>
+<para>
+This specifies who is providing this archive. In the case of Debian the string
+will read 'Debian'. Other providers may use their own string
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Label</term>
+<listitem>
+<para>
+This carries the encompassing name of the distribution. For Debian proper this
+field reads 'Debian'. For derived distributions it should contain their proper
+name.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Architecture</term>
+<listitem>
+<para>
+When the archive has packages for a single architecture then the Architecture
+is listed here. If a mixed set of systems are represented then this should
+contain the keyword <emphasis>mixed</emphasis>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>NotAutomatic</term>
+<listitem>
+<para>
+A Yes/No flag indicating that the archive is extremely unstable and its
+version's should never be automatically selected. This is to be used by
+experimental.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Description</term>
+<listitem>
+<para>
+Description is used to describe the release. For instance experimental would
+contain a warning that the packages have problems.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+The location of the Release file in the archive is very important, it must be
+located in the same location as the packages file so that it can be located in
+all situations. The following is an example for the current stable release,
+1.3.1r6
+</para>
+<screen>
+Archive: stable
+Component: main
+Version: 1.3.1r6
+Origin: Debian
+Label: Debian
+Architecture: i386
+</screen>
+<para>
+This is an example of experimental,
+</para>
+<screen>
+Archive: experimental
+Version: 0
+Origin: Debian
+Label: Debian
+Architecture: mixed
+NotAutomatic: Yes
+</screen>
+<para>
+And unstable,
+</para>
+<screen>
+Archive: unstable
+Component: main
+Version: 2.1
+Origin: Debian
+Label: Debian
+Architecture: i386
+</screen>
+</section>
+
+</chapter>
+
+
+</book>

doc/files.sgml

@@ -1,345 +0,0 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
-<book>
-<title>APT Files</title>
-
-<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: files.sgml,v 1.12 2003/04/26 23:26:13 doogie Exp $</version>
-
-<abstract>
-This document describes the complete implementation and format of the 
-installed APT directory structure. It also serves as guide to how APT 
-views the Debian archive.
-</abstract>
-
-<copyright>
-Copyright &copy; Jason Gunthorpe, 1998-1999.
-<p>
-"APT" and this document are free software; you can redistribute them and/or
-modify them under the terms of the GNU General Public License as published
-by the Free Software Foundation; either version 2 of the License, or (at your
-option) any later version.
-
-<p>
-For more details, on Debian systems, see the file
-/usr/share/common-licenses/GPL for the full license.
-</copyright>
-
-<toc sect>
-
-<chapt>Introduction
-<!-- General		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>General
-
-<p>
-This document serves two purposes. The first is to document the installed
-directory structure and the format and purpose of each file. The second
-purpose is to document how APT views the Debian archive and deals with 
-multiple package files.
-
-<p>
-The var directory structure is as follows:
-<example>
-  /var/lib/apt/
-		lists/
-		       partial/
-		periodic/
-		extended_states
-		cdroms.list
-  /var/cache/apt/
-		  archives/
-		          partial/
-		  pkgcache.bin
-		  srcpkgcache.bin
-  /etc/apt/
-	    sources.list.d/
-	    apt.conf.d/
-	    preferences.d/
-	    trusted.gpg.d/
-	    sources.list
-	    apt.conf
-	    apt_preferences
-	    trusted.gpg
-  /usr/lib/apt/
-	        methods/
-			 bzip2
-			 cdrom
-			 copy
-			 file
-			 ftp
-			 gpgv
-			 gzip
-			 http
-			 https
-			 lzma
-			 rred
-			 rsh
-			 ssh
-</example>
-
-<p>
-As is specified in the FHS 2.1 /var/lib/apt is used for application 
-data that is not expected to be user modified. /var/cache/apt is used
-for regeneratable data and is where the package cache and downloaded .debs
-go. /etc/apt is the place where configuration should happen and
-/usr/lib/apt is the place where the apt and other packages can place
-binaries which can be used by the acquire system of APT.
-</sect>
-                                                                  <!-- }}} -->
-
-<chapt>Files
-<!-- Distribution Source List					       {{{ -->
-<!-- ===================================================================== -->
-<sect>Files and fragment directories in /etc/apt
-
-<p>
-All files in /etc/apt are used to modify specific aspects of APT. To enable
-other packages to ship needed configuration herself all these files have
-a fragment directory packages can place their files in instead of mangling
-with the main files. The main files are therefore considered to be only
-used by the user and not by a package. The documentation omits this directories
-most of the time to be easier readable, so every time the documentation includes
-a reference to a main file it really means the file or the fragment directories.
-
-</sect>
-
-<sect>Distribution Source list (sources.list)
-
-<p>
-The distribution source list is used to locate archives of the debian
-distribution. It is designed to support any number of active sources and to
-support a mix of source media. The file lists one source per line, with the 
-fastest source listed first. The format of each line is:
-
-<p>
-<var>type uri args</var>
-
-<p>
-The first item, <var>type</var>, indicates the format for the remainder 
-of the line. It is designed to indicate the structure of the distribution
-the line is talking about. Currently the only defined values are <em>deb</em>
-and <em>deb-src</em> which indicate a standard debian (source) archive with a
-dists directory. More about these types and the URI specification can be found
-in the sources.list manpage.
-
-<sect1>Hashing the URI
-<p>
-All permanent information acquired from any of the sources is stored in the
-lists directory. Thus, there must be a way to relate the filename in the
-lists directory to a line in the sourcelist. To simplify things this is
-done by quoting the URI and treating _'s as quoteable characters and
-converting / to _. The URI spec says this is done by converting a 
-sensitive character into %xx where xx is the hexadecimal representation 
-from the ASCII character set. Examples:
-
-<example>
-http://www.debian.org/archive/dists/stable/binary-i386/Packages 
-/var/lib/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages
-
-cdrom:Debian 1.3/debian/Packages
-/var/lib/apt/info/Debian%201.3_debian_Packages
-</example>
-
-<p> 
-The other alternative that was considered was to use a deep directory 
-structure but this poses two problems, it makes it very difficult to prune
-directories back when sources are no longer used and complicates the handling
-of the partial directory. This gives a very simple way to deal with all
-of the situations that can arise. Also note that the same rules described in 
-the <em>Archive Directory</> section regarding the partial sub dir apply 
-here as well.
-</sect1>
-
-</sect>
-                                                                  <!-- }}} -->
-<!-- Extended Status						       {{{ -->
-<!-- ===================================================================== -->
-<sect>Extended States File (extended_states)
-
-<p>
-The extended_states file serves the same purpose as the normal dpkg status file
-(/var/lib/dpkg/status) except that it stores information unique to apt.
-This includes currently only the autoflag but is open to store more
-unique data that come up over time. It duplicates nothing from the normal
-dpkg status file.  Please see other APT documentation for a discussion
-of the exact internal behavior of these fields. The Package and the
-Architecture field are placed directly before the new fields to indicate
-which package they apply to. The new fields are as follows:
-
-<taglist>
-<tag>Auto-Installed<item>
-   The Auto flag can be 1 (Yes) or 0 (No) and controls whether the package
-   was automatical installed to satisfy a dependency or if the user requested
-   the installation
-</taglist>
-</sect>
-                                                                  <!-- }}} -->
-<!-- Binary Package Cache					       {{{ -->
-<!-- ===================================================================== -->
-<sect>Binary Package Cache (srcpkgcache.bin and pkgcache.bin)
-
-<p>
-Please see cache.sgml for a complete description of what this file is. The 
-cache file is updated whenever the contents of the lists directory changes.
-If the cache is erased, corrupted or of a non-matching version it will
-be automatically rebuilt by all of the tools that need it. 
-<em>srcpkgcache.bin</> contains a cache of all of the package files in the 
-source list. This allows regeneration of the cache when the status files 
-change to use a prebuilt version for greater speed.
-</sect>
-                                                                  <!-- }}} -->
-<!-- Downloads Directory					       {{{ -->
-<!-- ===================================================================== -->
-<sect>Downloads Directory (archives)
-
-<p>
-The archives directory is where all downloaded .deb archives go. When the
-file transfer is initiated the deb is placed in partial. Once the file
-is fully downloaded and its MD5 hash and size are verified it is moved
-from partial into archives/. Any files found in archives/ can be assumed 
-to be verified.
-
-<p>
-No directory structure is transferred from the receiving site and all .deb
-file names conform to debian conventions. No short (msdos) filename should
-be placed in archives. If the need arises .debs should be unpacked, scanned
-and renamed to their correct internal names. This is mostly to prevent
-file name conflicts but other programs may depend on this if convenient. 
-A conforming .deb is one of the form, name_version_arch.deb. Our archive
-scripts do not handle epochs, but they are necessary and should be re-inserted.
-If necessary _'s and :'s in the fields should be quoted using the % convention.
-It must be possible to extract all 3 fields by examining the file name.
-Downloaded .debs must be found in one of the package lists with an exact
-name + version match..
-</sect>
-                                                                  <!-- }}} -->
-<!-- The Methods Directory					       {{{ -->
-<!-- ===================================================================== -->
-<sect> The Methods Directory (/usr/lib/apt/methods)
-
-<p>
-The Methods directory is more fully described in the APT Methods interface
-document.
-</sect>
-                                                                  <!-- }}} -->
-<!-- The Configuration File					       {{{ -->
-<!-- ===================================================================== -->
-<sect> The Configuration File (/etc/apt/apt.conf)
-
-<p>
-The configuration file (and the associated fragments directory
-/etc/apt/apt.conf.d/) is described in the apt.conf manpage.
-</sect>
-                                                                  <!-- }}} -->
-<!-- The trusted.gpg File					       {{{ -->
-<!-- ===================================================================== -->
-<sect> The trusted.gpg File (/etc/apt/trusted.gpg)
-
-<p>
-The trusted.gpg file (and the files in the associated fragments directory
-/etc/apt/trusted.gpg.d/) is a binary file including the keyring used
-by apt to validate that the information (e.g. the Release file) it
-downloads are really from the distributor it clams to be and is
-unmodified and is therefore the last step in the chain of trust between
-the archive and the end user. This security system is described in the
-apt-secure manpage.
-</sect>
-                                                                  <!-- }}} -->
-<!-- The Release File						       {{{ -->
-<!-- ===================================================================== -->
-<sect> The Release File
-
-<p>
-This file plays an important role in how APT presents the archive to the 
-user. Its main purpose is to present a descriptive name for the source
-of each version of each package. It also is used to detect when new versions
-of debian are released. It augments the package file it is associated with 
-by providing meta information about the entire archive which the Packages
-file describes.
-
-<p>
-The full name of the distribution for presentation to the user is formed
-as 'label version archive', with a possible extended name being 
-'label version archive component'.
-
-<p>
-The file is formed as the package file (RFC-822) with the following tags
-defined:
-
-<taglist>
-<tag>Archive<item>
-This is the common name we give our archives, such as <em>stable</> or
-<em>unstable</>.
-
-<tag>Component<item>
-Refers to the sub-component of the archive, <em>main</>, <em>contrib</>
-etc. Component may be omitted if there are no components for this archive.
-
-<tag>Version<item>
-This is a version string with the same properties as in the Packages file.
-It represents the release level of the archive.
-
-<tag>Origin<item>
-This specifies who is providing this archive. In the case of Debian the
-string will read 'Debian'. Other providers may use their own string
-
-<tag>Label<item>
-This carries the encompassing name of the distribution. For Debian proper
-this field reads 'Debian'. For derived distributions it should contain their 
-proper name.
-
-<tag>Architecture<item>
-When the archive has packages for a single architecture then the Architecture
-is listed here. If a mixed set of systems are represented then this should
-contain the keyword <em>mixed</em>.
-
-<tag>NotAutomatic<item>
-A Yes/No flag indicating that the archive is extremely unstable and its
-version's should never be automatically selected. This is to be used by 
-experimental.
-
-<tag>Description<item>
-Description is used to describe the release. For instance experimental would
-contain a warning that the packages have problems.
-</taglist>
-
-<p>
-The location of the Release file in the archive is very important, it must 
-be located in the same location as the packages file so that it can be 
-located in all situations. The following is an example for the current stable
-release, 1.3.1r6 
-
-<example>
-Archive: stable
-Component: main
-Version: 1.3.1r6
-Origin: Debian
-Label: Debian
-Architecture: i386
-</example>
-
-This is an example of experimental,
-<example>
-Archive: experimental
-Version: 0
-Origin: Debian
-Label: Debian
-Architecture: mixed
-NotAutomatic: Yes
-</example>
-
-And unstable,
-<example>
-Archive: unstable
-Component: main
-Version: 2.1
-Origin: Debian
-Label: Debian
-Architecture: i386
-</example>
-
-</sect>
-                                                                  <!-- }}} -->
-
-</book>

doc/guide.dbk

@@ -0,0 +1,560 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+]>
+
+<book lang="en">
+
+<title>APT User's Guide</title>
+
+<bookinfo>
+
+<authorgroup>
+  <author>
+    <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email>
+  </author>
+</authorgroup>
+
+<releaseinfo>Version &apt-product-version;</releaseinfo>
+
+<abstract>
+<para>
+This document provides an overview of how to use the the APT package manager.
+</para>
+</abstract>
+
+<copyright><year>1998</year><holder>Jason Gunthorpe</holder></copyright>
+
+<legalnotice>
+<title>License Notice</title>
+<para>
+"APT" and this document are free software; you can redistribute them and/or
+modify them under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or (at your
+option) any later version.
+</para>
+</legalnotice>
+
+<legalnotice>
+<para>
+For more details, on Debian systems, see the file
+/usr/share/common-licenses/GPL for the full license.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+<chapter id="ch1"><title>General</title>
+<para>
+The APT package currently contains two sections, the APT
+<command>dselect</command> method and the <command>apt-get</command> command
+line user interface. Both provide a way to install and remove packages as well
+as download new packages from the Internet.
+</para>
+
+<section id="s1.1"><title>Anatomy of the Package System</title>
+<para>
+The Debian packaging system has a large amount of information associated with
+each package to help assure that it integrates cleanly and easily into the
+system. The most prominent of its features is the dependency system.
+</para>
+<para>
+The dependency system allows individual programs to make use of shared elements
+in the system such as libraries. It simplifies placing infrequently used
+portions of a program in separate packages to reduce the number of things the
+average user is required to install. Also, it allows for choices in mail
+transport agents, X servers and so on.
+</para>
+<para>
+The first step to understanding the dependency system is to grasp the concept
+of a simple dependency. The meaning of a simple dependency is that a package
+requires another package to be installed at the same time to work properly.
+</para>
+<para>
+For instance, mailcrypt is an emacs extension that aids in encrypting email
+with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a
+simple dependency on GPG. Also, because it is an emacs extension it has a
+simple dependency on emacs, without emacs it is completely useless.
+</para>
+<para>
+The other important dependency to understand is a conflicting dependency. It
+means that a package, when installed with another package, will not work and
+may possibly be extremely harmful to the system. As an example consider a mail
+transport agent such as sendmail, exim or qmail. It is not possible to have
+two mail transport agents installed because both need to listen to the network
+to receive mail. Attempting to install two will seriously damage the system so
+all mail transport agents have a conflicting dependency with all other mail
+transport agents.
+</para>
+<para>
+As an added complication there is the possibility for a package to pretend to
+be another package. Consider that exim and sendmail for many intents are
+identical, they both deliver mail and understand a common interface. Hence,
+the package system has a way for them to declare that they are both
+mail-transport-agents. So, exim and sendmail both declare that they provide a
+mail-transport-agent and other packages that need a mail transport agent depend
+on mail-transport-agent. This can add a great deal of confusion when trying to
+manually fix packages.
+</para>
+<para>
+At any given time a single dependency may be met by packages that are already
+installed or it may not be. APT attempts to help resolve dependency issues by
+providing a number of automatic algorithms that help in selecting packages for
+installation.
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch2"><title>apt-get</title>
+<para>
+<command>apt-get</command> provides a simple way to install packages from the
+command line. Unlike <command>dpkg</command>, <command>apt-get</command> does
+not understand .deb files, it works with the package's proper name and can only
+install .deb archives from a <emphasis>Source</emphasis>.
+</para>
+<para>
+The first <footnote><para> If you are using an http proxy server you must set
+the http_proxy environment variable first, see sources.list(5) </para>
+</footnote> thing that should be done before using <command>apt-get</command>
+is to fetch the package lists from the <emphasis>Sources</emphasis> so that it
+knows what packages are available. This is done with <literal>apt-get
+update</literal>. For instance,
+</para>
+<screen>
+# apt-get update
+Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
+Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages
+Reading Package Lists... Done
+Building Dependency Tree... Done
+</screen>
+<para>
+Once updated there are several commands that can be used:
+</para>
+<variablelist>
+<varlistentry>
+<term>upgrade</term>
+<listitem>
+<para>
+Upgrade will attempt to gently upgrade the whole system. Upgrade will never
+install a new package or remove an existing package, nor will it ever upgrade a
+package that might cause some other package to break. This can be used daily
+to relatively safely upgrade the system. Upgrade will list all of the packages
+that it could not upgrade, this usually means that they depend on new packages
+or conflict with some other package. <command>dselect</command> or
+<literal>apt-get install</literal> can be used to force these packages to
+install.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>install</term>
+<listitem>
+<para>
+Install is used to install packages by name. The package is automatically
+fetched and installed. This can be useful if you already know the name of the
+package to install and do not want to go into a GUI to select it. Any number
+of packages may be passed to install, they will all be fetched. Install
+automatically attempts to resolve dependency problems with the listed packages
+and will print a summary and ask for confirmation if anything other than its
+arguments are changed.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>dist-upgrade</term>
+<listitem>
+<para>
+Dist-upgrade is a complete upgrader designed to simplify upgrading between
+releases of Debian. It uses a sophisticated algorithm to determine the best
+set of packages to install, upgrade and remove to get as much of the system to
+the newest release. In some situations it may be desired to use dist-upgrade
+rather than spend the time manually resolving dependencies in
+<command>dselect</command>. Once dist-upgrade has completed then
+<command>dselect</command> can be used to install any packages that may have
+been left out.
+</para>
+<para>
+It is important to closely look at what dist-upgrade is going to do, its
+decisions may sometimes be quite surprising.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+<command>apt-get</command> has several command line options that are detailed
+in its man page,
+<citerefentry><refentrytitle>apt-get</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
+most useful option is <literal>-d</literal> which does not install the
+fetched files. If the system has to download a large number of package it
+would be undesired to start installing them in case something goes wrong. When
+<literal>-d</literal> is used the downloaded archives can be installed by
+simply running the command that caused them to be downloaded again without
+<literal>-d</literal>.
+</para>
+</chapter>
+
+<chapter id="ch3"><title>DSelect</title>
+<para>
+The APT <command>dselect</command> method provides the complete
+APT system with the <command>dselect</command> package selection
+GUI. <command>dselect</command> is used to select the packages to be
+installed or removed and APT actually installs them.
+</para>
+<para>
+To enable the APT method you need to select [A]ccess in
+<command>dselect</command> and then choose the APT method. You will be
+prompted for a set of <emphasis>Sources</emphasis> which are places to fetch
+archives from. These can be remote Internet sites, local Debian mirrors or
+CD-ROMs. Each source can provide a fragment of the total Debian archive, APT
+will automatically combine them to form a complete set of packages. If you
+have a CD-ROM then it is a good idea to specify it first and then specify a
+mirror so that you have access to the latest bug fixes. APT will automatically
+use packages on your CD-ROM before downloading from the Internet.
+</para>
+<screen>
+   Set up a list of distribution source locations
+
+ Please give the base URL of the debian distribution.
+ The access schemes I know about are: http file
+
+ For example:
+      file:/mnt/debian,
+      ftp://ftp.debian.org/debian,
+      http://ftp.de.debian.org/debian,
+
+
+ URL [http://llug.sep.bnl.gov/debian]:
+</screen>
+<para>
+The <emphasis>Sources</emphasis> setup starts by asking for the base of the
+Debian archive, defaulting to a HTTP mirror. Next it asks for the distribution
+to get.
+</para>
+<screen>
+ Please give the distribution tag to get or a path to the
+ package file ending in a /. The distribution
+ tags are typically something like: stable unstable testing non-US
+
+ Distribution [stable]:
+</screen>
+<para>
+The distribution refers to the Debian version in the archive,
+<emphasis>stable</emphasis> refers to the latest released version
+and <emphasis>unstable</emphasis> refers to the developmental
+version. <emphasis>non-US</emphasis> is only available on some mirrors
+and refers to packages that contain encryption technology or other
+things that cannot be exported from the United States. Importing these
+packages into the US is legal however.
+</para>
+<screen>
+ Please give the components to get
+ The components are typically something like: main contrib non-free
+
+ Components [main contrib non-free]:
+</screen>
+<para>
+The components list refers to the list of sub distributions to fetch. The
+distribution is split up based on software licenses, main being DFSG free
+packages while contrib and non-free contain things that have various
+restrictions placed on their use and distribution.
+</para>
+<para>
+Any number of sources can be added, the setup script will continue to prompt
+until you have specified all that you want.
+</para>
+<para>
+Before starting to use <command>dselect</command> it is necessary to update
+the available list by selecting [U]pdate from the menu. This is a superset of
+<literal>apt-get update</literal> that makes the fetched information available
+to <command>dselect</command>. [U]pdate must be performed even if
+<literal>apt-get update</literal> has been run before.
+</para>
+<para>
+You can then go on and make your selections using [S]elect and then perform
+the installation using [I]nstall. When using the APT method the [C]onfig and
+[R]emove commands have no meaning, the [I]nstall command performs both of
+them together.
+</para>
+<para>
+By default APT will automatically remove the package (.deb) files once they
+have been successfully installed. To change this behavior place
+<literal>Dselect::clean "prompt";</literal> in /etc/apt/apt.conf.
+</para>
+</chapter>
+
+<chapter id="ch4"><title>The Interface</title>
+<para>
+Both that APT <command>dselect</command> method and <command>apt-get</command>
+share the same interface. It is a simple system that generally tells you what
+it will do and then goes and does it. <footnote><para> The
+<command>dselect</command> method actually is a set of wrapper scripts to
+<command>apt-get</command>. The method actually provides more functionality
+than is present in <command>apt-get</command> alone. </para> </footnote> After
+printing out a summary of what will happen APT then will print out some
+informative status messages so that you can estimate how far along it is and
+how much is left to do.
+</para>
+
+<section id="s4.1"><title>Startup</title>
+<para>
+Before all operations except update, APT performs a number of actions
+to prepare its internal state. It also does some checks of the system's
+state. At any time these operations can be performed by running
+<literal>apt-get check</literal>.
+</para>
+<screen>
+# apt-get check
+Reading Package Lists... Done
+Building Dependency Tree... Done
+</screen>
+<para>
+The first thing it does is read all the package files into memory. APT uses a
+caching scheme so this operation will be faster the second time it is run. If
+some of the package files are not found then they will be ignored and a
+warning will be printed when apt-get exits.
+</para>
+<para>
+The final operation performs a detailed analysis of the system's
+dependencies. It checks every dependency of every installed or unpacked
+package and considers if it is OK. Should this find a problem then a report
+will be printed out and <command>apt-get</command> will refuse to run.
+</para>
+<screen>
+# apt-get check
+Reading Package Lists... Done
+Building Dependency Tree... Done
+You might want to run apt-get -f install' to correct these.
+Sorry, but the following packages have unmet dependencies:
+  9fonts: Depends: xlib6g but it is not installed
+  uucp: Depends: mailx but it is not installed
+  blast: Depends: xlib6g (&gt;= 3.3-5) but it is not installed
+  adduser: Depends: perl-base but it is not installed
+  aumix: Depends: libgpmg1 but it is not installed
+  debiandoc-sgml: Depends: sgml-base but it is not installed
+  bash-builtins: Depends: bash (&gt;= 2.01) but 2.0-3 is installed
+  cthugha: Depends: svgalibg1 but it is not installed
+           Depends: xlib6g (&gt;= 3.3-5) but it is not installed
+  libreadlineg2: Conflicts:libreadline2 (&lt;&lt; 2.1-2.1)
+</screen>
+<para>
+In this example the system has many problems, including a serious problem with
+libreadlineg2. For each package that has unmet dependencies a line is printed
+out indicating the package with the problem and the dependencies that are
+unmet. A short explanation of why the package has a dependency problem is also
+included.
+</para>
+<para>
+There are two ways a system can get into a broken state like this. The
+first is caused by <command>dpkg</command> missing some subtle relationships
+between packages when performing upgrades. <footnote><para> APT however
+considers all known dependencies and attempts to prevent broken
+packages </para> </footnote>. The second is if a package installation
+fails during an operation. In this situation a package may have been
+unpacked without its dependents being installed.
+</para>
+<para>
+The second situation is much less serious than the first because APT places
+certain constraints on the order that packages are installed. In both cases
+supplying the <literal>-f</literal> option to <command>apt-get</command>
+will cause APT to deduce a possible solution to the problem and then
+continue on. The APT <command>dselect</command> method always supplies
+the <literal>-f</literal> option to allow for easy continuation of failed
+maintainer scripts.
+</para>
+<para>
+However, if the <literal>-f</literal> option is used to correct a seriously
+broken system caused by the first case then it is possible that it will either
+fail immediately or the installation sequence will fail. In either case it is
+necessary to manually use dpkg (possibly with forcing options) to correct the
+situation enough to allow APT to proceed.
+</para>
+</section>
+
+<section id="s4.2"><title>The Status Report</title>
+<para>
+Before proceeding <command>apt-get</command> will present a report on what will
+happen. Generally the report reflects the type of operation being performed
+but there are several common elements. In all cases the lists reflect the
+final state of things, taking into account the <literal>-f</literal> option
+and any other relevant activities to the command being executed.
+</para>
+
+<section id="s4.2.1"><title>The Extra Package list</title>
+<screen>
+The following extra packages will be installed:
+  libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl
+  mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base
+  bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy
+  squake pgp-i python-base debmake ldso perl libreadlineg2
+  ssh
+</screen>
+<para>
+The Extra Package list shows all of the packages that will be installed or
+upgraded in excess of the ones mentioned on the command line. It is only
+generated for an <literal>install</literal> command. The listed packages are
+often the result of an Auto Install.
+</para>
+</section>
+
+<section id="s4.2.2"><title>The Packages to Remove</title>
+<screen>
+The following packages will be REMOVED:
+  xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix
+  xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel
+  xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid
+  nas xpilot xfig
+</screen>
+<para>
+The Packages to Remove list shows all of the packages that will be removed
+from the system. It can be shown for any of the operations and should be given
+a careful inspection to ensure nothing important is to be taken off. The
+<literal>-f</literal> option is especially good at generating packages to
+remove so extreme care should be used in that case. The list may contain
+packages that are going to be removed because they are only partially
+installed, possibly due to an aborted installation.
+</para>
+</section>
+
+<section id="s4.2.3"><title>The New Packages list</title>
+<screen>
+The following NEW packages will installed:
+  zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
+</screen>
+<para>
+The New Packages list is simply a reminder of what will happen. The packages
+listed are not presently installed in the system but will be when APT is done.
+</para>
+</section>
+
+<section id="s4.2.4"><title>The Kept Back list</title>
+<screen>
+The following packages have been kept back
+  compface man-db tetex-base msql libpaper svgalib1
+  gs snmp arena lynx xpat2 groff xscreensaver
+</screen>
+<para>
+Whenever the whole system is being upgraded there is the possibility that new
+versions of packages cannot be installed because they require new things or
+conflict with already installed things. In this case the package will appear
+in the Kept Back list. The best way to convince packages listed there to
+install is with <literal>apt-get install</literal> or by using
+<command>dselect</command> to resolve their problems.
+</para>
+</section>
+
+<section id="s4.2.5"><title>Held Packages warning</title>
+<screen>
+The following held packages will be changed:
+  cvs
+</screen>
+<para>
+Sometimes you can ask APT to install a package that is on hold, in such a case
+it prints out a warning that the held package is going to be changed. This
+should only happen during dist-upgrade or install.
+</para>
+</section>
+
+<section id="s4.2.6"><title>Final summary</title>
+<para>
+Finally, APT will print out a summary of all the changes that will occur.
+</para>
+<screen>
+206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded.
+12 packages not fully installed or removed.
+Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used.
+</screen>
+<para>
+The first line of the summary simply is a reduced version of all of the lists
+and includes the number of upgrades - that is packages already installed that
+have new versions available. The second line indicates the number of poorly
+configured packages, possibly the result of an aborted installation. The final
+line shows the space requirements that the installation needs. The first pair
+of numbers refer to the size of the archive files. The first number indicates
+the number of bytes that must be fetched from remote locations and the second
+indicates the total size of all the archives required. The next number
+indicates the size difference between the presently installed packages and the
+newly installed packages. It is roughly equivalent to the space required in
+/usr after everything is done. If a large number of packages are being removed
+then the value may indicate the amount of space that will be freed.
+</para>
+<para>
+Some other reports can be generated by using the -u option to show packages to
+upgrade, they are similar to the previous examples.
+</para>
+</section>
+
+</section>
+
+<section id="s4.3"><title>The Status Display</title>
+<para>
+During the download of archives and package files APT prints out a series of
+status messages.
+</para>
+<screen>
+# apt-get update
+Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages
+Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages
+Hit http://llug.sep.bnl.gov/debian/ testing/main Packages
+Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
+Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages
+11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
+</screen>
+<para>
+The lines starting with <emphasis>Get</emphasis> are printed out when APT
+begins to fetch a file while the last line indicates the progress of the
+download. The first percent value on the progress line indicates the total
+percent done of all files. Unfortunately since the size of the Package files
+is unknown <literal>apt-get update</literal> estimates the percent done which
+causes some inaccuracies.
+</para>
+<para>
+The next section of the status line is repeated once for each download
+thread and indicates the operation being performed and some useful
+information about what is happening. Sometimes this section will simply
+read <emphasis>Forking</emphasis> which means the OS is loading the download
+module. The first word after the [ is the fetch number as shown on the
+history lines. The next word is the short form name of the object being
+downloaded. For archives it will contain the name of the package that is
+being fetched.
+</para>
+<para>
+Inside of the single quote is an informative string indicating the progress of
+the negotiation phase of the download. Typically it progresses from
+<emphasis>Connecting</emphasis> to <emphasis>Waiting for file</emphasis> to
+<emphasis>Downloading</emphasis> or <emphasis>Resuming</emphasis>. The final
+value is the number of bytes downloaded from the remote site. Once the
+download begins this is represented as <literal>102/10.2k</literal> indicating
+that 102 bytes have been fetched and 10.2 kilobytes is expected. The total
+size is always shown in 4 figure notation to preserve space. After the size
+display is a percent meter for the file itself. The second last element is the
+instantaneous average speed. This values is updated every 5 seconds and
+reflects the rate of data transfer for that period. Finally is shown the
+estimated transfer time. This is updated regularly and reflects the time to
+complete everything at the shown transfer rate.
+</para>
+<para>
+The status display updates every half second to provide a constant feedback on
+the download progress while the Get lines scroll back whenever a new file is
+started. Since the status display is constantly updated it is unsuitable for
+logging to a file, use the <literal>-q</literal> option to remove the status
+display.
+</para>
+</section>
+
+<section id="s4.4"><title>Dpkg</title>
+<para>
+APT uses <command>dpkg</command> for installing the archives and will
+switch over to the <command>dpkg</command> interface once downloading is
+completed. <command>dpkg</command> will also ask a number of questions as
+it processes the packages and the packages themselves may also ask several
+questions. Before each question there is usually a description of what it
+is asking and the questions are too varied to discuss completely here.
+</para>
+</section>
+
+</chapter>
+
+</book>

doc/guide.sgml

@@ -1,547 +0,0 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
-<book>
-<title>APT User's Guide</title>
-
-<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $</version>
-
-<abstract>
-This document provides an overview of how to use the the APT package manager.
-</abstract>
-
-<copyright>
-Copyright &copy; Jason Gunthorpe, 1998.
-<p>
-"APT" and this document are free software; you can redistribute them and/or
-modify them under the terms of the GNU General Public License as published
-by the Free Software Foundation; either version 2 of the License, or (at your
-option) any later version.
-
-<p>
-For more details, on Debian systems, see the file
-/usr/share/common-licenses/GPL for the full license.
-</copyright>
-
-<toc sect>
-
-<!-- General		                                               {{{ -->
-<!-- ===================================================================== -->
-<chapt>General
-
-<p>
-The APT package currently contains two sections, the APT <prgn>dselect</>
-method and the <prgn>apt-get</> command line user interface. Both provide 
-a way to install and remove packages as well as download new packages from 
-the Internet. 
-
-<sect>Anatomy of the Package System
-<p>
-The Debian packaging system has a large amount of information associated with
-each package to help assure that it integrates cleanly and easily into
-the system. The most prominent of its features is the dependency system.
-
-<p>
-The dependency system allows individual programs to make use of shared 
-elements in the system such as libraries. It simplifies placing infrequently 
-used portions of a program in separate packages to reduce the
-number of things the average user is required to install. Also, it allows
-for choices in mail transport agents, X servers and 
-so on.
-
-<p>
-The first step to understanding the dependency system is to grasp the concept
-of a simple dependency. The meaning of a simple dependency is that a package
-requires another package to be installed at the same time to work properly.
-
-<p>
-For instance, mailcrypt is an emacs extension that aids in encrypting email
-with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a
-simple dependency on GPG. Also, because it is an emacs extension it has a 
-simple dependency on emacs, without emacs it is completely useless.
-
-<p>
-The other important dependency to understand is a conflicting dependency. It
-means that a package, when installed with another package, will not work and
-may possibly be extremely harmful to the system. As an example consider a
-mail transport agent such as sendmail, exim or qmail. It is not possible
-to have two mail transport agents installed because both need to listen to
-the network to receive mail. Attempting to install two will seriously
-damage the system so all mail transport agents have a conflicting dependency
-with all other mail transport agents.
-
-<p>
-As an added complication there is the possibility for a package to pretend
-to be another package. Consider that exim and sendmail for many intents are
-identical, they both deliver mail and understand a common interface. Hence,
-the package system has a way for them to declare that they are both
-mail-transport-agents. So, exim and sendmail both declare that they provide a
-mail-transport-agent and other packages that need a mail transport agent
-depend on mail-transport-agent. This can add a great deal of confusion when 
-trying to manually fix packages.
-
-<p>
-At any given time a single dependency may be met by packages that are already
-installed or it may not be. APT attempts to help resolve dependency issues
-by providing a number of automatic algorithms that help in selecting packages
-for installation.
-</sect>
-
-</chapt>
-                                                                  <!-- }}} -->
-<!-- apt-get		                                               {{{ -->
-<!-- ===================================================================== -->
-<chapt>apt-get
-
-<p>
-<prgn>apt-get</> provides a simple way to install packages from the command 
-line. Unlike <prgn>dpkg</>, <prgn>apt-get</> does not understand .deb files, 
-it works with the package's proper name and can only install .deb archives from 
-a <em>Source</>.
-
-<p>
-The first <footnote>If you are using an http proxy server you must set the
-http_proxy environment variable first, see sources.list(5)</footnote> thing that 
-should be done before using <prgn>apt-get</> is to fetch the package lists
-from the <em>Sources</> so that it knows what packages are 
-available. This is done with <tt>apt-get update</>. For instance,
-
-<p>
-<example>
-# apt-get update
-Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
-Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages
-Reading Package Lists... Done
-Building Dependency Tree... Done
-</example>
-
-<p>
-Once updated there are several commands that can be used:
-<taglist>
-<tag>upgrade<item>
-Upgrade will attempt to gently upgrade the whole system. Upgrade will
-never install a new package or remove an existing package, nor will it
-ever upgrade a package that might cause some other package to break.
-This can be used daily to relatively safely upgrade the system. Upgrade
-will list all of the packages that it could not upgrade, this usually
-means that they depend on new packages or conflict with some other package.
-<prgn>dselect</> or <tt>apt-get install</> can be used to force these
-packages to install.
-
-<tag>install<item>
-Install is used to install packages by name. The package is 
-automatically fetched and installed. This can be useful if you already
-know the name of the package to install and do not want to go into a GUI
-to select it. Any number of packages may be passed to install, they will
-all be fetched. Install automatically attempts to resolve dependency problems
-with the listed packages and will print a summary and ask for confirmation
-if anything other than its arguments are changed.
-
-<tag>dist-upgrade<item>
-Dist-upgrade is a complete upgrader designed to simplify upgrading between
-releases of Debian. It uses a sophisticated algorithm to determine the best
-set of packages to install, upgrade and remove to get as much of the system
-to the newest release. In some situations it may be desired to use dist-upgrade
-rather than spend the time manually resolving dependencies in <prgn>dselect</>.
-Once dist-upgrade has completed then <prgn>dselect</> can be used to install
-any packages that may have been left out.
-
-<p>
-It is important to closely look at what dist-upgrade is going to do, its
-decisions may sometimes be quite surprising.
-</taglist>
-
-<p>
-<prgn>apt-get</> has several command line options that are detailed in its
-man page, <manref name="apt-get" section="8">. The most useful option is 
-<tt>-d</> which does not install the fetched files. If the system has to
-download a large number of package it would be undesired to start installing
-them in case something goes wrong. When <tt>-d</> is used the downloaded
-archives can be installed by simply running the command that caused them to
-be downloaded again without <tt>-d</>.
-
-</chapt>
-                                                                  <!-- }}} -->
-<!-- DSelect		                                               {{{ -->
-<!-- ===================================================================== -->
-<chapt>DSelect
-<p>
-The APT <prgn>dselect</> method provides the complete APT system with 
-the <prgn>dselect</> package selection GUI. <prgn>dselect</> is used to
-select the packages to be installed or removed and APT actually installs them.
-
-<p>
-To enable the APT method you need to select [A]ccess in <prgn>dselect</> 
-and then choose the APT method. You will be prompted for a set of 
-<em>Sources</> which are places to fetch archives from. These can be remote
-Internet sites, local Debian mirrors or CD-ROMs. Each source can provide
-a fragment of the total Debian archive, APT will automatically combine them
-to form a complete set of packages. If you have a CD-ROM then it is a good idea
-to specify it first and then specify a mirror so that you have access to
-the latest bug fixes. APT will automatically use packages on your CD-ROM before
-downloading from the Internet.
-
-<p>
-<example>
-   Set up a list of distribution source locations
-	 
- Please give the base URL of the debian distribution.
- The access schemes I know about are: http file
-	   
- For example:
-      file:/mnt/debian,
-      ftp://ftp.debian.org/debian,
-      http://ftp.de.debian.org/debian,
-      
-      
- URL [http://llug.sep.bnl.gov/debian]: 
-</example>
-
-<p>
-The <em>Sources</> setup starts by asking for the base of the Debian
-archive, defaulting to a HTTP mirror. Next it asks for the distribution to
-get.
-
-<p>
-<example>
- Please give the distribution tag to get or a path to the
- package file ending in a /. The distribution
- tags are typically something like: stable unstable testing non-US
-   
- Distribution [stable]: 
-</example>
-
-<p>
-The distribution refers to the Debian version in the archive, <em>stable</>
-refers to the latest released version and <em>unstable</> refers to the
-developmental version. <em>non-US</> is only available on some mirrors and
-refers to packages that contain encryption technology or other things that
-cannot be exported from the United States. Importing these packages into the
-US is legal however. 
-
-<p>
-<example>
- Please give the components to get
- The components are typically something like: main contrib non-free
-  
- Components [main contrib non-free]:
-</example>
-
-<p>
-The components list refers to the list of sub distributions to fetch. The
-distribution is split up based on software licenses, main being DFSG free
-packages while contrib and non-free contain things that have various 
-restrictions placed on their use and distribution.
-
-<p>
-Any number of sources can be added, the setup script will continue to
-prompt until you have specified all that you want.
-
-<p>
-Before starting to use <prgn>dselect</> it is necessary to update the 
-available list by selecting [U]pdate from the menu. This is a superset of 
-<tt>apt-get update</> that makes the fetched information available to
-<prgn>dselect</>. [U]pdate must be performed even if <tt>apt-get update</>
-has been run before.
-
-<p>
-You can then go on and make your selections using [S]elect and then 
-perform the installation using [I]nstall. When using the APT method
-the [C]onfig and [R]emove commands have no meaning, the [I]nstall command
-performs both of them together. 
-
-<p>
-By default APT will automatically remove the package (.deb) files once they have been
-successfully installed. To change this behavior place <tt>Dselect::clean 
-"prompt";</> in /etc/apt/apt.conf.
-
-</chapt>
-                                                                  <!-- }}} -->
-<!-- The Interfaces						       {{{ -->
-<!-- ===================================================================== -->
-<chapt>The Interface
-
-<p>
-Both that APT <prgn>dselect</> method and <prgn>apt-get</> share the same
-interface. It is a simple system that generally tells you what it will do
-and then goes and does it. 
-<footnote>
-The <prgn>dselect</> method actually is a set of wrapper scripts
-to <prgn>apt-get</>. The method actually provides more functionality than
-is present in <prgn>apt-get</> alone.
-</footnote>
-After printing out a summary of what will happen APT then will print out some
-informative status messages so that you can estimate how far along it is and
-how much is left to do.
-
-<!-- ===================================================================== -->
-<sect>Startup
-
-<p>
-Before all operations except update, APT performs a number of actions to
-prepare its internal state. It also does some checks of the system's state.
-At any time these operations can be performed by running <tt>apt-get check</>.
-<p>
-<example>
-# apt-get check
-Reading Package Lists... Done
-Building Dependency Tree... Done
-</example>
-
-<p>
-The first thing it does is read all the package files into memory. APT
-uses a caching scheme so this operation will be faster the second time it
-is run. If some of the package files are not found then they will be ignored
-and a warning will be printed when apt-get exits. 
-
-<p>
-The final operation performs a detailed analysis of the system's dependencies.
-It checks every dependency of every installed or unpacked package and considers
-if it is OK. Should this find a problem then a report will be printed out and
-<prgn>apt-get</> will refuse to run.
-
-<p>
-<example>
-# apt-get check
-Reading Package Lists... Done
-Building Dependency Tree... Done
-You might want to run apt-get -f install' to correct these.
-Sorry, but the following packages have unmet dependencies:
-  9fonts: Depends: xlib6g but it is not installed
-  uucp: Depends: mailx but it is not installed
-  blast: Depends: xlib6g (>= 3.3-5) but it is not installed
-  adduser: Depends: perl-base but it is not installed
-  aumix: Depends: libgpmg1 but it is not installed
-  debiandoc-sgml: Depends: sgml-base but it is not installed
-  bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed
-  cthugha: Depends: svgalibg1 but it is not installed
-           Depends: xlib6g (>= 3.3-5) but it is not installed
-  libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)
-</example>
-
-<p>
-In this example the system has many problems, including a serious problem
-with libreadlineg2. For each package that has unmet dependencies a line
-is printed out indicating the package with the problem and the dependencies
-that are unmet. A short explanation of why the package has a dependency
-problem is also included.
-
-<p>
-There are two ways a system can get into a broken state like this. The
-first is caused by <prgn>dpkg</> missing some subtle relationships between 
-packages when performing upgrades. <footnote>APT however considers all known 
-dependencies and attempts to prevent broken packages</footnote>. The second is 
-if a package installation fails during an operation. In this situation a 
-package may have been unpacked without its dependents being installed.
-
-<p>
-The second situation is much less serious than the first because APT places
-certain constraints on the order that packages are installed. In both cases
-supplying the <tt>-f</> option to <prgn>apt-get</> will cause APT to deduce a
-possible solution to the problem and then continue on. The APT <prgn>dselect</> 
-method always supplies the <tt>-f</> option to allow for easy continuation
-of failed maintainer scripts.
-
-<p>
-However, if the <tt>-f</> option is used to correct a seriously broken system
-caused by the first case then it is possible that it will either fail 
-immediately or the installation sequence will fail. In either case it is
-necessary to manually use dpkg (possibly with forcing options) to correct
-the situation enough to allow APT to proceed.
-</sect>
-
-<!-- ===================================================================== -->
-<sect>The Status Report
-
-<p>
-Before proceeding <prgn>apt-get</> will present a report on what will happen.
-Generally the report reflects the type of operation being performed but there
-are several common elements. In all cases the lists reflect the final state
-of things, taking into account the <tt>-f</> option and any other relevant
-activities to the command being executed.
-
-<sect1>The Extra Package list
-<p>
-<example>
-The following extra packages will be installed:
-  libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl
-  mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base
-  bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy
-  squake pgp-i python-base debmake ldso perl libreadlineg2
-  ssh
-</example>
-
-<p>
-The Extra Package list shows all of the packages that will be installed 
-or upgraded in excess of the ones mentioned on the command line. It is
-only generated for an <tt>install</> command. The listed packages are
-often the result of an Auto Install.
-</sect1>
-
-<sect1>The Packages to Remove
-<p>
-<example>
-The following packages will be REMOVED:
-  xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix
-  xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel
-  xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid
-  nas xpilot xfig 
-</example>
-
-<p>
-The Packages to Remove list shows all of the packages that will be
-removed from the system. It can be shown for any of the operations and 
-should be given a careful inspection to ensure nothing important is to 
-be taken off. The <tt>-f</> option is especially good at generating packages
-to remove so extreme care should be used in that case. The list may contain
-packages that are going to be removed because they are only 
-partially installed, possibly due to an aborted installation.
-</sect1>
-
-<sect1>The New Packages list
-<p>
-<example>
-The following NEW packages will installed:
-  zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
-</example>
-
-<p>
-The New Packages list is simply a reminder of what will happen. The packages
-listed are not presently installed in the system but will be when APT is done.
-</sect1>
-
-<sect1>The Kept Back list
-<p>
-<example>
-The following packages have been kept back
-  compface man-db tetex-base msql libpaper svgalib1
-  gs snmp arena lynx xpat2 groff xscreensaver
-</example>
-
-<p>
-Whenever the whole system is being upgraded there is the possibility that
-new versions of packages cannot be installed because they require new things
-or conflict with already installed things. In this case the package will 
-appear in the Kept Back list. The best way to convince packages listed
-there to install is with <tt>apt-get install</> or by using <prgn>dselect</>
-to resolve their problems.
-</sect1>
-
-<sect1>Held Packages warning
-<p>
-<example>
-The following held packages will be changed:
-  cvs 
-</example>
-
-<p>
-Sometimes you can ask APT to install a package that is on hold, in such a 
-case it prints out a warning that the held package is going to be
-changed. This should only happen during dist-upgrade or install.
-</sect1>
-
-<sect1>Final summary
-<p>
-Finally, APT will print out a summary of all the changes that will occur.
-
-<p>
-<example>
-206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded.
-12 packages not fully installed or removed.
-Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used. 
-</example>
-
-<p>
-The first line of the summary simply is a reduced version of all of the
-lists and includes the number of upgrades - that is packages already 
-installed that have new versions available. The second line indicates the
-number of poorly configured packages, possibly the result of an aborted
-installation. The final line shows the space requirements that the
-installation needs. The first pair of numbers refer to the size of
-the archive files. The first number indicates the number of bytes that
-must be fetched from remote locations and the second indicates the
-total size of all the archives required. The next number indicates the
-size difference between the presently installed packages and the newly
-installed packages. It is roughly equivalent to the space required in 
-/usr after everything is done. If a large number of packages are being
-removed then the value may indicate the amount of space that will be
-freed.
-
-<p>
-Some other reports can be generated by using the -u option to show packages
-to upgrade, they are similar to the previous examples.
-</sect>
-
-<!-- ===================================================================== -->
-<sect>The Status Display
-<p>
-During the download of archives and package files APT prints out a series of
-status messages.
-
-<p>
-<example>
-# apt-get update
-Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages
-Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages
-Hit http://llug.sep.bnl.gov/debian/ testing/main Packages
-Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
-Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages
-11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
-</example>
-
-<p>
-The lines starting with <em>Get</> are printed out when APT begins to fetch 
-a file while the last line indicates the progress of the download. The first 
-percent  value on the progress line indicates the total percent done of all 
-files. Unfortunately since the size of the Package files is unknown 
-<tt>apt-get update</> estimates the percent done which causes some 
-inaccuracies.
-
-<p>
-The next section of the status line is repeated once for each download thread
-and indicates the operation being performed and some useful information
-about what is happening. Sometimes this section will simply read <em>Forking</>
-which means the OS is loading the download module. The first word after the [
-is the fetch number as shown on the history lines. The next word
-is the short form name of the object being downloaded. For archives it will
-contain the name of the package that is being fetched.
-
-<p>
-Inside of the single quote is an informative string indicating the progress
-of the negotiation phase of the download. Typically it progresses from 
-<em>Connecting</> to <em>Waiting for file</> to <em>Downloading</> or
-<em>Resuming</>. The final value is the number of bytes downloaded from the
-remote site. Once the download begins this is represented as <tt>102/10.2k</>
-indicating that 102 bytes have been fetched and 10.2 kilobytes is expected.
-The total size is always shown in 4 figure notation to preserve space. After
-the size display is a percent meter for the file itself.
-The second last element is the instantaneous average speed. This values is 
-updated every 5 seconds and reflects the rate of data transfer for that 
-period. Finally is shown the estimated transfer time. This is updated
-regularly and reflects the time to complete everything at the shown 
-transfer rate.
-
-<p> 
-The status display updates every half second to provide a constant feedback 
-on the download progress while the Get lines scroll back whenever a new
-file is started. Since the status display is constantly updated it is
-unsuitable for logging to a file, use the <tt>-q</> option to remove the
-status display.
-</sect>
-
-<!-- ===================================================================== -->
-<sect>Dpkg
-
-<p>
-APT uses <prgn>dpkg</> for installing the archives and will switch
-over to the <prgn>dpkg</> interface once downloading is completed.
-<prgn>dpkg</> will also ask a number of questions as it processes the packages
-and the packages themselves may also ask several questions. Before each 
-question there is usually a description of what it is asking and the
-questions are too varied to discuss completely here.
-</sect>
-
-</chapt>
-                                                                  <!-- }}} -->
-
-</book>

doc/method.dbk

@@ -0,0 +1,712 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+]>
+
+<book lang="en">
+
+<title>APT Method Interface</title>
+
+<bookinfo>
+
+<authorgroup>
+  <author>
+    <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email>
+  </author>
+</authorgroup>
+
+<releaseinfo>Version &apt-product-version;</releaseinfo>
+
+<abstract>
+<para>
+This document describes the interface that APT uses to the archive access
+methods.
+</para>
+</abstract>
+
+<copyright><year>1998</year><holder>Jason Gunthorpe</holder></copyright>
+
+<legalnotice>
+<title>License Notice</title>
+<para>
+"APT" and this document are free software; you can redistribute them and/or
+modify them under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or (at your
+option) any later version.
+</para>
+<para>
+For more details, on Debian systems, see the file
+/usr/share/common-licenses/GPL for the full license.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+<chapter id="ch1"><title>Introduction</title>
+
+<section id="s1.1"><title>General</title>
+<para>
+The APT method interface allows APT to acquire archive files (.deb), index
+files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It is a
+general, extensible system designed to satisfy all of these requirements:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Remote methods that download files from a distant site
+</para>
+</listitem>
+<listitem>
+<para>
+Resume of aborted downloads
+</para>
+</listitem>
+<listitem>
+<para>
+Progress reporting
+</para>
+</listitem>
+<listitem>
+<para>
+If-Modified-Since (IMS) checking for index files
+</para>
+</listitem>
+<listitem>
+<para>
+In-Line MD5 generation
+</para>
+</listitem>
+<listitem>
+<para>
+No-copy in-filesystem methods
+</para>
+</listitem>
+<listitem>
+<para>
+Multi-media methods (like CD's)
+</para>
+</listitem>
+<listitem>
+<para>
+Dynamic source selection for failure recovery
+</para>
+</listitem>
+<listitem>
+<para>
+User interaction for user/password requests and media swaps
+</para>
+</listitem>
+<listitem>
+<para>
+Global configuration
+</para>
+</listitem>
+</orderedlist>
+<para>
+Initial releases of APT (0.1.x) used a completely different method interface
+that only supported the first 6 items. This new interface deals with the
+remainder.
+</para>
+</section>
+
+<section id="s1.2"><title>Terms</title>
+<para>
+Several terms are used through out the document, they have specific meanings
+which may not be immediately evident. To clarify they are summarized here.
+</para>
+<variablelist>
+<varlistentry>
+<term>source</term>
+<listitem>
+<para>
+Refers to an item in source list. More specifically it is the broken down
+item, that is each source maps to exactly one index file. Archive sources map
+to Package files and Source Code sources map to Source files.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>archive file</term>
+<listitem>
+<para>
+Refers to a binary package archive (.deb, .rpm, etc).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>source file</term>
+<listitem>
+<para>
+Refers to one of the files making up the source code of a package. In debian
+it is one of .diff.gz, .dsc. or .tar.gz.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>URI</term>
+<listitem>
+<para>
+Universal Resource Identifier (URI) is a super-set of the familiar URL
+syntax used by web browsers. It consists of an access specification
+followed by a specific location in that access space. The form is
+&lt;access&gt;:&lt;location&gt;. Network addresses are given with the form
+&lt;access&gt;://[&lt;user&gt;[:&lt;pas&gt;]@]hostname[:port]/&lt;location&gt;.
+Some examples:
+</para>
+<screen>
+file:/var/mirrors/debian/
+ftp://ftp.debian.org/debian
+ftp://jgg:MooCow@localhost:21/debian
+nfs://bigred/var/mirrors/debian
+rsync://debian.midco.net/debian
+cdrom:Debian 2.0r1 Disk 1/
+</screen>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>method</term>
+<listitem>
+<para>
+There is a one to one mapping of URI access specifiers to methods. A method is
+a program that knows how to handle a URI access type and operates according to
+the specifications in this file.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>method instance</term>
+<listitem>
+<para>
+A specific running method. There can be more than one instance of each method
+as APT is capable of concurrent method handling.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>message</term>
+<listitem>
+<para>
+A series of lines terminated by a blank line sent down one of the communication
+lines. The first line should have the form xxx TAG where xxx are digits
+forming the status code and TAG is an informational string
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>acquire</term>
+<listitem>
+<para>
+The act of bring a URI into the local pathname space. This may simply be
+verifying the existence of the URI or actually downloading it from a remote
+site.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+
+</chapter>
+
+<chapter id="ch2"><title>Specification</title>
+
+<section id="s2.1"><title>Overview</title>
+<para>
+All methods operate as a sub process of a main controlling parent. 3 FD's are
+opened for use by the method allowing two way communication and emergency error
+reporting. The FD's correspond to the well known unix FD's, stdin, stdout and
+stderr.
+</para>
+<para>
+Through operation of the method communication is done via http style plain
+text. Specifically RFC-822 (like the Package file) fields are used to describe
+items and a numeric-like header is used to indicate what is happening. Each of
+these distinct communication messages should be sent quickly and without pause.
+</para>
+<para>
+In some instances APT may pre-invoke a method to allow things like file URI's
+to determine how many files are available locally.
+</para>
+</section>
+
+<section id="s2.2"><title>Message Overview</title>
+<para>
+The first line of each message is called the message header. The first 3
+digits (called the Status Code) have the usual meaning found in the http
+protocol. 1xx is informational, 2xx is successful and 4xx is failure. The 6xx
+series is used to specify things sent to the method. After the status code is
+an informational string provided for visual debugging.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+100 Capabilities - Method capabilities
+</para>
+</listitem>
+<listitem>
+<para>
+101 Log - General Logging
+</para>
+</listitem>
+<listitem>
+<para>
+102 Status - Inter-URI status reporting (login progress)
+</para>
+</listitem>
+<listitem>
+<para>
+200 URI Start - URI is starting acquire
+</para>
+</listitem>
+<listitem>
+<para>
+201 URI Done - URI is finished acquire
+</para>
+</listitem>
+<listitem>
+<para>
+400 URI Failure - URI has failed to acquire
+</para>
+</listitem>
+<listitem>
+<para>
+401 General Failure - Method did not like something sent to it
+</para>
+</listitem>
+<listitem>
+<para>
+402 Authorization Required - Method requires authorization to access the URI.
+Authorization is User/Pass
+</para>
+</listitem>
+<listitem>
+<para>
+403 Media Failure - Method requires a media change
+</para>
+</listitem>
+<listitem>
+<para>
+600 URI Acquire - Request a URI be acquired
+</para>
+</listitem>
+<listitem>
+<para>
+601 Configuration - Sends the configuration space
+</para>
+</listitem>
+<listitem>
+<para>
+602 Authorization Credentials - Response to the 402 message
+</para>
+</listitem>
+<listitem>
+<para>
+603 Media Changed - Response to the 403 message
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Only the 6xx series of status codes is sent TO the method. Furthermore the
+method may not emit status codes in the 6xx range. The Codes 402 and 403
+require that the method continue reading all other 6xx codes until the proper
+602/603 code is received. This means the method must be capable of handling an
+unlimited number of 600 messages.
+</para>
+<para>
+The flow of messages starts with the method sending out a <emphasis>100
+Capabilities</emphasis> and APT sending out a <emphasis>601
+Configuration</emphasis>. After that APT begins sending <emphasis>600 URI
+Acquire</emphasis> and the method sends out <emphasis>200 URI Start</emphasis>,
+<emphasis>201 URI Done</emphasis> or <emphasis>400 URI Failure</emphasis>. No
+synchronization is performed, it is expected that APT will send <emphasis>600
+URI Acquire</emphasis> messages at -any- time and that the method should queue
+the messages. This allows methods like http to pipeline requests to the remote
+server. It should be noted however that APT will buffer messages so it is not
+necessary for the method to be constantly ready to receive them.
+</para>
+</section>
+
+<section id="s2.3"><title>Header Fields</title>
+<para>
+The following is a short index of the header fields that are supported
+</para>
+<variablelist>
+<varlistentry>
+<term>URI</term>
+<listitem>
+<para>
+URI being described by the message
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Filename</term>
+<listitem>
+<para>
+Location in the filesystem
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Last-Modified</term>
+<listitem>
+<para>
+A time stamp in RFC1123 notation for use by IMS checks
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>IMS-Hit</term>
+<listitem>
+<para>
+The already existing item is valid
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Size</term>
+<listitem>
+<para>
+Size of the file in bytes
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Resume-Point</term>
+<listitem>
+<para>
+Location that transfer was started
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>MD5-Hash</term>
+<listitem>
+<para>
+Computed MD5 hash for the file
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Message</term>
+<listitem>
+<para>
+String indicating some displayable message
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Media</term>
+<listitem>
+<para>
+String indicating the media name required
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Site</term>
+<listitem>
+<para>
+String indicating the site authorization is required for
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>User</term>
+<listitem>
+<para>
+Username for authorization
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Password</term>
+<listitem>
+<para>
+Password for authorization
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Fail</term>
+<listitem>
+<para>
+Operation failed
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Drive</term>
+<listitem>
+<para>
+Drive the media should be placed in
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Config-Item</term>
+<listitem>
+<para>
+A string of the form
+<replaceable>item</replaceable>=<replaceable>value</replaceable> derived from
+the APT configuration space. These may include method specific values and
+general values not related to the method. It is up to the method to filter out
+the ones it wants.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Single-Instance</term>
+<listitem>
+<para>
+Requires that only one instance of the method be run This is a yes/no value.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Pipeline</term>
+<listitem>
+<para>
+The method is capable of pipelining.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Local</term>
+<listitem>
+<para>
+The method only returns Filename: fields.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Send-Config</term>
+<listitem>
+<para>
+Send configuration to the method.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Needs-Cleanup</term>
+<listitem>
+<para>
+The process is kept around while the files it returned are being used. This is
+primarily intended for CD-ROM and File URIs that need to unmount filesystems.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Version</term>
+<listitem>
+<para>
+Version string for the method
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+This is a list of which headers each status code can use
+</para>
+<variablelist>
+<varlistentry>
+<term>100 Capabilities</term>
+<listitem>
+<para>
+Displays the capabilities of the method. Methods should set the pipeline bit
+if their underlying protocol supports pipelining. The only known method that
+does support pipelining is http. Fields: Version, Single-Instance, Pre-Scan,
+Pipeline, Send-Config, Needs-Cleanup
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>101 Log</term>
+<listitem>
+<para>
+A log message may be printed to the screen if debugging is enabled. This is
+only for debugging the method. Fields: Message
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>102 Status</term>
+<listitem>
+<para>
+Message gives a progress indication for the method. It can be used to show
+pre-transfer status for Internet type methods. Fields: Message
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>200 URI Start</term>
+<listitem>
+<para>
+Indicates the URI is starting to be transferred. The URI is specified along
+with stats about the file itself. Fields: URI, Size, Last-Modified,
+Resume-Point
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>201 URI Done</term>
+<listitem>
+<para>
+Indicates that a URI has completed being transferred. It is possible to
+specify a <emphasis>201 URI Done</emphasis> without a <emphasis>URI
+Start</emphasis> which would mean no data was transferred but the file is now
+available. A Filename field is specified when the URI is directly available in
+the local pathname space. APT will either directly use that file or copy it
+into another location. It is possible to return Alt-* fields to indicate that
+another possibility for the URI has been found in the local pathname space.
+This is done if a decompressed version of a .gz file is found. Fields: URI,
+Size, Last-Modified, Filename, MD5-Hash
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>400 URI Failure</term>
+<listitem>
+<para>
+Indicates a fatal URI failure. The URI is not retrievable from this source. As
+with <emphasis>201 URI Done</emphasis> <emphasis>200 URI Start</emphasis> is
+not required to precede this message Fields: URI, Message
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>401 General Failure</term>
+<listitem>
+<para>
+Indicates that some unspecific failure has occurred and the method is unable
+to  continue. The method should terminate after sending this message. It
+is intended to check for invalid configuration options or other severe
+conditions. Fields: Message
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>402 Authorization Required</term>
+<listitem>
+<para>
+The method requires a Username and Password pair to continue. After sending
+this message the method will expect APT to send a <emphasis>602 Authorization
+Credentials</emphasis> message with the required information. It is possible
+for a method to send this multiple times. Fields: Site
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>403 Media Failure</term>
+<listitem>
+<para>
+A method that deals with multiple media requires that a new media be
+inserted. The Media field contains the name of the media to be
+inserted. Fields: Media, Drive
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>600 URI Acquire</term>
+<listitem>
+<para>
+APT is requesting that a new URI be added to the acquire list. Last-Modified
+has the time stamp of the currently cache file if applicable. Filename is the
+name of the file that the acquired URI should be written to. Fields: URI,
+Filename Last-Modified
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>601 Configuration</term>
+<listitem>
+<para>
+APT is sending the configuration space to the method. A series of Config-Item
+fields will be part of this message, each containing an entry from the
+configuration space. Fields: Config-Item.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>602 Authorization Credentials</term>
+<listitem>
+<para>
+This is sent in response to a <emphasis>402 Authorization Required</emphasis>
+message. It contains the entered username and password. Fields: Site, User,
+Password
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>603 Media Changed</term>
+<listitem>
+<para>
+This is sent in response to a <emphasis>403 Media Failure</emphasis>
+message. It indicates that the user has changed media and it is safe
+to proceed. Fields: Media, Fail
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+
+<section id="s2.4"><title>Notes</title>
+<para>
+The methods supplied by the stock apt are:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+cdrom - For Multi-Disc CD-ROMs
+</para>
+</listitem>
+<listitem>
+<para>
+copy - (internal) For copying files around the filesystem
+</para>
+</listitem>
+<listitem>
+<para>
+file - For local files
+</para>
+</listitem>
+<listitem>
+<para>
+gzip - (internal) For decompression
+</para>
+</listitem>
+<listitem>
+<para>
+http - For HTTP servers
+</para>
+</listitem>
+</orderedlist>
+<para>
+The two internal methods, copy and gzip, are used by the acquire code to
+parallize and simplify the automatic decompression of package files as well as
+copying package files around the file system. Both methods can be seen to act
+the same except that one decompresses on the fly. APT uses them by generating
+a copy URI that is formed identically to a file URI. The destination file is
+send as normal. The method then takes the file specified by the URI and writes
+it to the destination file. A typical set of operations may be:
+</para>
+<screen>
+http://foo.com/Packages.gz -&gt; /bar/Packages.gz
+gzip:/bar/Packages.gz -&gt; /bar/Packages.decomp
+rename Packages.decomp to /final/Packages
+</screen>
+<para>
+The http method implements a fully featured HTTP/1.1 client that supports
+deep pipelining and reget. It works best when coupled with an apache 1.3
+server. The file method simply generates failures or success responses
+with the filename field set to the proper location. The cdrom method acts
+the same except that it checks that the mount point has a valid cdrom in
+it. It does this by (effectively) computing a md5 hash of 'ls -l' on the
+mountpoint.
+</para>
+</section>
+
+</chapter>
+
+</book>

doc/method.sgml

@@ -1,354 +0,0 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
-<book>
-<title>APT Method Interface </title>
-
-<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: method.sgml,v 1.10 2003/02/12 15:05:46 doogie Exp $</version>
-
-<abstract>
-This document describes the interface that APT uses to the archive
-access methods.
-</abstract>
-
-<copyright>
-Copyright &copy; Jason Gunthorpe, 1998.
-<p>
-"APT" and this document are free software; you can redistribute them and/or
-modify them under the terms of the GNU General Public License as published
-by the Free Software Foundation; either version 2 of the License, or (at your
-option) any later version.
-
-<p>
-For more details, on Debian systems, see the file
-/usr/share/common-licenses/GPL for the full license.
-</copyright>
-
-<toc sect>
-
-<chapt>Introduction
-<!-- General		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>General
-
-<p>
-The APT method interface allows APT to acquire archive files (.deb), index
-files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It
-is a general, extensible system designed to satisfy all of these
-requirements:
-
-<enumlist>
-<item>Remote methods that download files from a distant site
-<item>Resume of aborted downloads
-<item>Progress reporting
-<item>If-Modified-Since (IMS) checking for index files
-<item>In-Line MD5 generation
-<item>No-copy in-filesystem methods
-<item>Multi-media methods (like CD's)
-<item>Dynamic source selection for failure recovery
-<item>User interaction for user/password requests and media swaps
-<item>Global configuration
-</enumlist>
-
-Initial releases of APT (0.1.x) used a completely different method
-interface that only supported the first 6 items. This new interface
-deals with the remainder.
-</sect>
-                                                                  <!-- }}} -->
-<!-- Terms		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Terms
-
-<p>
-Several terms are used through out the document, they have specific
-meanings which may not be immediately evident. To clarify they are summarized
-here.
-
-<taglist>
-<tag>source<item>
-Refers to an item in source list. More specifically it is the broken down
-item, that is each source maps to exactly one index file. Archive sources
-map to Package files and Source Code sources map to Source files.
-
-<tag>archive file<item>
-Refers to a binary package archive (.deb, .rpm, etc). 
-
-<tag>source file<item>
-Refers to one of the files making up the source code of a package. In
-debian it is one of .diff.gz, .dsc. or .tar.gz.
-
-<tag>URI<item>
-Universal Resource Identifier (URI) is a super-set of the familiar URL
-syntax used by web browsers. It consists of an access specification
-followed by a specific location in that access space. The form is
-&lt;access&gt;:&lt;location&gt;. Network addresses are given with the form 
-&lt;access&gt;://[&lt;user&gt;[:&lt;pas&gt;]@]hostname[:port]/&lt;location&gt;. 
-Some examples:
-<example>
-file:/var/mirrors/debian/
-ftp://ftp.debian.org/debian
-ftp://jgg:MooCow@localhost:21/debian
-nfs://bigred/var/mirrors/debian
-rsync://debian.midco.net/debian
-cdrom:Debian 2.0r1 Disk 1/
-</example>
-
-<tag>method<item>
-There is a one to one mapping of URI access specifiers to methods. A method
-is a program that knows how to handle a URI access type and operates according
-to the specifications in this file.
-
-<tag>method instance<item>
-A specific running method. There can be more than one instance of each method
-as APT is capable of concurrent method handling.
-
-<tag>message<item>
-A series of lines terminated by a blank line sent down one of the
-communication lines. The first line should have the form xxx TAG
-where xxx are digits forming the status code and TAG is an informational
-string
-
-<tag>acquire<item>
-The act of bring a URI into the local pathname space. This may simply
-be verifying the existence of the URI or actually downloading it from
-a remote site.
-
-</taglist>
-
-</sect>
-                                                                  <!-- }}} -->
-<chapt>Specification
-<!-- Overview		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Overview
-
-<p>
-All methods operate as a sub process of a main controlling parent. 3 FD's
-are opened for use by the method allowing two way communication and
-emergency error reporting. The FD's correspond to the well known unix FD's, 
-stdin, stdout and stderr.
-
-<p>
-Through operation of the method communication is done via http 
-style plain text. Specifically RFC-822 (like the Package file) fields
-are used to describe items and a numeric-like header is used to indicate
-what is happening. Each of these distinct communication messages should be
-sent quickly and without pause.
-
-<p> 
-In some instances APT may pre-invoke a method to allow things like file
-URI's to determine how many files are available locally.
-</sect>
-                                                                  <!-- }}} -->
-<!-- Message Overview	                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Message Overview
-
-<p>
-The first line of each message is called the message header. The first
-3 digits (called the Status Code) have the usual meaning found in the 
-http protocol. 1xx is informational, 2xx is successful and 4xx is failure. 
-The 6xx series is used to specify things sent to the method. After the 
-status code is an informational string provided for visual debugging.
-
-<list>
-<item>100 Capabilities - Method capabilities
-<item>101 Log - General Logging
-<item>102 Status - Inter-URI status reporting (login progress)
-<item>200 URI Start - URI is starting acquire
-<item>201 URI Done - URI is finished acquire
-<item>400 URI Failure - URI has failed to acquire
-<item>401 General Failure - Method did not like something sent to it
-<item>402 Authorization Required - Method requires authorization
-        to access the URI. Authorization is User/Pass
-<item>403 Media Failure - Method requires a media change	
-<item>600 URI Acquire - Request a URI be acquired
-<item>601 Configuration - Sends the configuration space
-<item>602 Authorization Credentials - Response to the 402 message
-<item>603 Media Changed - Response to the 403 message
-</list>
-
-Only the 6xx series of status codes is sent TO the method. Furthermore
-the method may not emit status codes in the 6xx range. The Codes 402
-and 403 require that the method continue reading all other 6xx codes
-until the proper 602/603 code is received. This means the method must be
-capable of handling an unlimited number of 600 messages.
-
-<p>
-The flow of messages starts with the method sending out a 
-<em>100 Capabilities</> and APT sending out a <em>601 Configuration</>.
-After that APT begins sending <em>600 URI Acquire</> and the method
-sends out <em>200 URI Start</>, <em>201 URI Done</> or 
-<em>400 URI Failure</>. No synchronization is performed, it is expected
-that APT will send <em>600 URI Acquire</> messages at -any- time and
-that the method should queue the messages. This allows methods like http
-to pipeline requests to the remote server. It should be noted however
-that APT will buffer messages so it is not necessary for the method
-to be constantly ready to receive them.
-</sect>
-                                                                  <!-- }}} -->
-<!-- Header Fields	                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Header Fields
-
-<p> 
-The following is a short index of the header fields that are supported
-
-<taglist>
-<tag>URI<item>URI being described by the message
-<tag>Filename<item>Location in the filesystem
-<tag>Last-Modified<item>A time stamp in RFC1123 notation for use by IMS checks
-<tag>IMS-Hit<item>The already existing item is valid
-<tag>Size<item>Size of the file in bytes
-<tag>Resume-Point<item>Location that transfer was started
-<tag>MD5-Hash<item>Computed MD5 hash for the file
-<tag>Message<item>String indicating some displayable message
-<tag>Media<item>String indicating the media name required
-<tag>Site<item>String indicating the site authorization is required for
-<tag>User<item>Username for authorization
-<tag>Password<item>Password for authorization
-<tag>Fail<item>Operation failed
-<tag>Drive<item>Drive the media should be placed in
-<tag>Config-Item<item>
-A string of the form <var>item</>=<var>value</> derived from the APT 
-configuration space. These may include method specific values and general
-values not related to the method. It is up to the method to filter out
-the ones it wants.
-<tag>Single-Instance<item>Requires that only one instance of the method be run
-                          This is a yes/no value.
-<tag>Pipeline<item>The method is capable of pipelining.
-<tag>Local<item>The method only returns Filename: fields.
-<tag>Send-Config<item>Send configuration to the method.
-<tag>Needs-Cleanup<item>The process is kept around while the files it returned
-are being used. This is primarily intended for CD-ROM and File URIs that need
-to unmount filesystems.
-<tag>Version<item>Version string for the method
-</taglist>
-
-This is a list of which headers each status code can use
-
-<taglist>
-<tag>100 Capabilities<item>
-Displays the capabilities of the method. Methods should set the
-pipeline bit if their underlying protocol supports pipelining. The
-only known method that does support pipelining is http.
-Fields: Version, Single-Instance, Pre-Scan, Pipeline, Send-Config, 
-Needs-Cleanup
-
-<tag>101 Log<item>
-A log message may be printed to the screen if debugging is enabled. This
-is only for debugging the method.
-Fields: Message
-
-<tag>102 Status<item>
-Message gives a progress indication for the method. It can be used to show
-pre-transfer status for Internet type methods.
-Fields: Message
-
-<tag>200 URI Start<item>
-Indicates the URI is starting to be transferred. The URI is specified
-along with stats about the file itself.
-Fields: URI, Size, Last-Modified, Resume-Point
-
-<tag>201 URI Done<item>
-Indicates that a URI has completed being transferred. It is possible
-to specify a <em>201 URI Done</> without a <em>URI Start</> which would
-mean no data was transferred but the file is now available. A Filename
-field is specified when the URI is directly available in the local 
-pathname space. APT will either directly use that file or copy it into 
-another location. It is possible to return Alt-* fields to indicate that
-another possibility for the URI has been found in the local pathname space.
-This is done if a decompressed version of a .gz file is found.
-Fields: URI, Size, Last-Modified, Filename, MD5-Hash
-
-<tag>400 URI Failure<item>
-Indicates a fatal URI failure. The URI is not retrievable from this source.
-As with <em>201 URI Done</> <em>200 URI Start</> is not required to precede
-this message
-Fields: URI, Message
-
-<tag>401 General Failure<item>
-Indicates that some unspecific failure has occurred and the method is unable
-to continue. The method should terminate after sending this message. It 
-is intended to check for invalid configuration options or other severe
-conditions.
-Fields: Message
-
-<tag>402 Authorization Required<item>
-The method requires a Username and Password pair to continue. After sending
-this message the method will expect APT to send a <em>602 Authorization 
-Credentials</> message with the required information. It is possible for
-a method to send this multiple times.
-Fields: Site
-
-<tag>403 Media Failure<item>
-A method that deals with multiple media requires that a new media be inserted.
-The Media field contains the name of the media to be inserted.
-Fields: Media, Drive
-
-<tag>600 URI Acquire<item>
-APT is requesting that a new URI be added to the acquire list. Last-Modified
-has the time stamp of the currently cache file if applicable. Filename
-is the name of the file that the acquired URI should be written to.
-Fields: URI, Filename Last-Modified
-
-<tag>601 Configuration<item>
-APT is sending the configuration space to the method. A series of
-Config-Item fields will be part of this message, each containing an entry
-from the configuration space.
-Fields: Config-Item.
-
-<tag>602 Authorization Credentials<item>
-This is sent in response to a <em>402 Authorization Required</> message. 
-It contains the entered username and password.
-Fields: Site, User, Password
-
-<tag>603 Media Changed<item>
-This is sent in response to a <em>403 Media Failure</> message. It
-indicates that the user has changed media and it is safe to proceed.
-Fields: Media, Fail
-</taglist>
-
-</sect>
-                                                                  <!-- }}} -->
-<!-- Method Notes		                                       {{{ -->
-<!-- ===================================================================== -->
-<sect>Notes
-
-<p>
-The methods supplied by the stock apt are:
-<enumlist>
-<item>cdrom - For Multi-Disc CD-ROMs
-<item>copy - (internal) For copying files around the filesystem
-<item>file - For local files
-<item>gzip - (internal) For decompression
-<item>http - For HTTP servers
-</enumlist>
-
-<p>
-The two internal methods, copy and gzip, are used by the acquire code to
-parallize and simplify the automatic decompression of package files as well 
-as copying package files around the file system. Both methods can be seen to 
-act the same except that one decompresses on the fly. APT uses them by
-generating a copy URI that is formed identically to a file URI. The destination
-file is send as normal. The method then takes the file specified by the 
-URI and writes it to the destination file. A typical set of operations may
-be:
-<example>
-http://foo.com/Packages.gz -> /bar/Packages.gz
-gzip:/bar/Packages.gz -> /bar/Packages.decomp
-rename Packages.decomp to /final/Packages
-</example>
-
-<p>
-The http method implements a fully featured HTTP/1.1 client that supports
-deep pipelining and reget. It works best when coupled with an apache 1.3
-server. The file method simply generates failures or success responses with
-the filename field set to the proper location. The cdrom method acts the same
-except that it checks that the mount point has a valid cdrom in it. It does 
-this by (effectively) computing a md5 hash of 'ls -l' on the mountpoint.
-
-</sect>
-                                                                  <!-- }}} -->
-
-</book>

doc/offline.sgml

@@ -1,74 +1,89 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
-<book>
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+]>
+
+<book lang="en">
+
 <title>Using APT Offline</title>
 
-<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: offline.sgml,v 1.8 2003/02/12 15:06:41 doogie Exp $</version>
+<bookinfo>
+
+<authorgroup>
+  <author>
+    <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email>
+  </author>
+</authorgroup>
+
+<releaseinfo>Version &apt-product-version;</releaseinfo>
 
 <abstract>
-This document describes how to use APT in a non-networked environment, 
+<para>
+This document describes how to use APT in a non-networked environment,
 specifically a 'sneaker-net' approach for performing upgrades.
+</para>
 </abstract>
 
-<copyright>
-Copyright &copy; Jason Gunthorpe, 1999.
-<p>
+<copyright><year>1999</year><holder>Jason Gunthorpe</holder></copyright>
+
+<legalnotice>
+<title>License Notice</title>
+<para>
 "APT" and this document are free software; you can redistribute them and/or
-modify them under the terms of the GNU General Public License as published
-by the Free Software Foundation; either version 2 of the License, or (at your
+modify them under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or (at your
 option) any later version.
-
-<p>
+</para>
+<para>
 For more details, on Debian systems, see the file
 /usr/share/common-licenses/GPL for the full license.
-</copyright>
+</para>
+</legalnotice>
 
-<toc sect>
+</bookinfo>
 
-<chapt>Introduction
-<!-- Overview		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Overview
+<chapter id="ch1"><title>Introduction</title>
 
-<p>
+<section id="s1.1"><title>Overview</title>
+<para>
 Normally APT requires direct access to a Debian archive, either from a local
 media or through a network. Another common complaint is that a Debian machine
-is on a slow link, such as a modem and another machine has a very fast 
+is on a slow link, such as a modem and another machine has a very fast
 connection but they are physically distant.
-
-<p>
-The solution to this is to use large removable media such as a Zip disc or a 
+</para>
+<para>
+The solution to this is to use large removable media such as a Zip disc or a
 SuperDisk disc. These discs are not large enough to store the entire Debian
-archive but can easily fit a subset large enough for most users. The idea
-is to use APT to generate a list of packages that are required and then fetch
-them onto the disc using another machine with good connectivity. It is 
-even possible to use another Debian machine with APT or to use a completely 
-different OS and a download tool like wget. Let <em>remote host</em> mean the
-machine downloading the packages, and <em>target host</em> the one with bad or
-no connection.
-
-<p>
+archive but can easily fit a subset large enough for most users. The idea is
+to use APT to generate a list of packages that are required and then fetch them
+onto the disc using another machine with good connectivity. It is even
+possible to use another Debian machine with APT or to use a completely
+different OS and a download tool like wget. Let <emphasis>remote
+host</emphasis> mean the machine downloading the packages, and <emphasis>target
+host</emphasis> the one with bad or no connection.
+</para>
+<para>
 This is achieved by creatively manipulating the APT configuration file. The
 essential premise to tell APT to look on a disc for it's archive files. Note
 that the disc should be formated with a filesystem that can handle long file
 names such as ext2, fat32 or vfat.
+</para>
+</section>
 
-</sect>
-                                                                  <!-- }}} -->
+</chapter>
 
-<chapt>Using APT on both machines
-<!-- Overview		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Overview
+<chapter id="ch2"><title>Using APT on both machines</title>
 
-<p>
-APT being available on both machines gives the simplest configuration. The 
-basic idea is to place a copy of the status file on the disc and use the 
-remote machine to fetch the latest package files and decide which packages to 
+<section id="s2.1"><title>Overview</title>
+<para>
+APT being available on both machines gives the simplest configuration. The
+basic idea is to place a copy of the status file on the disc and use the remote
+machine to fetch the latest package files and decide which packages to
 download. The disk directory structure should look like:
-
-<example>
+</para>
+<screen>
   /disc/
     archives/
        partial/
@@ -77,36 +92,32 @@ download. The disk directory structure should look like:
     status
     sources.list
     apt.conf
-</example>
-
-</sect>
-                                                                  <!-- }}} -->
-<!-- The configuartion file                                            {{{ -->
-<!-- ===================================================================== -->
-<sect>The configuration file
-
-<p>
-The configuration file should tell APT to store its files on the disc and
-to use the configuration files on the disc as well. The sources.list should
-contain the proper sites that you wish to use from the remote machine, and
-the status file should be a copy of <em>/var/lib/dpkg/status</em> from the
-<em>target host</em>. Please note, if you are using a local archive you must use
-copy URIs, the syntax is identical to file URIs.
-
-<p>
-<em>apt.conf</em> must contain the necessary information to make APT use the 
-disc:
-
-<example>
+</screen>
+</section>
+
+<section id="s2.2"><title>The configuration file</title>
+<para>
+The configuration file should tell APT to store its files on the disc and to
+use the configuration files on the disc as well. The sources.list should
+contain the proper sites that you wish to use from the remote machine, and the
+status file should be a copy of <emphasis>/var/lib/dpkg/status</emphasis> from
+the <emphasis>target host</emphasis>. Please note, if you are using a local
+archive you must use copy URIs, the syntax is identical to file URIs.
+</para>
+<para>
+<emphasis>apt.conf</emphasis> must contain the necessary information to make
+APT use the disc:
+</para>
+<screen>
  APT
  {
    /* This is not necessary if the two machines are the same arch, it tells
       the remote APT what architecture the target machine is */
    Architecture "i386";
-   
+
    Get::Download-Only "true";
  };
- 
+
  Dir
  {
    /* Use the disc for state information and redirect the status file from
@@ -117,120 +128,120 @@ disc:
    // Binary caches will be stored locally
    Cache::archives "/disc/archives/";
    Cache "/tmp/";
-   
+
    // Location of the source list.
    Etc "/disc/";
- }; 
-</example>
-
+ };
+</screen>
+<para>
 More details can be seen by examining the apt.conf man page and the sample
-configuration file in <em>/usr/share/doc/apt/examples/apt.conf</em>.
-
-<p>
-On the target machine the first thing to do is mount the disc and copy 
-<em>/var/lib/dpkg/status</em> to it. You will also need to create the directories
-outlined in the Overview, <em>archives/partial/</em> and <em>lists/partial/</em>.
-Then take the disc to the remote machine and configure the sources.list. 
-On the remote machine execute the following:
-
-<example>
+configuration file in
+<emphasis>/usr/share/doc/apt/examples/apt.conf</emphasis>.
+</para>
+<para>
+On the target machine the first thing to do is mount the disc and copy
+<emphasis>/var/lib/dpkg/status</emphasis> to it. You will also need
+to create the directories outlined in the Overview,
+<emphasis>archives/partial/</emphasis> and
+<emphasis>lists/partial/</emphasis>. Then take the disc to the
+remote machine and configure the sources.list. On the remote
+machine execute the following:
+</para>
+<screen>
  # export APT_CONFIG="/disc/apt.conf"
  # apt-get update
  [ APT fetches the package files ]
  # apt-get dist-upgrade
  [ APT fetches all the packages needed to upgrade the target machine ]
-</example>
-
+</screen>
+<para>
 The dist-upgrade command can be replaced with any other standard APT commands,
-particularly dselect-upgrade. You can even use an APT front end such as 
-<em>dselect</em>. However this presents a problem in communicating your 
-selections back to the local computer.
-
-<p>
-Now the disc contains all of the index files and archives needed to upgrade
-the target machine. Take the disc back and run:
-
-<example>
+particularly dselect-upgrade. You can even use an APT front end such as
+<emphasis>dselect</emphasis>. However this presents a problem in communicating
+your selections back to the local computer.
+</para>
+<para>
+Now the disc contains all of the index files and archives needed to upgrade the
+target machine. Take the disc back and run:
+</para>
+<screen>
   # export APT_CONFIG="/disc/apt.conf"
   # apt-get check
   [ APT generates a local copy of the cache files ]
   # apt-get --no-d -o dir::state::status=/var/lib/dpkg/status dist-upgrade
   [ Or any other APT command ]
-</example>
-
-<p> 
-It is necessary for proper function to re-specify the status file to be the 
+</screen>
+<para>
+It is necessary for proper function to re-specify the status file to be the
 local one. This is very important!
-
-<p>
-If you are using dselect you can do the very risky operation of copying 
+</para>
+<para>
+If you are using dselect you can do the very risky operation of copying
 disc/status to /var/lib/dpkg/status so that any selections you made on the
-remote machine are updated. I highly recommend that people only make selections
-on the local machine - but this may not always be possible. DO NOT copy
-the status file if dpkg or APT have been run in the mean time!!
-
-</sect>
-                                                                  <!-- }}} -->
-
-<chapt>Using APT and wget
-<!-- Overview		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Overview
-
-<p>
-<em>wget</em> is a popular and portable download tool that can run on nearly
-any machine. Unlike the method above this requires that the Debian machine
-already has a list of available packages.
-
-<p>
+remote machine are updated. I highly recommend that people only make
+selections on the local machine - but this may not always be possible. DO NOT
+copy the status file if dpkg or APT have been run in the mean time!!
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch3"><title>Using APT and wget</title>
+
+<section id="s3.1"><title>Overview</title>
+<para>
+<emphasis>wget</emphasis> is a popular and portable download tool that can run
+on nearly any machine. Unlike the method above this requires that the Debian
+machine already has a list of available packages.
+</para>
+<para>
 The basic idea is to create a disc that has only the archive files downloaded
 from the remote site. This is done by using the --print-uris option to apt-get
 and then preparing a wget script to actually fetch the packages.
+</para>
+</section>
 
-</sect>
-                                                                  <!-- }}} -->
-<!-- Operation		                                               {{{ -->
-<!-- ===================================================================== -->
-<sect>Operation
-
-<p>
+<section id="s3.2"><title>Operation</title>
+<para>
 Unlike the previous technique no special configuration files are required. We
 merely use the standard APT commands to generate the file list.
-
-<example>
- # apt-get dist-upgrade 
+</para>
+<screen>
+ # apt-get dist-upgrade
  [ Press no when prompted, make sure you are happy with the actions ]
- # apt-get -qq --print-uris dist-upgrade > uris
- # awk '{print "wget -O " $2 " " $1}' < uris > /disc/wget-script
-</example>
-
-Any command other than dist-upgrade could be used here, including 
+ # apt-get -qq --print-uris dist-upgrade &gt; uris
+ # awk '{print "wget -O " $2 " " $1}' &lt; uris &gt; /disc/wget-script
+</screen>
+<para>
+Any command other than dist-upgrade could be used here, including
 dselect-upgrade.
-
-<p>
-The /disc/wget-script file will now contain a list of wget commands to execute 
+</para>
+<para>
+The /disc/wget-script file will now contain a list of wget commands to execute
 in order to fetch the necessary archives. This script should be run with the
-current directory as the disc's mount point so as to save the output on the 
+current directory as the disc's mount point so as to save the output on the
 disc.
-
-<p>
+</para>
+<para>
 The remote machine would do something like
-
-<example>
+</para>
+<screen>
   # cd /disc
   # sh -x ./wget-script
   [ wait.. ]
-</example>
-
+</screen>
+<para>
 Once the archives are downloaded and the disc returned to the Debian machine
 installation can proceed using,
-
-<example>
+</para>
+<screen>
   # apt-get -o dir::cache::archives="/disc/" dist-upgrade
-</example>
-
+</screen>
+<para>
 Which will use the already fetched archives on the disc.
+</para>
+</section>
+
+</chapter>
 
-</sect>
-                                                                  <!-- }}} -->
 </book>