Join with aliencode

Author: jgg Date: 2001-02-20 07:03:16 GMT Join with aliencode
author: Arch Librarian <arch@canonical.com> 2004-09-20 16:56:32 +0000
committer: Arch Librarian <arch@canonical.com> 2004-09-20 16:56:32 +0000
commit: b2e465d6d32d2dc884f58b94acb7e35f671a87fe (patch)
tree: 5928383b9bde7b0ba9812e6526ad746466e558f7 /doc
parent: 00b47c98ca4a4349686a082eba6d77decbb03a4d (diff)
29 files changed, 3561 insertions, 1273 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore
new file mode 100644
index 000000000..22128776f
--- /dev/null
+++ b/doc/.cvsignore
@@ -0,0 +1,12 @@
+apt-cache.8
+apt-get.8
+apt-cdrom.8
+apt.conf.5
+sources.list.5
+apt-config.8
+apt-sortpkgs.1
+apt-ftparchive.1
+manpage.links
+manpage.refs
+manpage.log
+apt_preferences.5
diff --git a/doc/Bugs b/doc/Bugs
index 332abc592..deb7334db 100644
--- a/doc/Bugs
+++ b/doc/Bugs
@@ -26,7 +26,7 @@
  Summary: APT does not provide a way to download packages onto a 
           removable media for another computer
  Status: 0.3.0 has substantially better support for this to the point
-         that it is doable by using a seperate configuration file and
+         that it is doable by using a separate configuration file and
 	 the -c option
 #27601: srange errors from dselect
  Summary: Couldn't locate an archive source
diff --git a/doc/apt-cache.8.sgml b/doc/apt-cache.8.sgml
new file mode 100644
index 000000000..79bfa962f
--- /dev/null
+++ b/doc/apt-cache.8.sgml
@@ -0,0 +1,365 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-cache</>
+   <manvolnum>8</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-cache</>
+    <refpurpose>APT package handling utility -- cache manipulator</>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-config</>
+      <arg><option>-hvs</></arg>
+      <arg><option>-o=<replaceable/config string/</></arg>
+      <arg><option>-c=<replaceable/file/</></arg>
+      <group choice=req>
+         <arg>add <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg></arg>
+         <arg>gencaches</>
+         <arg>showpkg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>stats</>
+         <arg>dump</>
+         <arg>dumpavail</>
+         <arg>unmet</>
+         <arg>search <arg choice="plain"><replaceable>regex</replaceable></arg></arg>
+         <arg>show <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>showpkg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>depends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>pkgnames <arg choice="plain"><replaceable>prefix</replaceable></arg></arg>
+         <arg>dotty <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <RefSect1><Title>Description</>
+   <para>
+   <command/apt-cache/ performs a variety of operations on APT's package 
+   cache. <command/apt-cache/ does not manipulate the state of the system 
+   but does provide operations to search and generate interesting output 
+   from the package metadata.
+
+   <para>
+   Unless the <option/-h/, or <option/--help/ option is given one of the 
+   above commands must be present.
+
+   <VariableList>
+     <VarListEntry><Term>add</Term>
+     <ListItem><Para>
+     <literal/add/ adds the names package index files to the package cache.
+     </VarListEntry>
+     
+     <VarListEntry><Term>gencaches</Term>
+     <ListItem><Para>
+     <literal/gencaches/ performs the same opration as 
+     <command/apt-get check/. It builds the source and package caches from 
+     the sources in &sources-list; and from <filename>/var/lib/dpkg/status</>.
+     </VarListEntry>
+
+     <VarListEntry><Term>showpkg</Term>
+     <ListItem><Para>
+     <literal/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, <command>apt-cache showpkg libreadline2</> would produce 
+     output similar to the following:
+     
+<informalexample><programlisting>
+Package: libreadline2
+Versions: 2.1-12(/var/state/apt/lists/foo_Packages),
+Reverse Depends: 
+  libreadlineg2,libreadline2
+  libreadline2-altdev,libreadline2
+Dependencies:
+2.1-12 - libc5 (2 5.4.0-0) ncurses3.0 (0 (null))
+Provides:
+2.1-12 - 
+Reverse Provides: 
+</programlisting></informalexample>
+			    
+     <para>
+     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. For the specific meaning of the remainder of the output it
+     is best to consult the apt source code.
+     </VarListEntry>
+
+     <VarListEntry><Term>stats</Term>
+     <ListItem><Para>
+     <literal/stats/ displays some statistics about the cache.
+     No further arguments are expected. Statistics reported are:
+     <itemizedlist>
+       <listitem><para>
+       <literal/Total package names/ is the number of package names found 
+       in the cache.
+       </listitem>
+       
+       <listitem><para>
+       <literal/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.
+       </listitem>
+
+       <listitem><para>
+       <literal/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".
+       </listitem>
+   
+       <listitem><para>
+       <literal/Single virtual packages/ is the number of packages with only 
+       one package providing a particular virtual package. For example, in the
+       Debian GNU/Linux system, "X11-text-viewer" is a virtual package, but 
+       only one package, xless, provides "X11-text-viewer".
+       </listitem>
+
+       <listitem><para>
+       <literal/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, 
+       debconf is both an actual package, and provided by the debconf-tiny
+       package.
+       </listitem>
+   
+       <listitem><para>
+       <literal/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. Usually they
+       are referenced from Conflicts statements.
+       </listitem>
+
+       <listitem><para>
+       <literal/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.
+       </listitem>
+
+       <listitem><para>
+       <literal/Total dependencies/ is the number of dependency relationships 
+       claimed by all of the packages in the cache.
+       </listitem>
+     </itemizedlist>
+     </VarListEntry>
+     
+     <VarListEntry><Term>dump</Term>
+     <ListItem><Para>
+     <literal/dump/ shows a short listing of every package in the cache. It is 
+     primarily for debugging.
+     </VarListEntry>
+
+     <VarListEntry><Term>dumpavail</Term>
+     <ListItem><Para>
+     <literal/dumpavail/ prints out an available list to stdout. This is 
+     suitable for use with &dpkg; and is used by the &dselect; method.
+     </VarListEntry>
+
+     <VarListEntry><Term>unmet</Term>
+     <ListItem><Para>
+     <literal/unmet/ displays a summary of all unmet dependencies in the 
+     package cache.
+     </VarListEntry>
+
+     <VarListEntry><Term>show</Term>
+     <ListItem><Para>
+     <literal/show/ performs a function similar to 
+     <command>dpkg --print-avail</>, it displays the package records for the 
+     named packages.
+     </VarListEntry>
+
+     <VarListEntry><Term>search</Term>
+     <ListItem><Para>
+     <literal/search/ performs a full text search on all available package 
+     files for the regex pattern given. It searchs the package names and the 
+     descriptions for an occurance of the string and prints out the package 
+     name and the short description. If <option/--full/ is given then output 
+     identical to <literal/show/ is produced for each matched package and 
+     if <option/--names-only/ is given then the long description is not 
+     searched, only the package name is.
+     <para>
+     Seperate arguments can be used to specified multiple search patterns that 
+     are or'd together.
+     </VarListEntry>
+
+     <VarListEntry><Term>depends</Term>
+     <ListItem><Para>
+     <literal/depends/ shows a listing of each dependency a package has 
+     and all the possible other packages that can fullfill that dependency.
+     </VarListEntry>
+
+     <VarListEntry><Term>pkgnames</Term>
+     <ListItem><Para>
+     This command prints the name of each package in the system. The optional
+     argument is a prefix match to filter the name list. The output is suitable
+     for use in a shell tab complete function and the output is generated 
+     extremly quickly. This command is best used with the 
+     <option/--generate/ option.
+     </VarListEntry>
+     
+     <VarListEntry><Term>dotty</Term>
+     <ListItem><Para>
+     <literal/dotty/ takes a list of packages on the command line and 
+     gernerates output suitable for use by dotty from the 
+     <ulink url="http://www.research.att.com/sw/tools/graphviz/">GraphVis</>
+     package. The result will be a set of nodes and edges representing the 
+     relationships between the packages. By default the given packages will 
+     trace out all dependent packages which can produce a very large graph. 
+     This can be turned off by setting the 
+     <literal>APT::Cache::GivenOnly</> option.
+
+     <para>
+     The resulting nodes will have several shapse, normal packages are boxes,
+     pure provides are triangles, mixed provides are diamonds, 
+     hexagons are missing packages. Orange boxes mean recursion was stopped 
+     [leaf packages], blue lines are prre-depends, green lines are conflicts.
+
+     <para>
+     Caution, dotty cannot graph larger sets of packages.
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+ 
+ <RefSect1><Title>Options</>
+   &apt-cmdblurb;
+   
+   <VariableList>
+     <VarListEntry><term><option/-p/</><term><option/--pkg-cache/</>
+     <ListItem><Para>
+     Select the file to store the package cache. The package cache is the 
+     primary cache used by all operations.
+     Configuration Item: <literal/Dir::Cache::pkgcache/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-s/</><term><option/--src-cache/</>
+     <ListItem><Para>
+     Select the file to store the source cache. The source is used only by
+     <literal/gencaches/ and it stores a parsed version of the package 
+     information from remote sources. When building the package cache the 
+     source cache is used to advoid reparsing all of the package files.
+     Configuration Item: <literal/Dir::Cache::srcpkgcache/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-q/</><term><option/--quiet/</>
+     <ListItem><Para>
+     Quiet; produces output suitable for logging, omitting progress indicators.
+     More qs will produce more quite up to a maximum of 2. You can also use
+     <option/-q=#/ to set the quiet level, overriding the configuration file.
+     Configuration Item: <literal/quiet/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-i/</><term><option/--important/</>
+     <ListItem><Para>
+     Print only important deps; for use with unmet causes only Depends and 
+     Pre-Depends relations to be printed.
+     Configuration Item: <literal/APT::Cache::Important/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-f/</><term><option/--full/</>
+     <ListItem><Para>
+     Print full package records when searching. 
+     Configuration Item: <literal/APT::Cache::ShowFull/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-a/</><term><option/--all-versions/</>
+     <ListItem><Para>
+     Print full records for all available versions, this is only applicable to 
+     the show command. 
+     Configuration Item: <literal/APT::Cache::AllVersions/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-g/</><term><option/--generate/</>
+     <ListItem><Para>
+     Perform automatic package cache regeneration, rather than use the cache 
+     as it is. This is the default, to turn it off use <option/--no-generate/.
+     Configuration Item: <literal/APT::Cache::Generate/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--names-only/</>
+     <ListItem><Para>
+     Only search on the package names, not the long description. 
+     Configuration Item: <literal/APT::Cache::NamesOnly/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--all-names/</>
+     <ListItem><Para>
+     Make <literal/pkgnames/ print all names, including virtual packages 
+     and missing dependencies. 
+     Configuration Item: <literal/APT::Cache::AllNames/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--recurse/</>
+     <ListItem><Para>
+     Make <literal/depends/ recursive so that all packages mentioned are 
+     printed once.
+     Configuration Item: <literal/APT::Cache::RecruseDepends/.
+     </VarListEntry>
+
+     &apt-commonoptions;
+     
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>Files</>
+   <variablelist>
+     <VarListEntry><term><filename>/etc/apt/sources.list</></term>
+     <ListItem><Para>
+     locations to fetch packages from.
+     Configuration Item: <literal/Dir::Etc::SourceList/.
+     </VarListEntry>
+     
+     <VarListEntry><term><filename>&statedir;/lists/</></term>
+     <ListItem><Para>
+     storage area for state information for each package resource specified in
+     &sources-list;
+     Configuration Item: <literal/Dir::State::Lists/.
+     </VarListEntry>
+  
+     <VarListEntry><term><filename>&statedir;/lists/partial/</></term>
+     <ListItem><Para>
+     storage area for state information in transit.
+     Configuration Item: <literal/Dir::State::Lists/ (implicit partial).
+     </VarListEntry>     
+   </variablelist>
+ </RefSect1>
+
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-conf;, &sources-list;, &apt-get;
+ </RefSect1>
+
+ <RefSect1><Title>Diagnostics</>
+   <para>
+   <command/apt-cache/ returns zero on normal operation, decimal 100 on error.
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/apt-cache.8.yo b/doc/apt-cache.8.yo
deleted file mode 100644
index 5ce5c48a9..000000000
--- a/doc/apt-cache.8.yo
+++ /dev/null
@@ -1,280 +0,0 @@
-mailto(apt@packages.debian.org)
-manpage(apt-cache)(8)(4 Dec 1998)(apt)()
-manpagename(apt-cache)(APT package handling utility -- cache manipulator)
-
-manpagesynopsis()
-apt-cache command [argument ...]
-
-manpagedescription()
-bf(apt-cache) performs a variety of operations on APT's package cache.
-bf(apt-cache) is seldom called directly; instead its operations are
-performed automatically by the other bf(apt) utilities.
-
-em(command) is one of:
-itemize(
-  it() add file1 [file2] [...]
-  it() gencaches
-  it() showpkg package1 [package2] [...]
-  it() stats
-  it() dump
-  it() dumpavail
-  it() unmet
-  it() check
-  it() search
-  it() show
-  it() showpkg
-  it() depends
-  it() pkgnames
-  it() dotty
-)
-
-Unless the -h, or --help option is given one of the above commands
-must be present.
-
-startdit()
-dit(bf(add))
-bf(add) adds the names package index files to the package cache.
-
-dit(bf(gencaches))
-bf(gencaches) performs the same opration as bf(apt-get check). It builds
-the source and package caches from thes sources in bf(/etc/apt/sources.list)
-and from bf(/var/lib/dpkg/status).
-
-dit(bf(showpkg))
-bf(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, bf(apt-cache showpkg libreadline2) would produce output similar
-to the following:
-
-verb(
-Package: libreadline2
-
-Versions:
-
-2.1-12(/var/state/apt/lists/debian.midco.net_debian_dists_slink_main_binary-i386_Packages),
-
-Reverse Depends: 
-
-  libreadlineg2,libreadline2
-
-  libreadline2-altdev,libreadline2
-Dependencies:
-
-2.1-12 - libc5 (2 5.4.0-0) ncurses3.0 (0 (null)) ldso (2 1.9.0-1)
-
-Provides: 
-
-2.1-12 - 
-
-Reverse Provides: 
-)			    
-
-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. For the specific meaning of the remainder of the output it
-is best to consult the apt source code.
-
-dit(bf(stats))
-bf(stats) displays some statistics about bf(cache).
-No further arguments are expected. Statistics reported are:
-itemize(
-   it() bf(Total package names) is the number of package names found in the cache.
-   
-   it() bf(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.
-
-   it() bf(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".
-   
-   it() bf(Single virtual packages) is the number of packages with only one 
-   package providing a particular virtual package. For example, in the 
-   Debian GNU/Linux system, "X11-text-viewer" is a virtual package, but only 
-   one package, xless, provides "X11-text-viewer".
-
-   it() bf(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.
-   
-   it() bf(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.
-
-   it() bf(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.
-
-   it() bf(Total dependencies) is the number of dependency relationships claimed 
-   by all of the packages in the cache.
-)
-
-dit(bf(dump))
-bf(dump) shows a short listing of every package in the cache. It is primarily
-for debugging.
-
-dit(bf(dumpavail))
-bf(dumpavail) prints out an available list to stdout. This is suitable for use
-with bf(dpkg) and is used by the bf(dselect) method.
-
-dit(bf(unmet))
-bf(unmet) displays a summary of all unmet dependencies in the package cache.
-
-dit(bf(check))
-bf(check) is a random function for testing certain aspects of the cache.
-Do not use it.
-
-dit(bf(showpkg))
-bf(showpkg) displays a listing of the given package cache structure and some
-related information about it. The list is meant primarily for debugging.
-
-dit(bf(show))
-bf(show) performs a function similar to dpkg --print-avail, it displays
-the package records for the named packages.
-
-dit(bf(search))
-bf(search) performs a full text search on all available package files for
-the pattern given. It searchs the package names and the descriptions for
-an occurance of the string and prints out the package name and the short
-description. If --full is given then output identical to bf(show) is produced
-for each matched package and if --names-only is given then the long
-description is not searched, only the package name is.
-
-dit(bf(depends))
-bf(depends) shows a listing of each dependency a package has and all
-the possible other packages that can fullfill that dependency.
-
-dit(bf(pkgnames))
-This command prints the name of each package in the system. The optional
-argument is a prefix match to filter the name list. The output is suitable
-for use in a shell tab complete function and the output is generated extremly
-quickly. This command is best used with the bf(--no-generate) option.
-
-dit(bf(dotty))
-bf(dotty) Takes a list of packages on the command line and gernerates output
-suitable for use by dotty from the GraphVis
-(http://www.research.att.com/sw/tools/graphviz/) package. The result will be
-a set of nodes and edges representing the relationships between the
-packages. By default the given packages will trace out all dependent packages
-which can produce a very large graph. This can be turned off by setting the 
-APT::Cache::GivenOnly option.
-
-The resulting nodes will have several shapse, normal packages are boxes,
-pure provides are triangles, mixed provides are diamonds, 
-hexagons are missing packages. Orange boxes mean recursion was stopped 
-[leaf packages], blue lines are prre-depends, green lines are conflicts.
-
-Caution, dotty cannot graph larger sets of packages.
-
-enddit()
-
-manpageoptions()
-All command line options may be set using the configuration file, the
-descriptions indicate the configuration option to set. For boolean
-options you can override the config file by using something like bf(-f-),
-bf(--no-f), bf(-f=no) or several other variations.
-
-startdit()
-dit(bf(-h, --help))
-Show a short usage summary.
-
-dit(bf(-v, --version))
-Show the program verison.
-
-dit(bf(-p --pkg-cache))
-Select the file to store the package cache. The package cache is the primary
-cache used by all operations.
-Configuration Item: bf(Dir::Cache::pkgcache).
-
-dit(bf(-s --src-cache))
-Select the file to store the source cache. The source is used only by
-bf(gencaches) and it stores a parsed version of the package information from
-remote sources. When building the package cache the source cache is used
-to advoid reparsing all of the package files.
-Configuration Item: bf(Dir::Cache::srcpkgcache).
-
-dit(bf(-q, --quiet))
-Quiet; produces output suitable for logging, omitting progress indicators.
-More qs will produce more quite up to a maximum of 2. You can also use
-bf(-q=#) to set the quiet level, overriding the configuration file.
-Configuration Item: bf(quiet).
-
-dit(bf(-i --important))
-Print only important deps; for use with unmet causes only em(Depends) and 
-em(Pre-Depends) relations to be printed.
-Configuration Item: bf(APT::Cache::Important).
-
-dit(bf(-f --full))
-Print full package records when searching. Configuration Item: bf(APT::Cache::ShowFull).
-
-dit(bf(-a --all-versions))
-Print full records for all available versions, this is only applicable to the
-show command. Configuration Item: bf(APT::Cache::AllVersions)
-
-dit(bf(-g --no-generate))
-Do not perform automatic package cache regeneration, use the cache as it is.
-Configuration Item: bf(APT::Cache::NoGenerate).
-
-dit(bf(--names-only))
-Only search on the package names, not the long description. 
-Configuration Item: bf(APT::Cache::NamesOnly).
-
-dit(bf(--all-names))
-Make bf(pkgnames) print all names, including virtual packages and missing
-dependencies. Configuration Item: bf(APT::Cache::AllNames).
-
-dit(bf(-c, --config-file))
-Configuration File; Specify a configuration file to use. bf(apt-get) will
-read the default configuration file and then this configuration file. See
-bf(apt.conf(5)) for syntax information.
-
-dit(bf(-o, --option))
-Set a Configuration Option; This will set an arbitary configuration option.
-The syntax is 
-verb(-o Foo::Bar=bar)
-enddit()
-
-manpagefiles()
-itemize(
-  it() /etc/apt/sources.list 
-  locations to fetch packages from
-  
-  it() /var/state/apt/lists/
-  storage area for state information for each package resource specified in
-  
-  it() /var/state/apt/lists/partial/
-  storage area for state information in transit
-)
-
-manpageseealso()
-apt-get(8),
-sources.list(5),
-apt.conf(5)
-
-manpagediagnostics()
-apt-cache returns zero on normal operation, decimal 100 on error.
-
-manpagebugs()
-See http://bugs.debian.org/apt.  If you wish to report a
-bug in bf(apt-cache), please see bf(/usr/doc/debian/bug-reporting.txt)
-or the bf(bug(1)) command.
-
-manpageauthor()
-apt-get was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/apt-cdrom.8.sgml b/doc/apt-cdrom.8.sgml
new file mode 100644
index 000000000..414be4c09
--- /dev/null
+++ b/doc/apt-cdrom.8.sgml
@@ -0,0 +1,146 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-cdrom</>
+   <manvolnum>8</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-cdrom</>
+    <refpurpose>APT CDROM managment utility</>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-cdrom</>
+      <arg><option>-hvrmfan</></arg>
+      <arg><option>-d=<replaceable/cdrom mount point/</></arg>
+      <arg><option>-o=<replaceable/config string/</></arg>
+      <arg><option>-c=<replaceable/file/</></arg>
+      <group choice=req>
+         <arg>add</>
+         <arg>ident</>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <RefSect1><Title>Description</>
+   <para>
+   <command/apt-cdrom/ is used to add a new CDROM to APTs list of available 
+   sources. <command/apt-cdrom/ takes care of determining the structure of 
+   the disc as well as correcting for several possible mis-burns and 
+   verifying the index files.   
+   <para>
+   It is necessary to use <command/apt-cdrom/ to add CDs to the APT system, 
+   it cannot be done by hand. Furthermore each disk in a multi-cd set must be 
+   inserted and scanned separately to account for possible mis-burns.   
+   <para>
+   Unless the <option/-h/, or <option/--help/ option is given one of the 
+   above commands must be present.
+   
+   <VariableList>
+     <VarListEntry><Term>add</Term>
+     <ListItem><Para>
+     <literal/add/ is used to add a new disc to the source list. It will unmount the
+     CDROM device, prompt for a disk to be inserted and then procceed to 
+     scan it and copy the index files. If the disc does not have a proper
+     <filename>.disk/</> directory you will be prompted for a descriptive 
+     title.
+
+     <para>
+     APT uses a CDROM ID to track which disc is currently in the drive and
+     maintains a database of these IDs in 
+     <filename>&statedir;/cdroms.list</>
+     </VarListEntry>
+     
+     <VarListEntry><Term>ident</Term>
+     <ListItem><Para>
+     A debugging tool to report the identity of the current disc as well
+     as the stored file name
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>Options</>
+   &apt-cmdblurb;
+   
+   <VariableList>
+     <VarListEntry><term><option/-d/</><term><option/--cdrom/</>
+     <ListItem><Para>
+     Mount point; specify the location to mount the cdrom. This mount 
+     point must be listed in <filename>/etc/fstab</> and propely configured.
+     Configuration Item: <literal/Acquire::cdrom::mount/.
+     </VarListEntry>
+     
+     <VarListEntry><term><option/-r/</><term><option/--rename/</>
+     <ListItem><Para>
+     Rename a disc; change the label of a disk or override the disks 
+     given label. This option will cause <command/apt-cdrom/ to prompt for 
+     a new label.
+     Configuration Item: <literal/APT::CDROM::Rename/.
+     </VarListEntry>
+     
+     <VarListEntry><term><option/-m/</><term><option/--no-mount/</>
+     <ListItem><Para>
+     No mounting; prevent <command/apt-cdrom/ from mounting and unmounting 
+     the mount point.
+     Configuration Item: <literal/APT::CDROM::NoMount/.
+     </VarListEntry>
+     
+     <VarListEntry><term><option/-f/</><term><option/--fast/</>
+     <ListItem><Para>
+     Fast Copy; Assume the package files are valid and do not check 
+     every package. This option should be used only if
+     <command/apt-cdrom/ has been run on this disc before and did not detect 
+     any errors.
+     Configuration Item: <literal/APT::CDROM::Fast/.
+     </VarListEntry>
+     
+     <VarListEntry><term><option/-a/</><term><option/--thorough/</>
+     <ListItem><Para>
+     Thorough Package Scan; This option may be needed with some old 
+     Debian 1.1/1.2 discs that have Package files in strange places. It 
+     takes much longer to scan the CD but will pick them all up.
+     </VarListEntry>
+     
+     <VarListEntry><term><option/-n/</>
+                   <term><option/--just-print/</>
+                   <term><option/--recon/</>
+                   <term><option/--no-act/</>
+     <ListItem><Para>
+     No Changes; Do not change the &sources-list; file and do not 
+     write index files. Everything is still checked however.
+     Configuration Item: <literal/APT::CDROM::NoAct/.
+     </VarListEntry> 
+ 
+     &apt-commonoptions;
+     
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-conf;, &apt-get;, &sources-list;
+ </RefSect1>
+
+ <RefSect1><Title>Diagnostics</>
+   <para>
+   <command/apt-cdrom/ returns zero on normal operation, decimal 100 on error.
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+
+</refentry>
+
diff --git a/doc/apt-cdrom.8.yo b/doc/apt-cdrom.8.yo
deleted file mode 100644
index 9d5b598a2..000000000
--- a/doc/apt-cdrom.8.yo
+++ /dev/null
@@ -1,120 +0,0 @@
-mailto(apt@packages.debian.org)
-manpage(apt-cdrom)(8)(4 Dec 1998)(apt)()
-manpagename(apt-cdrom)(APT CDROM managment utility)
-
-manpagesynopsis()
-apt-cdrom command
-
-manpagedescription()
-bf(apt-cdrom) is used to add a new CDROM to APTs list of available sources.
-bf(apt-cdrom) takes care of determining the structure of the disc as well
-as correcting for several possible mis-burns and verifying the index files.
-It is necessary to use bf(apt-cdrom) to add CDs to the APT system, it cannot
-be done by hand. Furthermore each disk in a multi-cd set must be inserted
-and scanned seperately to account for possible mis-burns.
-
-em(command) is one of:
-itemize(
-  it() add 
-)
-
-Unless the -h, or --help option is given one of the above commands
-must be present.
-
-startdit()
-dit(bf(add))
-bf(add) is used to add a new disc to the source list. It will unmount the
-CDROM device, prompt for a disk to be inserted and then procceed to scan it
-and copy the index files. If the disc does not have a proper bf(.disk/) 
-directory you will be prompted for a descriptive title.
-
-APT uses a CDROM ID to track which disc is currently in the drive and
-maintains a database of these IDs in bf(/var/state/apt/cdroms.list)
-
-enddit()
-
-manpageoptions()
-All command line options may be set using the configuration file, the
-descriptions indicate the configuration option to set. For boolean
-options you can override the config file by using something like bf(-f-),
-bf(--no-f), bf(-f=no) or several other variations.
-
-startdit()
-dit(bf(-h, --help))
-Show a short usage summary.
-
-dit(bf(-v, --version))
-Show the program verison.
-
-dit(bf(-d --cdrom))
-Mount point; specify the location to mount the cdrom. This mount point must
-be listed in bf(/etc/fstab) and propely configured. 
-Configuration Item: bf(Acquire::cdrom::mount).
-
-dit(bf(-r --rename))
-Rename a disc; change the label of a disk or override the disks given label.
-This option will cause bf(apt-cdrom) to prompt for a new label
-Configuration Item: bf(APT::CDROM::Rename).
-
-dit(bf(-m, --no-mount))
-No mounting; prevent bf(apt-cdrom) from mounting and unmounting the mount
-point.
-Configuration Item: bf(APT::CDROM::NoMount).
-
-dit(bf(-f, --fast))
-Fast Copy; Assume the package files are valid and do not check every package.
-This option should be used only if bf(apt-cdrom) has been run on this disc
-before and did not detect any errors.
-Configuration Item: bf(APT::CDROM::Fast).
-
-dit(bf(-a, --thorough))
-Thorough Package Scan; This option may be needed with some old Debian 1.1/1.2
-burns that have Package files in strange places. It takes much longer to
-scan the CD but will pick them all up.
-
-dit(bf(-n --just-print, --recon, --no-act))
-No Changes; Do not change the sources.list and do not write package files. 
-Everything is still checked however.
-Configuration Item: bf(APT::CDROM::NoAct).
-
-dit(bf(-c, --config-file))
-Configuration File; Specify a configuration file to use. bf(apt-get) will
-read the default configuration file and then this configuration file. See
-bf(apt.conf(5)) for syntax information.
-
-dit(bf(-o, --option))
-Set a Configuration Option; This will set an arbitary configuration option.
-The syntax is 
-verb(-o Foo::Bar=bar)
-enddit()
-
-manpagefiles()
-itemize(
-  it() /etc/apt/sources.list 
-  locations to fetch packages from
-  
-  it() /var/state/apt/lists/
-  storage area for state information for each package resource specified in
-  
-  it() /var/state/apt/lists/partial/
-  storage area for state information in transit
-  
-  it() /var/state/apt/cdroms.list
-  list of cdrom IDs and names.
-)
-
-manpageseealso()
-apt-get(8),
-sources.list(5),
-apt.conf(5)
-
-manpagediagnostics()
-apt-cdrom returns zero on normal operation, decimal 100 on error.
-
-manpagebugs()
-See http://bugs.debian.org/apt.  If you wish to report a
-bug in bf(apt-cache), please see bf(/usr/doc/debian/bug-reporting.txt)
-or the bf(bug(1)) command.
-
-manpageauthor()
-apt-get was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/apt-config.8.sgml b/doc/apt-config.8.sgml
new file mode 100644
index 000000000..0f5324e0a
--- /dev/null
+++ b/doc/apt-config.8.sgml
@@ -0,0 +1,105 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-config</>
+   <manvolnum>8</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-config</>
+    <refpurpose>APT Configuration Query program</>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-config</>
+      <arg><option>-hv</></arg>
+      <arg><option>-o=<replaceable/config string/</></arg>
+      <arg><option>-c=<replaceable/file/</></arg>
+      <group choice=req>
+         <arg>shell</>
+         <arg>dump</>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <RefSect1><Title>Description</>
+   <para>
+   <command/apt-config/ is an internal program used by various portions of
+   the APT suite to provide consistent configurability. It accesses the main 
+   configuarion file <filename>/etc/apt/apt.conf</> in a manner that is 
+   easy to use by scripted applications.
+   <para>
+   Unless the <option/-h/, or <option/--help/ option is given one of the above commands
+   must be present.   
+   </para>
+   
+   <VariableList>
+     <VarListEntry><Term>shell</Term>
+     <ListItem><Para>
+     shell is used to access the configuration information from a shell 
+     script. It is given pairs of arguments, the first being a shell 
+     variable and the second the configuration value to query. As output 
+     it lists a series of shell assignments commands for each present value. 
+     In a shell script it should be used like:
+     </para>
+     
+<informalexample><programlisting>
+OPTS="-f"
+RES=`apt-config shell OPTS MyApp::Options`
+eval $RES
+</programlisting></informalexample>
+
+     <para>
+     This will set the shell environment variable $OPTS to the value of
+     MyApp::Options with a default of <option/-f/.
+     
+     <para>
+     The configuration item may be postfixed with a /[fdbi]. f returns file
+     names, d returns directories, b returns true or false and i returns an 
+     integer. Each of the returns is normalized and verified internally.
+     </VarListEntry>
+
+     <VarListEntry><Term>dump</Term>
+     <ListItem><Para>
+     Just show the contents of the configuration space.
+     </VarListEntry>
+
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>Options</>
+   &apt-cmdblurb;
+   
+   <VariableList>
+   
+     &apt-commonoptions;
+     
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-conf;
+ </RefSect1>
+
+ <RefSect1><Title>Diagnostics</>
+   <para>
+   <command/apt-config/ returns zero on normal operation, decimal 100 on error.
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/apt-config.8.yo b/doc/apt-config.8.yo
deleted file mode 100644
index 809c790c2..000000000
--- a/doc/apt-config.8.yo
+++ /dev/null
@@ -1,86 +0,0 @@
-mailto(apt@packages.debian.org)
-manpage(apt-config)(8)(14 Feb 1999)(apt)()
-manpagename(apt-config)(APT Configuration Query program)
-
-manpagesynopsis()
-apt-config command
-
-manpagedescription()
-bf(apt-config) is an internal program used by various portions of the APT
-suite to provide consistent configurability. It accesses the main configuarion
-file /etc/apt/apt.conf in a manner that is easy to use by scripted
-applications.
-
-em(command) is one of:
-itemize(
-  it() shell
-  it() dump
-)
-
-Unless the -h, or --help option is given one of the above commands
-must be present.
-
-startdit()
-dit(bf(shell))
-bf(shell) is used to access the configuration information from a shell script.
-It is given pairs of arguments, the first being a shell variable and the
-second the configuration value to query. As output it lists a series of shell
-assignments commands for each present value. In a shell script it should be
-used like:
-
-verb(
-OPTS="-f"
-
-RES=`apt-config shell OPTS MyApp::Options`
-
-eval $RES
-)
-
-This will set the shell environment variable $OPTS to the value of
-MyApp::Options with a default of -f.
-
-If the configuration item to retrieve is prefixed with a / then it will
-be retrieved using filename mode which prepends base paths.
-
-dit(bf(dump))
-Just show the contents of the configuration space.
-
-enddit()
-
-manpageoptions()
-All command line options may be set using the configuration file, the
-descriptions indicate the configuration option to set. For boolean
-options you can override the config file by using something like bf(-f-),
-bf(--no-f), bf(-f=no) or several other variations.
-
-startdit()
-dit(bf(-h, --help))
-Show a short usage summary.
-
-dit(bf(-v, --version))
-Show the program verison.
-
-dit(bf(-c, --config-file))
-Configuration File; Specify a configuration file to use. bf(apt-get) will
-read the default configuration file and then this configuration file. See
-bf(apt.conf(5)) for syntax information.
-
-dit(bf(-o, --option))
-Set a Configuration Option; This will set an arbitary configuration option.
-The syntax is 
-verb(-o Foo::Bar=bar)
-enddit()
-
-manpageseealso()
-apt.conf(5)
-
-manpagediagnostics()
-apt-config returns zero on normal operation, decimal 100 on error.
-
-manpagebugs()
-See http://bugs.debian.org/apt.  If you wish to report a
-bug in bf(apt-config), please see bf(/usr/doc/debian/bug-reporting.txt)
-or the bf(bug(1)) command.
-
-manpageauthor()
-apt-get was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/apt-ftparchive.1.sgml b/doc/apt-ftparchive.1.sgml
new file mode 100644
index 000000000..f05765650
--- /dev/null
+++ b/doc/apt-ftparchive.1.sgml
@@ -0,0 +1,507 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-ftparchive</>
+   <manvolnum>1</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-ftparchive</>
+    <refpurpose>Utility to generate index files</>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-ftparchive</>
+      <arg><option>-hvdsq</></arg>
+      <arg><option>--md5</></arg>
+      <arg><option>--delink</></arg>
+      <arg><option>--readonly</></arg>
+      <arg><option>--contents</></arg>
+      <arg><option>-o=<replaceable/config string/</></arg>
+      <arg><option>-c=<replaceable/file/</></arg>      
+      <group choice=req>
+         <arg>packages<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg>
+         <arg>sources<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg>
+         <arg>contents <arg choice="plain"><replaceable>path</replaceable></arg></arg>
+         <arg>generate <arg choice="plain"><replaceable>config-file</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>section</replaceable></arg></arg>
+         <arg>clean <arg choice="plain"><replaceable>config-file</replaceable></arg></arg>
+      </group>
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <RefSect1><Title>Description</>
+   <para>   
+   <command/apt-ftparchive/ is the command line tool that generates the index 
+   files that APT uses to access a distribution source. The index files should 
+   be generated on the origin site based on the content of that site.
+
+   <para>
+   <command/apt-ftparchive/ is a superset of the &dpkg-scanpackages; program,
+   incorporating it's entire functionality via the <literal/directory/ command.
+   It also contains a contents file generator, <literal/contents/, and an 
+   elaborate means to 'script' the generation process for a complete 
+   archive.
+
+   <para>
+   Internally <command/apt-ftparchive/ can make use of binary databases to 
+   cache the contents of a .deb file and it does not rely on any external 
+   programs aside from &gzip;. When doing a full generate it automatically 
+   performs file-change checks and builds the desired compressed output files.
+   
+   <para>
+   Unless the <option/-h/, or <option/--help/ option is given one of the above 
+   commands must be present.
+   
+   <VariableList>
+     <VarListEntry><term>packages</term>
+     <ListItem><Para>
+     The packages command generates a package file from a directory tree. It
+     takes the given directory and recursively searches it for .deb files, 
+     emitting a package record to stdout for each. This command is 
+     approximately equivalent to &dpkg-scanpackages;.
+     <para>
+     The option <option/--db/ can be used to specify a binary caching DB.
+     </VarListEntry>
+     
+     <VarListEntry><term>sources</term>
+     <ListItem><Para>
+     The <literal/sources/ command generates a source index file from a directory tree. 
+     It takes the given directory and recursively searches it for .dsc files,
+     emitting a source record to stdout for each. This command is approximately
+     equivalent to &dpkg-scansources;.
+     <para>
+     If an override file is specified then a source override file will be 
+     looked for with an extension of .src. The --source-override option can be 
+     used to change the source override file that will be used.
+     </VarListEntry>
+
+     <VarListEntry><term>contents</term>
+     <ListItem><Para>
+     The <literal/contents/ command generates a contents file from a directory tree. It
+     takes the given directory and recursively searches it for .deb files, 
+     and reads the file list from each file. It then sorts and writes to stdout
+     the list of files matched to packages. Directories are not written to 
+     the output. If multiple packages own the same file then each package is
+     separated by a comma in the output.
+     <para>
+     The option <option/--db/ can be used to specify a binary caching DB.
+     </VarListEntry>
+
+     <VarListEntry><term>generate</term>
+     <ListItem><Para>
+     The <literal/generate/ command is designed to be runnable from a cron script and
+     builds indexes according to the given config file. The config language
+     provides a flexible means of specifying which index files are built from 
+     which directories, as well as providing a simple means of maintaining the
+     required settings.
+     </VarListEntry>
+
+     <VarListEntry><term>clean</term>
+     <ListItem><Para>
+     The <literal/clean/ command tidies the databases used by the given 
+     configuration file by removing any records that are no longer necessary.
+     </VarListEntry>     
+   </VariableList>  
+   
+ </RefSect1>
+
+ <RefSect1><Title>The Generate Configuration</>
+   <para>
+   The <literal/generate/ command uses a configuration file to describe the 
+   archives that are going to be generated. It follows the typical ISC 
+   configuration format as seen in ISC tools like bind 8 and dhcpd. 
+   &apt-conf; contains a decsription of the syntax. Note that the generate 
+   configuration is parsed in sectional manner, but &apt-conf; is parsed in a
+   tree manner. This only effects how the scope tag is handled.
+
+   <para>
+   The generate configuration has 4 separate sections, each decribed below.
+
+   <refsect2><title>Dir Section</>
+     <Para>
+     The <literal/Dir/ section defines the standard directories needed to 
+     locate the files required during the generation process. These 
+     directories are prepended to certain relative paths defined in later 
+     sections to produce a complete an absolute path.
+     <VariableList>     
+      <VarListEntry><term>ArchiveDir</term>
+      <ListItem><Para>
+      Specifies the root of the FTP archive, in a standard
+      Debian configuration this is the directory that contains the 
+      <filename/ls-LR/, and dist nodes.
+      </VarListEntry>
+
+      <VarListEntry><term>OverrideDir</term>
+      <ListItem><Para>
+      Specifies the location of the override files.
+      </VarListEntry>
+      
+      <VarListEntry><term>CacheDir</term>
+      <ListItem><Para>
+      Specifies the location of the cache files
+      </VarListEntry>
+      
+      <VarListEntry><term>FileListDir</term>
+      <ListItem><Para>
+      Specifies the location of the file list files, 
+      if the <literal/FileList/ setting is used below.
+      </VarListEntry>
+     </VariableList>
+   </refsect2>
+   
+   <refsect2><title>Default Section</>
+     <para>
+     The <literal/Default/ section specifies default values, and settings 
+     that control the operation of the generator. Other sections may override 
+     these defaults with a per-section setting.
+     <VariableList>     
+      <VarListEntry><term>Packages::Compress</term>
+      <ListItem><Para>
+      Sets the default compression schemes to use 
+      for the Package index files. It is a string that contains a space 
+      separated list of at least one of: '.' (no compression), 'gzip' and 
+      'bzip2'. The default for all compression schemes is '. gzip'.
+      </VarListEntry>
+
+      <VarListEntry><term>Packages::Extensions</term>
+      <ListItem><Para>
+      Sets the default list of file extensions that are package files.
+      This defaults to '.deb'.
+      </VarListEntry>
+      
+      <VarListEntry><term>Sources::Compress</term>
+      <ListItem><Para>
+      This is similar to <literal/Packages::Compress/ 
+      except that it controls the compression for the Sources files.
+      </VarListEntry>
+      
+      <VarListEntry><term>Sources::Extensions</term>
+      <ListItem><Para>
+      Sets the default list of file extensions that are source files.
+      This defaults to '.dsc'.
+      </VarListEntry>
+      
+      <VarListEntry><term>Contents::Compress</term>
+      <ListItem><Para>
+      This is similar to <literal/Packages::Compress/ 
+      except that it controls the compression for the Contents files.
+      </VarListEntry>
+      
+      <VarListEntry><term>DeLinkLimit</term>
+      <ListItem><Para>
+      Specifies the number of kilobytes to delink (and 
+      replace with hard links) per run. This is used in conjunction with the 
+      per-section <literal/External-Links/ setting. 
+      </VarListEntry>
+      
+      <VarListEntry><term>FileMode</term>
+      <ListItem><Para>
+      Specifies the mode of all created index files. It 
+      defaults to 0644. All index files are set to this mode with no regard 
+      to the umask.
+      </VarListEntry>
+     </VariableList>
+   </refsect2>
+   
+   <refsect2><title>TreeDefault Section</>
+     <para>
+     Sets defaults specific to <literal/Tree/ sections. All of these 
+     variables are substitution variables and have the strings $(DIST), 
+     $(SECTION) and $(ARCH) replaced with their respective values.
+     
+     <VariableList>     
+      <VarListEntry><term>MaxContentsChange</term>
+      <ListItem><Para>
+      Sets  the number of kilobytes of contents 
+      files that are generated each day. The contents files are round-robined
+      so that over several days they will all be rebuilt.
+      </VarListEntry>
+      
+      <VarListEntry><term>ContentsAge</term>
+      <ListItem><Para>
+      Controls the number of days a contents file is allowed
+      to be checked without changing. If this limit is passed the mtime of the 
+      contents file is updated. This case can occur if the package file is 
+      changed in such a way that does not result in a new contents file 
+      [overried edit for instance]. A hold off is allowed in hopes that new 
+      .debs will be installed, requiring a new file anyhow. The default is 10, 
+      the units are in days.
+      </VarListEntry>
+      
+      <VarListEntry><term>Directory</term>
+      <ListItem><Para>
+      Sets the top of the .deb directory tree. Defaults to
+      <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/</>
+      </VarListEntry>
+      
+      <VarListEntry><term>Packages</term>
+      <ListItem><Para>
+      Sets the output Packages file. Defaults to 
+      <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/Packages</>
+      </VarListEntry>
+      
+      <VarListEntry><term>Sources</term>
+      <ListItem><Para>
+      Sets the output Packages file. Defaults to 
+      <filename>$(DIST)/$(SECTION)/source/Sources</>
+      </VarListEntry>
+      
+      <VarListEntry><term>InternalPrefix</term>
+      <ListItem><Para>
+      Sets the path prefix that causes a symlink to be
+      considered an internal link instead of an external link. Defaults to
+      <filename>$(DIST)/$(SECTION)/</>
+      </VarListEntry>
+      
+      <VarListEntry><term>Contents</term>
+      <ListItem><Para>
+      Sets the output Contents file. Defaults to
+      <filename>$(DIST)/Contents-$(ARCH)</>. If this setting causes multiple 
+      Packages files to map onto a single Contents file (such as the default) 
+      then <command/apt-ftparchive/ will integrate those package files 
+      together automatically.
+      </VarListEntry>
+      
+      <VarListEntry><term>Contents::Header</term>
+      <ListItem><Para>
+      Sets header file to prepend to the contents output.
+      </VarListEntry>
+
+      <VarListEntry><term>BinCacheDB</term>
+      <ListItem><Para>
+      Sets the binary cache database to use for this 
+      section. Multiple sections can share the same database.
+      </VarListEntry>
+      
+      <VarListEntry><term>FileList</term>
+      <ListItem><Para>
+      Specifies that instead of walking the directory tree 
+      that <command/apt-ftparchive/ should read the list of files from the given 
+      file. Relative files names are prefixed with the archive directory.
+      </VarListEntry>
+      
+      <VarListEntry><term>SourceFileList</term>
+      <ListItem><Para>
+      Specifies that instead of walking the directory tree 
+      that <command/apt-ftparchive/ should read the list of files from the given 
+      file. Relative files names are prefixed with the archive directory. 
+      This is used when processing source indexs.
+      </VarListEntry>
+     </VariableList>     
+   </refsect2>
+   
+   <refsect2><title>Tree Section</>
+     <para>
+     The <literal/Tree/ section defines a standard Debian file tree which 
+     consists of a base directory, then multiple sections in that base 
+     directory and finally multiple Architectures in each section. The exact 
+     pathing used is defined by the <literal/Directory/ substitution variable. 
+     <para>
+     The <literal/Tree/ section takes a scope tag which sets the 
+     <literal/$(DIST)/ variable and defines the root of the tree 
+     (the path is prefixed by <literal/ArchiveDir/).
+     Typically this is a setting such as <filename>dists/woody</>.
+     <para>
+     All of the settings defined in the <literal/TreeDefault/ section can be
+     use in a <literal/Tree/ section as well as three new variables.
+     <para>
+     When processing a <literal/Tree/ section <command/apt-ftparchive/ 
+     performs an operation similar to:
+<informalexample><programlisting>
+for i in Sections do 
+   for j in Architectures do
+      Generate for DIST=scope SECTION=i ARCH=j
+</programlisting></informalexample>
+
+     <VariableList>     
+      <VarListEntry><term>Sections</term>
+      <ListItem><Para>
+      This is a space separated list of sections which appear 
+      under the distribution, typically this is something like 
+      <literal/main contrib non-free/.
+      </VarListEntry>
+      
+      <VarListEntry><term>Architectures</term>
+      <ListItem><Para>
+      This is a space separated list of all the 
+      architectures that appear under seach section. The special architecture 
+      'source' is used to indicate that this tree has a source archive.
+      </VarListEntry>
+      
+      <VarListEntry><term>BinOverride</term>
+      <ListItem><Para>
+      Sets the binary override file. The override file 
+      contains section, priority and maintainer address information.
+      </VarListEntry>
+      
+      <VarListEntry><term>SrcOverride</term>
+      <ListItem><Para>
+      Sets the source override file. The override file 
+      contains section information.
+      </VarListEntry>
+     </VariableList>
+   </refsect2>
+   
+   <refsect2><title>BinDirectory Section</>
+     <para>
+     The <literal/bindirectory/ section defines a binary directory tree 
+     with no special structure. The scope tag specifies the location of 
+     the binary directory and the settings are similar to the <literal/Tree/ 
+     section with no substitution variables or
+     <literal>Section</><literal>Architecture</> settings.
+     <VariableList>
+      <VarListEntry><term>Packages</term>
+      <ListItem><Para>
+      Sets the Packages file output.
+      </VarListEntry>
+      
+      <VarListEntry><term>SrcPackages</term>
+      <ListItem><Para>
+      Sets the Sources file output. At least one of
+      <literal/Packages/ or <literal/SrcPackages/ is required.
+      </VarListEntry>
+      
+      <VarListEntry><term>Contents</term>
+      <ListItem><Para>
+      Sets the Contents file output. (Optional)
+      </VarListEntry>
+      
+      <VarListEntry><term>Binoverride</term>
+      <ListItem><Para>
+      Sets the binary override file.
+      </VarListEntry>
+      
+      <VarListEntry><term>SrcOverride</term>
+      <ListItem><Para>
+      Sets the source override file.
+      </VarListEntry>
+      
+      <VarListEntry><term>BinCacheDB</term>
+      <ListItem><Para>
+      Sets the cache DB.
+      </VarListEntry>
+      
+      <VarListEntry><term>PathPrefix</term>
+      <ListItem><Para>
+      Appends a path to all the output paths.
+      </VarListEntry>
+      
+      <VarListEntry><term>FileList, SourceFileList</term>
+      <ListItem><Para>
+      Specifies the file list file.
+      </VarListEntry>
+     </VariableList>
+   </refsect2>
+ </RefSect1>
+
+ <RefSect1><Title>The Binary Override File</>
+   <para>
+   The binary override file is fully compatible with &dpkg-scanpackages;. It
+   contains 4 fields sperated by spaces. The first field is the package name,
+   the second is the priority to force that package to, the third is the
+   the section to force that package to and the final field is the maintainer 
+   permutation field. 
+   <para>
+   The general form of the maintainer field is:
+   <literallayout>old [// oldn]* => new</literallayout>
+   or simply,
+   <literallayout>new</literallayout>
+   The first form allows a double-slash separated list of old email addresses 
+   to be specified. If any of those are found then new is substituted for the 
+   maintainer field. The second form unconditionally substitutes the 
+   maintainer field.
+ </RefSect1>
+ 
+ <RefSect1><title>The Source Override File</>
+   <para>
+   The source override file is fully compatible with &dpkg-scansources;. It
+   contains 2 fields separated by spaces. The first fields is the source 
+   package name, the second is the section to assign it.
+ </RefSect1>   
+
+ <RefSect1><Title>Options</>
+   &apt-cmdblurb;
+   
+   <VariableList>
+     <VarListEntry><term><option/--md5/</>
+     <ListItem><Para>
+     Generate MD5 sums. This defaults to on, when turned off the generated 
+     index files will not have MD5Sum fields where possible.
+     Configuration Item: <literal/APT::FTPArchive::MD5/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-d/</><term><option/--db/</>
+     <ListItem><Para>
+     Use a binary caching DB. This has no effect on the generate command.
+     Configuration Item: <literal/APT::FTPArchive::DB/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-q/</><term><option/--quiet/</>
+     <ListItem><Para>
+     Quiet; produces output suitable for logging, omitting progress indicators.
+     More q's will produce more quiet up to a maximum of 2. You can also use
+     <option/-q=#/ to set the quiet level, overriding the configuration file. 
+     Configuration Item: <literal/quiet/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--delink/</>
+     <ListItem><Para>
+     Perform Delinking. If the <literal/External-Links/ setting is used then 
+     this option actually enables delinking of the files. It defaults to on and 
+     can be turned off with <option/--no-delink/.
+     Configuration Item: <literal/APT::FTPArchive::DeLinkAct/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--contents/</>
+     <ListItem><Para>
+     Perform contents generation. When this option is set and package indexes
+     are being generated with a cache DB then the file listing will also be
+     extracted and stored in the DB for later use. When using the generate 
+     command this option also allows the creation of any Contents files. The 
+     default is on.
+     Configuration Item: <literal/APT::FTPArchive::Contents/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-s/</><term><option/--source-override/</>
+     <ListItem><Para>
+     Select the source override file to use with the <literal/sources/ command.
+     Configuration Item: <literal/APT::FTPArchive::SourceOverride/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--readonly/</>
+     <ListItem><Para>
+     Make the caching databases read only. 
+     Configuration Item: <literal/APT::FTPArchive::ReadOnlyDB/.
+     </VarListEntry>   
+   
+     &apt-commonoptions;
+     
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-conf;
+ </RefSect1>
+
+ <RefSect1><Title>Diagnostics</>
+   <para>
+   <command/apt-ftparchive/ returns zero on normal operation, decimal 100 on error.
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/apt-get.8.sgml b/doc/apt-get.8.sgml
new file mode 100644
index 000000000..cf35b65b0
--- /dev/null
+++ b/doc/apt-get.8.sgml
@@ -0,0 +1,451 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-get</>
+   <manvolnum>8</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-get</>
+    <refpurpose>APT package handling utility -- command-line interface</>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-config</>
+      <arg><option>-hvs</></arg>
+      <arg><option>-o=<replaceable/config string/</></arg>
+      <arg><option>-c=<replaceable/file/</></arg>
+      <group choice=req>
+         <arg>update</>
+         <arg>upgrade</>
+         <arg>dselect-upgrade</>
+         <arg>install <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>remove <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>source <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>build-dep <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>check</>
+         <arg>clean</>
+         <arg>autoclean</>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <RefSect1><Title>Description</>
+   <para>
+   <command/apt-get/ is the command-line tool for handling packages, and may be 
+   considered the user's "back-end" to other tools using the APT library.
+   <para>
+   Unless the <option/-h/, or <option/--help/ option is given one of the 
+   above commands must be present.
+   
+   <VariableList>
+     <VarListEntry><Term>update</Term>
+     <ListItem><Para>
+     <literal/update/ is used to resynchronize the package index files from
+     their sources. The indexes of available packages are fetched from the
+     location(s) specified in <filename>/etc/apt/sources.list</>.
+     For example, when using a Debian archive, this command retrieves and
+     scans the <filename>Packages.gz</> files, so that information about new 
+     and updated packages is available. An <literal/update/ should always be 
+     performed before an <literal/upgrade/ or <literal/dist-upgrade/. Please 
+     be aware that the overall progress meter will be incorrect as the size 
+     of the package files cannot be known in advance.
+     </VarListEntry>
+     
+     <VarListEntry><Term>upgrade</Term>
+     <ListItem><Para>   
+     <literal/upgrade/ is used to install the newest versions of all packages 
+     currently installed on the system from the sources enumerated in
+     <filename>/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 <literal/update/ must be 
+     performed first so that <command/apt-get/ knows that new versions of packages are 
+     available.
+     </VarListEntry>
+
+     <VarListEntry><Term>dselect-upgrade</Term>
+     <ListItem><Para>   
+     is used in conjunction with the traditional Debian GNU/Linux packaging
+     front-end, &dselect;. <literal/dselect-upgrade/
+     follows the changes made by &dselect; to the <literal/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). 
+     </VarListEntry>
+
+     <VarListEntry><Term>dist-upgrade</Term>
+     <ListItem><Para>   
+     <literal/dist-upgrade/, in addition to performing the function of 
+     <literal/upgrade/, also intelligently handles changing dependencies 
+     with new versions of packages; <command/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 <filename>/etc/apt/sources.list</> file contains a list of locations 
+     from which to retrieve desired package files.
+     </VarListEntry>
+
+     <VarListEntry><Term>install</Term>
+     <ListItem><Para>   
+     <literal/install/ is followed by one or more packages desired for 
+     installation. Each package is a package name, not a fully qualified 
+     filename (for instance, in a Debian GNU/Linux system, libc6 would be the 
+     argument provided, not em(libc6_1.9.6-2.deb)). All packages required 
+     by the package(s) specified for installation will also be retrieved and 
+     installed. The <filename>/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. Similarly a plus sign can be used to designate a package to 
+     isntall. These latter feature may be used to override decisions made by 
+     apt-get's conflict resolution  system.
+     <para>
+     A specific version of a package can be selected for installation by 
+     following the package name with an equals and the version of the package 
+     to select. This will cause that version to be located and selected for
+     install. Alternatively a specific distribution can be selected by 
+     following the package name with a slash and the version of the 
+     distribution or the Archive name (stable, frozen, unstable).
+     <para>
+     Both of the version selection mechansims can downgrade packages and must
+     be used with care.
+     <para>
+     If no package matches the given expression and the expression contains one
+     of '.', '?' or '*' then it is assumed to be a POSIX regex and it is applied
+     to all package names in the database. Any matches are then installed (or
+     removed). Note that matching is done by substring so 'lo.*' matches 'how-lo'
+     and 'lowest'. If this is undesired prefix with a '^' character.
+     </VarListEntry>
+
+     <VarListEntry><Term>remove</Term>
+     <ListItem><Para>   
+     <literal/remove/ is identical to bf(install) except that packages are 
+     removed instead of installed. If a plus sign is appended to the package 
+     name (with no intervening space), the identified package will be 
+     installed.
+     </VarListEntry>
+
+     <VarListEntry><Term>source</Term>
+     <ListItem><Para>
+     <literal/source/ causes <command/apt-get/ to fetch source packages. APT 
+     will examine the available packages to decide which source package to 
+     fetch. It will then find and download into the current directory the 
+     newest available version of that source package. Source packages are 
+     tracked separately from binary packages via <literal/deb-src/ type lines 
+     in the &sources-list; file. This probably will mean that you will not 
+     get the same source as the package you have installed or as you could 
+     install. If the --compile options is specified then the package will be 
+     compiled to a binary .deb using dpkg-buildpackage, if --download-only is 
+     specified then the source package will not be unpacked.
+     <para>
+     A specific source version can be retrieved by postfixing the source name
+     with an equals and then the version to fetch, similar to the mechanism
+     used for the package files. This enables exact matching of the source 
+     package name and version, implicitly enabling the 
+     <literal/APT::Get::Only-Source/ option.
+     
+     <para>
+     Note that source packages are not tracked like binary packages, they 
+     exist only in the current directory and are similar to downloading source
+     tar balls.
+     </VarListEntry>
+
+     <VarListEntry><Term>build-dep</Term>
+     <ListItem><Para>   
+     <literal/build-dep/ causes apt-get to install/remove packages in an 
+     attempt to satisfy the build dependencies for a source packages. Right 
+     now virtual package build depends choose a package at random.
+     </VarListEntry>
+
+     <VarListEntry><Term>check</Term>
+     <ListItem><Para>   
+     <literal/check/ is a diagnostic tool; it updates the package cache and checks 
+     for broken dependencies.
+     </VarListEntry>
+
+     <VarListEntry><Term>clean</Term>
+     <ListItem><Para>   
+     <literal/clean/ clears out the local repository of retrieved package 
+     files. It removes everything but the lock file from 
+     <filename>&cachedir;/archives/</> and 
+     <filename>&cachedir;/archive/partial/</>. When APT is used as a 
+     &dselect; method, <literal/clean/ is run automatically.
+     Those who do not use dselect will likely want to run <literal/apt-get clean/
+     from time to time to free up disk space.
+     </VarListEntry>
+
+     <VarListEntry><Term>autoclean</Term>
+     <ListItem><Para>   
+     Like <literal/clean/, <literal/autoclean/ clears out the local 
+     repository of retrieved package files. The difference is that it only 
+     removes package files that can no longer be downloaded, and are largely 
+     useless. This allows a cache to be maintained over a long period without 
+     it growing out of control. The configuration option 
+     <literal/APT::Clean-Installed/ will prevent installed packages from being
+     erased if it is set off.
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+ 
+ <RefSect1><Title>Options</>
+   &apt-cmdblurb;
+
+   <VariableList>
+     <VarListEntry><term><option/-d/</><term><option/--download-only/</>
+     <ListItem><Para>
+     Download only; package files are only retrieved, not unpacked or installed.
+     Configuration Item: <literal/APT::Get::Download-Only/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-f/</><term><option/--fix-broken/</>
+     <ListItem><Para>
+     Fix; attempt to correct a system with broken dependencies in            
+     place. This option, when used with install/remove, can omit any packages
+     to permit APT to deduce a likely soltion. Any Package that are specified
+     must completly correct the problem. The option 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 <command/dpkg --remove/ to eliminate some of 
+     the offending packages). Use of this option together with <option/-m/ may produce an
+     error in some situations. 
+     Configuration Item: <literal/APT::Get::Fix-Broken/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-m/</><term><option/--ignore-missing/</>
+                   <term><option/--fix-missing/</>
+     <ListItem><Para>
+     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  
+     <option/-f/ may produce an error in some situations. If a package is 
+     selected for installation (particularly if it is mentioned on the 
+     command line) and it could not be downloaded then it will be silently 
+     held back.
+     Configuration Item: <literal/APT::Get::Fix-Missing/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--no-download/</>
+     <ListItem><Para>
+     Disables downloading of packages. This is best used with 
+     <option/--ignore-missing/ to force APT to use only the .debs it has 
+     already downloaded.
+     Configuration Item: <literal/APT::Get::Download/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-q/</><term><option/--quiet/</>
+     <ListItem><Para>
+     Quiet; produces output suitable for logging, omitting progress indicators.
+     More q's will produce more quiet up to a maximum of 2. You can also use
+     <option/-q=#/ to set the quiet level, overriding the configuration file. 
+     Note that quiet level 2 implies <option/-y/, you should never use -qq 
+     without a no-action modifier such as -d, --print-uris or -s as APT may 
+     decided to do something you did not expect.
+     Configuration Item: <literal/quiet/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-s/</>
+                   <term><option/--simulate/</>
+		   <term><option/--just-print/</>
+		   <term><option/--dry-run/</>
+		   <term><option/--recon/</>
+		   <term><option/--no-act/</>
+     <ListItem><Para>
+     No action; perform a simulation of events that would occur but do not
+     actually change the system. 
+     Configuration Item: <literal/APT::Get::Simulate/.
+     <para>
+     Simulate prints out
+     a series of lines each one representing a dpkg operation, Configure (Conf),
+     Remove (Remv), Unpack (Inst). Square brackets indicate broken packages with
+     and empty set of square brackets meaning breaks that are of no consequence
+     (rare).
+     </VarListEntry>
+
+     <VarListEntry><term><option/-y/</><term><option/--yes/</>
+                   <term><option/--assume-yes/</>
+     <ListItem><Para>
+     Automatic yes to prompts; assume "yes" as answer to all prompts and run
+     non-interactively. If an undesirable situation, such as changing a held
+     package or removing an essential package occurs then <literal/apt-get/ 
+     will abort. 
+     Configuration Item: <literal/APT::Get::Assume-Yes/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-u/</><term><option/--show-upgraded/</>
+     <ListItem><Para>
+     Show upgraded packages; Print out a list of all packages that are to be
+     upgraded. 
+     Configuration Item: <literal/APT::Get::Show-Upgraded/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-b/</><term><option/--compile/</>
+                   <term><option/--build/</>
+     <ListItem><Para>
+     Compile source packages after downloading them.
+     Configuration Item: <literal/APT::Get::Compile/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--ignore-hold/</>
+     <ListItem><Para>
+     Ignore package Holds; This causes <command/apt-get/ to ignore a hold 
+     placed on a package. This may be useful in conjunction with 
+     <literal/dist-upgrade/ to override a large number of undesired holds. 
+     Configuration Item: <literal/APT::Ignore-Hold/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--no-upgrade/</>
+     <ListItem><Para>
+     Do not upgrade packages; When used in conjunction with <literal/install/
+     <literal/no-upgrade/ will prevent packages listed from being upgraded
+     if they are already installed. 
+     Configuration Item: <literal/APT::Get::Upgrade/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--force-yes/</>
+     <ListItem><Para>
+     Force yes; This is a dangerous option that will cause apt to continue 
+     without prompting if it is doing something potentially harmful. It 
+     should not be used except in very special situations. Using 
+     <literal/force-yes/ can potentially destroy your system! 
+     Configuration Item: <literal/APT::Get::force-yes/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--print-uris/</>
+     <ListItem><Para>
+     Instead of fetching the files to install their URIs are printed. Each
+     URI will have the path, the destination file name, the size and the expected
+     md5 hash. Note that the file name to write to will not always match
+     the file name on the remote site! This also works with the /source/
+     command. Configuration Item: <literal/APT::Get::Print-URIs/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--purge/</>
+     <ListItem><Para>
+     Use purge instead of remove for anything that would be removed.
+     Configuration Item: <literal/APT::Get::Purge/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--reinstall/</>
+     <ListItem><Para>
+     Re-Install packages that are already installed and at the newest version.
+     Configuration Item: <literal/APT::Get::ReInstall/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--list-cleanup/</>
+     <ListItem><Para>
+     This option defaults to on, use <literal/--no-list-cleanup/ to turn it 
+     off. When on <command/apt-get/ will automatically manage the contents of 
+     <filename>&statedir;/lists</> to ensure that obsolete files are erased. 
+     The only  reason to turn it off is if you frequently change your source 
+     list. 
+     Configuration Item: <literal/APT::Get::List-Cleanup/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-t/</>
+                   <term><option/--target-release/</>
+                   <term><option/--default-release/</>
+     <ListItem><Para>
+     This option controls the default input to the policy engine, it creates
+     a default pin at priority 990 using the specified release string. The
+     preferences file may further override this setting. In short, this option
+     lets you have simple control over which distribution packages will be
+     retrieved from. Some common examples might me 
+     <option>-t '2.1*'</> or <option>-t unstable</>.
+     Configuration Item: <literal/APT::Default-Release/
+     </VarListEntry>
+
+     <VarListEntry><term><option/--trivial-only/</>
+     <ListItem><Para>
+     Only perform operations are 'trivial'. Logically this can be considered
+     related to <option/--assume-yes/, where <option/--assume-yes/ will answer 
+     yes to any prompt, <option/--trivial-only/ will answer no. 
+     Configuration Item: <literal/APT::Get::Trivial-Only/.
+     </VarListEntry>
+
+     <VarListEntry><term><option/--no-remove/</>
+     <ListItem><Para>
+     If any packages are to be removed apt-get immediately aborts without
+     prompting. 
+     Configuration Item: <literal/APT::Get::Remove/
+     </VarListEntry>
+
+     <VarListEntry><term><option/--only-source/</>
+     <ListItem><Para>
+     Only has meaning for the <literal/source/ command. indicates that the
+     given source names are not to be mapped through the binary table.
+     Configuration Item: <literal/APT::Get::Only-Source/
+     </VarListEntry>
+
+     <VarListEntry><term><option/--diff-only/</><term><option/--tar-only/</>
+     <ListItem><Para>
+     Download only the diff or tar file of a source archive. 
+     Configuration Item: <literal/APT::Get::Diff-Only/ and 
+     <literal/APT::Get::Tar-Only/
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>Files</>
+   <variablelist>
+     <VarListEntry><term><filename>/etc/apt/sources.list</></term>
+     <ListItem><Para>
+     locations to fetch packages from.
+     Configuration Item: <literal/Dir::Etc::SourceList/.
+     </VarListEntry>
+     
+     <VarListEntry><term><filename>&cachedir;/archives/</></term>
+     <ListItem><Para>
+     storage area for retrieved package files
+     Configuration Item: <literal/Dir::Cache::Archives/.
+     </VarListEntry>
+     
+     <VarListEntry><term><filename>&cachedir;/archives/partial/</></term>
+     <ListItem><Para>
+     storage area for package files in transit
+     Configuration Item: <literal/Dir::Cache::Archives/ (implicit partial). 
+     </VarListEntry>
+     
+     <VarListEntry><term><filename>&statedir;/lists/</></term>
+     <ListItem><Para>
+     storage area for state information for each package resource specified in
+     &sources-list;
+     Configuration Item: <literal/Dir::State::Lists/.
+     </VarListEntry>
+  
+     <VarListEntry><term><filename>&statedir;/lists/partial/</></term>
+     <ListItem><Para>
+     storage area for state information in transit.
+     Configuration Item: <literal/Dir::State::Lists/ (implicit partial).
+     </VarListEntry>     
+   </variablelist>
+ </RefSect1>
+
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-cache;, &dpkg;, &dselect;, &sources-list;, &apt-conf;, The
+   APT users guide in &docdir;.
+ </RefSect1>
+
+ <RefSect1><Title>Diagnostics</>
+   <para>
+   <command/apt-get/ returns zero on normal operation, decimal 100 on error.
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/apt-get.8.yo b/doc/apt-get.8.yo
deleted file mode 100644
index 4983b2581..000000000
--- a/doc/apt-get.8.yo
+++ /dev/null
@@ -1,302 +0,0 @@
-mailto(apt@packages.debian.org)
-manpage(apt-get)(8)(4 Dec 1998)(apt)()
-manpagename(apt-get)(APT package handling utility -- command-line interface)
-
-manpagesynopsis()
-  apt-get [options] [command] [package ...]
-
-manpagedescription()
-
-apt-get is the command-line tool for handling packages, and may be considered 
-the user's "back-end" to apt(8).
-
-em(command) is one of:
-itemize(
-  it() update
-  it() upgrade
-  it() dselect-upgrade
-  it() dist-upgrade
-  it() install package1 [package2] [...]
-  it() remove package1 [package2] [...]
-  it() source package1 [package2] [...]
-  it() check
-  it() clean
-  it() autoclean
-)
-
-Unless the -h, or --help option is given one of the above commands
-must be present.
-
-startdit()
-dit(bf(update))
-bf(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 bf(/etc/apt/sources.list).
-For example, when using a Debian archive, this command retrieves and
-scans the bf(Packages.gz) files, so that information about new and updated 
-packages is available. An bf(update) should always be performed before an
-bf(upgrade) bf(dist-upgrade). Please be aware that the overall progress
-meter will be incorrect as the size of the package files cannot be known in
-advance.
-
-dit(bf(upgrade))
-bf(upgrade) is used to install the newest versions of all packages currently 
-installed on the system from the sources enumerated in
-bf(/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 bf(update) must be performed first so that
-bf(apt-get) knows that new versions of packages are available.
-
-dit(bf(dselect-upgrade))
-bf(dselect-upgrade)
-is used in conjunction with the traditional Debian GNU/Linux packaging
-front-end, bf(dselect (8)). bf(dselect-upgrade)
-follows the changes made by bf(dselect) to the em(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). 
-
-dit(bf(dist-upgrade))
-bf(dist-upgrade),in addition to performing the function of bf(upgrade),
-also intelligently handles changing dependencies with new versions of
-packages; bf(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 bf(/etc/apt/sources.list) file contains a 
-list of locations from which to retrieve desired package files.
-
-dit(bf(install))
-bf(install) is followed by one or more em(packages) desired for installation. 
-Each em(package) is a package name, not a fully qualified filename 
-(for instance, in a Debian GNU/Linux system, em(ldso) would be the argument 
-provided, not em(ldso_1.9.6-2.deb)). All packages required by the package(s) 
-specified for installation will also be retrieved and installed. The
-bf(/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.
-
-If no package matches the given expression and the expression contains one
-of '.', '?' or '*' then it is assumed to be a POSIX regex and it is applied
-to all package names in the database. Any matches are then installed (or
-removed). Note that matching is done by substring so 'lo*' matches 'how-lo'
-and 'lowest'. If this is undesired prefix with a '^' character.
-
-dit(bf(remove))
-bf(remove) is identical to bf(install) except that packages are removed
-instead of installed. If a plus sign is appended to the package name (with no
-intervening space), the identified package will be installed.
-
-dit(bf(source))
-bf(source) causes apt-get to fetch source packages. APT will examine the
-available packages to decide which source package to fetch. It will then
-find and download into the current directory the newest available version of
-that source package. Source packages are tracked separately from binary
-packages via bf(deb-src) type lines in the bf(/etc/apt/sources.list) file.
-This probably will mean that you will not get the same source as the package
-you have installed or as you could install. If the --compile options is
-specified then the package will be compiled to a binary .deb using
-dpkg-buildpackage, if --download-only is specified then the source package
-will not be unpacked.
-
-Note that source packages are not tracked like binary packages, they exist
-only in the current directory and are similar to downloading source
-tar balls.
-
-dit(bf(check))
-bf(check) is a diagnostic tool; it updates the package cache and checks for 
-broken packages.
-
-dit(bf(clean))
-bf(clean) clears out the local repository of retrieved package files. It 
-removes everything but the lock file from bf(/var/cache/apt/archives/)
-and bf(/var/cache/apt/archives/partial/).
-When APT is used as a bf(dselect(8)) method, bf(clean) is run automatically.
-Those who do not use dselect will likely want to run code(apt-get clean)
-from time to time to free up disk space.
-
-dit(bf(autoclean))
-Like bf(clean), bf(autoclean) clears out the local repository of retrieved 
-package files. The difference is that it only removes package files that
-can no longer be downloaded, and are largely useless. This allows a
-cache to be maintained over a long period without it growing out of
-control.
-
-enddit()
-
-manpageoptions()
-All command line options may be set using the configuration file, the
-descriptions indicate the configuration option to set. For boolean
-options you can override the config file by using something like bf(-f-),
-bf(--no-f), bf(-f=no) or several other variations.
-
-startdit()
-dit(bf(-d, --download-only))
-Download only; package files are only retrieved, not unpacked or installed.
-Configuration Item: bf(APT::Get::Download-Only).
-
-dit(bf(-f, --fix-broken))
-Fix; attempt to correct a system with broken dependencies in            
-place. This option, when used with install/remove, can omit any packages
-to permit APT to deduce a likely soltion. Any Package that are specified
-must completly correct the problem. The option 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 may produce an 
-error in some situations. Configuration Item: bf(APT::Get::Fix-Broken).
-
-dit(bf(-h, --help))
-Help; display a helpful usage message and exits.
-
-dit(bf(-v, --version))
-Show the program version.
-
-dit(bf(-m, --ignore-missing, --fix-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 may produce an error in some situations. If a package is selected for 
-installation (particularly if it is mentioned on the command line) and it
-could not be downloaded then it will be silently held back.
-Configuration Item: bf(APT::Get::ignore-missing).
-
-dit(bf(--no-download))
-Disables downloading of packages. This is best used with --ignore-missing to
-force APT to use only the .debs it has already downloaded.
-Configuration Item: bf(APT::Get::No-Download).
-
-dit(bf(-q, --quiet))
-Quiet; produces output suitable for logging, omitting progress indicators.
-More q's will produce more quiet up to a maximum of 2. You can also use
-bf(-q=#) to set the quiet level, overriding the configuration file. Note that
-quiet level 2 implies -y, you should never use -qq without a no-action
-modifier such as -d, --print-uris or -s as APT may decided to do something
-you did not expect.
-Configuration Item: bf(quiet)
-
-dit(bf(-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. Configuration Item: bf(APT::Get::Simulate). 
-
-Simulate prints out
-a series of lines each one representing a dpkg operation, Configure (Conf),
-Remove (Remv), Unpack (Inst). Square brackets indicate broken packages with
-and empty set of square brackets meaning breaks that are of no consequence
-(rare).
-
-dit(bf(-y, --yes, --assume-yes))
-Automatic yes to prompts; assume "yes" as answer to all prompts and run
-non-interactively. If an undesirable situation, such as changing a held
-package or removing an essential package occurs then bf(apt-get) will
-abort. Configuration Item: bf(APT::Get::Assume-Yes).
-
-dit(bf(-u, --show-upgraded))
-Show upgraded packages; Print out a list of all packages that are to be
-upgraded. Configuration Item: bf(APT::Get::Show-Upgraded).
-
-dit(bf(-b, --compile, --build))
-Compile source packages after downloading them.
-Configuration Item: bf(APT::Get::Compile).
-
-dit(bf(--ignore-hold))
-Ignore package Holds; This causes bf(apt-get) to ignore a hold placed on 
-a package. This may be useful in conjunction with bf(dist-upgrade) to
-override a large number of undesired holds. Configuration Item: bf(APT::Ignore-Hold).
-
-dit(bf(--no-upgrade))
-Do not upgrade packages; When used in conjunction with bf(install)
-bf(no-upgrade) will prevent packages listed from being upgraded if they
-are already installed. Configuration Item: bf(APT::Get::no-upgrade).
-
-dit(bf(--force-yes))
-Force yes; This is a dangerous option that will cause apt to continue without
-prompting if it is doing something potentially harmful. It should not be used
-except in very special situations. Using bf(force-yes) can potentially destroy
-your system! Configuration Item: bf(APT::Get::force-yes).
-
-dit(bf(--print-uris))
-Instead of fetching the files to install their URIs are printed. Each
-URI will have the path, the destination file name, the size and the expected
-md5 hash. Note that the file name to write to will not always match
-the file name on the remote site! This also works with the bf(source)
-command. Configuration Item: bf(APT::Get::Print-URIs).
-
-dit(bf(--purge))
-Use purge instead of remove for anything that would be removed.
-Configuration Item: bf(APT::Get::Purge).
-
-dit(bf(--reinstall))
-Re-Install packages that are already installed and at the newest version.
-
-dit(bf(--list-cleanup))
-This option defaults to on, use bf(--no-list-cleanup) to turn it off.
-When on apt-get will automatically manage the contents of 
-/var/state/apt/lists to ensure that obsolete files are erased. The only 
-reason to turn it off is if you frequently change your source list. 
-Configuration Item: bf(APT::Get::List-Cleanup)
-
-dit(bf(--trivial-only))
-Only perform operations are 'trivial'. Logically this can be considered
-related to --assume-yes, where --assume-yes will answer yes to any prompt,
---trivial-only will answer no. Configuration Item: bf(APT::Get::Trivial-Only)
-
-dit(bf(--no-remove))
-If any packages are to be removed apt-get immediately aborts without
-prompting. Configuration Item: bf(APT::Get::No-Remove)
-
-dit(bf(--diff-only), bf(--tar-only))
-Download only the diff or tar file of a source archive. 
-Configuration Item: bf(APT::Get::Diff-Only)
-
-dit(bf(-c, --config-file))
-Configuration File; Specify a configuration file to use. bf(apt-get) will
-read the default configuration file and then this configuration file. See
-bf(apt.conf(5)) for syntax information.
-
-dit(bf(-o, --option))
-Set a Configuration Option; This will set an arbitrary configuration option.
-The syntax is 
-verb(-o Foo::Bar=bar)
-enddit()
-
-manpagefiles()
-itemize(
-  it() /etc/apt/sources.list 
-  locations to fetch packages from
-  
-  it() /var/cache/apt/archives/
-  storage area for retrieved package files
-  
-  it() /var/cache/apt/archives/partial/
-  storage area for package files in transit
-  
-  it() /var/state/apt/lists/
-  storage area for state information for each package resource specified in
-  the source list
-  
-  it() /var/state/apt/lists/partial/
-  storage area for state information in transit
-)
-
-manpageseealso()
-apt-cache(8),
-dpkg(8),
-dselect(8),
-sources.list(5),
-apt.conf(5),
-The APT Users Guide in /usr/doc/apt/
-
-manpagediagnostics()
-apt-get returns zero on normal operation, decimal 100 on error.
-
-manpagebugs()
-See http://bugs.debian.org/apt.  If you wish to report a
-bug in bf(apt-get), please see bf(/usr/doc/debian/bug-reporting.txt)
-or the bf(bug(1)) command.
-
-manpageauthor()
-apt-get was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/apt-sortpkgs.1.sgml b/doc/apt-sortpkgs.1.sgml
new file mode 100644
index 000000000..c939b973f
--- /dev/null
+++ b/doc/apt-sortpkgs.1.sgml
@@ -0,0 +1,73 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-sortpkgs</>
+   <manvolnum>1</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-sortpkgs</>
+    <refpurpose>Utility to sort package index files</>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-config</>
+      <arg><option>-hvs</></arg>
+      <arg><option>-o=<replaceable/config string/</></arg>
+      <arg><option>-c=<replaceable/file/</></arg>
+      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <RefSect1><Title>Description</>
+   <para>   
+   <command/apt-sortpkgs/ will take an index file (Source index or Package 
+   index) and sort the records so that they are ordered by the package name. 
+   It will also sort the internal fields of each record according to the 
+   internal sorting rules.
+
+   <para>
+   All output is sent to stdout, the input must be a seekable file.
+ </RefSect1>
+ 
+ <RefSect1><Title>Options</>
+   &apt-cmdblurb;
+   
+   <VariableList>
+     <VarListEntry><term><option/-s/</><term><option/--source/</>
+     <ListItem><Para>
+     Use Source index field ordering.
+     Configuration Item: <literal/APT::SortPkgs::Source/.
+     </VarListEntry>
+   
+     &apt-commonoptions;
+     
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-conf;
+ </RefSect1>
+
+ <RefSect1><Title>Diagnostics</>
+   <para>
+   <command/apt-sortpkgs/ returns zero on normal operation, decimal 100 on error.
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/apt.conf.5.sgml b/doc/apt.conf.5.sgml
new file mode 100644
index 000000000..da40e3df9
--- /dev/null
+++ b/doc/apt.conf.5.sgml
@@ -0,0 +1,407 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt.conf</>
+   <manvolnum>5</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt.conf</>
+    <refpurpose>Configuratoin file for APT</>
+ </refnamediv>
+ 
+ <RefSect1><Title>Description</>
+   <para>   
+   <filename/apt.conf/ is the main configuration file for the APT suite of
+   tools, all tools make use of the configuration file and a common command line
+   parser to provide a uniform environment. When an APT tool starts up it will
+   read the configuration specified by the <envar/APT_CONFIG/ environment 
+   variable (if any) and then read the files in <literal/Dir::Etc::Parts/ 
+   then read the main configuration file specified by 
+   <literal/Dir::Etc::main/ then finally apply the
+   command line options to override the configuration directives, possibly 
+   loading even more config files.
+   <para>
+   The configuration file is organized in a tree with options organized into
+   functional groups. Option specification is given with a double colon
+   notation, for instance <literal/APT::Get::Assume-Yes/ is an option within 
+   the APT tool group, for the Get tool. Options do not inherit from their 
+   parent groups.
+   <para>
+   Syntacticly the configuration language is modeled after what the ISC tools
+   such as bind and dhcp use. Each line is of the form
+   <literallayout>APT::Get::Assume-Yes "true";</literallayout> The trailing 
+   semicolon is required and the quotes are optional. A new scope can be
+   opened with curly braces, like:
+<informalexample><programlisting>   
+APT {
+  Get {
+    Assume-Yes "true";
+    Fix-Broken "true";
+  };
+};
+</programlisting></informalexample>
+   with newlines placed to make it more readable. Lists can be created by 
+   opening a scope and including a single word enclosed in quotes followed by a 
+   semicolon. Multiple entries can be included, each seperated by a semicolon.
+<informalexample><programlisting>   
+DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
+</programlisting></informalexample>
+   <para>
+   In general the sample configuration file in 
+   <filename>&docdir;/examples/apt.conf</> &configureindex;
+   is a good guide for how it should look.
+   <para>
+   Two specials are allowed, <literal/#include/ and <literal/#clear/. 
+   <literal/#include/ will include the given file, unless the filename
+   ends in a slash, then the whole directory is included.  
+   <literal/#clear/ is used to erase a list of names.
+   <para>
+   All of the APT tools take a -o option which allows an arbitary configuration 
+   directive to be specified on the command line. The syntax is a full option
+   name (<literal/APT::Get::Assume-Yes/ for instance) followed by an equals
+   sign then the new value of the option. Lists can be appended too by adding 
+   a trailing :: to the list name.   
+ </RefSect1>
+
+ <RefSect1><Title>The APT Group</>
+   <para>   
+   This group of options controls general APT behavoir as well as holding the
+   options for all of the tools.
+
+   <VariableList>
+     <VarListEntry><Term>Architecture</Term>
+     <ListItem><Para>
+     System Architecture; sets the architecture to use when fetching files and
+     parsing package lists. The internal default is the architecture apt was 
+     compiled for.
+     </VarListEntry>
+     
+     <VarListEntry><Term>Ignore-Hold</Term>
+     <ListItem><Para>
+     Ignore Held packages; This global options causes the problem resolver to
+     ignore held packages in its decision making. 
+     </VarListEntry>
+
+     <VarListEntry><Term>Clean-Installed</Term>
+     <ListItem><Para>
+     Defaults to on. When turned on the autoclean feature will remove any pacakge
+     which can no longer be downloaded from the cache. If turned off then
+     packages that are locally installed are also excluded from cleaning - but
+     note that APT provides no direct means to reinstall them.
+     </VarListEntry>
+
+     <VarListEntry><Term>Immediate-Configure</Term>
+     <ListItem><Para>
+     Disable Immedate Configuration; This dangerous option disables some
+     of APT's ordering code to cause it to make fewer dpkg calls. Doing
+     so may be necessary on some extremely slow single user systems but 
+     is very dangerous and may cause package install scripts to fail or worse.
+     Use at your own risk.
+     </VarListEntry>
+
+     <VarListEntry><Term>Force-LoopBreak</Term>
+     <ListItem><Para>
+     Never Enable this option unless you -really- know what you are doing. It
+     permits APT to temporarily remove an essential package to break a
+     Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential
+     packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option 
+     will work if the essential packages are not tar, gzip, libc, dpkg, bash or
+     anything that those packages depend on.
+     </VarListEntry>
+
+     <VarListEntry><Term>Cache-Limit</Term>
+     <ListItem><Para>
+     APT uses a fixed size memory mapped cache file to store the 'available'
+     information. This sets the size of that cache.
+     </VarListEntry>
+
+     <VarListEntry><Term>Get</Term>
+     <ListItem><Para>
+     The Get subsection controls the &apt-get; tool, please see its
+     documentation for more information about the options here.
+     </VarListEntry>
+
+     <VarListEntry><Term>Cache</Term>
+     <ListItem><Para>
+     The Cache subsection controls the &apt-cache; tool, please see its
+     documentation for more information about the options here.
+     </VarListEntry>
+
+     <VarListEntry><Term>CDROM</Term>
+     <ListItem><Para>
+     The CDROM subsection controls the &apt-cdrom; tool, please see its
+     documentation for more information about the options here.
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>The Acquire Group</>
+   <para>   
+   The <literal/Acquire/ group of options controls the download of packages 
+   and the URI handlers. 
+
+   <VariableList>
+     <VarListEntry><Term>Queue-Mode</Term>
+     <ListItem><Para>
+     Queuing mode; <literal/Queue-Mode/ can be one of <literal/host/ or 
+     <literal/access/ which determins how APT parallelizes outgoing 
+     connections. <literal/host/ means that one connection per target host 
+     will be opened, <literal/access/ means that one connection per URI type 
+     will be opened.
+     </VarListEntry>
+
+     <VarListEntry><Term>Retries</Term>
+     <ListItem><Para>
+     Number of retries to perform. If this is non-zero APT will retry failed 
+     files the given number of times.
+     </VarListEntry>
+
+     <VarListEntry><Term>Source-Symlinks</Term>
+     <ListItem><Para>
+     Use symlinks for source archives. If set to true then source archives will
+     be symlinked when possible instead of copying. True is the default
+     </VarListEntry>
+
+     <VarListEntry><Term>http</Term>
+     <ListItem><Para>
+     HTTP URIs; http::Proxy is the default http proxy to use. It is in the 
+     standard form of <literal>http://[[user][:pass]@]host[:port]/</>. Per 
+     host proxies can also be specified by using the form 
+     <literal/http::Proxy::&lt;host&gt;/ with the special keyword <literal/DIRECT/ 
+     meaning to use no proxies. The <envar/http_proxy/ environment variable
+     will override all settings.
+     <para>
+     Three settings are provided for cache control with HTTP/1.1 complient 
+     proxy caches. <literal/No-Cache/ tells the proxy to not used its cached 
+     response under any circumstances, <literal/Max-Age/ is sent only for 
+     index files and tells the cache to refresh its object if it is older than 
+     the given number of seconds. Debian updates its index files daily so the 
+     default is 1 day. <literal/No-Store/ specifies that the cache should never 
+     store this request, it is only set for archive files. This may be useful 
+     to prevent polluting a proxy cache with very large .deb files. Note: 
+     Squid 2.0.2 does not support any of these options.
+     <para>
+     The option <literal/timeout/ sets the timeout timer used by the method, 
+     this applies to all things including connection timeout and data timeout.
+     <para>
+     One setting is provided to control the pipeline depth in cases where the
+     remote server is not RFC conforming or buggy (such as Squid 2.0.2)
+     <literal/Acquire::http::Pipeline-Depth/ can be a value from 0 to 5 
+     indicating how many outstanding requests APT should send. A value of
+     zero MUST be specified if the remote host does not properly linger
+     on TCP connections - otherwise data corruption will occure. Hosts which
+     require this are in violation of RFC 2068.     
+     </VarListEntry>
+
+     <VarListEntry><Term>ftp</Term>
+     <ListItem><Para>
+     FTP URis; ftp::Proxy is the default proxy server to use. It is in the 
+     standard form of <literal>ftp://[[user][:pass]@]host[:port]/</> and is 
+     overriden by the <envar/ftp_proxy/ environment variable. To use a ftp 
+     proxy you will have to set the <literal/ftp::ProxyLogin/ script in the 
+     configuration file. This entry specifies the commands to send to tell 
+     the proxy server what to connect to. Please see 
+     &configureindex; for an example of 
+     how to do this. The subsitution variables available are 
+     <literal/$(PROXY_USER)/, <literal/$(PROXY_PASS)/, <literal/$(SITE_USER)/,
+     <literal/$(SITE_PASS)/, <literal/$(SITE)/, and <literal/$(SITE_PORT)/.
+     Each is taken from it's respective URI component.
+     <para>
+     The option <literal/timeout/ sets the timeout timer used by the method, 
+     this applies to all things including connection timeout and data timeout.
+     <para>
+     Several settings are provided to control passive mode. Generally it is 
+     safe to leave passive mode on, it works in nearly every environment. 
+     However some situations require that passive mode be disabled and port 
+     mode ftp used instead. This can be done globally, for connections that 
+     go through a proxy or for a specific host (See the sample config file 
+     for examples)
+     <para>
+     It is possible to proxy FTP over HTTP by setting the <envar/ftp_proxy/
+     environment variable to a http url - see the discussion of the http method
+     above for syntax. You cannot set this in the configuration file and it is
+     not recommended to use FTP over HTTP due to its low efficiency.
+     <para>
+     The setting <literal/ForceExtended/ controls the use of RFC2428 
+     <literal/EPSV/ and <literal/EPRT/ commands. The defaut is false, which means
+     these commands are only used if the control connection is IPv6. Setting this
+     to true forces their use even on IPv4 connections. Note that most FTP servers
+     do not support RFC2428.
+     </VarListEntry>
+
+     <VarListEntry><Term>cdrom</Term>
+     <ListItem><Para>
+     CDROM URIs; the only setting for CDROM URIs is the mount point, 
+     <literal/cdrom::Mount/ which must be the mount point for the CDROM drive 
+     as specified in <filename>/etc/fstab</>. It is possible to provide 
+     alternate mount and unmount commands if your mount point cannot be listed 
+     in the fstab (such as an SMB mount and old mount packages). The syntax 
+     is to put <literallayout>"/cdrom/"::Mount "foo";</literallayout> within 
+     the cdrom block. It is important to have the trailing slash. Unmount 
+     commands can be specified using UMount.
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>Directories</>
+   <para>   
+   The <literal/Dir::State/ section has directories that pertain to local 
+   state information. <literal/lists/ is the directory to place downloaded 
+   package lists in and <literal/status/ is the name of the dpkg status file.
+   <literal/preferences/ is the name of the APT preferencse file.
+   <literal/Dir::State/ contains the default directory to prefix on all sub 
+   items if they do not start with <filename>/</> or <filename>./</>. 
+   <para>
+   <literal/Dir::Cache/ contains locations pertaining to local cache 
+   information, such as the two package caches <literal/srcpkgcache/ and 
+   <literal/pkgcache/ as well as the location to place downloaded archives, 
+   <literal/Dir::Cache::archives/. Generation of caches can be turned off
+   by setting their names to be blank. This will slow down startup but
+   save disk space. It is probably prefered to turn off the pkgcache rather
+   than the srcpkgcache. Like <literal/Dir::State/ the default
+   directory is contained in <literal/Dir::Cache/
+   <para>
+   <literal/Dir::Etc/ contains the location of configuration files, 
+   <literal/sourcelist/ gives the location of the sourcelist and 
+   <literal/main/ is the default configuration file (setting has no effect,
+   unless it is done from the config file specified by 
+   <envar/APT_CONFIG/).
+   <para>
+   The <literal/Dir::Parts/ setting reads in all the config fragments in 
+   lexical order from the directory specified. After this is done then the
+   main config file is loaded.
+   <para>
+   Binary programs are pointed to by <literal/Dir::Bin/. <literal/methods/ 
+   specifies the location of the method handlers and <literal/gzip/, 
+   <literal/dpkg/, <literal/apt-get/, <literal/dpkg-source/, 
+   <literal/dpkg-buildpackage/ and <literal/apt-cache/ specify the location
+   of the respective programs.
+ </RefSect1>
+ 
+ <RefSect1><Title>APT in DSelect</>
+   <para>   
+   When APT is used as a &dselect; method several configuration directives
+   control the default behavoir. These are in the <literal/DSelect/ section.
+   
+   <VariableList>
+     <VarListEntry><Term>Clean</Term>
+     <ListItem><Para>
+     Cache Clean mode; this value may be one of always, auto, prompt and never.
+     always will remove all archives after they have been downloaded while auto
+     will only remove things that are no longer downloadable (replaced with a 
+     new version for instance)
+     </VarListEntry>
+     
+     <VarListEntry><Term>Options</Term>
+     <ListItem><Para>
+     The contents of this variable is passed to &apt-get; as command line
+     options when it is run for the install phase.
+     </VarListEntry>
+
+     <VarListEntry><Term>UpdateOptions</Term>
+     <ListItem><Para>
+     The contents of this variable is passed to &apt-get; as command line
+     options when it is run for the update phase.
+     </VarListEntry>
+
+     <VarListEntry><Term>PromptAfterUpdate</Term>
+     <ListItem><Para>
+     If true the [U]pdate operation in &dselect; will always prompt to continue. 
+     The default is to prompt only on error.
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+ 
+ <RefSect1><Title>How APT calls dpkg</>
+   <para>   
+   Several configuration directives control how APT invokes &dpkg;. These are 
+   in the <literal/DPkg/ section.
+
+   <VariableList>
+     <VarListEntry><Term>Options</Term>
+     <ListItem><Para>
+     This is a list of options to pass to dpkg. The options must be specified
+     using the list notation and each list item is passed as a single arugment
+     to &dpkg;.
+     </VarListEntry>
+     
+     <VarListEntry><Term>Pre-Invoke</Term><Term>Post-Invoke</Term>
+     <ListItem><Para>
+     This is a list of shell commands to run before/after invoking &dpkg;. 
+     Like <literal/Options/ this must be specified in list notation. The 
+     commands are invoked in order using <filename>/bin/sh</>, should any 
+     fail APT will abort.
+     </VarListEntry>
+
+     <VarListEntry><Term>Pre-Install-Pkgs</Term>
+     <ListItem><Para>
+     This is a list of shell commands to run before invoking dpkg. Like
+     <literal/Options/ this must be specified in list notation. The commands
+     are invoked in order using <filename>/bin/sh</>, should any fail APT 
+     will abort. APT will pass to the commands on standard input the 
+     filenames of all .deb files it is going to install, one per line.
+     <para>
+     Version 2 of this protocol dumps more information, including the 
+     protocol version, the APT configuration space and the packages, files
+     and versions being changed. Version 2 is enabled by setting 
+     <literal/DPkg::Tools::Options::cmd::Version/ to 2. <literal/cmd/ is a
+     command given to <literal/Pre-Install-Pkgs/.
+     </VarListEntry>
+
+     <VarListEntry><Term>Run-Directory</Term>
+     <ListItem><Para>
+     APT chdirs to this directory before invoking dpkg, the default is 
+     <filename>/</>.
+     </VarListEntry>
+
+     <VarListEntry><Term>Build-Options</Term>
+     <ListItem><Para>
+     These options are passed to &dpkg-buildpackage; when compiling packages,
+     the default is to disable signing and produce all binaries.
+     </VarListEntry>
+   </VariableList>
+ </RefSect1>
+
+ <RefSect1><Title>Debug Options</>
+   <para>   
+   Most of the options in the <literal/debug/ section are not interesting to 
+   the normal user, however <literal/Debug::pkgProblemResolver/ shows 
+   interesting output about the decisions dist-upgrade makes. 
+   <literal/Debug::NoLocking/ disables file locking so APT can do some 
+   operations as non-root and <literal/Debug::pkgDPkgPM/ will print out the 
+   command line for each dpkg invokation. <literal/Debug::IdentCdrom/ will 
+   disable the inclusion of statfs data in CDROM IDs.
+ </RefSect1>
+ 
+ <RefSect1><Title>Examples</>
+   <para>
+   &configureindex; contains a 
+   sample configuration file showing the default values for all possible 
+   options.
+ </RefSect1>
+ 
+ <RefSect1><Title>Files</>
+   <para>
+   <filename>/etc/apt/apt.conf</>
+ </RefSect1>
+ 
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-cache; &apt-conf;
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/apt.conf.5.yo b/doc/apt.conf.5.yo
deleted file mode 100644
index d0759802f..000000000
--- a/doc/apt.conf.5.yo
+++ /dev/null
@@ -1,282 +0,0 @@
-mailto(apt@packages.debian.org)
-manpage(apt.conf)(5)(5 Dec 1998)(apt)()
-manpagename(apt.conf)(configuration file for APT)
-
-manpagedescription()
-bf(apt.conf) is the main configuration file for the APT suite of
-tools, all tools make use of the configuration file and a common command line
-parser to provide a uniform environment. When an APT tool starts up it will
-read bf(/etc/apt/apt.conf), then read the configuration specified by the
-bf($APT_CONFIG) environment variable and then finally apply the command line
-options to override the configuration directives, possibly loading more 
-config files.
-
-The configuration file is organized in a tree with options organized into
-functional groups. Option specification is given with a double colon
-notation, for instance em(APT::Get::Assume-Yes) is an option within the
-APT tool group, for the Get tool. Options do not inherit from their parent
-groups.
-
-Syntacticly the configuration language is modeled after what the ISC tools
-such as bind and dhcp use. Each line is of the form
-quote(APT::Get::Assume-Yes "true";) The trailing semicolon is required and
-the quotes are optional. A new em(scope) can be opened with curly braces,
-like: 
-verb(APT {
-  Get {
-    Assume-Yes "true";
-    Fix-Broken "true";
-  };
-};
-)
-with newlines placed to make
-it more readable. Lists can be created by opening a scope an including a 
-single word enclosed in quotes followed by a semicolon. 
-In general the sample configuration file in
-em(/usr/doc/apt/examples/apt.conf) and
-em(/usr/doc/apt/examples/configure-index) 
-is a good guide for how it should look.
-
-All of the APT tools take a -o option which allows an arbitary configuration 
-directive to be specified on the command line. The syntax is a full option
-name (APT::Get::Assume-Yes for instance) followed by an equals sign then the
-new value of the option. Lists can be appended too by adding a trailing ::
-to the list name.
-
-manpagesection(The APT Group)
-This group of options controls general APT behavoir as well as holding the
-options for all of the tools.
-
-startdit()
-dit(bf(Architecture))
-System Architecture; sets the architecture to use when fetching files and
-parsing package lists. The internal default is the architecture apt was 
-compiled for.
-
-dit(bf(Ignore-Hold))
-Ignore Held packages; This global options causes the problem resolver to
-ignore held packages in its decision making. 
-
-dit(bf(Clean-Installed))
-Defaults to on. When turned on the autoclean feature will remove any pacakge
-which can no longer be downloaded from the cache. If turned off then
-packages that are locally installed are also excluded from cleaning - but
-note that APT provides no direct means to reinstall them.
-
-dit(bf(Immediate-Configure))
-Disable Immedate Configuration; This dangerous option disables some
-of APT's ordering code to cause it to make fewer dpkg calls. Doing
-so may be necessary on some extremely slow single user systems but 
-is very dangerous and may cause package install scripts to fail or worse.
-Use at your own risk.
-
-dit(bf(Force-LoopBreak))
-Never Enable this option unless you -really- know what you are doing. It
-permits APT to temporarily remove an essential package to break a
-Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential
-packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option will
-work if the essential packages are not tar, gzip, libc, dpkg, bash or 
-anything that those packages depend on.
-
-dit(bf(Cache-Limit))
-APT uses a fixed size memory mapped cache file to store the 'available'
-information. This sets the size of that cache.
-
-dit(bf(Get))
-The Get subsection controls the bf(apt-get(8)) tool, please see its
-documentation for more information about the options here.
-
-dit(bf(Cache))
-The Cache subsection controls the bf(apt-cache(8)) tool, please see its
-documentation for more information about the options here.
-
-dit(bf(CDROM))
-The CDROM subsection controls the bf(apt-cdrom(8)) tool, please see its
-documentation for more information about the options here.
-
-enddit()
-
-manpagesection(The Acquire Group)
-The bf(Acquire) group of options controls the download of packages and the 
-URI handlers. 
-
-startdit()
-dit(bf(Queue-Mode))
-Queuing mode; bf(Queue-Mode) can be one of bf(host) or bf(access) which 
-determins how APT parallelizes outgoing connections. bf(host) means that
-one connection per target host will be opened, bf(access) means that one
-connection per URI type will be opened.
-
-dit(bf(Retries))
-Number of retries to perform. If this is non-zero apt will retry failed 
-files the given number of times.
-
-dit(bf(Source-Symlinks))
-Use symlinks for source archives. If set to true then source archives will
-be symlinked when possible instead of copying. True is the default
-
-dit(bf(http))
-HTTP URIs; http::Proxy is the default http proxy to use. It is in the standard
-form of em(http://[[user][:pass]@]host[:port]/). Per host proxies can also
-be specified by using the form http::Proxy::<host> with the special keyword
-em(DIRECT) meaning to use no proxies. The em($http_proxy) environment variable
-will override all settings.
-
-Three settings are provided for cache control with HTTP/1.1 complient proxy
-caches. bf(No-Cache) tells the proxy to not used its cached response under
-any circumstances, bf(Max-Age) is sent only for index files and tells the
-cache to refresh its object if it is older than the given number of seconds. 
-Debian updates its index files daily so the default is 1 day. bf(No-Store) 
-specifies that the cache should never store this request, it is only
-set for archive files. This may be usefull to prevent polluting a proxy cache
-with very large .deb files. Note: Squid 2.0.2 does not support any of
-these options. 
-
-The option bf(timeout) sets the timeout timer used by the method, this
-applies to all things including connection timeout and data timeout.
-
-One setting is provided to control the pipeline depth in cases where the
-remote server is not RFC conforming or buggy (such as Squid 2.0.2)
-Acquire::http::Pipeline-Depth can be a value from 0 to 5 indicating how many
-outstanding requests APT should send.
-
-dit(bf(ftp))
-FTP URis; ftp::Proxy is the default proxy server to use. It is in the 
-standard form of em(ftp://[[user][:pass]@]host[:port]/) and is overriden
-by the ftp_proxy environment variable. To use a ftp proxy you will have to
-set the ftp::ProxyLogin script in the configuration file. This entry 
-specifies the commands to send to tell the proxy server what to connect
-to. Please see em(/usr/doc/apt/examples/configure-index) for an example of how 
-to do this. The subsitution variables available are $(PROXY_USER),
-$(PROXY_PASS), $(SITE_USER), $(SITE_PASS), $(SITE), and $(SITE_PORT). 
-Each is taken from it's respective URI component.
-
-The option bf(timeout) sets the timeout timer used by the method, this
-applies to all things including connection timeout and data timeout.
-
-Several settings are provided to control passive mode. Generally it is safe
-to leave passive mode on, it works in nearly every environment. However some
-situations require that passive mode be disabled and port mode ftp used
-instead. This can be done globally, for connections that go through a proxy
-or for a specific host (See the sample config file for examples)
-
-
-It is possible to proxy FTP over HTTP by setting the em(ftp_proxy)
-environment variable to a http url - see the discussion of the http method
-above for syntax. You cannot set this in the configuration file and it is
-not recommended to use FTP over HTTP due to its low efficiency.
-
-dit(bf(cdrom))
-CDROM URIs; the only setting for CDROM URIs is the mount point, cdrom::Mount
-which must be the mount point for the CDROM drive as specified in /etc/fstab.
-It is possible to provide alternate mount and unmount commands if your
-mount point cannot be listed in the fstab (such as an SMB mount). The syntax
-is to put "/cdrom/"::Mount "foo"; within the cdrom block. It is important to
-have the trailing slash. Unmount commands can be specified using UMount.
-
-enddit()
-
-manpagesection(Directories)
-The bf(Dir::State) section has directories that pertain to local state
-information. bf(lists) is the directory to place downloaded package lists
-in and bf(status) is the name of the dpkg status file. bf(Dir::State)
-contains the default directory to prefix on all sub items if they do not
-start with em(/) or em(./). bf(xstatus) and bf(userstatus) are for future
-use.
-
-bf(Dir::Cache) contains locations pertaining to local cache information, such
-as the two package caches bf(srcpkgcache) and bf(pkgcache) as well as the
-location to place downloaded archives, bf(Dir::Cache::archives). Like 
-bf(Dir::State) the default directory is contained in bf(Dir::Cache)
-
-bf(Dir::Etc) contains the location of configuration files, bf(sourcelist)
-gives the location of the sourcelist and bf(main) is the default configuration
-file (setting has no effect)
-
-Binary programs are pointed to by bf(Dir::Bin). bf(methods) specifies the
-location of the method handlers and bf(gzip), bf(dpkg), bf(apt-get), 
-bf(dpkg-source), bf(dpkg-buildpackage) and
-bf(apt-cache) specify the location of the respective programs.
-
-manpagesection(APT in DSelect)
-When APT is used as a bf(dselect(8)) method several configuration directives
-control the default behavoir. These are in the bf(DSelect) section.
-
-startdit()
-dit(bf(Clean))
-Cache Clean mode; this value may be one of always, auto, prompt and never.
-always will remove all archives after they have been downloaded while auto
-will only remove things that are no longer downloadable (replaced with a new
-version for instance)
-
-dit(bf(Options))
-The contents of this variable is passed to bf(apt-get(8)) as command line
-options when it is run for the install phase.
-
-dit(bf(UpdateOptions))
-The contents of this variable is passed to bf(apt-get(8)) as command line
-options when it is run for the update phase.
-
-dit(bf(PromptAfterUpdate))
-If true the [U]pdate operation in dselect will always prompt to continue. 
-The default is to prompt only on error.
-enddit()
-
-manpagesection(How APT calls DPkg)
-Several configuration directives control how APT invokes dpkg. These are in 
-the bf(DPkg) section.
-
-startdit()
-dit(bf(Options))
-This is a list of options to pass to dpkg. The options must be specified
-using the list notation and each list item is passed as a single arugment
-to dpkg.
-
-dit(bf(Pre-Invoke), bf(Post-Invoke))
-This is a list of shell commands to run before/after invoking dpkg. Like 
-bf(Options) this must be specified in list notation. The commands
-are invoked in order using /bin/sh, should any fail APT will abort.
-
-dit(bf(Pre-Install-Pkgs))
-This is a list of shell commands to run before invoking dpkg. Like
-bf(Options) this must be specified in list notation. The commands
-are invoked in order using /bin/sh, should any fail APT will abort.
-Apt will pass to the commands on standard input the filenames of all
-.deb files it is going to install, one per line.
-
-dit(bf(Run-Directory))
-APT chdirs to this directory before invoking dpkg, the default is /.
-
-dit(bf(Build-Options))
-These options are passed to dpkg-buildpackage when compiling packages,
-the default is to disable signing and produce all binaries.
-
-enddit()
-
-manpagesection(Debug Options)
-Most of the options in the bf(debug) section are not interesting to the
-normal user, however bf(Debug::pkgProblemResolver) shows interesting
-output about the decisions dist-upgrade makes. bf(Debug::NoLocking)
-disables file locking so apt can do some operations as non-root and
-bf(Debug::pkgDPkgPM) will print out the command line for each dpkg 
-invokation. bf(Debug::IdentCdrom) will disable the inclusion of statfs 
-data in CDROM IDs.
-
-manpagesection(EXAMPLES)
-bf(/usr/doc/apt/examples/configure-index.gz) contains a sample configuration 
-file showing the default values for all possible options.
-
-manpagesection(FILES)
-/etc/apt/apt.conf
-
-manpageseealso()
-apt-cache (8),
-apt-get (8)
-
-manpagebugs()
-See http://bugs.debian.org/apt.  If you wish to report a
-bug in bf(apt-get), please see bf(/usr/doc/debian/bug-reporting.txt)
-or the bf(bug(1)) command.
-
-manpageauthor()
-apt-get was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/apt.ent b/doc/apt.ent
new file mode 100644
index 000000000..fb1aa3c91
--- /dev/null
+++ b/doc/apt.ent
@@ -0,0 +1,159 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+
+<!-- Some common paths.. -->
+<!ENTITY docdir "/usr/share/doc/apt/">
+<!ENTITY configureindex "<filename>&docdir;/examples/configure-index</>">
+<!ENTITY aptconfdir "<filename>/etc/apt.conf</>">
+<!ENTITY statedir "/var/lib/apt">
+<!ENTITY cachedir "/var/cache/apt">
+
+<!-- Cross references to other man pages -->
+<!ENTITY apt-conf "
+  <CiteRefEntry>
+    <RefEntryTitle><filename/apt.conf/</RefEntryTitle>
+    <ManVolNum/5/
+  </CiteRefEntry>
+">
+
+<!ENTITY apt-get "
+  <CiteRefEntry>
+    <RefEntryTitle><command/apt-get/</RefEntryTitle>
+    <ManVolNum/8/
+  </CiteRefEntry>
+">
+
+<!ENTITY apt-cdrom "
+  <CiteRefEntry>
+    <RefEntryTitle><command/apt-cdrom/</RefEntryTitle>
+    <ManVolNum/8/
+  </CiteRefEntry>
+">
+
+<!ENTITY apt-cache "
+  <CiteRefEntry>
+    <RefEntryTitle><command/apt-cache/</RefEntryTitle>
+    <ManVolNum/8/
+  </CiteRefEntry>
+">
+
+<!ENTITY sources-list "
+  <CiteRefEntry>
+    <RefEntryTitle><filename/sources.list/</RefEntryTitle>
+    <ManVolNum/5/
+  </CiteRefEntry>
+">
+
+<!ENTITY bug "
+  <CiteRefEntry>
+    <RefEntryTitle><command/bug/</RefEntryTitle>
+    <ManVolNum/1/
+  </CiteRefEntry>
+">
+
+<!ENTITY dpkg "
+  <CiteRefEntry>
+    <RefEntryTitle><command/dpkg/</RefEntryTitle>
+    <ManVolNum/8/
+  </CiteRefEntry>
+">
+
+<!ENTITY dpkg-buildpackage "
+  <CiteRefEntry>
+    <RefEntryTitle><command/dpkg-buildpackage/</RefEntryTitle>
+    <ManVolNum/1/
+  </CiteRefEntry>
+">
+
+<!ENTITY gzip "
+  <CiteRefEntry>
+    <RefEntryTitle><command/gzip/</RefEntryTitle>
+    <ManVolNum/1/
+  </CiteRefEntry>
+">
+
+<!ENTITY dpkg-scanpackages "
+  <CiteRefEntry>
+    <RefEntryTitle><command/dpkg-scanpackages/</RefEntryTitle>
+    <ManVolNum/8/
+  </CiteRefEntry>
+">
+
+<!ENTITY dpkg-scansources "
+  <CiteRefEntry>
+    <RefEntryTitle><command/dpkg-scansources/</RefEntryTitle>
+    <ManVolNum/8/
+  </CiteRefEntry>
+">
+
+<!ENTITY dselect "
+  <CiteRefEntry>
+    <RefEntryTitle><command/dselect/</RefEntryTitle>
+    <ManVolNum/8/
+  </CiteRefEntry>
+">
+    
+<!-- Boiler plate docinfo section -->
+<!ENTITY apt-docinfo "
+ <docinfo>
+   <address><email>apt@packages.debian.org</></address>
+   <author><firstname>Jason</> <surname>Gunthorpe</></>
+   <copyright><year>1998-2000</> <holder>Jason Gunthorpe</></>
+   <date>20 September 2000</>
+ </docinfo>
+"> 
+
+<!-- Boiler plate Bug reporting section -->
+<!ENTITY manbugs "
+ <RefSect1><Title>Bugs</>
+   <para>
+   See the <ulink url='http://bugs.debian.org/apt'>APT bug page</>.  
+   If you wish to report a bug in APT, please see 
+   <filename>/usr/doc/debian/bug-reporting.txt</> or the &bug; command.
+ </RefSect1>
+">
+
+<!-- Boiler plate Author section -->
+<!ENTITY manauthor "
+ <RefSect1><Title>Author</>
+   <para>
+   APT was written by the APT team <email>apt@packages.debian.org</>.
+ </RefSect1>
+">
+
+<!-- Should be used within the option section of the text to
+     put in the blurb about -h, -v, -c and -o -->
+<!ENTITY apt-commonoptions "
+     <VarListEntry><term><option/-h/</><term><option/--help/</>
+     <ListItem><Para>
+     Show a short usage summary.
+     </VarListEntry>
+     
+     <VarListEntry><term><option/-v/</><term><option/--version/</>
+     <ListItem><Para>
+     Show the program verison.
+     </VarListEntry>
+
+     <VarListEntry><term><option/-c/</><term><option/--config-file/</>
+     <ListItem><Para>
+     Configuration File; Specify a configuration file to use. 
+     The program will read the default configuration file and then this 
+     configuration file. See &apt-conf; for syntax information.     
+     </VarListEntry>
+     
+     <VarListEntry><term><option/-o/</><term><option/--option/</>
+     <ListItem><Para>
+     Set a Configuration Option; This will set an arbitary configuration 
+     option. The syntax is <option>-o Foo::Bar=bar</>.
+     </VarListEntry>
+">
+
+<!-- Should be used within the option section of the text to
+     put in the blurb about -h, -v, -c and -o -->
+<!ENTITY apt-cmdblurb "
+   <para>
+   All command line options may be set using the configuration file, the
+   descriptions indicate the configuration option to set. For boolean
+   options you can override the config file by using something like 
+   <option/-f-/,<option/--no-f/, <option/-f=no/ or several other variations.
+   </para>
+">
diff --git a/doc/apt_preferences.5.sgml b/doc/apt_preferences.5.sgml
new file mode 100644
index 000000000..fdac01d37
--- /dev/null
+++ b/doc/apt_preferences.5.sgml
@@ -0,0 +1,227 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt_preferences</>
+   <manvolnum>5</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt_preferences</>
+    <refpurpose>Preference control file for APT</>
+ </refnamediv>
+ 
+ <RefSect1><Title>Description</>
+   <para>
+   The APT preferences file controls various aspects of the APT system. 
+   It is ment to be user editable and manipulatable from software. The file
+   consists of a number of records formed like the dpkg status file, space
+   seperated sections of text with at the start of each line tags seperated 
+   by a colon. It is stored in <filename>/etc/apt/preferences</>.
+ </RefSect1>
+
+ <RefSect1><Title>Versioning</>
+   <para>
+   One purpose of the preferences file is to let the user select which version
+   of a package will be installed. This selection can be made in a number of
+   ways that fall into three categories, version, release and origin.   
+   <para>
+   Selection by version can be done by exact match or prefix match. The format
+   is <literal/2.1.2/ or <literal/2.2*/ for a prefix match. Matching by prefix 
+   can be used to ignore the <literal/r/ in the Debian release versioning, like
+   <literal/2.1r*/ or to ignore Debian specific revisions, <literal/1.1-*/.
+   When matching versions with a prefix the highest matching version will
+   always be picked.
+   <para>
+   Selection by release is more complicated and has three forms. The primary
+   purpose of release selections is to identify a set of packages that match
+   a specific vendor, or release (ie Debian 2.1). The first two forms are 
+   shortcuts intended for quick command line use. If the first character of the
+   specification is a digit then it is considered to be a release version match, 
+   otherwise a release label match. Specifications which contain equals are
+   full release data matches and are a comma seperated list of one letter keys
+   followed by an equals then by the string. Examples:
+<informalexample><programlisting>
+v=2.1*,o=Debian,c=main
+l=Debian
+a=stable
+</programlisting></informalexample>   
+   <para>
+   The data for these matches are taken from the <filename/Release/ files
+   that APT downloads during an <literal/update/. The available keys are:
+   <VariableList>
+     <VarListEntry><term>a= Archive</term>
+     <ListItem><Para>
+     This is the common name we give our archives, such as <literal/stable/ or
+     <literal/unstable/. The special name <literal/now/ is used to designate
+     the set of packages that are currently installed.
+     </VarListEntry>
+     
+     <VarListEntry><term>c= Component</term>
+     <ListItem><Para>
+     Referes to the sub-component of the archive, <literal/main/, 
+     <literal/contrib/ etc. Component may be omitted if there are no 
+     components for this archive.
+     </VarListEntry>
+     
+     <VarListEntry><term>v= Version</term>
+     <ListItem><Para>
+     This is a version string with the same properties as in the Packages file.
+     It represents the release level of the archive. Typical Debian release
+     numbers look like <literal/2.1r2/ with the r designating the release of 
+     2.1. New releases are limited to security updates.
+     </VarListEntry>
+
+     <VarListEntry><term>o= Origin</term>
+     <ListItem><Para>
+     This specifies who is providing this archive. In the case of Debian the
+     string will read <literal/Debian/. Other providers may use their own 
+     string.
+     </VarListEntry>
+
+     <VarListEntry><term><term>l= Label</term>
+     <ListItem><Para>
+     This carries the encompassing name of the distribution. For Debian proper
+     this field reads <literal/Debian/. For derived distributions it should 
+     contain their proper name.
+     </VarListEntry>
+   </VariableList>   
+   <para>
+   The final selection method is by origin. This is simply the site name
+   of the originating package files. The empty string is used for file URIs.
+   <para>
+   Version selection, particularly the latter two methods, are used in may
+   different part of APT, not just the preferences file.
+ </RefSect1>
+ 
+ <RefSect1><Title>Candidate Version Policy</>
+   <para>
+   Interaly APT maintains a list of all available versions for all packages.
+   If you place multiple releases or vendors in your &sources-list; file then
+   these features are available. By default APT selects the highest version
+   from all automatic sources. Some sources, such as 
+   <filename>project/experimental</> are marked Not Automatic - these fall 
+   to the bottom of the selection pile.
+   <para>
+   When deciding what version to use APT assigns a priority to each available
+   version of the package. It then does two things, first it selects
+   the highest priorty version that is newer than the installed version of the 
+   package, then it selects the highest priority version that is older than
+   the installed version. Next, if the older versions have a priority greater
+   than 1000 they are compared with the priority of the upgrade set, the larger
+   becomes the selected result. Otherwise the downgrade versions are ignored
+   and the highest priority of the ugprade set is selected.
+   <para>
+   It is possible to think of the priorities in strata:
+   <VariableList>
+     <VarListEntry><term>1000 and up</term>
+     <ListItem><Para>
+     Downgradable priorities
+     </VarListEntry>
+     
+     <VarListEntry><term>1000</term>
+     <ListItem><Para>
+     The downgrade prevention barrier
+     </VarListEntry>
+     
+     <VarListEntry><term>100 to 1000</term>
+     <ListItem><Para>
+     Standard priorities. 990 is the priority set by the 
+     <option/--target-release / &apt-get; option. 989 is the start for auto
+     priorities and 500 are all the default package files.
+     </VarListEntry>
+     
+     <VarListEntry><term>100</term>
+     <ListItem><Para>
+     The currently installed version
+     </VarListEntry>
+
+     <VarListEntry><term>0 to 100</term>
+     <ListItem><Para>
+     Non automatic priorities. These are only used if the package
+     is not installed and there is no other version available.
+     </VarListEntry>
+
+     <VarListEntry><term>less than 0</term>
+     <ListItem><Para>
+     The version is never selected.
+     </VarListEntry>
+   </VariableList>   
+   <para>
+   Giving a pin a priority greater than 1000 will allow APT to downgrade
+   in order to get to that version.   
+   <para>
+   Each package may be pinned to a specific version and each Package file
+   has a priority for every package inside. The highest priority assigned
+   to a package is the one that is used.
+   <para>
+   A package pin looks like this:
+<informalexample><programlisting>
+Package: apt
+Pin: version 0.4.0
+Pin-Priority: 1001
+</programlisting></informalexample>   
+   The first line specifies the package, the second gives the Pin specification
+   and the last gives the priority of this pin. The first word of the pin
+   specification may be version, release or origin, the remainder of the field
+   is described in the Versioning sectin above.
+   <para>
+   A default pin is how the priorities of package files are set. Any number
+   of default pins may be specified, the first matching default will select
+   the priority of the package file. Only release or origin may be used in 
+   the Pin specification since they match Package files.
+<informalexample><programlisting>
+Package: *
+Pin: release v=2.1*
+Pin-Priority: 998
+</programlisting></informalexample>
+   <para>
+   If the Pin-Priorty field is omitted then the priority defaults to 989 for
+   both cases.
+   
+   <RefSect2><title>Interesting Effects</>
+   <para>
+   Due to the downgrade prevention barrier at priority 1000 it is possible
+   that a lower priority version  will be selected if the higher priority 
+   would casue a downgrade. For instance, if package foo has versions
+   <literal/1.2/, <literal/1.1/ and <literal/1.0/ installed, with 
+   <literal/1.1/ being the currently installed version and the priorities of 
+   each version being 900, 100 and 950 repectively the winning version will be 
+   <literal/1.2/.
+   <para>
+   In practice this is often desired. A user may use a default pin to
+   make the stable distribution the default and then use the 
+   <option/--target-dist/ option with &apt-get; to select newer versions
+   from unstable. The packages that have been upgraded to unstable will
+   continue to follow the versions that are available in unstable since
+   the stable versions now fall below the downgrade prevention barrier.
+   <para>
+   If this is not desired then a default pin should be used to make unstable
+   have a priority less than 100.
+   <para>
+   Users of 3rd party add ons such as Helix GNOME can use this mechanism to
+   force the usage of Helix packages, or force the usage of Debian packages
+   by setting the priority of that source sufficiently high. It is even
+   possible to mass downgrade from one set of packages to another by
+   using a priority larger than 1000.
+   </RefSect2>
+ </RefSect1>
+  
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-cache; &apt-conf;
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/cache.sgml b/doc/cache.sgml
index 6c2307579..7d2334761 100644
--- a/doc/cache.sgml
+++ b/doc/cache.sgml
@@ -4,7 +4,7 @@
 <title>APT Cache File Format</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: cache.sgml,v 1.7 1999/05/23 22:55:55 jgg Exp $</version>
+<version>$Id: cache.sgml,v 1.8 2001/02/20 07:03:17 jgg Exp $</version>
 
 <abstract>
 This document describes the complete implementation and format of the APT
@@ -140,11 +140,13 @@ This is the first item in the file.
       unsigned long VersionCount;
       unsigned long DependsCount;
       unsigned long PackageFileCount;
-      unsigned long MaxVerFileSize;
       
       // Offsets
       unsigned long FileList;              // PackageFile
       unsigned long StringList;            // StringItem
+      unsigned long VerSysName;            // StringTable
+      unsigned long Architecture;          // StringTable
+      unsigned long MaxVerFileSize;
       
       // Allocation pools
       struct
@@ -155,7 +157,7 @@ This is the first item in the file.
       } Pools[7];
 
       // Package name lookup
-      unsigned long HashTable[512];        // Package
+      unsigned long HashTable[2*1024];        // Package
    };
 </example>
 <taglist>
@@ -191,9 +193,15 @@ the client should refuse the load the file.
 <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. 
+PackageCount is especially useful for generating user state structures. 
 See Package::Id for more info.
 
+<tag>VerSysName<item>
+String representing the versiong system used for this cache
+
+<tag>Architecture<item>
+Architecture the cache was built against.
+
 <tag>MaxVerFileSize<item>
 The maximum size of a raw entry from the original Package file 
 (ie VerFile::Size) is stored here.
@@ -252,9 +260,7 @@ the Header->HashTable.
       // 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 
@@ -286,17 +292,10 @@ 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
+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.
@@ -334,7 +333,7 @@ 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. 
+Flags are some useful indicators of the package's state. 
 
 </taglist>
 
@@ -357,6 +356,8 @@ Header.FileList
       unsigned long Origin;          // Stringtable
       unsigned long Label;           // Stringtable
       unsigned long Architecture;    // Stringtable
+      unsigned long Site;            // Stringtable
+      unsigned long IndexType;       // Stringtable
       unsigned long Size;            
 
       // Linked list
@@ -381,6 +382,12 @@ Refers the the physical disk file that this PacakgeFile represents.
 This is the release information. Please see the files document for a 
 description of what the release information means.
 
+<tag>Site<item>
+The site the index file was fetched from.
+
+<tag>IndexType<item>
+A string indicating what sort of index file this is.
+
 <tag>Size<item>
 Size is provided as a simple check to ensure that the package file has not
 been altered.
@@ -622,7 +629,7 @@ this version.
 <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 
+like Section Name are are useful to have as unique tags. It is part of 
 a linked list based at Header::StringList.
 <example>
    struct StringItem
diff --git a/doc/examples/configure-index b/doc/examples/configure-index
index 30ab29219..78171c9ba 100644
--- a/doc/examples/configure-index
+++ b/doc/examples/configure-index
@@ -1,4 +1,4 @@
-// $Id: configure-index,v 1.2 2000/05/13 01:52:59 jgg Exp $
+// $Id: configure-index,v 1.3 2001/02/20 07:03:17 jgg Exp $
 /* This file is an index of all APT configuration directives. It should
    NOT actually be used as a real config file, though it is a completely
    valid file. Most of the options have sane default values, unless
@@ -32,15 +32,15 @@ APT
      Fix-Broken "false";  
      Fix-Missing "false";     
      Show-Upgraded "false";
-     No-Upgrade "false";
+     Upgrade "true";
      Print-URIs "false";
      Compile "false";
-     No-Download "false";
+     Download "true";
      Purge "false";
      List-Cleanup "true";
      ReInstall "false";
      Trivial-Only "false";
-     No-Remove "false";
+     Remove "true";
   };
 
   Cache 
@@ -48,6 +48,7 @@ APT
      Important "false";
      AllVersions "false";
      GivenOnly "false";
+     RecruseDepends "false";
   };
 
   CDROM 
@@ -125,10 +126,10 @@ Acquire
 };
 
 // Directory layout
-Dir 
+Dir "/"
 {
   // Location of the state dir
-  State "/var/state/apt/" 
+  State "var/lib/apt/" 
   {
      lists "lists/";
      xstatus "xstatus";
@@ -138,16 +139,17 @@ Dir
   };
   
   // Location of the cache dir
-  Cache "/var/cache/apt/" {
+  Cache "var/cache/apt/" {
      archives "archives/";
      srcpkgcache "srcpkgcache.bin";
      pkgcache "pkgcache.bin";     
   };
   
   // Config files
-  Etc "/etc/apt/" {
+  Etc "etc/apt/" {
      sourcelist "sources.list";
      main "apt.conf";
+     preferences "preferences";     
   };
   
   // Locations of binaries
@@ -169,6 +171,7 @@ DSelect
    Options "-f";
    UpdateOptions "";
    PromptAfterUpdate "no";
+   CheckDir "no";
 }
 
 DPkg 
@@ -201,6 +204,7 @@ Debug
   pkgAcquire "false";
   pkgAcquire::Worker "false";
   pkgDPkgPM "false";
+  pkgOrderList "false";
   
   pkgInitialize "false";   // This one will dump the configuration space
   NoLocking "false";
diff --git a/doc/examples/ftp-archive.conf b/doc/examples/ftp-archive.conf
new file mode 100644
index 000000000..a1866ba2d
--- /dev/null
+++ b/doc/examples/ftp-archive.conf
@@ -0,0 +1,81 @@
+/* This configuration file describes the standard Debian distribution
+   as it once looked */
+   
+Dir 
+{
+   ArchiveDir "/org/ftp.debian.org/ftp/";
+   OverrideDir "/org/ftp.debian.org/scripts/override/";
+   CacheDir "/org/ftp.debian.org/scripts/cache/";
+};
+
+Default
+{
+   Packages::Compress ". gzip";
+   Sources::Compress "gzip";
+   Contents::Compress "gzip";
+   DeLinkLimit 10000;          // 10 Meg delink per day
+   MaxContentsChage 10000;     // 10 Meg of new contents files per day
+};
+
+TreeDefault
+{
+   Contents::Header "/org/ftp.debian.org/scripts/masterfiles/Contents.top";
+   BinCacheDB "packages-$(ARCH).db";
+   
+   // These are all defaults and are provided for completeness
+   Directory "$(DIST)/$(SECTION)/binary-$(ARCH)/";
+   Packages "$(DIST)/$(SECTION)/binary-$(ARCH)/Packages";
+   
+   SrcDirectory "$(DIST)/$(SECTION)/source/";
+   Sources "$(DIST)/$(SECTION)/source/Sources";
+   
+   Contents "$(DIST)/Contents-$(ARCH)";   
+};
+
+tree "dists/woody"
+{
+   Sections "main contrib non-free";
+   Architectures "alpha arm hurd-i386 i386 m68k powerpc sparc sparc64 source";
+   BinOverride "override.woody.$(SECTION)";
+   SrcOverride "override.woody.$(SECTION).src";
+};
+
+tree "dists/potato"
+{
+   Sections "main contrib non-free";
+   Architectures "alpha arm i386 m68k powerpc sparc source";
+   BinOverride "override.potato.$(SECTION)";
+   SrcOverride "override.woody.$(SECTION).src";
+};
+
+tree "dists/slink"
+{
+   Sections "main contrib non-free";
+   Architectures "alpha i386 m68k sparc source";
+   BinOverride "override.slink.$(SECTION)";
+   SrcOverride "override.woody.$(SECTION).src";
+   External-Links false;             // Slink should contain no links outside itself
+};
+
+
+bindirectory "project/experimental"
+{
+   Sources "project/experimental/Sources";
+   Packages "project/experimental/Packages";
+   
+   BinOverride "override.experimental";
+   BinCacheDB "packages-experimental.db";
+   SrcOverride "override.experimental.src";
+};
+
+bindirectory "dists/proposed-updates"
+{
+   Packages "project/proposed-updates/Packages";
+   Contents "project/proposed-updates/Contents";
+   
+   BinOverride "override.slink.all3";
+   BinOverride "override.slink.all3.src";
+   BinCacheDB "packages-proposed-updates.db";
+};
+
+   
diff --git a/doc/examples/sources.list b/doc/examples/sources.list
index ed5ad75ea..9f2343277 100644
--- a/doc/examples/sources.list
+++ b/doc/examples/sources.list
@@ -7,4 +7,4 @@ deb http://security.debian.org stable/updates main contrib non-free
 
 # Uncomment if you want the apt-get source function to work
 #deb-src http://http.us.debian.org/debian stable main contrib non-free
-#deb-src http://non-us.debian.org/debian-non-US stable non-US
+#deb-src http://non-us.debian.org/debian-non-US stable/non-US main contrib non-free
diff --git a/doc/files.sgml b/doc/files.sgml
index 2b68cf9bc..6a9f3ed27 100644
--- a/doc/files.sgml
+++ b/doc/files.sgml
@@ -4,7 +4,7 @@
 <title>APT Files</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: files.sgml,v 1.7 1999/02/15 06:38:03 jgg Exp $</version>
+<version>$Id: files.sgml,v 1.8 2001/02/20 07:03:17 jgg Exp $</version>
 
 <abstract>
 This document describes the complete implementation and format of the 
@@ -41,7 +41,7 @@ multiple package files.
 <p>
 The var directory structure is as follows:
 <example>
-  /var/state/apt/
+  /var/lib/apt/
 		  lists/
 		       partial/
 		  xstatus
@@ -66,7 +66,7 @@ The var directory structure is as follows:
 </example>
 
 <p>
-As is specified in the FHS 2.0 /var/state/apt is used for application 
+As is specified in the FHS 2.1 /var/lib/apt is used for application 
 data that is not expected to be user modified. /var/cache/apt is used
 for regeneratable data and is where the package cache and downloaded .debs
 go.
@@ -156,7 +156,7 @@ URIs in the source list support a large number of access schemes.
 
 <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 
+   considered as a debian archive. This is useful for NFS mounts and 
    local mirrors/archives.
    <example>
    file:/var/debian
@@ -183,10 +183,10 @@ 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
+/var/lib/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
+/var/lib/apt/info/Debian%201.3_debian_Packages
 </example>
 
 <p> 
diff --git a/doc/guide.it.sgml b/doc/guide.it.sgml
new file mode 100644
index 000000000..e251fe053
--- /dev/null
+++ b/doc/guide.it.sgml
@@ -0,0 +1,585 @@
+<!doctype debiandoc system>
+<!-- -*- mode: sgml; mode: fold -*- -->
+<book>
+<title>Guida dell'utente di APT</title>
+
+<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
+<author>Traduzione di Eugenia Franzoni <email>eugenia@linuxcare.com</email>
+</author>
+<version>$Id: guide.it.sgml,v 1.2 2001/02/20 07:03:17 jgg Exp $</version>
+
+<abstract>
+Guida per l'uso del gestore di pacchetti APT.
+</abstract>
+
+<copyright>
+Copyright &copy; Jason Gunthorpe, 1998.
+
+<p>Ed. italiana Copyright &copy; Eugenia Franzoni, 2000.
+
+<p>
+"APT" e questo documento sono software libero, e li si pu� ridistribuire 
+e/o modificare secondo i termini della Licenza Pubblica Generica GNU
+(GPL), pubblicata dalla Free Software Foundation, nella versione 2 o
+(se preferite) qualsiasi versione successiva.
+
+<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>
+Per ulteriori dettagli sui sistemi GNU/Linux si veda il testo
+completo della licenza nel file
+/usr/doc/copyright/GPL.
+</copyright>
+
+<toc sect>
+
+<!-- General		                                               {{{ -->
+<!-- ===================================================================== -->
+<chapt>Descrizione generale
+
+<p>
+Il pacchetto APT al momento contiene due sezioni, il metodo APT 
+<prgn>dselect</> e l'interfaccia utente a linea di comando <prgn>apt-get</>;
+entrambi danno modo di installare e rimuovere pacchetti, e di scaricarne
+altri da Internet.
+
+<sect>Anatomia del sistema di pacchettizzazione
+<p>
+Il sistema di pacchettizzazione di Debian contiene un gran numero di
+informazioni associate a ciascun pacchetto, per assicurarsi che si
+integri facilmente ed in maniera pulita nel sistema; la pi�
+importante di esse � il sistema di dipendenze.
+
+<p>
+Il sistema di dipendenze permette ai singoli programmi di fare uso
+degli elementi condivisi del sistema, quali le librerie; per 
+ridurre il numero di elementi che l'utente medio debba installare,
+le porzioni di programmi che non vengono usate spesso vengono poste
+in pacchetti separati. Inoltre, � possibile avere pi� di una scelta per
+cose quali i programmi di posta elettronica, i server X e cos� via.
+
+<p>
+Il primo passo per capire il sistema di dipendenze � la 
+comprensione del concetto di dipendenza semplice: un pacchetto richiede
+che un altro sia installato insieme ad esso per poter
+funzionare.
+
+
+<p>
+Ad esempio, mail-crypt � un'estensione di emacs che aiuta a criptare le
+mail con PGP. Se PGP non � installato, mail-crypt � inutile, quindi
+mail-crypt ha una dipendenza semplice da PGP. Inoltre, dato che si tratta
+di un'estensione di emacs, mail-crypt dipende anche da emacs, senza il
+quale � totalmente inutile.
+
+<p>
+L'altro tipo di dipendenza importante da capire � la dipendenza di
+conflitto; con questa, un pacchetto che venga installato insieme ad un
+altro pacchetto non funziona, e si hanno seri problemi al sistema.
+Come esempio, si consideri un programma di trasporto della posta,
+quale sendmail, exim o qmail: non � possibile averne due contemporaneamente,
+perch� entrambi hanno bisogno di restare in ascolto sulla stessa porta di rete 
+per ricevere la posta. Tentare di installarne due danneggerebbe seriamente il
+sistema, quindi ciascun programma di trasporto della posta ha una
+dipendenza di conflitto con tutti gli altri.
+
+<p>
+Come ulteriore complicazione, c'� la possibilit� che un pacchetto
+voglia prendere il posto di un altro; ad esempio, exim e sendmail per molte
+cose sono identici, dato che entrambi gestiscono la posta e comprendono
+un'interfaccia comune, quindi il sistema di pacchettizzazione deve dichiarare
+che sono entrambi agenti di trasporto della posta, e che gli altri
+pacchetti a cui serve uno dei due devono dipendere da un pacchetto
+fittizio agente-di-trasporto-della-posta. Quando si modificano
+a mano i pacchetti, questo pu� portare a moltissima confusione.
+
+<p>
+In ciascun momento una singola dipendenza pu� essere soddisfatta o meno
+dai pacchetti gi� installati; APT cerca di risolvere i problemi
+di dipendenze con un buon numero di algoritmi automatici, che aiutano
+a selezionare i pacchetti da installare.
+</sect>
+
+</chapt>
+                                                                  <!-- }}} -->
+<!-- apt-get		                                               {{{ -->
+<!-- ===================================================================== -->
+<chapt>apt-get
+
+<p>
+<prgn>apt-get</> fornisce un modo semplice di installare i pacchetti dalla
+linea di comando. Diversamente da <prgn>dpkg</>, <prgn>apt-get</> non 
+capisce i nomi dei file .deb, ma utilizza il vero nome dei pacchetti,
+e pu� installare archivi .deb solo da una fonte.
+
+<p>
+La prima <footnote>Se state usando un proxy server http, dovete prima ancora
+impostare la variabile d'ambiente http_proxy; vedere 
+sources.list(5).</footnote>
+cosa da fare prima di usare <prgn>apt-get</> � impostare l'elenco dei
+pacchetti dalle fonti in modo che il programma sappia quali pacchetti
+sono disponibili. Lo si fa con <tt>apt-get update</>. Ad esempio,
+
+<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
+Reading Package Lists... Done
+Building Dependency Tree... Done
+</example>
+
+<p>
+Dopo aver aggiornato l'elenco si possono usare molti comandi:
+<taglist>
+<tag>upgrade<item>
+Upgrade tenter� di fare un aggiornamento indolore del sistema completo,
+senza installare nuovi pacchetti o rimuoverne di esistenti, e senza
+aggiornare un pacchetto che possa rovinarne altri. Upgrade far� un elenco
+di tutti i pacchetti che non avr� potuto aggiornare, cosa che in genere
+significa che questi dipendono da nuovi pacchetti o vanno in conflitto
+con altri. Per forzare la loro installazione si pu� usare 
+<prgn>dselect</> o <tt>apt-get install</>.
+
+<tag>install<item>
+Install viene usato per installare i singoli pacchetti dando il loro nome. 
+Il pacchetto viene automaticamente scaricato ed installato, cosa molto utile
+se gi� se ne conosce il nome e non si vuole entrare in grafica per 
+selezionarlo. Al comando si possono passare anche pi� pacchetti, che saranno
+tutti scaricati. L'installazione automatica cerca di risolvere i problemi
+di dipendenze con gli altri pacchetti elencati, stampa un riassunto e
+chiede conferma se si devono modificare altri pacchetti che non siano quelli
+sulla linea di comando.
+
+<tag>dist-upgrade<item>
+Dist-upgrade fa un aggiornamento completo, progettato in modo da rendere 
+semplici gli aggiornamenti tra versioni di Debian. Usa un algoritmo 
+sofisticato per determinare il miglior insieme di pacchetti da installare,
+aggiornare e rimuovere per arrivare alla versione pi� aggiornata
+del sistema possibile. In alcune situazioni pu� essere vantaggioso usare
+dist-upgrade invece che sprecare tempo a risolvere manualmente le 
+dipendenze con <prgn>dselect</>. Una volta completato dist-upgrade, si pu�
+usare <prgn>dselect</> per installare eventuali pacchetti che sono stati
+tralasciati.
+
+<p>
+� importante controllare attentamente cosa intende fare dist-upgrade,
+dato che le sue decisioni a volte possono essere abbastanza sorprendenti.
+</taglist>
+
+<p>
+<prgn>apt-get</> ha diverse opzioni a linea di comando, che vengono 
+documentate dettagliatamente nella sua pagina man, 
+<manref name="apt-get" section="8">. L'opzione pi� utile � 
+<tt>-d</>, che non installa i file scaricati: se il sistema deve
+scaricare un gran numero di pacchetti, non � bene farglieli installare
+subito, in caso dovesse andare male qualcosa. Dopo aver usato <tt>-d</>,
+gli archivi scaricati possono essere installati semplicemente dando di
+nuovo lo stesso comando senza l'opzione <tt>-d</>.
+
+</chapt>
+                                                                  <!-- }}} -->
+<!-- DSelect		                                               {{{ -->
+<!-- ===================================================================== -->
+<chapt>DSelect
+<p>
+Il metodo APT di <prgn>dselect</> fornisce tutte le funzionalit� di APT
+all'interno dell'interfaccia grafica di selezione dei pacchetti 
+<prgn>dselect</>. <prgn>dselect</> viene usato per selezionare i pacchetti
+da installare o rimuovere, ed APT li installa.
+
+<p>
+Per abilitare il metodo APT dovete selezionare [A]ccess in <prgn>dselect</> 
+e scegliere il metodo APT; vi verr� chiesto un insieme di fonti
+(<em>Sources</>), cio� di posti da cui scaricare gli archivi.
+Tali fonti possono essere siti Internet remoti, mirror locali di Debian
+o CDROM; ciascuna di esse pu� fornire una parte dell'archivio Debian,
+ed APT le combiner� insieme in un set completo di pacchetti. Se avete un
+CDROM � una buona idea indicare quello per primo, e poi i mirror, in modo
+da avere accesso alle ultime versioni; APT user� in questo modo automaticamente
+i pacchetti sul CDROM prima di scaricarli da 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>
+La configurazione delle fonti inizia chiedendo la base dell'archivio Debian,
+propone come default un mirror HTTP, e poi chiede la distribuzione
+da scaricare.
+
+<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>
+La distribuzione (``distribution'') fa riferimento alla versione Debian
+dell'archivio: <em>stable</> � l'ultima rilasciata, ed <em>unstable</> 
+� quella di sviluppo. <em>non-US</> � disponibile solo su alcuni mirror,
+e contiene dei pacchetti in cui viene usata della tecnologia di criptazione
+o altre cose che non possano essere esportate dagli Stati Uniti; importare
+questi pacchetti negli US � per� legale.
+
+<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>
+L'elenco dei componenti (``components'') si riferisce alla lista di
+sotto-distribuzioni da scaricare. Ciascuna distribuzione viene divisa in
+base al copyright del software: la main contiene pacchetti la cui licenza
+soddisfa le DFSG, mentre contrib e non-free contengono software che ha
+diverse restrizioni sull'uso e sulla distribuzione.
+
+<p>
+Si possono inserire un qualsiasi numero di fonti, e lo script di 
+configurazione continuer� a chiedere fino a che abbiate specificato tutti gli
+elementi che volete.
+
+<p>
+Prima di cominciare ad usare <prgn>dselect</> � necessario aggiornare 
+l'elenco dei pacchetti disponibili selezionando [U]pdate dal men�:
+si tratta di un sovrainsieme di ci� che fa <tt>apt-get update</>,
+che rende l'informazione scaricata disponibile a
+<prgn>dselect</>. [U]pdate deve essere fatto anche se prima � stato dato 
+<tt>apt-get update</>.
+
+<p>
+Si pu� a questo punto continuare selezionando i pacchetti desiderati
+usando [S]elect e poi installando con [I]nstall. Se si usa il metodo APT,
+i comandi [C]onfig e [R]emove non hanno significato, dato che entrambe le
+fasi sono contenute in [I]nstall.
+
+<p>
+Per default APT rimuover� automaticamente i pacchetti che sono stati installati
+con successo. Per modificare questo comportamento, si inserisca 
+<tt>Dselect::clean "prompt";</> in /etc/apt/apt.conf.
+
+</chapt>
+                                                                  <!-- }}} -->
+<!-- The Interfaces						       {{{ -->
+<!-- ===================================================================== -->
+<chapt>L'interfaccia
+
+<p>
+Entrambi i metodi,  <prgn>dselect</> APT ed <prgn>apt-get</>, condividono la
+stessa interfaccia; si tratta di un sistema semplice che indica in genere
+cosa sta per fare, e poi lo fa.
+<footnote>
+Il metodo <prgn>dselect</> � in realt� un insieme di script di wrapper ad
+<prgn>apt-get</>. Il metodo fornisce delle funzionalit� maggiori del
+solo <prgn>apt-get</>.
+</footnote>
+Dopo la stampa di un riassunto delle operazioni che saranno fatte,
+APT stampa dei messaggi informativi sullo stato del sistema, in modo che
+possiate avere davanti agli occhi a quale punto dell'operazione si trova,
+e quanto ancora si deve aspettare.
+
+<!-- ===================================================================== -->
+<sect>Avvio
+
+<p>
+Prima di ciascuna operazione, eccetto l'aggiornamento della lista, APT
+compie alcune operazioni per prepararsi, oltre a dei controlli dello
+stato del sistema. In qualsiasi momento le stesse operazioni possono essere
+fatte con <tt>apt-get check</>
+<p>
+<example>
+# apt-get check
+Reading Package Lists... Done
+Building Dependancy Tree... Done
+</example>
+
+<p>
+La prima cosa che fa � leggere tutti i file dei pacchetti in memoria,
+usando uno schema di caching in modo da rendere la stessa operazione pi�
+veloce la seconda volta che la si fa. Se alcuni dei file dei pacchetti
+non vengono trovati, sono ignorati e viene stampato un avvertimento
+all'uscita di apt-get.
+
+<p>
+L'operazione finale consiste in un'analisi dettagliata delle
+dipendenze del sistema: viene controllato che tutte le dipendenze dei
+singoli pacchetti installati o non scompattati siano soddisfatte.
+Se vengono individuati dei problemi, viene stampato un resoconto,
+ed <prgn>apt-get</> esce senza eseguire alcuna operazione.
+
+<p>
+<example>
+# apt-get check
+Reading Package Lists... Done
+Building Dependancy Tree... Done
+You might want to run apt-get -f install' to correct these.
+Sorry, but the following packages have unmet dependencies:
+  9fonts: Depends: xlib6g but it is not installed
+  uucp: Depends: mailx but it is not installed
+  blast: Depends: xlib6g (>= 3.3-5) but it is not installed
+  adduser: Depends: perl-base but it is not installed
+  aumix: Depends: libgpmg1 but it is not installed
+  debiandoc-sgml: Depends: sgml-base but it is not installed
+  bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed
+  cthugha: Depends: svgalibg1 but it is not installed
+           Depends: xlib6g (>= 3.3-5) but it is not installed
+  libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)
+</example>
+
+<p>
+In questo esempio il sistema ha molti problemi, tra cui uno piuttosto serio
+con la libreadlineg2. Per ciascun pacchetto che ha dipendenze non soddisfatte,
+viene stampata una linea che indica il pacchetto che crea il problema e
+quali problemi ci sono. Viene inclusa inoltre una breve spiegazione
+del perch� il pacchetto ha un problema di dipendenze.
+
+<p>
+Ci sono due modi in cui un sistema possa arrivare in uno stato problematico
+di questo genere: il primo � causato dal fatto che <prgn>dpkg</> possa
+mancare alcune relazioni sottili tra pacchetti durante un aggiornamento
+del sistema<footnote>APT considera comunque tutte le dipendenze note,
+e cerca di prevenire problemi ai pacchetti</footnote>; il secondo � possibile
+se l'installazione di un pacchetto fallisce, ed in questo caso � possibile
+che un pacchetto venga scompattato senza che tutti quelli da cui dipende
+siano stati installati.
+
+<p>
+La seconda possibilit� � meno seria della prima, dato che APT gestisce
+l'ordine di installazione dei pacchetti; in entrambi i casi l'opzione
+<tt>-f</> di <prgn>apt-get</> gli far� trovare una soluzione e lo far�
+continuare. Il metodo APT di <prgn>dselect</> comprende sempre l'opzione 
+<tt>-f</> per permettere di configurare facilmente anche i pacchetti con
+script errati.
+
+<p>
+Se viene usata per� l'opzione <tt>-f</> per correggere un sistema in uno
+stato molto problematico, � possibile che anche con l'opzione il programma
+fallisca, subito o durante la sequenza di installazione. In entrambi i casi
+� necessario usare dpkg a mano (probabilmente usando delle opzioni
+di forzatura) per correggere quanto basta per poter fare continuare APT.
+</sect>
+
+<!-- ===================================================================== -->
+<sect>Il resoconto sullo stato
+
+<p>
+Prima di procedere,  <prgn>apt-get</> presenter� un resoconto delle operazioni
+che sta per fare. In genere tale resoconto varier� con il tipo di operazioni
+da fare, ma ci sono alcuni elementi comuni: in tutti i casi gli elenchi 
+dipendono dallo stato finale delle cose, e tengono conto dell'opzione 
+<tt>-f</> e di altre attivit� rilevanti per il comando da eseguire.
+
+<sect1>L'elenco dei pacchetti Extra
+<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>
+L'elenco dei pacchetti Extra mostra tutti i pacchetti che verranno installati
+o aggiornati oltre a quelli indicati sulla linea di comando. Viene generato
+solo per il comando <tt>install</>. I pacchetti elencati sono spesso il
+risultato di un'operazione di auto installazione (Auto Install).
+</sect1>
+
+<sect1>I pacchetti da rimuovere
+<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>
+L'elenco dei pacchetti da rimuovere (Remove) indica tutti i pacchetti che
+verranno rimossi dal sistema. Pu� essere mostrato per una qualsiasi delle
+operazioni, e deve sempre essere esaminato attentamente per assicurarsi
+che non venga eliminato qualcosa di importante. Con l'opzione <tt>-f</>
+� particolarmente probabile che vengano eliminati dei pacchetti, ed in questo
+caso va fatta estrema attenzione. La lista pu� contenere dei pacchetti
+che verranno rimossi perch� sono gi� rimossi parzialmente, forse a causa
+di un'installazione non terminata correttamente.
+</sect1>
+
+<sect1>L'elenco dei nuovi pacchetti installati
+<p>
+<example>
+The following NEW packages will installed:
+  zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
+</example>
+
+<p>
+L'elenco dei nuovi pacchetti installati (New) � semplicemente un appunto
+su quello che accadr�. I pacchetti nell'elenco non sono al momento installati
+nel sistema, ma lo saranno alla fine delle operazioni di APT.
+</sect1>
+
+<sect1>L'elenco dei pacchetti trattenuti
+<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>
+In ogni caso in cui il sistema viene aggiornato nel suo insieme, c'� la
+possibilit� che non possano venire installate nuove versioni di alcuni 
+pacchetti, dato che potrebbero richiedere l'installazione di pacchetti non
+presenti nel sistema, o entrare in conflitto con altri gi� presenti. 
+In questo caso, il pacchetto viene elencato nella lista di quelli
+trattenuti (Kept Back). Il miglior modo per convincere i pacchetti 
+elencati in questa lista � di installarli con <tt>apt-get install</> o 
+usare <prgn>dselect</> per risolvere i problemi.
+</sect1>
+
+<sect1>Messaggi di attenzione sui pacchetti trattenuti
+<p>
+<example>
+The following held packages will be changed:
+  cvs 
+</example>
+
+<p>
+A volte si pu� richiedere ad APT di installare un pacchetto
+che � stato trattenuto; in questi casi viene stampato un messaggio di
+attenzione, che avverte che il pacchetto verr� modificato. Questo 
+dovrebbe accadere solo durante operazioni di dist-upgrade o di install.
+</sect1>
+
+<sect1>Resoconto finale
+<p>
+Infine, APT stamper� un riassunto di tutte le modifiche che accadranno.
+
+<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>
+La prima linea del riassunto � semplicemente una versione ridotta di tutte
+le liste, ed include il numero di aggiornamenti -- cio� dei pacchetti
+gi� installati per cui sono disponibili nuove versioni. La seconda
+linea indica il numero di pacchetti con problemi di configurazione,
+probabilmente in conseguenza di un'installazione non andata a buon fine.
+La linea finale indica i requisiti di spazio dell'installazione: i primi
+due numeri indicano rispettivamente il numero di byte che devono
+essere trasferiti da posizioni remote, ed il secondo la dimensione totale
+di tutti gli archivi necessari per l'installazione. Il numero successivo
+indica la differenza in dimensione tra i pacchetti gi� installati
+e quelli che lo saranno, ed � approssimativamente equivalente allo spazio
+richiesto in /usr dopo l'installazione. Se si stanno rimuovendo dei
+pacchetti, il valore pu� indicare lo spazio che verr� liberato.
+
+<p>
+Si possono generare altri resoconti usando l'opzione -u per mostrare
+i pacchetti da aggiornare, ma sono simili all'esempio precedente.
+</sect>
+
+<!-- ===================================================================== -->
+<sect>La visualizzazione dello stato
+<p>
+Durante il download degli archivi e dei file dei pacchetti, APT
+stampa una serie di messaggi di stato.
+
+<p>
+<example>
+# apt-get update
+Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages
+Get:2 http://llug.sep.bnl.gov/debian/ frozen/contrib Packages
+Hit http://llug.sep.bnl.gov/debian/ frozen/main Packages
+Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
+Get:5 http://llug.sep.bnl.gov/debian/ frozen/non-free Packages
+11% [5 frozen/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
+</example>
+
+<p>
+Le linee che cominciano con <em>Get</> vengono stampate quando APT inizia
+a scaricare un file, e l'ultima linea indica il progresso dell'operazione.
+Il primo valore in percentuale indica la percentuale totale di tutti i file;
+dato che la dimensione dei file Package non � nota, purtroppo a volte
+<tt>apt-get update</> fa una stima poco accurata.
+
+<p>
+La sezione successiva della linea di stato viene ripetuta una volta per 
+ciascuna fase del download, ed indica l'operazione in corso, insieme
+ad alcune informazioni utili su cosa stia accadendo. A volte questa
+sezione contiene solamente <em>Forking</>, che significa che il sistema
+operativo sta caricando il modulo. La prima parola dopo la parentesi quadra
+aperta � il nome breve dell'oggetto che si sta scaricando, che per gli archivi 
+� il nome del pacchetto.
+
+<p>
+All'interno delle virgolette c'� una stringa informativa, che indica il 
+progresso della fase di negoziazione del download. Tipicamente comincia con
+<em>Connecting</>, procede con <em>Waiting for file</> e poi con 
+<em>Downloading</> o <em>Resuming</>. Il valore finale � il numero di byte 
+che sono stati scaricati dal sito remoto: una volta cominciato il 
+download viene rappresentato come <tt>102/10.2k</>, che indica che
+sono stati scaricati 102 byte di 10.2 kilobyte. La dimensione totale
+viene sempre espressa in notazione a quattro cifre, per risparmiare 
+spazio. Dopo la dimensione viene indicato un indicatore
+progressivo della percentuale del file. Il penultimo elemento � la velocit�
+istantanea media, che viene aggiornata ogni 5 secondi, e riflette la
+velocit� di trasferimento dei dati in quel periodo. Infine, viene 
+visualizzato il tempo stimato per il trasferimento, che viene aggiornato
+periodicamente e riflette il tempo necessario per completare tutte le
+operazioni alla velocit� di trasferimento mostrata.
+
+<p> 
+La visualizzazione dello stato viene aggiornata ogni mezzo secondo per
+fornire un feedback costante del processo di download, e le linee Get
+scorrono indietro quando viene cominciato il download di un nuovo file.
+Dato che la visualizzazione dello stato viene costantemente
+aggiornata, non � adatta per essere registrata in un file; per non 
+visualizzarla si pu� usare l'opzione <tt>-q</>.
+</sect>
+
+<!-- ===================================================================== -->
+<sect>Dpkg
+
+<p>
+APT usa <prgn>dpkg</> per installare gli archivi e passer� all'interfaccia
+<prgn>dpkg</> una volta finito il download. 
+<prgn>dpkg</> porr� anche alcune domande durante la manipolazione dei
+pacchetti, ed i pacchetti stessi 
+potranno farne altre. Prima di ciascuna domanda viene
+proposta una descrizione di quello che sta per chiedere, e le domande
+sono troppo diverse per poter essere discusse in maniera completa in questa
+occasione.
+</sect>
+
+</chapt>
+                                                                  <!-- }}} -->
+
+</book>
diff --git a/doc/guide.sgml b/doc/guide.sgml
index 67efbc93f..1d6923aad 100644
--- a/doc/guide.sgml
+++ b/doc/guide.sgml
@@ -4,7 +4,7 @@
 <title>APT User's Guide</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: guide.sgml,v 1.2 1998/11/23 01:15:59 jgg Exp $</version>
+<version>$Id: guide.sgml,v 1.3 2001/02/20 07:03:17 jgg Exp $</version>
 
 <abstract>
 This document provides an overview of how to use the the APT package manager.
@@ -55,9 +55,9 @@ 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 
+For instance, mailcrypt is an emacs extension that aids in encrypting email
+with GPG. Without GPGP installed mail-crypt is useless, so mailcrypt has a
+simple dependency on GPG. Also, because it is an emacs extension it has a 
 simple dependency on emacs, without emacs it is completely useless.
 
 <p>
@@ -280,7 +280,7 @@ how much is left to do.
 <p>
 Before all operations, except update, APT performs a number of actions to
 prepare its internal state. It also does some checks of the systems state.
-At any time these operations can be performed by running <tt>apt-get chec</>
+At any time these operations can be performed by running <tt>apt-get check</>.
 <p>
 <example>
 # apt-get check
@@ -295,7 +295,7 @@ is run. If some of the package files are not found then they will be ignored
 and a warning will be printed when apt-get exits. 
 
 <p>
-The final operation performs a detailed analysis of the systems dependencies. 
+The final operation performs a detailed analysis of the system's dependencies.
 It checks every dependency of every installed or unpacked package and considers
 if it is ok. Should this find a problem then a report will be printed out and
 <prgn>apt-get</> will refuse to run.
@@ -328,7 +328,7 @@ problem is also included.
 
 <p>
 There are two ways a system can get into a broken state like this. The
-first is caused by <prgn>dpkg missing</> some subtle relationships between 
+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 
@@ -337,7 +337,7 @@ 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
+supplying the <tt>-f</> option to <prgn>apt-get</> will cause APT to deduce a
 possible solution to the problem and then continue on. The APT <prgn>dselect</> 
 method always supplies the <tt>-f</> option to allow for easy continuation
 of failed maintainer scripts.
@@ -476,7 +476,7 @@ to upgrade, they are similar to the previous examples.
 <sect>The Status Display
 <p>
 During the download of archives and package files APT prints out a series of
-status messages,
+status messages.
 
 <p>
 <example>
@@ -499,7 +499,7 @@ 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
+and indicates the operation being performed and some useful information
 about what is happening. Sometimes this section will simply read <em>Forking</>
 which means the OS is loading the download module. The first word after the [
 is the fetch number as shown on the history lines. The next word
@@ -511,7 +511,7 @@ 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</>
+remote site. Once the download begings 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.
@@ -535,7 +535,7 @@ status display.
 <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
+<prgn>dpkg</> will also ask a number of questions as it processes the packages
 and the packages themselves may also ask several questions. Before each 
 question there is usually a description of what it is asking and the
 questions are too varied to discuss completely here.
diff --git a/doc/libapt-pkg2_to_3.txt b/doc/libapt-pkg2_to_3.txt
new file mode 100644
index 000000000..c1f71f9f2
--- /dev/null
+++ b/doc/libapt-pkg2_to_3.txt
@@ -0,0 +1,89 @@
+libapt-pkg v2 to v3 incorperates several source-incompatible changes that
+people need to be aware of.. Many of this changes are done so that most old
+source will continue to function, but perhaps at reduced functionality.
+
+* pkgDepCache is no longer self initilizing, you have to call the Init
+  method seperately after constructing it. Users of pkgCacheFile do not
+  need to worry about this
+* GetCandidateVer/etc is gone from the pkgCache. It exists only in the 
+  DepCache and is just an inline around the new Policy class
+* TargetVer/TargetDist have been eliminated. Nothing should have been using
+  these.
+* There is a policy class. The v0 policy engine which has been used since
+  APT 0.0.0 is instantiated by the DepCache by default. However pkgCacheFile 
+  constructs and initializes the new v4 engine. People accessing GetCandidate
+  version outside of a CacheFile/DepCache will need to instantiate and 
+  initialize a policy engine on their own.
+* All byte counters are now doubles to advoid 4G wraparound. The compiler 
+  should generate warnings on any incorrect use of these.
+* The PriorityType/CompType/DepType functions have been moved out of the 
+  iterators and into generate static functions of pkgCache - inline stubs
+  are left in the iterators. 
+* The deb dependency element parser has been made into a static function
+  of the list parser and enhanced to optionally understand architecture 
+  restrictions.
+* TagSections no longer include the trailing \n. This means that the 
+  Offset/Length of a package record in the version structure also does not
+  include the trailing \n.
+* GenCaches::SelectFile accepts a site parameter now too.
+* Global version compare functions are gone. If you 
+    #define APT_COMPATABILITY 1
+  They will come back as they were before. Code should be updated to 
+  reference the compare functions to the VersioningSystem (VS) referenced
+  by the Cache or _system structures.
+* Initialization is now two stage (define APT_COMPATABILITY..) The first
+  stage, pkgInitConfig is called before commandline parsing, and
+  pkgInitSystem is called after. This gives the user the oppertunity to
+  override default settings from the config files before startup has been
+  finalized.
+* pkgSourceList has been gutted. All the junk that was in there before is
+  cleaned up and put in the pkgIndexFile class. There is very little API
+  corrispondence here.. 
+* pkgMakeStatusCacheMem is gone, pkgMakeStatusCache does the same thing if
+  you set the AllowMem flag. Also, you can get a copy of the map used to
+  store the cache to advoid having to remap it in the calling code. A bunch
+  of other cache related functions are gone, but nobody should have been using
+  them in the first place!
+* Downloading the 'Package' and 'Source' index files is different, use
+  the GetIndexes call in SourceList.
+* SourceRecords::Parser::Source is gone, replaced with Index which does 
+  much the same thing.
+* DynamicMap has changed slightly, nobody should care
+* pkgMakeOnlyStatusCache exists, which creates a really small cache that
+  only contains the status file, and in memory.
+* The pkgRecords stuff is changed to abstract through the index file list
+  (should be transparent largely)
+* Locking is handled differently, there is no dpkg lock class, the _system
+  class provides Lock/UnLock methods
+* pkgDepCache is not a subclass of pkgCache, it agregates it now. Some 
+  compatibility functions are provided that make this transition fairly 
+  easy.
+* The following functions have had minor argument changes:
+   -   pkgSimulate(pkgDepCache &Cache);
+   +   pkgSimulate(pkgDepCache *Cache);
+   
+   -   pkgProblemResolver(pkgDepCache &Cache);
+   +   pkgProblemResolver(pkgDepCache *Cache);
+   
+   -   pkgDepCache(MMap &Map,Policy *Plcy = 0);
+   +   pkgDepCache(pkgCache *Cache,Policy *Plcy = 0);
+   
+   -   pkgOrderList(pkgDepCache &Cache);
+   +   pkgOrderList(pkgDepCache *Cache);
+   
+   -   pkgPackageManager(pkgDepCache &Cache);
+   +   pkgPackageManager(pkgDepCache *Cache);
+   
+   -   pkgCache(MMap &Map,bool DoMap = true);
+   +   pkgCache(MMap *Map,bool DoMap = true);
+   
+   -   pkgCacheGenerator(DynamicMMap &Map,OpProgress &Progress);
+   +   pkgCacheGenerator(DynamicMMap *Map,OpProgress *Progress);
+   
+   -   pkgTagFile(FileFd &F,unsigned long Size = 32*1024);
+   +   pkgTagFile(FileFd *F,unsigned long Size = 32*1024);
+   
+* Configuration class is const-correct  
+* The legacy ability to create a PkgFileIterator that started at Begin
+  is gone, everyone should be using FileBegin().
+* A new dependency relation called obsoletes that is similar to conflicts.
diff --git a/doc/makefile b/doc/makefile
index a8f95b70e..45cb7a878 100644
--- a/doc/makefile
+++ b/doc/makefile
@@ -5,16 +5,18 @@ SUBDIR=doc
 # Bring in the default rules
 include ../buildlib/defaults.mak
 
-# SGML Documents
-SOURCE = dpkg-tech.sgml design.sgml files.sgml guide.sgml cache.sgml \
-         method.sgml offline.sgml
+# Debian Doc SGML Documents
+SOURCE = dpkg-tech.sgml design.sgml files.sgml guide.sgml guide.it.sgml \
+         cache.sgml method.sgml offline.sgml
 include $(DEBIANDOC_H)
 
 # Man pages
-SOURCE = apt-cache.8 apt-get.8 apt-cdrom.8 apt.conf.5 sources.list.5 apt-config.8
-include $(YODL_MANPAGE_H)
+SOURCE = apt-cache.8 apt-get.8 apt-cdrom.8 apt.conf.5 sources.list.5 \
+         apt-config.8 apt-sortpkgs.1 apt-ftparchive.1 apt_preferences.5
+INCLUDES = apt.ent	 
+include $(SGML_MANPAGE_H)
 
 # Examples
-SOURCE = examples/apt.conf examples/sources.list examples/configure-index
+SOURCE = examples/apt.conf examples/sources.list examples/configure-index 
 TO = $(DOC)
 include $(COPY_H)
diff --git a/doc/offline.sgml b/doc/offline.sgml
index 9a664ac3d..0db89f12e 100644
--- a/doc/offline.sgml
+++ b/doc/offline.sgml
@@ -4,7 +4,7 @@
 <title>Using APT Offline</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: offline.sgml,v 1.2 2000/02/13 07:20:47 jgg Exp $</version>
+<version>$Id: offline.sgml,v 1.3 2001/02/20 07:03:17 jgg Exp $</version>
 
 <abstract>
 This document describes how to use APT in a non-networked environment, 
@@ -43,7 +43,7 @@ SuperDisk disc. These discs are not large enough to store the entire Debian
 archive but can easily fit a subset large enough for most users. The idea
 is to use APT to generate a list of packages that are required and then fetch
 them onto the disc using another machine with good connectivity. It is 
-even Possible to use another Debian machine with APT or to use a completely 
+even possible to use another Debian machine with APT or to use a completely 
 different OS and a download tool like wget.
 
 <p>
@@ -124,7 +124,7 @@ More details can be seen by examining the apt.conf man page and the sample
 configuration file in <em>/usr/doc/apt/examples/apt.conf</em>.
 
 <p>
-On the Debian machine the first thing to do is mount the disc and copy 
+On the remote Debian machine the first thing to do is mount the disc and copy 
 <em>/var/lib/dpkg/status</em> to it. You will also need to create the directories
 outlined in the Overview, <em>archives/partial/</em> and <em>lists/partial/</em>
 Then take the disc to the remote machine and configure the sources.list. 
@@ -139,8 +139,9 @@ On the remote machine execute the following:
 </example>
 
 The dist-upgrade command can be replaced with any-other standard APT commands,
-you can even use an APT front end such as <em>gnome-apt</em> [still in 
-development].
+particularly dselect-upgrad. You can even use an APT front end such as 
+<em>dselect</em> However this presents a problem in communicating your 
+selections back to the local computer.
 
 <p>
 Now the disc contains all of the index files and archives needed to upgrade
@@ -158,6 +159,13 @@ the Debian machine. Take the disc back and run:
 It is necessary for proper function to re-specify the status file to be the 
 local one. This is very important!
 
+<p>
+If you are using dselect you can do the very risky operation of copying 
+disc/status to /var/lib/dpkg/status so that any selections you made on the
+remote machine are updated. I highly recommend that people only make selections
+on the local machine - but this may not always be possible. DO NOT copy
+the status file if dpkg or APT have been run in the mean time!!
+
 </sect>
                                                                   <!-- }}} -->
 
@@ -193,6 +201,10 @@ merely use the standard APT commands to generate the file list.
  # awk '{print "wget -O " $2 " " $1}' < uris > /disc/wget-script
 </example>
 
+Any command other than dist-upgrade could be used here, including 
+dselect-upgrade.
+
+<p>
 The /disc/wget-script file will now contain a list of wget commands to execute 
 in order to fetch the necessary archives. This script should be run with the
 current directory as the disc's mount point so as to save the output on the 
diff --git a/doc/sources.list.5.sgml b/doc/sources.list.5.sgml
new file mode 100644
index 000000000..d630e12fd
--- /dev/null
+++ b/doc/sources.list.5.sgml
@@ -0,0 +1,199 @@
+<!-- -*- mode: sgml; mode: fold -*- -->
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>sources.list</>
+   <manvolnum>5</>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>sources.list</>
+    <refpurpose>Package resource list for APT</>
+ </refnamediv>
+ 
+ <RefSect1><Title>Description</>
+   <para>   
+   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.
+   This control file is located in <filename>/etc/apt/sources.list</>
+   <para>
+   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:
+   <literal/type uri args/. The first item, <literal/type/, determines the 
+   format for <literal/args/. <literal/uri/ is a Universal Resource Identifier 
+   (URI), which is a superset of the more specific and well-known Universal
+   Resource Locator, or URL. The rest of the line can be marked as a comment 
+   by using a #.
+ </RefSect1>
+ 
+ <RefSect1><Title>The deb and deb-src types</>
+   <para>   
+   The <literal/deb/ type describes a typical two-level Debian archive,
+   <filename>distribution/component</>. Typically, <literal/distribution/ is 
+   generally one of <literal/stable/, <literal/unstable/, or 
+   <literal/frozen/, while component is one of <literal/main/, 
+   <literal/contrib/, <literal/non-free/, or <literal/non-us/. The 
+   <literal/deb-src/ type describes a debian distribution's source code in 
+   the same form as the <literal/deb/ type. A <literal/deb-src/ line is 
+   required to fetch source indexes.
+   <para>
+   The format for a <filename/sources.list/ entry using the <literal/deb/ 
+   and <literal/deb-src/ types are:
+   <literallayout>deb uri distribution [component1] [componenent2] [...]</literallayout>
+   <para>
+   The URI for the <literal/deb/ type must specify the base of the Debian 
+   distribution, from which APT will find the information it needs. 
+   <literal/distribution/ can specify an exact path, in which case the 
+   components must be omitted and <literal/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 <literal/distribution/ does 
+   not specify an exact path, at least one <literal/component/ must be present.
+   <para>
+   <literal/distribution/ may also contain a variable, <literal/$(ARCH)/,
+   which expands to the Debian architecture (i386, m68k, powerpc, ...)
+   used on the system. This permits archiecture-independent
+   <filename/sources.list/ files to be used. In general this is only of 
+   interest when specifying an exact path, <literal/APT/ will automatically 
+   generate a URI with the current architecture otherwise.
+   <para>
+   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.
+   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. bf(APT) also parallizes connections to 
+   different hosts to more effectively deal with sites with low bandwidth.
+   <para>
+   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).
+   <para>
+   Some examples:
+   <literallayout>
+deb http://http.us.debian.org/debian stable main contrib non-free
+deb http://http.us.debian.org/debian dists/stable-updates/
+   </literallayout>
+ </RefSect1>
+
+ <RefSect1><title>URI specification</title>
+   <para>
+   The currently recognized URI types are cdrom, file, http, and ftp.
+   <VariableList>
+    <VarListEntry><term>file</term>
+    <ListItem><Para>
+    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.
+    </VarListEntry>
+    
+    <VarListEntry><term>cdrom</term>
+    <ListItem><Para>
+    The cdrom scheme allows APT to use a local CDROM drive with media
+    swapping. Use the &apt-cdrom; program to create cdrom entries in the
+    source list.
+    </VarListEntry>
+
+    <VarListEntry><term>http</term>
+    <ListItem><Para>
+    The http scheme specifies an HTTP server for the archive. If an environment
+    variable <EnVar/http_proxy/ is set with the format 
+    http://server:port/, the proxy server specified in
+    <EnVar/http_proxy/ will be used. Users of authenticated HTTP/1.1 proxies 
+    may use a string of the format http://user:pass@server:port/
+    Note that this is an insecure method of authentication.
+    </VarListEntry>
+
+    <VarListEntry><term>ftp</term>
+    <ListItem><Para>
+    The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
+    is highly configurable; for more information see the
+    &apt-conf; manual page. Please note that a ftp proxy can be specified
+    by using the <EnVar/ftp_proxy/ environment variable. It is possible to 
+    specify a http proxy (http proxy servers often understand ftp urls) using 
+    this method and ONLY this method. ftp proxies using http specified in the 
+    configuration file will be ignored.
+    </VarListEntry>
+
+    <VarListEntry><term>copy</term>
+    <ListItem><Para>
+    The copy scheme is identical to the file scheme except that packages are
+    copied into the cache directory instead of used directly at their location.
+    This is useful for people using a zip disk to copy files around with APT.
+    </VarListEntry>
+    
+    <VarListEntry><term>rsh</term><term>ssh</term>
+    <ListItem><Para>
+    The rsh/ssh method method invokes rsh/ssh to connect to a remote host
+    as a given user and access the files. No password authentication is 
+    possible, prior arrangements with RSA keys or rhosts must have been made.
+    Access to files on the remote uses standard <command/find/ and <command/dd/ 
+    commands to perform the file transfers from the remote.
+    </VarListEntry>
+  </VariableList>
+ </RefSect1>
+ 
+ <RefSect1><title>Examples</title>
+   <para>
+   Uses the archive stored locally (or NFS mounted) at /home/jason/debian
+   for stable/main, stable/contrib, and stable/non-free.
+   <literallayout>deb file:/home/jason/debian stable main contrib non-free</literallayout>
+   <para>
+   As above, except this uses the unstable (development) distribution.
+   <literallayout>deb file:/home/jason/debian unstable main contrib non-free</literallayout>
+   <para>
+   Source line for the above
+   <literallayout>deb-src file:/home/jason/debian unstable main contrib non-free</literallayout>
+   <para>
+   Uses HTTP to access the archive at archive.debian.org, and uses only the
+   hamm/main area.
+   <literallayout>deb http://archive.debian.org/debian-archive hamm main</literallayout>
+   <para>
+   Uses FTP to access the archive at ftp.debian.org, under the debian
+   directory, and uses only the stable/contrib area.
+   <literallayout>deb ftp://ftp.debian.org/debian stable contrib</literallayout>
+   <para>
+   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 <filename/sources.list/,
+   a single FTP session will be used for both resource lines.
+   <literallayout>deb ftp://ftp.debian.org/debian unstable contrib</literallayout>
+   <para>
+   Uses HTTP to access the archive at nonus.debian.org, under the debian-non-US
+   directory.
+   <literallayout>deb http://nonus.debian.org/debian-non-US stable/non-US main contrib non-free</literallayout>
+   <para>
+   Uses HTTP to access the archive at nonus.debian.org, under the
+   debian-non-US directory, and uses only files found under
+   <filename>unstable/binary-i386</> on i386 machines, 
+   <filename>unstable/binary-m68k</> on m68k, and so
+   forth for other supported architectures. [Note this example only 
+   illustrates how to use the substitution variable; non-us is no longer 
+   structured like this] 
+   <literallayout>deb http://ftp.de.debian.org/debian-non-US unstable/binary-$(ARCH)/</literallayout>
+ </RefSect1>
+ 
+ <RefSect1><Title>See Also</>
+   <para>
+   &apt-cache; &apt-conf;
+ </RefSect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
diff --git a/doc/sources.list.5.yo b/doc/sources.list.5.yo
deleted file mode 100644
index 2a501f776..000000000
--- a/doc/sources.list.5.yo
+++ /dev/null
@@ -1,148 +0,0 @@
-mailto(apt@packages.debian.org)
-manpage(sources.list)(5)(5 Dec 1998)(apt)()
-manpagename(sources.list)(package resource list for APT)
-
-manpagedescription()
-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.
-
-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:
-em(type uri args) The first item, em(type), determines the format for
-em(args). em(uri) is a Universal Resource Identifier (URI), which is a 
-superset of the more specific and well-known Universal Resource Locator, or 
-URL.
-
-manpagesection(The deb and deb-src types)
-The bf(deb) type describes a typical two-level Debian archive,
-em(distribution/component). Typically, em(distribution) is one of
-em(stable), em(unstable), or em(frozen), while component is one of
-em(main), em(contrib), em(non-free), or em(non-us). The bf(deb-src) type
-describes a debian distribution's source code in the same form as the bf(deb)
-type. A bf(deb-src) line is required to fetch source indexes.
-The format for a bf(sources.list) entry using the em(deb) and em(deb-src)
-types are:
-verb(deb uri distribution [component1] [componenent2] [...])
-The URI for the em(deb) type must specify the base of the Debian distribution, 
-from which bf(APT) will find the information it needs. em(distribution)
-can specify an exact path, in which case the em(component)s
-must be omitted and bf(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 bf(distribution) does not specify an exact path, at 
-least one bf(component) must be present.
-
-bf(distribution) may also contain a variable, bf($(ARCH)),
-which expands to the Debian architecture (i386, m68k, powerpc, ...)     
-used on the system. This permits archiecture-independent                
-bf(sources.list) files to be used. In general this is only of interest
-when specifying an exact path, bf(APT) will automatically generate a URI
-with the current architecture otherwise.
-
-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.
-bf(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. bf(APT) also parallizes connections to different hosts
-to more effectively deal with sites with low bandwidth.
-
-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).
-
-Some examples:
-verb(deb http://http.us.debian.org/debian stable main contrib non-free)
-verb(deb http://http.us.debian.org/debian dists/stable-updates)
-
-manpagesection(URI specification)
-The currently recognized URI types are cdrom, file, http, and ftp.
-
-startdit()
-dit(bf(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.
-
-dit(bf(cdrom))
-The cdrom scheme allows bf(APT) to use a local CDROM drive with media
-swapping. Use the bf(apt-cdrom(8)) program to create cdrom entires in the
-source list.
-
-dit(bf(http))
-The http scheme specifies an HTTP server for the archive. If an environment
-variable bf($http_proxy) is set with the format 
-bf(http://server:port/), the proxy server specified in
-bf($http_proxy) will be used. Users of authenticated HTTP/1.1 proxies may 
-use a string of the format bf(http://user:pass@server:port/)
-Note that this is an insecure method of authentication.
-
-dit(bf(ftp))
-The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
-is highly configurable; for more information see the
-bf(apt.conf(5)) manual page. Please note that a ftp proxy can be specified
-by using the ftp_proxy environment variable. It is possible to specify a http
-proxy (http proxy servers often understand ftp urls) using this method and 
-ONLY this method. ftp proxies using http specified in the configuration 
-file will be ignored.
-
-dit(bf(copy))
-The copy scheme is identical to the file scheme except that packages are
-copied into the cache directory instead of used directly at their location.
-This is usefull for people using a zip disk to copy files around with APT.
-
-enddit()
-
-manpagesection(EXAMPLES)
-Uses the archive stored locally (or NFS mounted) at /home/jason/debian
-for stable/main, stable/contrib, and stable/non-free.
-quote("deb file:/home/jason/debian stable main contrib non-free")
-
-As above, except this uses the unstable (development) distribution.
-quote("deb file:/home/jason/debian unstable main contrib non-free")
-
-Source line for the above
-quote("deb-src file:/home/jason/debian unstable main contrib non-free")
-
-Uses HTTP to access the archive at archive.debian.org, and uses only the
-hamm/main area.
-quote("deb http://archive.debian.org/debian-archive hamm main")
-
-Uses FTP to access the archive at ftp.debian.org, under the debian
-directory, and uses only the stable/contrib area.
-quote("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 unstable/contrib area. If this line appears as
-well as the one in the previous example in bf(sources.list),
-a single FTP session will be used for both resource lines.
-quote("deb ftp://ftp.debian.org/debian unstable contrib")
-
-Uses HTTP to access the archive at nonus.debian.org, under the debian-non-US
-directory.
-quote("deb http://nonus.debian.org/debian-non-US stable/non-US main contrib non-free")
-
-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. [Note this example only illistrates
-how to use the substitation variable non-us is no longer structured like this]
-quote("deb http://ftp.de.debian.org/debian-non-US unstable/binary-$(ARCH)/")
-
-manpageseealso()
-apt-cache (8),
-apt.conf (5)
-
-manpagebugs()
-See http://bugs.debian.org/apt.  If you wish to report a
-bug in bf(apt-get), please see bf(/usr/doc/debian/bug-reporting.txt)
-or the bf(bug(1)) command.
-
-manpageauthor()
-apt-get was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/style.txt b/doc/style.txt
new file mode 100644
index 000000000..8d0778b4a
--- /dev/null
+++ b/doc/style.txt
@@ -0,0 +1,75 @@
+Acronyms
+~~~~~~~~
+* dpkg is a 'word' the first d may be upper case - Dpkg
+* APT is a proper Acronym, all upper case please.
+
+Pkg - A Package
+Ver - A version
+
+Indenting, Comments, Etc
+~~~~~~~~~~~~~~~~~~~~~~~~
+Would make Linus cry :P However it is what I prefer. 3 space indent,
+8 space tab all braces on seperate lines, function return on the same line 
+as the function, cases aligned with their code. The 'indent' options for 
+this style are:
+   indent -bl -bli0 -di1 -i3 -nsc -ts8 -npcs -npsl
+
+Each file gets a block at the top that should describe what the file does,
+basically a summary of purpose along with any special notes and 
+attributions. The }}} and {{{ are folding marks if you have a folding
+editor such as jed, the function seperators are intended to give
+a visual seperate between functions for easier browsing of the larger files,
+or indexed folding if you have such an editor.
+
+Each file should have 1 or 0 primary include files, that include
+file must always be the first include file included by the .cc. G++ 
+#pragma interface/implementation is used, as well as anti-include-twice
+#ifdefs.
+
+Include files, since there are so many, get their own subdirectory off
+the include search path, this is used consistently throughout all the code.
+#include "" should never be used for a global exported header file, only 
+local ones.
+
+C++ Features
+~~~~~~~~~~~~
+Due to the legacy compiler heritage, exceptions, RTTI and name spaces are
+not used. Templates are used *sparingly* since G++ has traditionally had
+very weak support for them, this includes STL templates.
+
+Namespaces will probably be put in the code sometime after G++ 3, which will
+be a huge re-org again to make sanity, the majority of all nested things
+will go away.
+
+The C++ standard library's non parameterized types (string is included in
+this) are used freely when appropriate.
+
+The new C++ #include <iostream> (note the lack of a .h) is used for the
+standard library, but not for my code.
+
+Arguments and Ownership
+~~~~~~~~~~~~~~~~~~~~~~~
+[much of the code follows this now]
+These guidlines should be followed except in two cases.. the first
+is where it makes no sense, such as in a casting operator and the second is to
+retain API compatibility (this should be rare, since a change in the input
+almost always designates a change in ownership rules).
+
+  * Pass by value or pass by reference should borrow the object from the
+    caller
+  * Pass by non-const reference may be used to indicate a OUT type variable
+  * Pass by pointer (except in the case where the pointer is really an array)
+    should be used when the object will be retained or ownership will be
+    transfered. Ownership transference should be rare and noted by a comment.
+  * Standard C things (FILE * etc) should be left as is.
+  
+  * Return by references should indicate a borrowed object
+  * Return by pointer (except arrays) should indicate ownership is 
+    transfered. Return by pointer should not be used unless ownership is 
+    transfered.
+  * Return by pointer to variable indicates ownership transfer unless the
+    pointer is an 'input' parameter (designated generally by an =0, 
+    indicating a default of 'none')
+     
+Non-ownership transfering arrays/lists should probably return an iterator 
+typedef or references..
author	Arch Librarian <arch@canonical.com>	2004-09-20 16:56:32 +0000
committer	Arch Librarian <arch@canonical.com>	2004-09-20 16:56:32 +0000
commit	b2e465d6d32d2dc884f58b94acb7e35f671a87fe (patch)
tree	5928383b9bde7b0ba9812e6526ad746466e558f7 /doc
parent	00b47c98ca4a4349686a082eba6d77decbb03a4d (diff)