Base revisions

Author: jgg
Date: 1998-07-02 02:58:12 GMT
Base revisions

10 files changed, 3489 insertions, 0 deletions

diff --git a/doc/apt-cache.8 b/doc/apt-cache.8
new file mode 100644
index 000000000..0292973ed
--- /dev/null
+++ b/doc/apt-cache.8
@@ -0,0 +1,199 @@
+.\" This manpage is copyright (C) 1998 Branden Robinson <branden@debian.org>.

+.\" 

+.\" This 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.

+.\"

+.\" This is distributed in the hope that it will be useful, but

+.\" WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with APT; if not, write to the Free Software

+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 

+.\" 02111-1307 USA

+.TH apt-cache 8 "16 June 1998" "Debian GNU/Linux"

+.SH NAME

+apt-cache \- APT package handling utility \(em cache manipulator

+.SH SYNOPSIS

+.B apt-cache

+.I command cache

+.RI [ argument 

+.IR ... ]

+.SH DESCRIPTION

+.B apt-cache

+performs a variety of operations on APT's package cache.

+.I apt-cache

+is seldom called directly; instead it is usually invoked internally by

+.BR apt-get (8)

+or

+.BR apt (8).

+.PP

+.I command

+is one of

+.RS

+.PD 0

+.B add

+.PP

+.B dump

+.PP

+.B dumpavail

+.PP

+.B showpkg

+.PP

+.B stats

+.RE

+.PD 1

+.PP

+.I cache

+must be a package cache file (for instance,

+.IR /var/cache/apt/pkgcache.bin ).

+Some

+.IR command s

+require additional arguments.

+.SS add

+.B add

+adds a new set of package records to

+.IR cache .

+Remaining arguments are of the form

+.IR file : dist : ver ,

+where

+.I file

+is the full path to file in question.

+.I dist

+and

+.I ver

+can be any string and are not yet implemented.

+.SS dump

+.B dump

+displays information about all the packages in the cache. See

+.B showpkg

+below for an explanation of what data is output for each package.

+.SS dumpavail

+.B dumpavail

+generates an

+.I available

+file suitable for use with

+.BR dpkg (8)

+based on the information in the cache.

+.SS showpkg

+.B showpkg

+displays information about the packages listed on the command line.     

+Remaining arguments are package names. The available versions and       

+reverse dependencies of each package listed are listed, as well as      

+forward dependencies for each version. Forward (normal) dependencies   

+are those packages upon which the package in question depends; reverse  

+dependencies are those packages that depend upon the package in         

+question. Thus, forward dependencies must be satisfied for a package,  

+but reverse dependencies need not be.                                   

+For instance,

+.B apt-cache showpkg

+.I cache

+.B libreadline2

+would produce output similar to the following:

+.PP

+.RS

+.PD 0

+Package: libreadline2

+.PP

+Versions: 2.1-8,2.1-7,

+.PP

+Reverse Depends:

+.RS

+.PP

+libreadlineg2,libreadline2

+.PP

+libreadlineg2,libreadline2

+.PP

+libreadline2-altdev,libreadline2

+.RE

+.PP

+Dependencies:

+.PP

+2.1-8 - libc5 ncurses3.0 ldso

+.PP

+2.1-7 - ldso libc5 ncurses3.0

+.RE

+.PD 1

+.PP

+Thus it may be seen that libreadline2, version 2.1-8, depends on libc5,

+ncurses3.0, and ldso, which must be installed for libreadline2 to work. In

+turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If

+libreadline2 is installed, libc5, ncurses3.0, and ldso must also be

+installed; libreadlineg2 and libreadline2-altdev do not have to be

+installed.

+.SS stats

+.B stats

+displays some statistics about

+.IR cache .

+No further arguments are expected. Statistics reported are:

+.RS

+.TP

+.I Total package names

+is the number of package names found in the cache.

+.TP

+.I Normal packages

+is the number of regular, ordinary package names; these

+are packages that bear a one-to-one correspondence between their names and

+the names used by other packages for them in dependencies. The majority of

+packages fall into this category.

+.TP

+.I Pure virtual packages

+is the number of packages that exist only as a virtual package name; that

+is, packages only "provide" the virtual package name, and no package

+actually uses the name. For instance, "mail-transport-agent" in the Debian

+GNU/Linux system is a pure virtual package; several packages provide

+"mail-transport-agent", but there is no package named "mail-transport-agent".

+.TP

+.I Single virtual packages

+is the number of packages with only one package providing a particular  

+virtual package. For instance, in the Debian GNU/Linux system,         

+"X11-text-viewer" is a virtual package, but only one package, xless,    

+provides "X11-text-viewer".

+.TP

+.I Mixed virtual packages

+is the number of packages that either provide a particular virtual package

+or have the virtual package name as the package name. For instance, in the

+Debian GNU/Linux system, e2fsprogs is both an actual package, and

+provided by the e2compr package.

+.TP

+.I Missing

+is the number of package names that were referenced in a dependency but

+were not provided by any package. Missing packages may be in evidence

+if a full distribution is not accesssed, or if a package (real or virtual)

+has been dropped from the distribution.

+.TP

+.I Total distinct versions

+is the number of package versions found in the cache; this value is

+therefore at least equal to the number of total package names. If more than

+one distribution (both "stable" and "unstable", for instance), is being

+accessed, this value can be considerably larger than the number of total

+package names.

+.TP

+.I Total dependencies

+is the number of dependency relationships claimed by all of the packages in

+the cache.

+.RE

+.SH OPTIONS

+None.

+.SH FILES

+None.

+.SH SEE ALSO

+.BR apt (8),

+.BR apt-get (8),

+.I /usr/doc/apt/cache*

+.SH DIAGNOSTICS

+apt-cache returns zero on normal operation, decimal 100 on error.

+.SH BUGS

+See <http://www.debian.org/Bugs/db/pa/lapt.html>.  If you wish to report a

+bug in

+.BR apt-cache ,

+please see

+.I /usr/doc/debian/bug-reporting.txt

+or the

+.BR bug (1)

+command.

+.SH AUTHOR

+apt-cache was written by the APT team <apt@packages.debian.org>.

diff --git a/doc/apt-get.8 b/doc/apt-get.8
new file mode 100644
index 000000000..c53dc70d7
--- /dev/null
+++ b/doc/apt-get.8
@@ -0,0 +1,250 @@
+.\" $Id: apt-get.8,v 1.1 1998/07/02 02:58:12 jgg Exp $

+.\" This manpage is copyright (C) 1998 Branden Robinson <branden@debian.org>.

+.\" 

+.\" This 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.

+.\"

+.\" This is distributed in the hope that it will be useful, but

+.\" WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with APT; if not, write to the Free Software

+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 

+.\" 02111-1307 USA

+.TH apt-get 8 "16 June 1998" "Debian GNU/Linux"

+.SH NAME

+apt-get \- APT package handling utility \(em command-line interface

+.SH SYNOPSIS

+.B apt-get

+.RI [ options ]

+.RI [ command ]

+.RI [ package

+.IR ... ]

+.SH DESCRIPTION

+.B apt-get

+is the command-line tool for handling packages, and may be considered the

+user's "back-end" to

+.BR apt (8).

+Use

+.BR apt (8)

+if the usage of apt-get does not seem intuitive.

+.PP

+.I command

+is one of

+.RS

+.PD 0

+.B update

+.PP

+.B upgrade

+.PP

+.B dselect-upgrade

+.PP

+.B dist-upgrade

+.PP

+.B install

+.PP

+.B check

+.PP

+.B clean

+.RE

+.PD 1

+.PP

+Unless one of the

+.IR -h ,

+.IR --help ,

+.IR -f ,

+or

+.I --fix-broken

+options is given, one of the above commands must be present. Only the

+.B install

+command requires any further arguments.

+.SS update

+.B update

+is used to resynchronize the package overview files from their

+sources. The overviews of available packages are fetched from the

+location(s) specified in

+.IR /etc/apt/sources.list .

+For example, when using a Debian archive, this command retrieves and

+scans the

+.I Packages.gz

+files, so that information about new and updated packages is available. An

+.B update

+should always be performed before an

+.B upgrade

+or

+.BR dist-upgrade .

+.SS upgrade

+.B upgrade

+is used to install the newest versions of all packages currently installed

+on the system from the sources enumerated in

+.IR /etc/apt/sources.list .

+Packages currently installed with new versions available are retrieved

+and upgraded; under no circumstances are currently installed packages

+removed, or packages not already installed retrieved and installed. New

+versions of currently installed packages that cannot be upgraded without

+changing the install status of another package will be left at their

+current version. An

+.B update

+must be performed first so that

+.B apt-get

+knows that new versions of packages are available.

+.SS dselect-upgrade

+.B dselect-upgrade

+is used in conjunction with the traditional Debian GNU/Linux packaging

+front-end,

+.BR dselect (8). " dselect-upgrade"

+follows the changes made by

+.B dselect

+to the

+.I Status

+field of available packages, and performs the actions necessary to realize

+that state (for instance, the removal of old and the installation of new

+packages).

+.B dselect-upgrade

+does not attempt to intelligently address dependency issues as

+.B dist-upgrade

+or

+.B install

+do. If any dependency problems arise,

+.B apt-get

+aborts without performing any of the actions requested, even those

+without problems.

+.B dselect-upgrade

+is only useful to users of

+.B dselect

+and the

+.I .deb

+package file format. The

+.I /etc/apt/sources.list

+file contains a list of locations from which to retrieve desired package

+files.

+.SS dist-upgrade

+.BR dist-upgrade ,

+in addition to performing the function of

+.BR upgrade ,

+also intelligently handles changing dependencies with new versions of

+packages;

+.B apt-get

+has a "smart" conflict resolution system, and it will attempt to upgrade

+the most important packages at the expense of less important ones if

+necessary. The

+.I /etc/apt/sources.list

+file contains a list of locations from which to retrieve desired package

+files.

+.SS install

+.B install

+is followed by one or more

+.I packages

+desired for installation. Each

+.I package

+is a package name, not a fully qualified filename (for instance, in a

+Debian GNU/Linux system,

+.I lsdo

+would be the argument provided, not

+.IR ldso_1.9.6-2.deb ).

+All packages required by the package(s) specified for installation will

+also be retrieved and installed. The

+.I /etc/apt/sources.list

+file is used to locate the desired packages. If a hyphen is appended to

+the package name (with no intervening space), the identified package will

+be removed if it is installed. This latter feature may be used to override

+decisions made by apt-get's conflict resolution system.

+.SS check

+.B check

+is a diagnostic tool; it updates the package cache and checks for broken

+packages.

+.SS clean

+.B clean

+clears out the local repository of retrieved package files. It removes

+everything but the lock file from

+.I /var/cache/apt/archives/

+and

+.IR /var/cache/apt/archives/partial/ .

+When APT is used as a

+.BR dselect (8)

+method,

+.B

+clean

+is run automatically.  Those who do not use dselect will likely want to

+run

+.B

+apt-get clean

+from time to time to free up disk space.

+.SH OPTIONS

+.TP

+.IR \-d , " --download-only"

+Download only; package files are only retrieved, not unpacked or installed.

+.TP

+.IR \-f , " --fix-broken"

+Fix; attempt to correct a system with broken dependencies in            

+place. This option may be used alone or in conjunction with any of the  

+command actions, and is sometimes necessary when running APT for the    

+first time; APT itself does not allow broken package dependencies to    

+exist on a system. It is possible that a system's dependency structure  

+can be so corrupt as to require manual intervention (which usually      

+means using dselect or dpkg --remove to eliminate some of the offending 

+packages). Use of this option together with -m is discouraged.          

+.TP

+.IR \-h , " --help"

+Help; display a helpful usage message and exit.

+.TP

+.IR \-m , " --ignore-missing"

+Ignore missing packages; If packages cannot be retrieved or fail the    

+integrity check after retrieval (corrupted package files), hold back    

+those packages and handle the result. Use of this option together with  

+-f is discouraged.                                                      

+.TP

+.IR \-q , " --silent"

+Quiet; produces output suitable for logging, omitting progress indicators.

+.TP

+.I \-qq

+Very quiet; no output except for errors.

+.TP

+.IR \-s , " --simulate" , " --just-print" , " --dry-run" , " --recon " , " --no-act"

+No action; perform a simulation of events that would occur but do not

+actually change the system.

+.TP

+.IR \-y , " --yes" , " --assume-yes"

+Automatic yes to prompts; assume "yes" as answer to all prompts and run

+non-interactively.

+.SH FILES

+.TP

+.I /etc/apt/sources.list

+see

+.BR sources.list (5)

+.TP

+.I /var/cache/apt/archives/

+storage area for retrieved package files

+.TP

+.I /var/cache/apt/archives/partial/

+storage area for package files in transit

+.TP

+.I /var/state/apt/lists/

+storage area for state information for each package resource specified in

+.I /etc/apt/sources.list

+.TP

+.I /var/state/apt/lists/partial/

+storage area for state information in transit

+.SH SEE ALSO

+.BR apt (8),

+.BR apt-cache (8),

+.BR dpkg (8),

+.BR dselect (8),

+.BR sources.list (5)

+.SH DIAGNOSTICS

+apt-get returns zero on normal operation, decimal 100 on error.

+.SH BUGS

+See <http://www.debian.org/Bugs/db/pa/lapt.html>.  If you wish to report a

+bug in

+.BR apt-get ,

+please see

+.I /usr/doc/debian/bug-reporting.txt

+or the

+.BR bug (1)

+command.

+.SH AUTHOR

+apt-get was written by the APT team <apt@packages.debian.org>.

diff --git a/doc/apt.8 b/doc/apt.8
new file mode 100644
index 000000000..08aa2c4fd
--- /dev/null
+++ b/doc/apt.8
@@ -0,0 +1,50 @@
+.\" This manpage is copyright (C) 1998 Branden Robinson <branden@debian.org>.
+.\" 
+.\" This 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.
+.\"
+.\" This is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with APT; if not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
+.\" 02111-1307 USA
+.TH apt 8 "16 June 1998" "Debian GNU/Linux"
+.SH NAME
+apt \- Advanced Package Tool
+.SH SYNOPSIS
+.B apt
+.SH DESCRIPTION
+APT is a management system for software packages.  It is still
+under development; the snazzy front ends are not yet available.  In the
+meantime, please see
+.BR apt-get (8).
+.SH OPTIONS
+None.
+.SH FILES
+None.
+.SH SEE ALSO
+.BR apt-cache (8),
+.BR apt-get (8),
+.BR ftp.conf (5),
+.BR sources.list (5)
+.SH DIAGNOSTICS
+apt returns zero on normal operation, decimal 100 on error.
+.SH BUGS
+This manpage isn't even started.
+.PP
+See <http://www.debian.org/Bugs/db/pa/lapt.html>.  If you wish to report a
+bug in
+.BR apt ,
+please see
+.I /usr/doc/debian/bug-reporting.txt
+or the
+.BR bug (1)
+command.
+.SH AUTHOR
+apt was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/cache.sgml b/doc/cache.sgml
new file mode 100644
index 000000000..43f8d4fff
--- /dev/null
+++ b/doc/cache.sgml
@@ -0,0 +1,761 @@
+<!doctype debiandoc system>
+<!-- -*- mode: sgml; mode: fold -*- -->
+<book>
+<title>APT Cache File Format</title>
+
+<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
+<version>$Id: cache.sgml,v 1.1 1998/07/02 02:58:12 jgg Exp $</version>
+
+<abstract>
+This document describes the complete implementation and format of the APT
+Cache file. The APT Cache file is a way for APT to parse and store a 
+large number of package files for display in the UI. It's primary design 
+goal is to make display of a single package in the tree very fast by 
+pre-linking important things like dependencies and provides.
+
+The specification doubles as documentation for one of the in-memory 
+structures used by the package library and the APT GUI.
+
+</abstract>
+
+<copyright>
+Copyright &copy; Jason Gunthorpe, 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 GNU/Linux systems, see the file
+/usr/doc/copyright/GPL for the full license.
+</copyright>
+
+<toc sect>
+
+<chapt>Introduction
+<!-- Purpose		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>Purpose
+
+<p>
+This document describes the implementation of an architecture
+dependent binary cache file. The goal of this cache file is two fold, 
+firstly to speed loading and processing of the package file array and
+secondly to reduce memory consumption of the package file array.
+
+<p>
+The implementation is aimed at an environment with many primary package
+files, for instance someone that has a Package file for their CD-ROM, a
+Package file for the latest version of the distribution on the CD-ROM and a
+package file for the development version. Always present is the information
+contained in the status file which might be considered a separate package
+file.
+
+<p>
+Please understand, this is designed as a -CACHE FILE- it is not ment to be
+used on any system other than the one it was created for. It is not ment to
+be authoritative either, ie if a system crash or software failure occures it
+must be perfectly acceptable for the cache file to be in an inconsistant
+state. Furthermore at any time the cache file may be erased without losing
+any information.
+
+<p>
+Also the structures and storage layout is optimized for use by the APT
+GUI and may not be suitable for all purposes. However it should be possible 
+to extend it with associate cache files that contain other information.
+
+<p>
+To keep memory use down the cache file only contains often used fields and
+fields that are inexepensive to store, the Package file has a full list of
+fields. Also the client may assume that all items are perfectly valid and
+need not perform checks against their correctness. Removal of information
+from the cache is possible, but blanks will be left in the file, and
+unused strings will also be present. The recommended implementation is to
+simply rebuild the cache each time any of the data files change. It is
+possible to add a new package file to the cache without any negative side
+effects.
+
+<sect1>Note on Pointer access
+<p>
+Every item in every structure is stored as the index to that structure.
+What this means is that once the files is mmaped every data access has to
+go through a fixup stage to get a real memory pointer. This is done
+by taking the tndex, multiplying it by the type size and then adding
+it to the start address of the memory block. This sounds complex, but
+in C it is a single array dereference. Because all items are aligned to 
+their size and indexs are stored as multiples of the size of the structure
+the format is immediately portable to all possible architectures - BUT the
+generated files are -NOT-.
+
+<p>
+This scheme allows code like this to be written:
+<example>
+  void *Map = mmap(...);
+  Package *PkgList = (Package *)Map;
+  Header *Head = (Header *)Map;
+  char *Strings = (char *)Map;
+  cout << (Strings + PkgList[Head->HashTable[0]]->Name) << endl;
+</example>
+<p>
+Notice the lack of casting or multiplication. The net result is to return
+the name of the first package in the first hash bucket, without error
+checks. 
+
+<p>
+The generator uses allocation pools to group similarly sized structures in
+large blocks to eliminate any alignment overhead. The generator also
+assures that no structures overlap and all indexes are unique. Although
+at first glance it may seem like there is the potential for two structures
+to exist at the same point the generator never allows this to happen.
+(See the discussion of free space pools)
+                                                                  <!-- }}} -->
+
+<chapt>Structures
+<!-- Header		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>Header
+<p>
+This is the first item in the file.
+<example>
+   struct Header
+   {
+      // Signature information
+      unsigned long Signature;
+      short MajorVersion;
+      short MinorVersion;
+      bool Dirty;
+       
+      // Size of structure values
+      unsigned short HeaderSz;
+      unsigned short PackageSz;
+      unsigned short PackageFileSz;
+      unsigned short VersionSz;
+      unsigned short DependencySz;
+      unsigned short ProvidesSz;
+
+      // Structure counts
+      unsigned long PackageCount;
+      unsigned long VersionCount;
+      unsigned long DependsCount;
+      unsigned long PackageFileCount;
+      
+      // Offsets
+      unsigned long FileList;              // PackageFile
+      unsigned long StringList;            // StringItem
+      
+      // Pool structures
+      unsigned long PoolStart[6];
+      unsigned long PoolSize[6];
+      unsigned long PoolAln[6];
+      
+      // Package name lookup
+      unsigned long HashTable[512];        // Package
+   };
+</example>
+<taglist>
+<tag>Signature<item>
+This must contain the hex value 0x98FE76DC which is designed to verify
+that the system loading the image has the same byte order and byte size as
+the system saving the image
+
+<tag>MajorVersion
+<tag>MinorVersion<item>
+These contain the version of the cache file, currently 0.2.
+
+<tag>Dirty<item>
+Dirty is true if the cache file was opened for reading, the client expects
+to have written things to it and have not fully synced it. The file should
+be erased and rebuilt if it is true.
+
+<tag>HeaderSz
+<tag>PackageSz
+<tag>PackageFileSz
+<tag>VersionSz
+<tag>DependencySz
+<tag>ProvidesSz<item>
+*Sz contains the sizeof() that particular structure. It is used as an
+extra consistancy check on the structure of the file.
+
+If any of the size values do not exactly match what the client expects then
+the client should refuse the load the file.
+
+<tag>PackageCount
+<tag>VersionCount
+<tag>DependsCount
+<tag>PackageFileCount<item>
+These indicate the number of each structure contianed in the cache. 
+PackageCount is especially usefull for generating user state structures. 
+See Package::Id for more info.
+
+<tag>FileList<item>
+This contains the index of the first PackageFile structure. The PackageFile
+structures are singely linked lists that represent all package files that
+have been merged into the cache.
+
+<tag>StringList<item>
+This contains a list of all the unique strings (string item type strings) in 
+the cache. The parser reads this list into memory so it can match strings 
+against it.
+
+<tag>PoolStart
+<tag>PoolSize
+<tag>PoolAln<item>
+The Pool structures manage the allocation pools that the generator uses.
+Start indicates the first byte of the pool, Size is the number of bytes
+remaining in the pool and Aln (alignment) is the structure size of the pool. 
+An Aln of 0 indicates the slot is empty. There should be the same number of
+slots as there are structure types. The generator stores this information 
+so future additions can make use of any unused pool blocks.
+
+<tag>HashTable<item>
+HashTable is a hash table that provides indexing for all of the packages.
+Each package name is inserted into the hash table using the following has
+function:
+<example>
+   unsigned long Hash(string Str)
+   {
+      unsigned long Hash = 0;
+      for (const char *I = Str.begin(); I != Str.end(); I++)
+         Hash += *I * ((Str.end() - I + 1));
+      return Hash % _count(Head.HashTable);
+   }
+</example>
+<p>
+By iterating over each entry in the hash table it is possible to iterate over 
+the entire list of packages. Hash Collisions are handled with a singely linked
+list of packages based at the hash item. The linked list contains only 
+packages that macth the hashing function.
+
+</taglist>
+                                                                  <!-- }}} -->
+<!-- Package		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>Package
+<p>
+This contians information for a single unique package. There can be any
+number of versions of a given package. Package exists in a singly
+linked list of package records starting at the hash index of the name in 
+the Header->HashTable.
+<example>
+   struct Pacakge
+   {
+      // Pointers
+      unsigned long Name;              // Stringtable
+      unsigned long VersionList;       // Version
+      unsigned long TargetVer;         // Version
+      unsigned long CurrentVer;        // Version
+      unsigned long TargetDist;        // StringTable (StringItem)
+      unsigned long Section;           // StringTable (StringItem)
+      
+      // Linked lists 
+      unsigned long NextPackage;       // Package
+      unsigned long RevDepends;        // Dependency
+      unsigned long ProvidesList;      // Provides
+       
+      // Install/Remove/Purge etc
+      unsigned char SelectedState;     // What
+      unsigned char InstState;         // Flags
+      unsigned char CurrentState;      // State
+
+      // Unique ID for this pkg
+      unsigned short ID;
+      unsigned short Flags;
+   };
+</example>   
+
+<taglist>
+<tag>Name<item>
+Name of the package.
+
+<tag>VersionList<item>
+Base of a singely linked list of version structures. Each structure 
+represents a unique version of the package. The version structures
+contain links into PackageFile and the original text file as well as
+detailed infromation about the size and dependencies of the specific
+package. In this way multiple versions of a package can be cleanly handled
+by the system. Furthermore, this linked list is guarenteed to be sorted
+from Highest version to lowest version with no duplicate entries.
+
+<tag>TargetVer
+<tag>CurrentVer<item>
+This is an index (pointer) to the sub version that is being targeted for
+upgrading. CurrentVer is an index to the installed version, either can be
+0.
+
+<tag>TargetDist<item>
+This indicates the target distribution. Automatic upgrades should not go
+outside of the specified dist. If it is 0 then the global target dist should 
+be used. The string should be contained in the StringItem list.
+
+<tag>Section<item>
+This indicates the deduced section. It should be "Unknown" or the section
+of the last parsed item.
+
+<tag>NextPackage<item>
+Next link in this hash item. This linked list is based at Header.HashTable
+and contains only packages with the same hash value.
+
+<tag>RevDepends<item>
+Reverse Depends is a linked list of all dependencies linked to this package.
+
+<tag>ProvidesList<item>
+This is a linked list of all provides for this package name.
+
+<tag>SelectedState
+<tag>InstState
+<tag>CurrentState<item>
+These corrispond to the 3 items in the Status field found in the status
+file. See the section on defines for the possible values.
+<p>
+SelectedState is the state that the user wishes the package to be
+in.
+<p>
+InstState is the installation state of the package. This normally
+should be Ok, but if the installation had an accident it may be otherwise.
+<p>
+CurrentState indicates if the package is installed, partially installed or
+not installed.
+
+<tag>ID<item>
+ID is a value from 0 to Header->PackageCount. It is a unique value assigned
+by the generator. This allows clients to create an array of size PackageCount
+and use it to store state information for the package map. For instance the
+status file emitter uses this to track which packages have been emitted 
+already.
+
+<tag>Flags<item>
+Flags are some usefull indicators of the package's state. 
+
+</taglist>
+
+                                                                  <!-- }}} -->
+<!-- PackageFile	                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>PackageFile
+<p>
+This contians information for a single package file. Package files are
+referenced by Version structures. This is a singly linked list based from
+Header.FileList
+<example>
+   struct PackageFile
+   {
+      // Names
+      unsigned long FileName;        // Stringtable
+      unsigned long Version;         // Stringtable
+      unsigned long Distribution;    // Stringtable
+      unsigned long Size;            
+      
+      // Linked list
+      unsigned long NextFile;        // PackageFile
+      unsigned short ID;
+      unsigned short Flags;
+      time_t mtime;                  // Modification time
+   };
+</example>   
+<taglist>
+
+<tag>FileName<item>
+Refers the the physical disk file that this PacakgeFile represents.
+
+<tag>Version<item>
+Version is the given version, ie 1.3.1, 2.4_revision_1 etc.
+
+<tag>Distribution<item>
+Distribution is the symbolic name for this PackageFile, hamm,bo,rexx etc
+
+<tag>Size<item>
+Size is provided as a simple check to ensure that the package file has not
+been altered.
+
+<tag>ID<item>
+See Package::ID.
+
+<tag>Flags<item>
+Provides some flags for the PackageFile, see the section on defines.
+
+<tag>mtime<item>
+Modification time for the file at time of cache generation.
+
+</taglist>
+
+                                                                  <!-- }}} -->
+<!-- Version		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>Version
+<p>
+This contians the information for a single version of a package. This is a
+singley linked list based from Package.Versionlist.
+
+<p>
+The version list is always sorted from highest version to lowest version by
+the generator. Also there may not be any duplicate entries in the list (same 
+VerStr).
+
+<example>
+   struct Version
+   {
+      unsigned long VerStr;            // Stringtable
+      unsigned long File;              // PackageFile
+      unsigned long Section;           // StringTable (StringItem)
+      
+      // Lists
+      unsigned long NextVer;           // Version
+      unsigned long DependsList;       // Dependency
+      unsigned long ParentPkg;         // Package
+      unsigned long ProvidesList;      // Provides
+     
+      unsigned long Offset;
+      unsigned long Size;
+      unsigned long InstalledSize;
+      unsigned short ID;
+      unsigned char Priority;
+   };
+</example>
+<taglist>
+
+<tag>VerStr<item>
+This is the complete version string.
+
+<tag>File<item>
+References the PackageFile that this version came out of. File can be used
+to determine what distribution the Version applies to. If File is 0 then
+this is a blank version. The structure should also have a 0 in all other
+fields excluding VerStr and Possibly NextVer.
+
+<tag>Section<item>
+This string indicates which section it is part of. The string should be
+contained in the StringItem list.
+
+<tag>NextVer<item>
+Next step in the linked list.
+
+<tag>DependsList<item>
+This is the base of the dependency list.
+
+<tag>ParentPkg<item>
+This links the version to the owning package, allowing reverse dependencies
+to determine the package.
+
+<tag>ProvidesList<item>
+Head of the linked list of Provides::NextPkgProv, forward provides.
+
+<tag>Offset<item>
+The byte offset of the first line of this item in the specified
+PackageFile
+
+<tag>Size
+<tag>InstalledSize<item>
+The archive size for this version. For debian this is the size of the .deb
+file. Installed size is the uncompressed size for this version
+
+<tag>ID<item>
+See Package::ID.
+
+<tag>Priority<item>
+This is the parsed priority value of the package.
+</taglist>
+
+                                                                  <!-- }}} -->
+<!-- Dependency		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>Dependency
+<p>
+Dependency contains the information for a single dependency record. The records
+are split up like this to ease processing by the client. The base of list
+linked list is Version.DependsList. All forms of dependencies are recorded
+here including Conflicts, Suggests and Recommends.
+
+<p>
+Multiple depends on the same package must be grouped together in 
+the Dependency lists. Clients should assume this is always true.
+
+<example>
+    struct Dependency
+    {
+       unsigned long Version;         // Stringtable
+       unsigned long Package;         // Package
+       unsigned long NextDepends;     // Dependency
+       unsigned long NextRevDepends;  // Reverse dependency linking
+       unsigned long ParentVer;       // Upwards parent version link
+       
+       // Specific types of depends
+       unsigned char Type;
+       unsigned char CompareOp;
+       unsigned short ID;
+    };
+</example>
+<taglist>
+<tag>Version<item>
+The string form of the version that the dependency is applied against.
+
+<tag>Package<item>
+The index of the package file this depends applies to. If the package file
+does not already exist when the dependency is inserted a blank one (no
+version records) should be created.
+
+<tag>NextDepends<item>
+Linked list based off a Version structure of all the dependencies in that
+version.
+
+<tag>NextRevDepends<item>
+Reverse dependency linking, based off a Package structure. This linked list
+is a list of all packages that have a depends line for a given package.
+
+<tag>ParentVer<item>
+Parent version linking, allows the reverse dependency list to link
+back to the version and package that the dependency are for.
+
+<tag>Type<item>
+Describes weather it is depends, predepends, recommends, suggests, etc.
+
+<tag>CompareOp<item>
+Describes the comparison operator specified on the depends line. If the high
+bit is set then it is a logical or with the previous record.
+
+<tag>ID<item>
+See Package::ID.
+
+</taglist>
+
+                                                                  <!-- }}} -->
+<!-- Provides		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>Provides
+<p>
+Provides handles virtual packages. When a Provides: line is encountered 
+a new provides record is added associating the package with a virtual 
+package name. The provides structures are linked off the package structures.
+This simplifies the analysis of dependencies and other aspects A provides 
+refers to a specific version of a specific package, not all versions need to 
+provide that provides.
+
+<p>
+There is a linked list of provided package names started from each 
+version that provides packages. This is the forwards provides mechanism.
+<example>
+    struct Provides
+    {
+       unsigned long ParentPkg;        // Package
+       unsigned long Version;          // Version
+       unsigned long ProvideVersion;   // Stringtable
+       unsigned long NextProvides;     // Provides
+       unsigned long NextPkgProv;      // Provides
+    };
+</example>
+<taglist>
+<tag>ParentPkg<item>
+The index of the package that head of this linked list is in. ParentPkg->Name
+is the name of the provides.
+
+<tag>Version<item>
+The index of the version this provide line applies to.
+
+<tag>ProvideVersion<item>
+Each provides can specify a version in the provides line. This version allows
+dependencies to depend on specific versions of a Provides, as well as allowing
+Provides to override existing packages. This is experimental.
+
+<tag>NextProvides<item>
+Next link in the singly linked list of provides (based off package)
+
+<tag>NextPkgProv<item>
+Next link in the singly linked list of provides for 'Version'.
+
+</taglist>
+
+                                                                  <!-- }}} -->
+<!-- StringItem		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>StringItem
+<p>
+StringItem is used for generating single instances of strings. Some things
+like Section Name are are usefull to have as unique tags. It is part of 
+a linked list based at Header::StringList.
+<example>
+   struct StringItem
+   {
+      unsigned long String;        // Stringtable
+      unsigned long NextItem;      // StringItem
+   };
+</example>
+<taglist>
+<tag>String<item>
+The string this refers to.
+
+<tag>NextItem<item>
+Next link in the chain.
+</taglist>
+                                                                  <!-- }}} -->
+<!-- StringTable	                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>StringTable
+<p>
+All strings are simply inlined any place in the file that is natural for the
+writer. The client should make no assumptions about the positioning of
+strings. All stringtable values point to a byte offset from the start of the
+file that a null terminated string will begin.
+                                                                  <!-- }}} -->
+<!-- Defines		                                               {{{ -->
+<!-- ===================================================================== -->
+<sect>Defines
+<p>
+Several structures use variables to indicate things. Here is a list of all
+of them.
+
+<sect1>Definitions for Dependency::Type
+<p>
+<example>
+#define pkgDEP_Depends 1
+#define pkgDEP_PreDepends 2
+#define pkgDEP_Suggests 3
+#define pkgDEP_Recommends 4
+#define pkgDEP_Conflicts 5
+#define pkgDEP_Replaces 6
+</example>
+</sect1>
+
+<sect1>Definitions for Dependency::CompareOp
+<p>
+<example>
+#define pkgOP_OR 0x10
+#define pkgOP_LESSEQ 0x1
+#define pkgOP_GREATEREQ 0x2
+#define pkgOP_LESS 0x3
+#define pkgOP_GREATER 0x4
+#define pkgOP_EQUALS 0x5
+</example>
+The lower 4 bits are used to indicate what operator is being specified and
+the upper 4 bits are flags. pkgOP_OR indicates that the next package is
+or'd with the current package.
+</sect1>
+
+<sect1>Definitions for Package::SelectedState
+<p>
+<example>
+#define pkgSTATE_Unkown 0
+#define pkgSTATE_Install 1
+#define pkgSTATE_Hold 2
+#define pkgSTATE_DeInstall 3
+#define pkgSTATE_Purge 4
+</example>
+</sect1>
+
+<sect1>Definitions for Package::InstState
+<p>
+<example>
+#define pkgSTATE_Ok 0
+#define pkgSTATE_ReInstReq 1
+#define pkgSTATE_Hold 2
+#define pkgSTATE_HoldReInstReq 3
+</example>
+</sect1>
+
+<sect1>Definitions for Package::CurrentState
+<p>
+<example>
+#define pkgSTATE_NotInstalled 0
+#define pkgSTATE_UnPacked 1
+#define pkgSTATE_HalfConfigured 2
+#define pkgSTATE_UnInstalled 3
+#define pkgSTATE_HalfInstalled 4
+#define pkgSTATE_ConfigFiles 5
+#define pkgSTATE_Installed 6
+</example>
+</sect1>
+
+<sect1>Definitions for Package::Flags
+<p>
+<example>
+#define pkgFLAG_Auto (1 << 0)
+#define pkgFLAG_New (1 << 1)
+#define pkgFLAG_Obsolete (1 << 2)
+#define pkgFLAG_Essential (1 << 3)
+#define pkgFLAG_ImmediateConf (1 << 4)
+</example>
+</sect1>
+
+<sect1>Definitions for Version::Priority
+<p>
+Zero is used for unparsable or absent Priority fields.
+<example>
+#define pkgPRIO_Important 1
+#define pkgPRIO_Required 2
+#define pkgPRIO_Standard 3
+#define pkgPRIO_Optional 4
+#define pkgPRIO_Extra 5
+</example>
+</sect1>
+
+<sect1>Definitions for PackageFile::Flags
+<p>
+<example>
+#define pkgFLAG_NotSource (1 << 0)
+</example>
+</sect1>
+
+                                                                  <!-- }}} -->
+
+<chapt>Notes on the Generator
+<!-- Notes on the Generator 	                                       {{{ -->
+<!-- ===================================================================== -->
+<p>
+The pkgCache::MergePackageFile function is currently the only generator of
+the cache file. It implements a conversion from the normal textual package
+file into the cache file.
+
+<p>
+The generator assumes any package declaration with a
+Status: line is a 'Status of the package' type of package declaration. 
+A Package with a Target-Version field should also really have a status field.
+The processing of a Target-Version field can create a place-holder Version
+structure that is empty to refer to the specified version (See Version
+for info on what a empty Version looks like). The Target-Version syntax
+allows the specification of a specific version and a target distribution. 
+
+<p>
+Different section names on different versions is supported, but I 
+do not expect to use it. To simplify the GUI it will mearly use the section
+in the Package structure. This should be okay as I hope sections do not change
+much.
+
+<p>
+The generator goes through a number of post processing steps after producing
+a disk file. It sorts all of the version lists to be in descending order
+and then generates the reverse dependency lists for all of the packages.
+ID numbers and count values are also generated in the post processing step.
+
+<p>
+It is possible to extend many of the structures in the cache with extra data.
+This is done by using the ID member. ID will be a unique number from 0 to
+Header->??Count. For example
+<example>
+struct MyPkgData;
+MyPkgData *Data = new MyPkgData[Header->PackageCount];
+Data[Package->ID]->Item = 0;
+</example>
+This provides a one way reference between package structures and user data. To
+get a two way reference would require a member inside the MyPkgData structure.
+
+<p>
+The generators use of free space pools tend to make the package file quite
+large, and quite full of blank space. This could be fixed with sparse files.
+
+                                                                  <!-- }}} -->
+
+<chapt>Future Directions
+<!-- Future Directions		                                       {{{ -->
+<!-- ===================================================================== -->
+<p>
+Some good directions to take the cache file is into a cache directory that
+contains many associated caches that cache other important bits of
+information. (/var/cache/apt, FHS2) 
+
+<p>
+Caching of the info/*.list is an excellent place to start, by generating all
+the list files into a tree structure and reverse linking them to the package
+structures in the main cache file major speed gains in dpkg might be achived.
+
+                                                                  <!-- }}} -->
+
+</book>
diff --git a/doc/design.sgml b/doc/design.sgml
new file mode 100644
index 000000000..55fd7e551
--- /dev/null
+++ b/doc/design.sgml
@@ -0,0 +1,411 @@
+<!doctype debiandoc system>
+<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.1 1998/07/02 02:58:12 jgg 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 GNU/Linux system, in
+	  <tt>/usr/doc/copyright/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> Diety/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 emhasis 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 accesible 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 retrive 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 succesful. 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 forst 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 genrator</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>
diff --git a/doc/dpkg-tech.sgml b/doc/dpkg-tech.sgml
new file mode 100644
index 000000000..3c01ee8f0
--- /dev/null
+++ b/doc/dpkg-tech.sgml
@@ -0,0 +1,509 @@
+<!doctype debiandoc system>
+<book>
+<title>dpkg technical manual</title>
+
+<author>Tom Lees <email>tom@lpsg.demon.co.uk</email></author>
+<version>$Id: dpkg-tech.sgml,v 1.1 1998/07/02 02:58:12 jgg 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 GNU/Linux systems, see the file
+/usr/doc/copyright/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
+	</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, CDROMs, 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 folowing 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 ther "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 effeciently 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>
diff --git a/doc/files.sgml b/doc/files.sgml
new file mode 100644
index 000000000..d98d6f68a
--- /dev/null
+++ b/doc/files.sgml
@@ -0,0 +1,491 @@
+<!doctype debiandoc system>
+<!-- -*- mode: sgml; mode: fold -*- -->
+<book>
+<title>APT Files</title>
+
+<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
+<version>$Id: files.sgml,v 1.1 1998/07/02 02:58:12 jgg 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.
+<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 GNU/Linux systems, see the file
+/usr/doc/copyright/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/state/apt/
+		  lists/
+		       partial/
+		  xstatus
+  /var/cache/apt/
+                  pkgcache.bin
+		  srcpkgcache.bin
+		  archives/
+		          partial/
+  /etc/apt/
+           sources.list
+	   cdromdevs.list
+  /usr/lib/apt/
+                methods/
+		       cdrom
+		       ftp
+		       http
+</example>
+
+<p>
+As is specified in the FHS 2.0 /var/state/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.
+</sect>
+                                                                  <!-- }}} -->
+
+<chapt>Files
+<!-- Distribution Source List					       {{{ -->
+<!-- ===================================================================== -->
+<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 ui 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 value is <em>deb</em>
+which indicates a standard debian archive with a dists dir.
+
+<sect1>The deb Type
+   <p>
+   The <em>deb</em> type is to be a typical two level debian distributions,
+   dist/<var>distribution</var>/<var>component</var>. Typically distribution
+   is one of stable, unstable or frozen while component is one of main, 
+   contrib, non-free or non-us. The format for the deb line is as follows:
+
+   <p>
+   deb <var>uri</var> <var>distribution</var> <var>compontent</var> 
+   [<var>component</var> ...]
+
+   <p>
+   <var>uri</var> for the <em>deb</em> type must specify the base of the 
+   debian distribution. APT will automatically generate the proper longer 
+   URIs to get the information it needs. <var>distribution</var> can specify 
+   an exact path, in this case the components must be omitted and
+   <var>distribution</var> must end in a slash.
+   
+   <p>
+   Since only one distribution can be specified per deb line it may be
+   necessary to list a number of deb lines for the same URI. APT will
+   sort the URI list after it has generated a complete set to allow 
+   connection reuse. It is important to order things in the sourcelist
+   from most prefered to least prefered (fastest to slowest).
+</sect1>
+
+<sect1>URI specification
+<p> 
+URIs in the source list support a large number of access schemes.
+
+<taglist>
+<tag>cdrom<item>
+   The cdrom scheme is special in that If Modifed Since queries are never
+   performed and that APT knows how to match a cdrom to the name it
+   was given when first inserted. It does this by examining the date
+   and size of the package file. APT also knows all of the possible 
+   prefix paths for the cdrom drives and that the user should be prompted
+   to insert a CD if it cannot be found. The path is relative to an 
+   arbitary mount point (of APT's choosing) and must not start with a 
+   slash. The first pathname component is the given name and is purely
+   descriptive and of the users choice. However, if a file in the root of 
+   the cdrom is called 'cdname' its contents will be used instead of 
+   prompting. The name serves as a tag for the cdrom and should be unique.
+   APT will track the CDROM's based on their tag and package file
+   properties.
+   <example>
+   cdrom:Debian 1.3/debian
+   </example>
+
+<tag>http<item>
+   This scheme specifies a HTTP server for the debian archive. HTTP is prefered
+   over FTP because If Modified Since queries against the Package file are
+   possible. Newer HTTP protcols may even support reget which would make
+   http the protocol of choice.
+   <example>
+   http://www.debian.org/archive
+   </example>
+
+<tag>ftp<item>
+   This scheme specifies a FTP connection to the server. FTP is limited because
+   there is no support for IMS and is hard to proxy over firewalls.
+   <example>
+   ftp://ftp.debian.org/debian
+   </example>
+
+<tag>file<item>
+   The file scheme allows an arbitary directory in the file system to be 
+   considered as a debian archive. This is usefull for NFS mounts and 
+   local mirrors/archives.
+   <example>
+   file:/var/debian
+   </example>
+   
+<tag>mirror<item>
+   The mirror scheme is special in that it does not specify the location of a
+   debian archive but specifies the location of a list of mirrors to use
+   to access the archive. Some technique will be used to determine the
+   best choice for a mirror. The mirror file is specified in the Mirror File
+   section. If/when URIs take off they should obsolete this field.
+   <example>
+   mirror:http://www.debian.org/archivemirrors
+   </example>
+   
+<tag>smb<item>
+   A possible future expansion may be to have direct support for smb (Samba 
+   servers).
+   <example>
+   smb://ftp.kernel.org/pub/mirrors/debian
+   </example>
+</taglist>
+</sect1>
+
+<sect1>Hashing the URI
+<p>
+All permanent information aquired 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/state/apt/lists/www.debian.org=archive=dists=stable=binary-i386=Packages
+
+cdrom:Debian 1.3/debian/Packages
+/var/state/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. The equals sign was choosen on the 
+suggestion of Manoj because it is very infrequently used in filenames.
+Also note that the same rules described in the <em>Archive Directory</>
+section regarding the partial sub dir apply here as well.
+</sect1>
+
+</sect>
+                                                                  <!-- }}} -->
+<!-- Extra Status						       {{{ -->
+<!-- ===================================================================== -->
+<sect>Extra Status File (xstatus)
+
+<p>
+The extra status file serves the same purpose as the normal dpkg status file 
+(/var/lib/dpkg/status) except that it stores information unique to diety.
+This includes the autoflag, target distribution and version and any other
+uniqe features 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 field is
+placed directly before the new fields to indicate which package they
+apply to. The new fields are as follows:
+
+<taglist>
+<tag>X-Auto<item>
+   The Auto flag can be Yes or No and controls whether the package is in
+   auto mode. 
+
+<tag>X-TargetDist<item>
+   The TargetDist item indicates which distribution versions are offered for
+   installation from. It should be stable, unstable or frozen.
+   
+<tag>X-TargetVersion<item>
+   The target version item is set if the user selects a specific version, it
+   overrides the TargetDist selection if both are present.
+</taglist>
+</sect>
+                                                                  <!-- }}} -->
+<!-- Binary Package Cache					       {{{ -->
+<!-- ===================================================================== -->
+<sect>Binary Package Cache (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 verifitied it is moved
+from partial into archives/. Any files found in archives/ can be assumed 
+to be verified.
+
+<p>
+No dirctory structure is transfered 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.
+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>
+Like dselect, APT will support plugable acquisition methods to complement
+its internaly supported methods. The files in
+this directory are execultables named after the URI type. APT will
+sort the required URIs and spawn these programs giving a full sorted, quoted 
+list of URIs.
+
+<p>
+The interface is simple, the program will be given a list
+of URIs on the command line. The URIs will be in pairs, the first 
+being the actual URI and the second being the filename to write the data to. 
+The current directory will be set properly by APT and it is 
+expected the method will put files relative to the current directory. 
+The output of these programs is strictly speficied. The programs must accept
+nothing from stdin (stdin will be an invalid fd) and they must output 
+status information to stdout according to the format below.
+Stderr will be redirected to the logging facility.
+
+<p>
+Each line sent to stdout must be a line that has a single letter and a
+space. Strings after the first letter do not need quoting, they are taken
+as is till the end of the line. The tag letters, listed in expected order, 
+is as follows:
+
+<taglist>
+
+<tag>F - Change URI<item>
+This specifies a change in URI. All information after this will be applied
+to the new URI. When the URI is changed it is assumed that the old URI has
+completed unless an error is set. The format is <var>F URI</>
+
+<tag>S - Object Size<item>
+This specifies the expected size of the object. APT will use this to 
+compute percent done figures. If it is not sent then a kilobyte meter
+will be used instead of a percent display. The foramat is <var>S INTEGER</>
+
+<tag>E - Error Information<item>
+Exactly one line of error information can be set for each URI. The
+information will be summarized for the user. If an E tag is send before
+any F tags then the error is assumed to be a fatal method error and all URI
+fetches for that method are aborted with that error string. The format 
+is <var>E String</>
+
+<tag>I - Informative progress information<item>
+The I tag allows the method to specify the status of the connection. 
+Typically the GUI will show the last recieved I line. The format is
+<var>I String</> As a general rule an I tag should be ommitted before a
+lengthy operation only. Things that always take a short period are not
+suited for I tags. I tags should change wnenever the methods state changes.
+Some standard forms, in order of occurance, are <var>Connecting to SITE</>,
+<var>Connecting to SITE (1.1.1.1)</>, <var>Waiting for file</>, 
+<var>Authenticating</>, <var>Downloading</>, <var>Resuming (size)</>, 
+<var>Computing MD5</> <var>I</> lines should never print out information that 
+APT is already aware of, such as file names.
+
+<tag>R - Set final path<item>
+The R tag allows the method to tell APT that the file is present in the
+local file system. APT might copy it into a the download directory. The format
+is <var>R String</>
+
+<tag>M - MD5Sum of the file<item>
+The method is expected to compute the md5 hash on the fly as the download
+progresses. The final md5 of the file is to be output when the file is 
+completed. If the md5 is not output it will not be checked! Some methods
+such as the file method will not check md5's because they are most
+commonly used on mirrors or local CD-ROM's, a paranoid option may be
+provided in future to force checking. The format is <var>M MD5-String</>
+
+<tag>L - Log output<item>
+This tag indicates a string that should be dumped to some log file. The
+string is for debugging and is not ment to be seen by the user. The format
+is <var>L String</> Log things should only be used in a completed method
+if they have special relavence to what is happening.
+</taglist>
+
+<p>
+APT monitors the progress of the transfer by watching the file size. This
+means the method must not create any temp files and must use a fairly small
+buffer. The method is also responsible for If-Modified-Since (IMS) queries
+for the object. It should check ../outputname to get the time stamp but not
+size. The size may be different because the file was uncompressed after
+it was transfed. A method must <em>never</> change the file in .., it may
+only change the output file in the current directory.
+
+<p>
+The APT 'http' program is the reference implementation of this specification, 
+it implements all of the features a method is expected to do.
+</sect>
+                                                                  <!-- }}} -->
+<!-- The Mirror List						       {{{ -->
+<!-- ===================================================================== -->
+<sect> The Mirror List
+
+<p>
+The mirror list is stored on the primary debian web server (www.debian.org)
+and contains a machine readable list of all known debian mirrors. The mirror
+URI type will cause this list to be downloaded and considered. It has the
+same form as the source list. When the source list specifies mirror
+as the target the mirror list is scanned to find the nescessary parts for 
+the requested distributions and components. This means the user could 
+have a line like:
+
+<var>deb mirror:http://www.debian.org/mirrorlist stable main non-us</var>
+
+which would likely cause APT to choose two separate sites to download from,
+one for main and another for non-us.
+
+<p>
+Some form of network measurement will have to be used to gauge performance
+of each of the mirrors. This will be discussed later, initial versions
+will use the first found URI.
+</sect>
+                                                                  <!-- }}} -->
+<!-- The Release File						       {{{ -->
+<!-- ===================================================================== -->
+<sect> The Release File
+
+<p>
+This file plays and 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>
+Referes to the sub-component of the archive, <em>main</>, <em>contrib</>
+etc.
+
+<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
+Compontent: 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
+Compontent: main
+Version: 2.1
+Origin: Debian
+Label: Debian
+Architecture: i386
+</example>
+
+</sect>
+                                                                  <!-- }}} -->
+
+</book>
diff --git a/doc/ftp.conf.5 b/doc/ftp.conf.5
new file mode 100644
index 000000000..30c7c031b
--- /dev/null
+++ b/doc/ftp.conf.5
@@ -0,0 +1,93 @@
+.\" This manpage is copyright (C) 1998 Branden Robinson <branden@debian.org>

+.\" and Manoj Srivastava <srivasta@datasync.com>.

+.\" 

+.\" This 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.

+.\"

+.\" This is distributed in the hope that it will be useful, but

+.\" WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with APT; if not, write to the Free Software

+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 

+.\" 02111-1307 USA

+.TH ftp.conf 5 "16 June 1998" "Debian GNU/Linux"

+.SH NAME

+ftp.conf \- configuration file for APT FTP method

+.SH DESCRIPTION

+The ftp.conf file determines the behavior of the FTP method for the APT

+packaging tool.  The syntax of the file is

+.IR variable = value .

+Quotes are not required around

+.IR value s.

+Comments start with a '#' and end at the next newline. Blank lines are  

+ignored. The following

+.I variables

+are understood:                        

+.IP Firewall

+is the hostname of a machine which acts as an FTP firewall. This can be 

+overridden by an environment variable                                   

+.IR FTP_FIREWALL .

+If specified, and the given hostname cannot be directly contacted, a connection

+is made to the firewall machine and the string

+.B @hostname

+is appended to the login identifier. This type of setup is also known as an

+FTP proxy.

+.IP ProxyLogName

+is a parameter used by some firewall FTP proxies. It is used to authorize

+the user specified by

+.I ProxyLogName

+to send data beyond the

+.I Firewall

+machine.

+.IP ProxyPassword

+is the password used to authenticate

+.I ProxyLogName

+on the

+.I Firewall

+machine.

+.IP TimeOut

+sets a timeout value in seconds (the default is sixty seconds).

+.IP Passive

+is either

+.B true

+or

+.BR false .

+If true, then all data transfers will be done using passive mode. This is

+required for some dumb FTP servers and firewall configurations. It can

+also be overridden by the environment variable

+.IR FTP_PASSIVE .

+.IP Verbose

+is either

+.B true

+or

+.B false,

+and makes the FTP method output more data than it normally does.

+.IP Debug

+is either

+.B true

+or

+.B false,

+and makes the FTP method output debugging information. This variable is 

+not currently implemented.                                              

+.IP MaxReTry

+sets the number of times a connection is re-tried before giving up (the

+default is twice).

+.SH SEE ALSO

+.BR apt (8),

+.BR apt-get (8)

+.SH BUGS

+See <http://www.debian.org/Bugs/db/pa/lapt.html>.  If you wish to report a

+bug in

+.BR apt-get ,

+please see

+.I /usr/doc/debian/bug-reporting.txt

+or the

+.BR bug (1)

+command.

+.SH AUTHOR

+APT was written by the APT team <apt@packages.debian.org>.

diff --git a/doc/guide.sgml b/doc/guide.sgml
new file mode 100644
index 000000000..bbc01b78b
--- /dev/null
+++ b/doc/guide.sgml
@@ -0,0 +1,548 @@
+<!doctype debiandoc system>
+<!-- -*- mode: sgml; mode: fold -*- -->
+<book>
+<title>APT User's Guide</title>
+
+<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
+<version>$Id: guide.sgml,v 1.1 1998/07/02 02:58:12 jgg 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 GNU/Linux systems, see the file
+/usr/doc/copyright/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 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
+a choices in for such things as 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, mail-crypt is an emacs extension that aids in encrypting email
+with PGP. Without PGP installed mail-crypt is useless, so mail-crypt has a 
+simple dependency on PGP. 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 packages 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/ frozen/contrib Packages
+Updating package file cache...done
+Updating package status cache...done
+Checking system integrity...ok
+</example>
+
+<p>
+Once updated there are several useful 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 single 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 it's arguments are changed
+
+<tag>dist-upgrade<item>
+Dist-upgrade is a complete upgrader designed to make simple 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 it's
+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 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 CDROMs. 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 CDROM 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 CDROM 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 frozen 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. 
+<footnote>As of this writing the non-US distribution has 
+not been created, the only way to access it is by specifying 
+stable/binary-i386/ at this prompt and by specifying a URL ending in 
+debian-non-US </footnote>
+
+<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 copyright, 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 super-set 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. 
+
+</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>The Pre-Checks
+
+<p>
+Before all operations, except update, APT performs a number of checks on the
+systems. These are designed to safe guard the operations it is about to 
+undertake. At any time the full set of checks may be run by performing
+<tt>apt-get check</>. 
+<p>
+<example>
+# apt-get check
+Updating package file cache...done
+Updating package status cache...done
+Checking system integrity...ok
+</example>
+
+<p>
+The first check is to ensure that the archive package lists are matched to 
+the pre-generated data cache, if they are not then the cache is automatically
+refreshed. This may fail if <tt>apt-get update</> has not been run to 
+synchronize with the <em>Sources</>. The next check verifies that the state of 
+the system matches the cached state and automatically rebuilds the cached
+state if they are not synchronized. This check should never fail and it 
+indicates a serious error if it ever does.
+
+<p>
+The final check performs a detailed analysis of the system integrity. 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
+Updating package file cache...done
+Updating package status cache...done
+Checking system integrity...dependency error
+You might want to run apt-get -f install' to correct these.
+Sorry, but the following packages are broken - this means they have unmet
+dependencies:
+  libdbd-mysql-perl: Depends:perl
+  xzx: Depends:xlib6
+  libdbd-msql-perl: Depends:perl
+  mailpgp: Depends:pgp-i Depends:pgp-us
+  xdpkg: Depends:python
+  squake: Depends:quake-lib Depends:quake-lib-stub
+  debmake: Depends:fileutils
+  libreadlineg2: Conflicts:libreadline2
+  ssh: Depends:gmp2 Depends:xlib6g Depends:zlib1g 
+</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. For brevity the version inter-relationships are omitted.
+
+<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 assurances on the order that packages are installed. In both cases
+supplying the <tt>-f</> option to <prgn>atp-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 removed, 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.
+
+</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 http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
+Get http://llug.sep.bnl.gov/debian/ frozen/contrib Packages
+Get http://llug.sep.bnl.gov/debian/ frozen/main Packages
+Get http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
+Get http://llug.sep.bnl.gov/debian/ frozen/non-free Packages
+11% [Packages `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 dowload thread
+and indicates the operation being performed and some usefull 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 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 beings 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 instantenous 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 as 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>
diff --git a/doc/sources.list.5 b/doc/sources.list.5
new file mode 100644
index 000000000..779f216bf
--- /dev/null
+++ b/doc/sources.list.5
@@ -0,0 +1,177 @@
+.\" $Id: sources.list.5,v 1.1 1998/07/02 02:58:12 jgg Exp $

+.\" This manpage is copyright (C) 1998 Branden Robinson <branden@debian.org>.

+.\" 

+.\" This 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.

+.\"

+.\" This is distributed in the hope that it will be useful, but

+.\" WITHOUT ANY WARRANTY; without even the implied warranty of

+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+.\" GNU General Public License for more details.

+.\"

+.\" You should have received a copy of the GNU General Public

+.\" License along with APT; if not, write to the Free Software

+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 

+.\" 02111-1307 USA

+.TH sources.list 5 "16 June 1998" "Debian GNU/Linux"

+.SH NAME

+sources.list \- package resource list for APT

+.SH DESCRIPTION

+The package resource list is used to locate archives of the package

+distribution system in use on the system. At this time, this manual page

+documents only the packaging system used by the Debian GNU/Linux system.

+.PP

+The source list is designed to support any number of active sources and a

+variety of source media. The file lists one source per line, with the

+most preferred source listed first. The format of each line is:

+.I type uri args

+The first item,

+.IR type ,

+determines the format for

+.IR args .

+.I uri

+is a Universal Resource Identifier (URI), which is a superset of the more

+specific and well-known Universal Resource Locator, or URL.

+.SS The deb type

+The

+.B deb

+type describes a typical two-level Debian archive,

+.IR distribution / component .

+Typically,

+.I distribution

+is one of

+.BR stable ,

+.BR unstable ,

+or

+.BR frozen ,

+while component is one of

+.BR main ,

+.BR contrib ,

+.BR non-free ,

+or

+.BR non-us .

+The format for a

+.I sources.list

+entry using the

+.B deb

+type is:

+.RS

+deb

+.I uri distribution

+.RI [ component

+.I ...

+]

+.RE

+The URI for the

+.B deb

+type must specify the base of the Debian distribution, from which

+.B APT

+will find the information it needs.

+.I distribution

+can specify an exact path, in which case the

+.IR component s

+must be omitted and

+.I distribution

+must end with a slash (/). This is useful for when only a particular

+sub-section of the archive denoted by the URI is of interest.

+If

+.I distribution

+does not specify an exact path, at least one

+.I component

+must be present.

+.PP

+.I distribution

+may also contain a variable, 

+.BR $(ARCH) ,

+which expands to the Debian architecture (i386, m68k, powerpc, ...)     

+used on the system. This permits archiecture-independent                

+.I sources.list

+files to be used.

+.PP

+Since only one distribution can be specified per line it may be necessary

+to have multiple lines for the same URI, if a subset of all available

+distributions or components at that location is desired.

+.B APT

+will sort the URI list after it has generated a complete set internally,

+and will collapse multiple references to the same Internet host, for

+instance, into a single connection, so that it does not inefficiently

+establish an FTP connection, close it, do something else, and then

+re-establish a connection to that same host. This feature is useful

+for accessing busy FTP sites with limits on the number of simultaneous

+anonymous users.

+.PP

+It is important to list sources in order of preference, with the most

+preferred source listed first. Typically this will result in sorting

+by speed from fastest to slowest (CD-ROM followed by hosts on a local

+network, followed by distant Internet hosts, for example).

+.SS URI specification

+The three currently recognized URI types are file, http, and ftp.

+.IP file

+The file scheme allows an arbitrary directory in the file system to be

+considered an archive. This is useful for NFS mounts and local mirrors or

+archives.

+.IP http

+The http scheme specifies an HTTP server for the archive. If an environment

+variable

+.B $http_proxy

+is set with the format

+.\" Ugly hackery ahead, nroff doesn't like three different typefaces in a

+.\" row with no spaces between anything.

+.BI http:// server : port /\c

+, the proxy server specified in

+.B $http_proxy

+will be used. Users of

+authenticated HTTP/1.1 proxies may use a string of the format

+.BI http:// user : pass @ server : port /\c

+.\" For some reason, starting the next line with \. didn't work. So we kludge.

+\&. Note that this is an insecure method of authentication.

+.IP ftp

+The ftp scheme specifies an FTP server for the archive. APT's FTP behavior

+is highly configurable; for more information see the

+.BR ftp.conf (5)

+manual page.

+.SH EXAMPLES

+.IP "deb file:/home/jason/debian stable main contrib non-free"

+Uses the archive stored locally (or NFS mounted) at

+.I /home/jason/debian

+for stable/main, stable/contrib, and stable/non-free.

+.IP "deb file:/home/jason/debian unstable main contrib non-free"

+As above, except this uses the unstable (development) distribution.

+.IP "deb http://www.debian.org/archive stable main"

+Uses HTTP to access the archive at www.debian.org, and uses only the

+stable/main area.

+.IP "deb ftp://ftp.debian.org/debian stable contrib"

+Uses FTP to access the archive at ftp.debian.org, under the debian

+directory, and uses only the stable/contrib area.

+.IP "deb ftp://ftp.debian.org/debian unstable contrib"

+Uses FTP to access the archive at ftp.debian.org, under the debian

+directory, and uses only the unstable/contrib area. If this line appears as

+well as the one in the previous example in

+.IR sources.list ,

+a single FTP session will be used for both resource lines.

+.IP "deb ftp://nonus.debian.org/debian-non-US unstable/binary-i386/"

+Uses FTP to access the archive at nonus.debian.org, under the debian-non-US

+directory, and uses only files found under unstable/binary-i386.

+.IP "deb http://ftp.de.debian.org/debian-non-US unstable/binary-$(ARCH)/"

+Uses HTTP to access the archive at nonus.debian.org, under the

+debian-non-US directory, and uses only files found under

+unstable/binary-i386 on i386 machines, unstable/binary-m68k on m68k, and so

+forth for other supported architectures.

+.SH SEE ALSO

+.BR apt (8),

+.BR apt-cache (8),

+.BR apt-get (8),

+.BR ftp.conf (5)

+.SH BUGS

+See <http://www.debian.org/Bugs/db/pa/lapt.html>.  If you wish to report a

+bug in

+.BR apt-get ,

+please see

+.I /usr/doc/debian/bug-reporting.txt

+or the

+.BR bug (1)

+command.

+.SH AUTHOR

+APT was written by the APT team <apt@packages.debian.org>.