* Replace SGML manpages with XML man pages from richard...

Author: mdz
Date: 2004-02-07 21:48:14 GMT
* Replace SGML manpages with XML man pages from richard.bos@xs4all.nl
(Closes: #230687)

buildlib/defaults.mak

@@ -83,6 +83,7 @@ PYTHON_H = $(BASE)/buildlib/python.mak
 COPY_H = $(BASE)/buildlib/copy.mak
 YODL_MANPAGE_H = $(BASE)/buildlib/yodl_manpage.mak
 SGML_MANPAGE_H = $(BASE)/buildlib/sgml_manpage.mak
+XML_MANPAGE_H = $(BASE)/buildlib/xml_manpage.mak
 FAIL_H = $(BASE)/buildlib/fail.mak
 PODOMAIN_H = $(BASE)/buildlib/podomain.mak
 

buildlib/environment.mak.in

@@ -31,6 +31,9 @@ DEBIANDOC_TEXT = @DEBIANDOC_TEXT@
 # SGML for the man pages
 DOCBOOK2MAN := @DOCBOOK2MAN@
 
+# XML for the man pages
+XMLTO := @XMLTO@
+
 # Gettext settings
 GMSGFMT = @GMSGFMT@
 XGETTEXT = @XGETTEXT@

configure.in

@@ -160,6 +160,9 @@ AC_PATH_PROG(DEBIANDOC_TEXT,debiandoc2text)
 dnl Check for the SGML tools needed to build man pages
 AC_PATH_PROG(DOCBOOK2MAN,docbook2man)
 
+dnl Check for the XML tools needed to build man pages
+AC_PATH_PROG(XMLTO,xmlto)
+
 dnl Check for YODL
 dnl AC_CHECK_PROG(YODL_MAN,yodl2man,"yes","")
 

debian/changelog

@@ -14,6 +14,8 @@ apt (0.5.22) unstable; urgency=low
     (Closes: #230102)
   * Simplified Chinese translation of message catalog from "Carlos
     Z.F. Liu" <carlos_liu@yahoo.com> (Closes: #230960)
+  * Replace SGML manpages with XML man pages from richard.bos@xs4all.nl
+    (Closes: #230687)
 
  --
 

doc/apt-cache.8.sgml

@@ -1,412 +0,0 @@
-<!-- -*- 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-cache</>
-      <arg><option>-hvsn</></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>showsrc <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>depends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
-         <arg>rdepends <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>
-         <arg>policy <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg>
-         <arg>madison <arg choice="plain" rep="repeat"><replaceable>pkgs</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
-   commands below must be present.
-
-   <VariableList>
-     <VarListEntry><Term>add <replaceable/file(s)/</Term>
-     <ListItem><Para>
-     <literal/add/ adds the named package index files to the package cache.
-     This is for debugging only.
-     </VarListEntry>
-     
-     <VarListEntry><Term>gencaches</Term>
-     <ListItem><Para>
-     <literal/gencaches/ performs the same operation 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 <replaceable/pkg(s)/</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-12, depends on libc5 and
-     ncurses3.0 which must be installed for libreadline2 to work. 
-     In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If
-     libreadline2 is installed, libc5 and 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 accessed, 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>showsrc <replaceable/pkg(s)/</Term>
-     <ListItem><Para>
-     <literal/showsrc/ displays all the source package records that match
-     the given package names. All versions are shown, as well as all 
-     records that declare the name to be a Binary.
-     </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 <replaceable/pkg(s)/</Term>
-     <ListItem><Para>
-     <literal/show/ performs a function similar to 
-     <command>dpkg --print-avail</>i; it displays the package records for the 
-     named packages.
-     </VarListEntry>
-
-     <VarListEntry><Term>search <replaceable/regex [ regex ... ]/</Term>
-     <ListItem><Para>
-     <literal/search/ performs a full text search on all available package
-     lists for the regex pattern given. It searches the package names and the
-     descriptions for an occurrence of the regular expression 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>
-     Separate arguments can be used to specify multiple search patterns that 
-     are and'ed together.
-     </VarListEntry>
-
-     <VarListEntry><Term>depends <replaceable/pkg(s)/</Term>
-     <ListItem><Para>
-     <literal/depends/ shows a listing of each dependency a package has 
-     and all the possible other packages that can fulfill that dependency.
-     </VarListEntry>
-
-     <VarListEntry><Term>rdepends <replaceable/pkg(s)/</Term>
-     <ListItem><Para>
-     <literal/rdepends/ shows a listing of each reverse dependency a package
-     has.
-     </VarListEntry>
-
-     <VarListEntry><Term>pkgnames <replaceable/[ prefix ]/</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 
-     extremely quickly. This command is best used with the 
-     <option/--generate/ option.
-     </VarListEntry>
-     
-     <VarListEntry><Term>dotty <replaceable/pkg(s)/</Term>
-     <ListItem><Para>
-     <literal/dotty/ takes a list of packages on the command line and 
-     generates output suitable for use by dotty from the 
-     <ulink url="http://www.research.att.com/sw/tools/graphviz/">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; this can produce a very large graph. 
-     To limit the output to only the packages listed on the command line,
-     set the <literal>APT::Cache::GivenOnly</> option.
-
-     <para>
-     The resulting nodes will have several shapes; normal packages are boxes,
-     pure provides are triangles, mixed provides are diamonds, 
-     missing packages are hexagons. Orange boxes mean recursion was stopped 
-     [leaf packages], blue lines are pre-depends, green lines are conflicts.
-
-     <para>
-     Caution, dotty cannot graph larger sets of packages.
-     
-     <VarListEntry><Term>policy <replaceable/[ pkg(s) ]/</Term>
-     <ListItem><Para>
-     <literal/policy/ is ment to help debug issues relating to the 
-     preferences file. With no arguments it will print out the 
-     priorities of each source. Otherwise it prints out detailed information
-     about the priority selection of the named package.
-     </VarListEntry>
-
-     <VarListEntry><Term>madison <replaceable/[ pkg(s) ]/</Term>
-     <ListItem><Para>
-
-     <literal/apt-cache/'s <literal/madison/ command attempts to mimic
-     the output format and a subset of the functionality of the Debian
-     archive management tool, <literal/madison/.  It displays
-     available versions of a package in a tabular format.  Unlike the
-     original <literal/madison/, it can only display information for
-     the architecture for which APT has retrieved package lists
-     (<literal/APT::Architecture/).
-
-     </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 q's will produce more quietness up to a maximum of 2. You can also use
-     <option/-q=#/ to set the quietness level, overriding the configuration file.
-     Configuration Item: <literal/quiet/.
-     </VarListEntry>
-
-     <VarListEntry><term><option/-i/</><term><option/--important/</>
-     <ListItem><Para>
-     Print only important dependencies; 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 the
-     default; to turn it off, use <option/--no-all-versions/.
-     If <option/--no-all-versions/ is specified, only the candidate version
-     will displayed (the one which would be selected for installation).
-     This option is only applicable to  the <literal/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/</><term><option/-n/</>
-     <ListItem><Para>
-     Only search on the package names, not the long descriptions. 
-     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/ and <literal/rdepends/ recursive so that
-     all packages mentioned are printed once.
-     Configuration Item: <literal/APT::Cache::RecurseDepends/.
-     </VarListEntry>
-
-     <VarListEntry><term><option/--installed/</>
-     <ListItem><Para>
-     Limit the output of <literal/depends/ and <literal/rdepends/ to
-     packages which are currently installed.
-     Configuration Item: <literal/APT::Cache::Installed/.
-     </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>

doc/apt-cache.8.xml

@@ -0,0 +1,371 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-cache</refentrytitle>
+   <manvolnum>8</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-cache</refname>
+    <refpurpose>APT package handling utility -- cache manipulator</refpurpose>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-cache</command>
+      <arg><option>-hvsn</option></arg>
+      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
+      <arg><option>-c=<replaceable>file</replaceable></option></arg>
+      <group choice="req">
+         <arg>add <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg></arg>
+         <arg>gencaches</arg>
+         <arg>showpkg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>showsrc <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>stats</arg>
+         <arg>dump</arg>
+         <arg>dumpavail</arg>
+         <arg>unmet</arg>
+         <arg>search <arg choice="plain"><replaceable>regex</replaceable></arg></arg>
+         <arg>show <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>depends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
+         <arg>rdepends <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>
+         <arg>policy <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg>
+         <arg>madison <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <refsect1><title>Description</title>
+   <para><command>apt-cache</command> performs a variety of operations on APT's package 
+   cache. <command>apt-cache</command> does not manipulate the state of the system 
+   but does provide operations to search and generate interesting output 
+   from the package metadata.</para>
+
+   <para>Unless the <option>-h</option>, or <option>--help</option> option is given, one of the
+   commands below must be present.</para>
+
+   <variablelist>
+     <varlistentry><term>add <replaceable>file(s)</replaceable></term>
+     <listitem><para><literal>add</literal> adds the named package index files to the package cache.
+     This is for debugging only.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>gencaches</term>
+     <listitem><para><literal>gencaches</literal> performs the same operation as 
+     <command>apt-get check</command>. It builds the source and package caches from 
+     the sources in &sources-list; and from
+     <filename>/var/lib/dpkg/status</filename>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>showpkg <replaceable>pkg(s)</replaceable></term>
+     <listitem><para><literal>showpkg</literal> 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</command> would produce 
+     output similar to the following:</para>
+     
+<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-12, depends on
+     libc5 and ncurses3.0 which must be installed for libreadline2 to work. 
+     In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If
+     libreadline2 is installed, libc5 and 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.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>stats</term><listitem><para><literal>stats</literal> displays some statistics about the cache.
+     No further arguments are expected. Statistics reported are:
+     <itemizedlist>
+       <listitem><para><literal>Total package names</literal> is the number of package names found 
+       in the cache.</para>
+       </listitem>
+       
+       <listitem><para><literal>Normal packages</literal> 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.</para>
+       </listitem>
+
+       <listitem><para><literal>Pure virtual packages</literal> 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".</para>
+       </listitem>
+   
+       <listitem><para><literal>Single virtual packages</literal> 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".</para>
+       </listitem>
+
+       <listitem><para><literal>Mixed virtual packages</literal> 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.</para>
+       </listitem>
+   
+       <listitem><para><literal>Missing</literal> 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 accessed, or if a package
+       (real or virtual) has been dropped from the distribution. Usually they
+       are referenced from Conflicts statements.</para>
+       </listitem>
+
+       <listitem><para><literal>Total distinct</literal> 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.</para>
+       </listitem>
+
+       <listitem><para><literal>Total dependencies</literal> is the number of dependency relationships 
+       claimed by all of the packages in the cache.</para>
+       </listitem>
+     </itemizedlist>
+     </para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>showsrc <replaceable>pkg(s)</replaceable></term>
+     <listitem><para><literal>showsrc</literal> displays all the source package records that match
+     the given package names. All versions are shown, as well as all 
+     records that declare the name to be a Binary.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>dump</term>
+     <listitem><para><literal>dump</literal> shows a short listing of every package in the cache. It is 
+     primarily for debugging.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>dumpavail</term>
+     <listitem><para><literal>dumpavail</literal> prints out an available list to stdout. This is 
+     suitable for use with &dpkg; and is used by the &dselect; method.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>unmet</term>
+     <listitem><para><literal>unmet</literal> displays a summary of all unmet dependencies in the 
+     package cache.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>show <replaceable>pkg(s)</replaceable></term>
+     <listitem><para><literal>show</literal> performs a function similar to 
+     <command>dpkg --print-avail</command>i; it displays the package records for the 
+     named packages.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>search <replaceable>regex [ regex ... ]</replaceable></term>
+     <listitem><para><literal>search</literal> performs a full text search on all available package
+     lists for the regex pattern given. It searches the package names and the
+     descriptions for an occurrence of the regular expression and prints out
+     the package name and the short description. If <option>--full</option> is given
+     then output identical to <literal>show</literal> is produced for each matched
+     package, and if <option>--names-only</option> is given then the long description
+     is not searched, only the package name is.</para>
+     <para>
+     Separate arguments can be used to specify multiple search patterns that 
+     are and'ed together.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>depends <replaceable>pkg(s)</replaceable></term>
+     <listitem><para><literal>depends</literal> shows a listing of each dependency a package has 
+     and all the possible other packages that can fulfill that dependency.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>rdepends <replaceable>pkg(s)</replaceable></term>
+     <listitem><para><literal>rdepends</literal>shows a listing of each reverse dependency a
+      package has.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>pkgnames <replaceable>[ prefix ]</replaceable></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 
+     extremely quickly. This command is best used with the 
+     <option>--generate</option> option.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>dotty <replaceable>pkg(s)</replaceable></term>
+     <listitem><para><literal>dotty</literal> takes a list of packages on the command line and 
+     generates output suitable for use by dotty from the 
+     <ulink url="http://www.research.att.com/sw/tools/graphviz/">GraphViz</ulink>
+     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; this can produce a very large graph. 
+     To limit the output to only the packages listed on the command line,
+     set the <literal>APT::Cache::GivenOnly</literal> option.</para>
+
+     <para>The resulting nodes will have several shapes; normal packages are boxes,
+     pure provides are triangles, mixed provides are diamonds, 
+     missing packages are hexagons. Orange boxes mean recursion was stopped 
+     [leaf packages], blue lines are pre-depends, green lines are conflicts.</para>
+
+     <para>Caution, dotty cannot graph larger sets of packages.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>policy <replaceable>[ pkg(s) ]</replaceable></term>
+     <listitem><para><literal>policy</literal> is ment to help debug issues relating to the 
+     preferences file. With no arguments it will print out the 
+     priorities of each source. Otherwise it prints out detailed information
+     about the priority selection of the named package.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>madison <replaceable>/[ pkg(s) ]</replaceable></term>
+     <listitem><para><literal>apt-cache</literal>'s <literal>madison</literal> command attempts to mimic
+     the output format and a subset of the functionality of the Debian
+     archive management tool, <literal>madison</literal>.  It displays
+     available versions of a package in a tabular format.  Unlike the
+     original <literal>madison</literal>, it can only display information for
+     the architecture for which APT has retrieved package lists
+     (<literal>APT::Architecture</literal>).</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+ 
+ <refsect1><title>options</title>
+   &apt-cmdblurb;
+   
+   <variablelist>
+     <varlistentry><term><option>-p</option></term><term><option>--pkg-cache</option></term>
+     <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</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-s</option></term><term><option>--src-cache</option></term>
+     <listitem><para>Select the file to store the source cache. The source is used only by
+     <literal>gencaches</literal> 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</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-q</option></term><term><option>--quiet</option></term>
+     <listitem><para>Quiet; produces output suitable for logging, omitting progress indicators.
+     More q's will produce more quietness up to a maximum of 2. You can also use
+     <option>-q=#</option> to set the quietness level, overriding the configuration file.
+     Configuration Item: <literal>quiet</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-i</option></term><term><option>--important</option></term>
+     <listitem><para>Print only important dependencies; for use with unmet. Causes only Depends and 
+     Pre-Depends relations to be printed.
+     Configuration Item: <literal>APT::Cache::Important</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-f</option></term><term><option>--full</option></term>
+     <listitem><para>Print full package records when searching. 
+     Configuration Item: <literal>APT::Cache::ShowFull</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-a</option></term><term><option>--all-versions</option></term>
+     <listitem><para>Print full records for all available versions. This is the
+     default; to turn it off, use <option>--no-all-versions</option>.
+     If <option>--no-all-versions</option> is specified, only the candidate version
+     will displayed (the one which would be selected for installation).
+     This option is only applicable to  the <literal>show</literal> command.
+     Configuration Item: <literal>APT::Cache::AllVersions</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-g</option></term><term><option>--generate</option></term>
+     <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</option>.
+     Configuration Item: <literal>APT::Cache::Generate</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--names-only</option></term><term><option>-n</option></term>
+     <listitem><para>Only search on the package names, not the long descriptions. 
+     Configuration Item: <literal>APT::Cache::NamesOnly</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--all-names</option></term>
+     <listitem><para>Make <literal>pkgnames</literal> print all names, including virtual packages 
+     and missing dependencies. 
+     Configuration Item: <literal>APT::Cache::AllNames</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--recurse</option></term>
+     <listitem><para>Make <literal>depends</literal> and <literal>rdepends</literal> recursive so
+     that all packages mentioned are printed once.
+     Configuration Item: <literal>APT::Cache::RecurseDepends</literal>.</para></listitem>
+     </varlistentry>
+
+      <varlistentry><term><option>--installed</option></term>
+      <listitem><para>
+      Limit the output of <literal>depends</literal> and <literal>rdepends</literal> to
+      packages which are currently installed.
+      Configuration Item: <literal>APT::Cache::Installed</literal>.</para></listitem>
+      </varlistentry>
+
+     &apt-commonoptions;
+     
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>Files</title>
+   <variablelist>
+     <varlistentry><term><filename>/etc/apt/sources.list</filename></term>
+     <listitem><para>Locations to fetch packages from.
+     Configuration Item: <literal>Dir::Etc::SourceList</literal>.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><filename>&statedir;/lists/</filename></term>
+     <listitem><para>Storage area for state information for each package resource specified in
+     &sources-list;
+     Configuration Item: <literal>Dir::State::Lists</literal>.</para></listitem>
+     </varlistentry>
+  
+     <varlistentry><term><filename>&statedir;/lists/partial/</filename></term>
+     <listitem><para>Storage area for state information in transit.
+     Configuration Item: <literal>Dir::State::Lists</literal> (implicit partial).</para></listitem>
+     </varlistentry>     
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>&apt-conf;, &sources-list;, &apt-get;
+   </para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para><command>apt-cache</command> returns zero on normal operation, decimal 100 on error.
+   </para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>

doc/apt-cdrom.8.sgml

@@ -1,147 +0,0 @@
-<!-- -*- 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 management 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
-   commands below 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 properly 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>
-

doc/apt-cdrom.8.xml

@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+
+ &apt-docinfo;
+
+ <refmeta>
+   <refentrytitle>apt-cdrom</refentrytitle>
+   <manvolnum>8</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-cdrom</refname>
+    <refpurpose>APT CDROM management utility</refpurpose>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-cdrom</command>
+      <arg><option>-hvrmfan</option></arg>
+      <arg><option>-d=<replaceable>cdrom mount point</replaceable></option></arg>
+      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
+      <arg><option>-c=<replaceable>file</replaceable></option></arg>
+      <group>
+         <arg>add</arg>
+         <arg>ident</arg>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1><title>Description</title>
+   <para><command>apt-cdrom</command> is used to add a new CDROM to APTs list
+    of available sources. <command>apt-cdrom</command> takes care of
+   determining the structure of
+   the disc as well as correcting for several possible mis-burns and 
+   verifying the index files.   
+   </para>
+
+   <para>It is necessary to use <command>apt-cdrom</command> 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>
+
+   <para>Unless the <option>-h</option>, or <option>--help</option> option is
+    given one of the commands below must be present.
+   
+    <variablelist>
+     <varlistentry><term>add</term>
+     <listitem><para><literal>add</literal> 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</filename> directory you will be prompted for a descriptive 
+     title.
+     </para>
+
+     <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</filename>
+     </para>
+     </listitem>
+     </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
+     </para>
+     </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+ </refsect1>
+
+ <refsect1><title>Options</title>
+   &apt-cmdblurb;
+   
+   <variablelist>
+     <varlistentry><term><option>-d</option></term><term><option>--cdrom</option></term>
+     <listitem><para>Mount point; specify the location to mount the cdrom. This
+      mount point must be listed in <filename>/etc/fstab</filename> and
+      properly configured.
+      Configuration Item: <literal>Acquire::cdrom::mount</literal>.
+     </para>
+     </listitem>
+     </varlistentry>
+     
+     <varlistentry><term><option>-r</option></term><term><option>--rename</option></term>
+     <listitem><para>Rename a disc; change the label of a disk or override the
+      disks given label. This option will cause <command>apt-cdrom</command> to
+      prompt for a new label.
+     Configuration Item: <literal>APT::CDROM::Rename</literal>.
+     </para>
+     </listitem>
+     </varlistentry>
+     
+     <varlistentry><term><option>-m</option></term><term><option>--no-mount</option></term>
+     <listitem><para>No mounting; prevent <command>apt-cdrom</command> from
+      mounting and unmounting the mount point.
+     Configuration Item: <literal>APT::CDROM::NoMount</literal>.
+     </para>
+     </listitem>
+     </varlistentry>
+     
+     <varlistentry><term><option>-f</option></term><term><option>--fast</option></term>
+     <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</command> has been run on this disc before and did not
+     detect any errors.
+     Configuration Item: <literal>APT::CDROM::Fast</literal>.
+     </para>
+     </listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-a</option></term><term><option>--thorough</option></term>
+     <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.
+     </para>
+     </listitem>
+     </varlistentry>
+     
+     <varlistentry><term><option>-n</option></term>
+                   <term><option>--just-print</option></term>
+                   <term><option>--recon</option></term>
+                   <term><option>--no-act</option></term>
+     <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</literal>.
+     </para>
+     </listitem>
+     </varlistentry> 
+
+     &apt-commonoptions;
+
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>&apt-conf;, &apt-get;, &sources-list;
+   </para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para><command>apt-cdrom</command> returns zero on normal operation, decimal 100 on error.
+   </para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+
+</refentry>
+

doc/apt-config.8.sgml

@@ -1,105 +0,0 @@
-<!-- -*- 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 
-   configuration 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
-   commands below 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>

doc/apt-config.8.xml

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-config</refentrytitle>
+   <manvolnum>8</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-config</refname>
+    <refpurpose>APT Configuration Query program</refpurpose>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-config</command>
+      <arg><option>-hv</option></arg>
+      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
+      <arg><option>-c=<replaceable>file</replaceable></option></arg>
+      <group choice="req">
+         <arg>shell</arg>
+         <arg>dump</arg>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <refsect1><title>Description</title>
+   <para><command>apt-config</command> is an internal program used by various
+   portions of the APT suite to provide consistent configurability. It accesses
+   the main configuration file <filename>/etc/apt/apt.conf</filename> in a
+   manner that is easy to use by scripted applications.</para>
+
+   <para>Unless the <option>-h</option>, or <option>--help</option> option is
+   given one of the commands below 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</option>.</para>
+
+     
+     <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.</para>
+     </listitem>
+     </varlistentry>
+
+     <varlistentry><term>dump</term>
+     <listitem><para>
+     Just show the contents of the configuration space.</para>
+     </listitem>
+     </varlistentry>
+
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>options</title>
+   &apt-cmdblurb;
+   
+   <variablelist>
+   
+     &apt-commonoptions;
+     
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>
+   &apt-conf;
+   </para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para><command>apt-config</command> returns zero on normal operation, decimal 100 on error.
+   </para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
+

doc/apt-extracttemplates.1.sgml

@@ -1,80 +0,0 @@
-<!-- -*- 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-extracttemplates</>
-   <manvolnum>1</>
- </refmeta>
- 
- <!-- Man page title -->
- <refnamediv>
-    <refname>apt-extracttemplates</>
-    <refpurpose>Utility to extract DebConf config and templates from Debian packages</>
- </refnamediv>
-
- <!-- Arguments -->
- <refsynopsisdiv>
-   <cmdsynopsis>
-      <command>apt-extracttemplates</>
-      <arg><option>-hv</></arg>
-      <arg><option>-t=<replaceable/temporary directory/</></arg>
-      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
-   </cmdsynopsis>
- </refsynopsisdiv>
- 
- <RefSect1><Title>Description</>
-   <para>   
-   <command/apt-extracttemplates/ will take one or more Debian package files
-   as input and write out (to a temporary directory) all associated config
-   scripts and template files. For each passed in package that contains 
-   config scripts and templates, one line of output will be generated
-   in the format:
-   <para>
-   package version template-file config-script
-   <para>
-   template-file and config-script are written to the temporary directory
-   specified by the -t or --tempdir (<literal>APT::ExtractTemplates::TempDir</>) 
-   directory, with filenames of the form <filename>package.template.XXXX</> and 
-   <filename>package.config.XXXX</>
- </RefSect1>
- 
- <RefSect1><Title>Options</>
-   &apt-cmdblurb;
-
-   <VariableList>
-     <VarListEntry><term><option/-t/</><term><option/--tempdir/</>
-     <ListItem><Para>
-     Temporary directory in which to write extracted debconf template files
-     and config scripts
-     Configuration Item: <literal/APT::ExtractTemplates::TempDir/.
-     </VarListEntry>
-
-     &apt-commonoptions;
-     
-   </VariableList>
-     
-   
- </RefSect1>
-
- <RefSect1><Title>See Also</>
-   <para>
-   &apt-conf;
- </RefSect1>
-
- <RefSect1><Title>Diagnostics</>
-   <para>
-   <command/apt-extracttemplates/ returns zero on normal operation, decimal 100 on error.
- </RefSect1>
-
- &manbugs;
- &manauthor;
- 
-</refentry>

doc/apt-extracttemplates.1.xml

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-extracttemplates</refentrytitle>
+   <manvolnum>1</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-extracttemplates</refname>
+    <refpurpose>Utility to extract DebConf config and templates from Debian packages</refpurpose>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-extracttemplates</command>
+      <arg><option>-hv</option></arg>
+      <arg><option>-t=<replaceable>temporary directory</replaceable></option></arg>
+      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <refsect1><title>Description</title>
+   <para><command>apt-extracttemplates</command> will take one or more Debian package files
+   as input and write out (to a temporary directory) all associated config
+   scripts and template files. For each passed in package that contains 
+   config scripts and templates, one line of output will be generated
+   in the format:</para>
+   <para>package version template-file config-script</para>
+   <para>template-file and config-script are written to the temporary directory
+   specified by the -t or --tempdir (<literal>APT::ExtractTemplates::TempDir</literal>) 
+   directory, with filenames of the form <filename>package.template.XXXX</filename> and 
+   <filename>package.config.XXXX</filename></para>
+ </refsect1>
+ 
+ <refsect1><title>options</title>
+   &apt-cmdblurb;
+
+   <variablelist>
+     <varlistentry><term><option>-t</option></term><term><option>--tempdir</option></term>
+     <listitem><para>
+     Temporary directory in which to write extracted debconf template files
+     and config scripts
+     Configuration Item: <literal>APT::ExtractTemplates::TempDir</literal></para></listitem>
+     </varlistentry>
+
+     &apt-commonoptions;
+     
+   </variablelist>
+     
+   
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>&apt-conf;</para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para>
+   <command>apt-extracttemplates</command> returns zero on normal operation, decimal 100 on error.</para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>

doc/apt-ftparchive.1.sgml

@@ -1,571 +0,0 @@
-<!-- -*- 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>release <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 its entire functionality via the <literal/packages/ 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
-   commands below 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>release</term>
-     <ListItem><Para>
-     The <literal/release/ command generates a Release file from a
-     directory tree. It recursively searches the given directory for
-     Packages, Packages.gz, Packages.bz2, Sources, Sources.gz,
-     Sources.bz2, Release and md5sum.txt files.  It then writes to
-     stdout a Release file containing an MD5 digest and SHA1 digest
-     for each file.
-     <para>
-     Values for the additional metadata fields in the Release file are
-     taken from the corresponding variables under
-     <literal/APT::FTPArchive::Release/,
-     e.g. <literal/APT::FTPArchive::Release::Origin/.  The supported fields
-     are: <literal/Origin/, <literal/Label/, <literal/Suite/,
-     <literal/Version/, <literal/Codename/, <literal/Date/,
-     <literal/Architectures/, <literal/Components/, <literal/Description/.
-
-     </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 description 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 described 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 
-      [override 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>SrcDirectory</term>
-      <ListItem><Para>
-      Sets the top of the source package directory tree. Defaults to
-      <filename>$(DIST)/$(SECTION)/source/</>
-      </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, 
-      <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, 
-      <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 search 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>
-      
-      <VarListEntry><term>ExtraOverride</term>
-      <ListItem><Para>
-      Sets the binary extra override file. 
-      </VarListEntry>
-      
-      <VarListEntry><term>SrcExtraOverride</term>
-      <ListItem><Para>
-      Sets the source extra override file. 
-      </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>ExtraOverride</term>
-      <ListItem><Para>
-      Sets the binary extra override file.
-      </VarListEntry>
-      
-      <VarListEntry><term>SrcExtraOverride</term>
-      <ListItem><Para>
-      Sets the source extra 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 separated 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>The Extra Override File</>
-   <para>
-   The extra override file allows any arbitrary tag to be added or replaced
-   in the output. It has 3 columns, the first is the package, the second is
-   the tag and the remainder of the line is the new value.
- </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>Examples</>
-
-<para>To create a compressed Packages file for a directory containing
-binary packages (.deb):
-
-<programlisting
-<command/apt-ftparchive/ packages <replaceable/directory/ | <command/gzip/ > <filename/Packages.gz/
-</programlisting>
-
-</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>

doc/apt-ftparchive.1.xml

@@ -0,0 +1,565 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-ftparchive</refentrytitle>
+   <manvolnum>1</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-ftparchive</refname>
+    <refpurpose>Utility to generate index files</refpurpose>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-ftparchive</command>
+      <arg><option>-hvdsq</option></arg>
+      <arg><option>--md5</option></arg>
+      <arg><option>--delink</option></arg>
+      <arg><option>--readonly</option></arg>
+      <arg><option>--contents</option></arg>
+      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
+      <arg><option>-c=<replaceable>file</replaceable></option></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>release <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</title>
+   <para><command>apt-ftparchive</command> 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>
+
+   <para><command>apt-ftparchive</command> is a superset of the &dpkg-scanpackages; program,
+   incorporating its entire functionality via the <literal>packages</literal> command.
+   It also contains a contents file generator, <literal>contents</literal>, and an 
+   elaborate means to 'script' the generation process for a complete 
+   archive.</para>
+
+   <para>Internally <command>apt-ftparchive</command> 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>
+   
+   <para>Unless the <option>-h</option>, or <option>--help</option> option is given one of the
+   commands below must be present.</para>
+   
+   <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>
+
+     <para>The option <option>--db</option> can be used to specify a binary caching DB.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>sources</term>
+     <listitem><para>
+     The <literal>sources</literal> 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>
+     <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.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>contents</term>
+     <listitem><para>
+     The <literal>contents</literal> 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>
+     <para>
+     The option <option>--db</option> can be used to specify a binary caching DB.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>release</term>
+     <listitem><para>
+     The <literal>release</literal> command generates a Release file from a
+     directory tree. It recursively searches the given directory for
+     Packages, Packages.gz, Packages.bz2, Sources, Sources.gz,
+     Sources.bz2, Release and md5sum.txt files.  It then writes to
+     stdout a Release file containing an MD5 digest and SHA1 digest
+     for each file.</para>
+     <para>
+     Values for the additional metadata fields in the Release file are
+     taken from the corresponding variables under
+     <literal>APT::FTPArchive::Release</literal>,
+     e.g. <literal>APT::FTPArchive::Release::Origin</literal>.  The supported fields
+     are: <literal>Origin</literal>, <literal>Label</literal>, <literal>Suite</literal>,
+     <literal>Version</literal>, <literal>Codename</literal>, <literal>Date</literal>,
+     <literal>Architectures</literal>, <literal>Components</literal>, <literal>Description</literal>.</para></listitem>
+
+     </varlistentry>
+
+     <varlistentry><term>generate</term>
+     <listitem><para>
+     The <literal>generate</literal> 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.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>clean</term>
+     <listitem><para>
+     The <literal>clean</literal> command tidies the databases used by the given 
+     configuration file by removing any records that are no longer necessary.</para></listitem>
+     </varlistentry>     
+   </variablelist>  
+ </refsect1>
+
+ <refsect1><title>The Generate Configuration</title>
+   <para>
+   The <literal>generate</literal> 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 description 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>
+
+   <para>
+   The generate configuration has 4 separate sections, each described below.</para>
+
+   <refsect2><title>Dir Section</title>
+     <para>
+     The <literal>Dir</literal> 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.</para>
+     <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</filename> and dist nodes.</para></listitem>
+      </varlistentry>
+
+      <varlistentry><term>OverrideDir</term>
+      <listitem><para>
+      Specifies the location of the override files.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>CacheDir</term>
+      <listitem><para>
+      Specifies the location of the cache files</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>FileListDir</term>
+      <listitem><para>
+      Specifies the location of the file list files, 
+      if the <literal>FileList</literal> setting is used below.</para></listitem>
+      </varlistentry>
+     </variablelist>
+   </refsect2>
+   
+   <refsect2><title>Default Section</title>
+     <para>
+     The <literal>Default</literal> section specifies default values, and settings 
+     that control the operation of the generator. Other sections may override 
+     these defaults with a per-section setting.</para>
+     <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'.</para></listitem>
+      </varlistentry>
+
+      <varlistentry><term>Packages::Extensions</term>
+      <listitem><para>
+      Sets the default list of file extensions that are package files.
+      This defaults to '.deb'.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Sources::Compress</term>
+      <listitem><para>
+      This is similar to <literal>Packages::Compress</literal> 
+      except that it controls the compression for the Sources files.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Sources::Extensions</term>
+      <listitem><para>
+      Sets the default list of file extensions that are source files.
+      This defaults to '.dsc'.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Contents::Compress</term>
+      <listitem><para>
+      This is similar to <literal>Packages::Compress</literal> 
+      except that it controls the compression for the Contents files.</para></listitem>
+      </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</literal> setting.</para></listitem>
+      </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.</para></listitem>
+      </varlistentry>
+     </variablelist>
+   </refsect2>
+   
+   <refsect2><title>TreeDefault Section</title>
+     <para>
+     Sets defaults specific to <literal>Tree</literal> sections. All of these
+     variables are substitution variables and have the strings $(DIST), 
+     $(SECTION) and $(ARCH) replaced with their respective values.</para>
+     
+     <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.</para></listitem>
+      </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 
+      [override 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.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Directory</term>
+      <listitem><para>
+      Sets the top of the .deb directory tree. Defaults to
+      <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/</filename></para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>SrcDirectory</term>
+      <listitem><para>
+      Sets the top of the source package directory tree. Defaults to
+      <filename>$(DIST)/$(SECTION)/source/</filename></para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Packages</term>
+      <listitem><para>
+      Sets the output Packages file. Defaults to 
+      <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/Packages</filename></para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Sources</term>
+      <listitem><para>
+      Sets the output Packages file. Defaults to 
+      <filename>$(DIST)/$(SECTION)/source/Sources</filename></para></listitem>
+      </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)/</filename></para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Contents</term>
+      <listitem><para>
+      Sets the output Contents file. Defaults to
+      <filename>$(DIST)/Contents-$(ARCH)</filename>. If this setting causes multiple 
+      Packages files to map onto a single Contents file (such as the default) 
+      then <command>apt-ftparchive</command> will integrate those package files 
+      together automatically.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Contents::Header</term>
+      <listitem><para>
+      Sets header file to prepend to the contents output.</para></listitem>
+      </varlistentry>
+
+      <varlistentry><term>BinCacheDB</term>
+      <listitem><para>
+      Sets the binary cache database to use for this 
+      section. Multiple sections can share the same database.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>FileList</term>
+      <listitem><para>
+      Specifies that instead of walking the directory tree, 
+      <command>apt-ftparchive</command> should read the list of files from the given 
+      file. Relative files names are prefixed with the archive directory.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>SourceFileList</term>
+      <listitem><para>
+      Specifies that instead of walking the directory tree, 
+      <command>apt-ftparchive</command> 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.</para></listitem>
+      </varlistentry>
+     </variablelist>     
+   </refsect2>
+   
+   <refsect2><title>Tree Section</title>
+     <para>
+     The <literal>Tree</literal> 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</literal> substitution variable.</para> 
+     <para>
+     The <literal>Tree</literal> section takes a scope tag which sets the 
+     <literal>$(DIST)</literal> variable and defines the root of the tree 
+     (the path is prefixed by <literal>ArchiveDir</literal>).
+     Typically this is a setting such as <filename>dists/woody</filename>.</para>
+     <para>
+     All of the settings defined in the <literal>TreeDefault</literal> section can be
+     use in a <literal>Tree</literal> section as well as three new variables.</para>
+     <para>
+     When processing a <literal>Tree</literal> section <command>apt-ftparchive</command> 
+     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></para>
+
+     <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</literal></para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Architectures</term>
+      <listitem><para>
+      This is a space separated list of all the 
+      architectures that appear under search section. The special architecture 
+      'source' is used to indicate that this tree has a source archive.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>BinOverride</term>
+      <listitem><para>
+      Sets the binary override file. The override file 
+      contains section, priority and maintainer address information.</para></listitem>
+      </varlistentry>
+
+      <varlistentry><term>SrcOverride</term>
+      <listitem><para>
+      Sets the source override file. The override file 
+      contains section information.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>ExtraOverride</term>
+      <listitem><para>
+      Sets the binary extra override file.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>SrcExtraOverride</term>
+      <listitem><para>
+      Sets the source extra override file.</para></listitem> 
+      </varlistentry>
+     </variablelist>
+   </refsect2>
+   
+   <refsect2><title>BinDirectory Section</title>
+     <para>
+     The <literal>bindirectory</literal> 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</literal> 
+     section with no substitution variables or
+     <literal>Section</literal><literal>Architecture</literal> settings.</para>
+     <variablelist>
+      <varlistentry><term>Packages</term>
+      <listitem><para>
+      Sets the Packages file output.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>SrcPackages</term>
+      <listitem><para>
+      Sets the Sources file output. At least one of
+      <literal>Packages</literal> or <literal>SrcPackages</literal> is required.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>Contents</term>
+      <listitem><para>
+      Sets the Contents file output. (optional)</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>BinOverride</term>
+      <listitem><para>
+      Sets the binary override file.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>SrcOverride</term>
+      <listitem><para>
+      Sets the source override file.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>ExtraOverride</term>
+      <listitem><para>
+      Sets the binary extra override file.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>SrcExtraOverride</term>
+      <listitem><para>
+      Sets the source extra override file.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>BinCacheDB</term>
+      <listitem><para>
+      Sets the cache DB.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>PathPrefix</term>
+      <listitem><para>
+      Appends a path to all the output paths.</para></listitem>
+      </varlistentry>
+      
+      <varlistentry><term>FileList, SourceFileList</term>
+      <listitem><para>
+      Specifies the file list file.</para></listitem>
+      </varlistentry>
+     </variablelist>
+   </refsect2>
+ </refsect1>
+
+
+ <refsect1><title>The Binary Override File</title>
+   <para>The binary override file is fully compatible with &dpkg-scanpackages;. It
+   contains 4 fields separated 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>
+   <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.</para>
+ </refsect1>
+
+ 
+ <refsect1><title>The Source Override File</title>
+   <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.</para>
+ </refsect1>   
+
+ <refsect1><title>The Extra Override File</title>
+   <para>
+   The extra override file allows any arbitrary tag to be added or replaced
+   in the output. It has 3 columns, the first is the package, the second is
+   the tag and the remainder of the line is the new value.</para>
+ </refsect1>   
+
+ <refsect1><title>options</title>
+   &apt-cmdblurb;
+   
+   <variablelist>
+     <varlistentry><term><option>--md5</option></term>
+     <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</literal></para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-d</option></term><term><option>--db</option></term>
+     <listitem><para>
+     Use a binary caching DB. This has no effect on the generate command.
+     Configuration Item: <literal>APT::FTPArchive::DB</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-q</option></term><term><option>--quiet</option></term>
+     <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=#</option> to set the quiet level, overriding the configuration file. 
+     Configuration Item: <literal>quiet</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--delink</option></term>
+     <listitem><para>
+     Perform Delinking. If the <literal>External-Links</literal> 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</option>.
+     Configuration Item: <literal>APT::FTPArchive::DeLinkAct</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--contents</option></term>
+     <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</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-s</option></term><term><option>--source-override</option></term>
+     <listitem><para>
+     Select the source override file to use with the <literal>sources</literal> command.
+     Configuration Item: <literal>APT::FTPArchive::SourceOverride</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--readonly</option></term>
+     <listitem><para>
+     Make the caching databases read only. 
+     Configuration Item: <literal>APT::FTPArchive::ReadOnlyDB</literal>.</para></listitem>
+     </varlistentry>   
+   
+     &apt-commonoptions;
+     
+   </variablelist>
+ </refsect1>
+
+<refsect1><title>Examples</title>
+
+<para>To create a compressed Packages file for a directory containing
+binary packages (.deb):
+
+<programlisting>
+<command>apt-ftparchive</command> packages <replaceable>directory</replaceable> | <command>gzip</command> > <filename>Packages.gz</filename>
+</programlisting></para>
+
+</refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>&apt-conf;</para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para><command>apt-ftparchive</command> returns zero on normal operation, decimal 100 on error.</para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>

doc/apt-get.8.sgml

@@ -1,512 +0,0 @@
-<!-- -*- 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-get</>
-      <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.  Several "front-end" interfaces exist, such as dselect(8),
-   aptitude, synaptic, gnome-apt and wajig.
-   <para>
-   Unless the <option/-h/, or <option/--help/ option is given, one of the
-   commands below 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>   
-     <literal/dselect-upgrade/
-     is used in conjunction with the traditional Debian 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.
-     See also &apt-preferences; for a mechanism for
-     overriding the general settings for individual packages.
-     </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 <literal/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 
-     install. These latter features 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, testing, unstable).
-     <para>
-     Both of the version selection mechanisms can downgrade packages and must
-     be used with care.
-     <para>
-     Finally, the &apt-preferences; mechanism allows you to
-     create an alternative installation policy for
-     individual packages.
-     <para>
-     If no package matches the given expression and the expression contains one
-     of '.', '?' or '*' then it is assumed to be a POSIX regular expression,
-     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, anchor the regular expression
-     with a '^' or '$' character, or create a more specific regular expression.
-     </VarListEntry>
-
-     <VarListEntry><Term>remove</Term>
-     <ListItem><Para>   
-     <literal/remove/ is identical to <literal/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 instead of removed.
-     </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 package.
-     </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;/archives/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 to 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 solution. Any Package that are specified
-     must completely 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/-V/</><term><option/--verbose-versions/</>
-     <ListItem><Para>
-     Show full versions for upgraded and installed packages.
-     Configuration Item: <literal/APT::Get::Show-Versions/.
-     </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 on the command linefrom 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 
-     <literal/source/ and <literal/update/ commands. When used with the
-     <literal/update/ command the MD5 and size are not included, and it is
-     up to the user to decompress any compressed files.
-     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.
-     An asterisk ("*") will be displayed next to packages which are
-     scheduled to be purged.
-     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 be 
-     <option>-t '2.1*'</> or <option>-t unstable</>.
-     Configuration Item: <literal/APT::Default-Release/;
-     see also the &apt-preferences; manual page.
-     </VarListEntry>
-
-     <VarListEntry><term><option/--trivial-only/</>
-     <ListItem><Para>
-     Only perform operations that 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.  This means that if this option is specified, the
-     <literal/source/ command will only accept source package names as
-     arguments, rather than accepting binary package names and looking
-     up the corresponding source package.
-     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>
-     
-     <VarListEntry><term><option/--arch-only/</>
-     <ListItem><Para>
-     Only process architecture-dependent build-dependencies.
-     Configuration Item: <literal/APT::Get::Arch-Only/ 
-     </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>/etc/apt/apt.conf</></term>
-     <ListItem><Para>
-     APT configuration file.
-     Configuration Item: <literal/Dir::Etc::Main/.
-     </VarListEntry>
-     
-     <VarListEntry><term><filename>/etc/apt/apt.conf.d/</></term>
-     <ListItem><Para>
-     APT configuration file fragments
-     Configuration Item: <literal/Dir::Etc::Parts/.
-     </VarListEntry>
-     
-     <VarListEntry><term><filename>/etc/apt/preferences</></term>
-     <ListItem><Para>
-     Version preferences file.
-     This is where you would specify "pinning",
-     i.e. a preference to get certain packages
-     from a separate source
-     or from a different version of a distribution.
-     Configuration Item: <literal/Dir::Etc::Preferences/.
-     </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;, &apt-cdrom;, &dpkg;, &dselect;, &sources-list;,
-   &apt-conf;, &apt-config;,
-   The APT User's guide in &docdir;, &apt-preferences;, the APT Howto.
- </RefSect1>
-
- <RefSect1><Title>Diagnostics</>
-   <para>
-   <command/apt-get/ returns zero on normal operation, decimal 100 on error.
- </RefSect1>
-
- &manbugs;
- &manauthor;
- 
-</refentry>

doc/apt-get.8.xml

@@ -0,0 +1,466 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ <!--<date>14 December 2003</date> -->
+ 
+ <refmeta>
+   <refentrytitle>apt-get</refentrytitle>
+   <manvolnum>8</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-get</refname>
+    <refpurpose>APT package handling utility -- command-line interface</refpurpose>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-get</command>
+      <arg><option>-hvs</option></arg>
+      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
+      <arg><option>-c=<replaceable>file</replaceable></option></arg>
+      <group choice="req">
+         <arg>update</arg>
+         <arg>upgrade</arg>
+         <arg>dselect-upgrade</arg>
+         <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>
+         <arg>clean</arg>
+         <arg>autoclean</arg>
+      </group>   
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <refsect1><title>Description</title>
+   <para><command>apt-get</command> is the command-line tool for handling packages, and may be 
+   considered the user's "back-end" to other tools using the APT
+   library.  Several "front-end" interfaces exist, such as dselect(8),
+   aptitude, synaptic, gnome-apt and wajig.</para>
+
+   <para>Unless the <option>-h</option>, or <option>--help</option> option is given, one of the
+   commands below must be present.</para>
+   
+   <variablelist>
+     <varlistentry><term>update</term>
+     <listitem><para><literal>update</literal> 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</filename>.
+     For example, when using a Debian archive, this command retrieves and
+     scans the <filename>Packages.gz</filename> files, so that information about new 
+     and updated packages is available. An <literal>update</literal> should always be 
+     performed before an <literal>upgrade</literal> or <literal>dist-upgrade</literal>. Please 
+     be aware that the overall progress meter will be incorrect as the size 
+     of the package files cannot be known in advance.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>upgrade</term>
+     <listitem><para><literal>upgrade</literal> 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</filename>. 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</literal> must be 
+     performed first so that <command>apt-get</command> knows that new versions of packages are 
+     available.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>dselect-upgrade</term>
+     <listitem><para><literal>dselect-upgrade</literal>
+     is used in conjunction with the traditional Debian packaging
+     front-end, &dselect;. <literal>dselect-upgrade</literal>
+     follows the changes made by &dselect; to the <literal>Status</literal>
+     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).</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>dist-upgrade</term>
+     <listitem><para><literal>dist-upgrade</literal> in addition to performing the function of 
+     <literal>upgrade</literal>, also intelligently handles changing dependencies 
+     with new versions of packages; <command>apt-get</command> 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</filename> file contains a list of locations 
+     from which to retrieve desired package files.
+     See also &apt-preferences; for a mechanism for
+     overriding the general settings for individual packages.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>install</term>
+     <listitem><para><literal>install</literal> 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 <literal>libc6_1.9.6-2.deb</literal>) All packages required 
+     by the package(s) specified for installation will also be retrieved and 
+     installed. The <filename>/etc/apt/sources.list</filename> 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 
+     install. These latter features may be used to override decisions made by 
+     apt-get's conflict resolution system.</para>
+
+     <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, testing, unstable).</para>
+
+     <para>Both of the version selection mechanisms can downgrade packages and must
+     be used with care.</para>
+
+     <para>Finally, the &apt-preferences; mechanism allows you to
+     create an alternative installation policy for
+     individual packages.</para>
+
+     <para>If no package matches the given expression and the expression contains one
+     of '.', '?' or '*' then it is assumed to be a POSIX regular expression,
+     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, anchor the regular expression
+     with a '^' or '$' character, or create a more specific regular expression.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>remove</term>
+     <listitem><para><literal>remove</literal> is identical to <literal>install</literal> 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 instead of removed.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>source</term>
+     <listitem><para><literal>source</literal> causes <command>apt-get</command> 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</literal> 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>
+
+     <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</literal> option.</para>
+     
+     <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.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>build-dep</term>
+     <listitem><para><literal>build-dep</literal> causes apt-get to install/remove packages in an 
+     attempt to satisfy the build dependencies for a source package.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>check</term>
+     <listitem><para><literal>check</literal> is a diagnostic tool; it updates the package cache and checks 
+     for broken dependencies.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>clean</term>
+     <listitem><para><literal>clean</literal> clears out the local repository of retrieved package 
+     files. It removes everything but the lock file from 
+     <filename>&cachedir;/archives/</filename> and 
+     <filename>&cachedir;/archives/partial/</filename>. When APT is used as a 
+     &dselect; method, <literal>clean</literal> is run automatically.
+     Those who do not use dselect will likely want to run <literal>apt-get clean</literal>
+     from time to time to free up disk space.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>autoclean</term>
+     <listitem><para>Like <literal>clean</literal>, <literal>autoclean</literal> 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</literal> will prevent installed packages from being
+     erased if it is set to off.</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+ 
+ <refsect1><title>options</title>
+   &apt-cmdblurb;
+
+   <variablelist>
+     <varlistentry><term><option>-d</option></term><term><option>--download-only</option></term>
+     <listitem><para>Download only; package files are only retrieved, not unpacked or installed.
+     Configuration Item: <literal>APT::Get::Download-Only</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-f</option></term><term><option>--fix-broken</option></term>
+     <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 solution. Any Package that are specified
+     must completely 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</command> to eliminate some of 
+     the offending packages). Use of this option together with <option>-m</option> may produce an
+     error in some situations. 
+     Configuration Item: <literal>APT::Get::Fix-Broken</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-m</option></term><term><option>--ignore-missing</option></term>
+     <term><option>--fix-missing</option></term>
+     <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</option> 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</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--no-download</option></term>
+     <listitem><para>Disables downloading of packages. This is best used with 
+     <option>--ignore-missing</option> to force APT to use only the .debs it has 
+     already downloaded.
+     Configuration Item: <literal>APT::Get::Download</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-q</option></term><term><option>--quiet</option></term>
+     <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=#</option> to set the quiet level, overriding the configuration file. 
+     Note that quiet level 2 implies <option>-y</option>, 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</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-s</option></term>
+                   <term><option>--simulate</option></term>
+		   <term><option>--just-print</option></term>
+		   <term><option>--dry-run</option></term>
+		   <term><option>--recon</option></term>
+		   <term><option>--no-act</option></term>
+     <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</literal>.</para>
+
+     <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).</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-y</option></term><term><option>--yes</option></term>
+                   <term><option>--assume-yes</option></term>
+     <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</literal> 
+     will abort. 
+     Configuration Item: <literal>APT::Get::Assume-Yes</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-u</option></term><term><option>--show-upgraded</option></term>
+     <listitem><para>Show upgraded packages; Print out a list of all packages that are to be
+     upgraded. 
+     Configuration Item: <literal>APT::Get::Show-Upgraded</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-V</option></term><term><option>--verbose-versions</option></term>
+     <listitem><para>Show full versions for upgraded and installed packages.
+     Configuration Item: <literal>APT::Get::Show-Versions</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-b</option></term><term><option>--compile</option></term>
+                   <term><option>--build</option></term>
+     <listitem><para>Compile source packages after downloading them.
+     Configuration Item: <literal>APT::Get::Compile</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--ignore-hold</option></term>
+     <listitem><para>Ignore package Holds; This causes <command>apt-get</command> to ignore a hold 
+     placed on a package. This may be useful in conjunction with 
+     <literal>dist-upgrade</literal> to override a large number of undesired holds. 
+     Configuration Item: <literal>APT::Ignore-Hold</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--no-upgrade</option></term>
+     <listitem><para>Do not upgrade packages; When used in conjunction with <literal>install</literal>,
+     <literal>no-upgrade</literal> will prevent packages on the command line
+     from being upgraded if they are already installed.
+     Configuration Item: <literal>APT::Get::Upgrade</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--force-yes</option></term>
+     <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</literal> can potentially destroy your system! 
+     Configuration Item: <literal>APT::Get::force-yes</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--print-uris</option></term>
+     <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 
+     <literal>source</literal> and <literal>update</literal> commands. When used with the
+     <literal>update</literal> command the MD5 and size are not included, and it is
+     up to the user to decompress any compressed files.
+     Configuration Item: <literal>APT::Get::Print-URIs</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--purge</option></term>
+     <listitem><para>Use purge instead of remove for anything that would be removed.
+     An asterisk ("*") will be displayed next to packages which are
+     scheduled to be purged.
+     Configuration Item: <literal>APT::Get::Purge</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--reinstall</option></term>
+     <listitem><para>Re-Install packages that are already installed and at the newest version.
+     Configuration Item: <literal>APT::Get::ReInstall</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--list-cleanup</option></term>
+     <listitem><para>This option defaults to on, use <literal>--no-list-cleanup</literal> to turn it 
+     off. When on <command>apt-get</command> will automatically manage the contents of 
+     <filename>&statedir;/lists</filename> 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</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>-t</option></term>
+                   <term><option>--target-release</option></term>
+                   <term><option>--default-release</option></term>
+     <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 be 
+     <option>-t '2.1*'</option> or <option>-t unstable</option>.
+     Configuration Item: <literal>APT::Default-Release</literal>;
+     see also the &apt-preferences; manual page.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--trivial-only</option></term>
+     <listitem><para>
+     Only perform operations that are 'trivial'. Logically this can be considered
+     related to <option>--assume-yes</option>, where <option>--assume-yes</option> will answer 
+     yes to any prompt, <option>--trivial-only</option> will answer no. 
+     Configuration Item: <literal>APT::Get::Trivial-Only</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--no-remove</option></term>
+     <listitem><para>If any packages are to be removed apt-get immediately aborts without
+     prompting. 
+     Configuration Item: <literal>APT::Get::Remove</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--only-source</option></term>
+     <listitem><para>Only has meaning for the <literal>source</literal> command.  Indicates that the
+     given source names are not to be mapped through the binary
+     table.  This means that if this option is specified, the
+     <literal>source</literal> command will only accept source package names as
+     arguments, rather than accepting binary package names and looking
+     up the corresponding source package.
+     Configuration Item: <literal>APT::Get::Only-Source</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term><option>--diff-only</option></term><term><option>--tar-only</option></term>
+     <listitem><para>Download only the diff or tar file of a source archive. 
+     Configuration Item: <literal>APT::Get::Diff-Only</literal> and 
+     <literal>APT::Get::Tar-Only</literal>.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><option>--arch-only</option></term>
+     <listitem><para>Only process architecture-dependent build-dependencies.
+     Configuration Item: <literal>APT::Get::Arch-Only</literal>.</para></listitem>
+     </varlistentry>
+     
+     &apt-commonoptions;
+     
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>Files</title>
+   <variablelist>
+     <varlistentry><term><filename>/etc/apt/sources.list</filename></term>
+     <listitem><para>Locations to fetch packages from.
+     Configuration Item: <literal>Dir::Etc::SourceList</literal>.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><filename>/etc/apt/apt.conf</filename></term>
+     <listitem><para>APT configuration file.
+     Configuration Item: <literal>Dir::Etc::Main</literal>.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><filename>/etc/apt/apt.conf.d/</filename></term>
+     <listitem><para>APT configuration file fragments
+     Configuration Item: <literal>Dir::Etc::Parts</literal>.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><filename>/etc/apt/preferences</filename></term>
+     <listitem><para>Version preferences file.
+     This is where you would specify "pinning",
+     i.e. a preference to get certain packages
+     from a separate source
+     or from a different version of a distribution.
+     Configuration Item: <literal>Dir::Etc::Preferences</literal>.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><filename>&cachedir;/archives/</filename></term>
+     <listitem><para>Storage area for retrieved package files.
+     Configuration Item: <literal>Dir::Cache::Archives</literal>.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><filename>&cachedir;/archives/partial/</filename></term>
+     <listitem><para>Storage area for package files in transit.
+     Configuration Item: <literal>Dir::Cache::Archives</literal> (implicit partial). </para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term><filename>&statedir;/lists/</filename></term>
+     <listitem><para>Storage area for state information for each package resource specified in
+     &sources-list;
+     Configuration Item: <literal>Dir::State::Lists</literal>.</para></listitem>
+     </varlistentry>
+  
+     <varlistentry><term><filename>&statedir;/lists/partial/</filename></term>
+     <listitem><para> Storage area for state information in transit.
+     Configuration Item: <literal>Dir::State::Lists</literal> (implicit partial).</para></listitem>
+     </varlistentry>     
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>&apt-cache;, &apt-cdrom;, &dpkg;, &dselect;, &sources-list;,
+   &apt-conf;, &apt-config;,
+   The APT User's guide in &docdir;, &apt-preferences;, the APT Howto.</para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para><command>apt-get</command> returns zero on normal operation, decimal 100 on error.</para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>

doc/apt-sortpkgs.1.sgml

@@ -1,73 +0,0 @@
-<!-- -*- 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-sortpkgs</>
-      <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>

doc/apt-sortpkgs.1.xml

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-sortpkgs</refentrytitle>
+   <manvolnum>1</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt-sortpkgs</refname>
+    <refpurpose>Utility to sort package index files</refpurpose>
+ </refnamediv>
+
+ <!-- Arguments -->
+ <refsynopsisdiv>
+   <cmdsynopsis>
+      <command>apt-sortpkgs</command>
+      <arg><option>-hvs</option></arg>
+      <arg><option>-o=<replaceable>config string</replaceable></option></arg>
+      <arg><option>-c=<replaceable>file</replaceable></option></arg>
+      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
+   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <refsect1><title>Description</title>
+   <para><command>apt-sortpkgs</command> 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>
+
+   <para>
+   All output is sent to stdout, the input must be a seekable file.</para>
+ </refsect1>
+ 
+ <refsect1><title>options</title>
+   &apt-cmdblurb;
+   
+   <variablelist>
+     <varlistentry><term><option>-s</option></term><term><option>--source</option></term>
+     <listitem><para>
+     Use Source index field ordering.
+     Configuration Item: <literal>APT::SortPkgs::Source</literal>.</para></listitem>
+     </varlistentry>
+   
+     &apt-commonoptions;
+     
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>See Also</title>
+   <para>&apt-conf;</para>
+ </refsect1>
+
+ <refsect1><title>Diagnostics</title>
+   <para><command>apt-sortpkgs</command> returns zero on normal operation, decimal 100 on error.</para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>

doc/apt.conf.5.sgml

@@ -1,415 +0,0 @@
-<!-- -*- 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>Configuration 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.  Lines starting with
-   <literal>//</literal> are treated as comments (ignored).  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 separated 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 arbitrary 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 behavior 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 option 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 packages
-     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 Immediate 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>Build-Essential</Term>
-     <ListItem><Para>
-     Defines which package(s) are considered essential build dependencies.
-     </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 determines 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 compliant 
-     proxy caches. <literal/No-Cache/ tells the proxy to not use 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 occur. 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 
-     overridden 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 preferences 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/Dir::Bin::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 behaviour. These are in the <literal/DSelect/ section.
-   
-   <VariableList>
-     <VarListEntry><Term>Clean</Term>
-     <ListItem><Para>
-     Cache Clean mode; this value may be one of always, prompt, auto,
-     pre-auto and never.  always and prompt will remove all packages from
-     the cache after upgrading, prompt (the default) does so conditionally. 
-     auto removes only those packages which are no longer downloadable
-     (replaced with a new version for instance).  pre-auto performs this
-     action before downloading new packages.
-     </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 argument
-     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-config;<!-- ? reading apt.conf -->, &apt-preferences;.
- </RefSect1>
-
- &manbugs;
- &manauthor;
- 
-</refentry>

doc/apt.conf.5.xml

@@ -0,0 +1,389 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt.conf</refentrytitle>
+   <manvolnum>5</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>apt.conf</refname>
+    <refpurpose>Configuration file for APT</refpurpose>
+ </refnamediv>
+ 
+ <refsect1><title>Description</title>
+   <para><filename>apt.conf</filename> 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</envar> environment 
+   variable (if any) and then read the files in <literal>Dir::Etc::Parts</literal> 
+   then read the main configuration file specified by 
+   <literal>Dir::Etc::main</literal> then finally apply the
+   command line options to override the configuration directives, possibly 
+   loading even more config files.</para>
+
+   <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</literal> is an option within 
+   the APT tool group, for the Get tool. options do not inherit from their 
+   parent groups.</para> 
+
+   <para>Syntacticly the configuration language is modeled after what the ISC tools
+   such as bind and dhcp use.  Lines starting with
+   <literal>//</literal> are treated as comments (ignored).
+   Each line is of the form
+   <literal>APT::Get::Assume-Yes "true";</literal> The trailing 
+   semicolon is required and the quotes are optional. A new scope can be
+   opened with curly braces, like:</para>
+
+<informalexample><programlisting>   
+APT {
+  Get {
+    Assume-Yes "true";
+    Fix-Broken "true";
+  };
+};
+</programlisting></informalexample>
+
+   <para>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 separated by a semicolon.</para>
+
+<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</filename> &configureindex;
+   is a good guide for how it should look.</para>
+
+   <para>Two specials are allowed, <literal>#include</literal> and <literal>#clear</literal> 
+   <literal>#include</literal> will include the given file, unless the filename
+   ends in a slash, then the whole directory is included.  
+   <literal>#clear</literal> is used to erase a list of names.</para>
+
+   <para>All of the APT tools take a -o option which allows an arbitrary configuration 
+   directive to be specified on the command line. The syntax is a full option
+   name (<literal>APT::Get::Assume-Yes</literal> 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.</para>
+ </refsect1>
+
+ <refsect1><title>The APT Group</title>
+   <para>This group of options controls general APT behavior as well as holding the
+   options for all of the tools.</para>
+
+   <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.</para></listitem>
+     </varlistentry>
+     
+     <varlistentry><term>Ignore-Hold</term>
+     <listitem><para>Ignore Held packages; This global option causes the problem resolver to
+     ignore held packages in its decision making.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>Clean-Installed</term>
+     <listitem><para>Defaults to on. When turned on the autoclean feature will remove any packages
+     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.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>Immediate-Configure</term>
+     <listitem><para>Disable Immediate 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.</para></listitem>
+     </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.</para></listitem>
+     </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.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>Build-Essential</term>
+     <listitem><para>Defines which package(s) are considered essential build dependencies.</para></listitem>
+     </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.</para></listitem>
+     </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.</para></listitem>
+     </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.</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>The Acquire Group</title>
+   <para>The <literal>Acquire</literal> 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</literal> can be one of <literal>host</literal> or 
+     <literal>access</literal> which determines how  APT parallelizes outgoing 
+     connections. <literal>host</literal> means that one connection per target host 
+     will be opened, <literal>access</literal> means that one connection per URI type 
+     will be opened.</para></listitem>
+     </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.</para></listitem>
+     </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.</para></listitem>
+     </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]/</literal>. Per 
+     host proxies can also be specified by using the form 
+     <literal>http::Proxy::&lt;host&gt;</literal> with the special keyword <literal>DIRECT</literal> 
+     meaning to use no proxies. The <envar>http_proxy</envar> environment variable
+     will override all settings.</para>
+
+     <para>Three settings are provided for cache control with HTTP/1.1 compliant 
+     proxy caches. <literal>No-Cache</literal> tells the proxy to not use its cached 
+     response under any circumstances, <literal>Max-Age</literal> 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</literal> 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>
+
+     <para>The option <literal>timeout</literal> sets the timeout timer used by the method, 
+     this applies to all things including connection timeout and data timeout.</para>
+
+     <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</literal> 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 occur. Hosts which
+     require this are in violation of RFC 2068.</para></listitem>
+     </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]/</literal> and is 
+     overridden by the <envar>ftp_proxy</envar> environment variable. To use a ftp 
+     proxy you will have to set the <literal>ftp::ProxyLogin</literal> 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> <literal>$(PROXY_PASS)</literal> <literal>$(SITE_USER)</literal>
+     <literal>$(SITE_PASS)</literal> <literal>$(SITE)</literal> and <literal>$(SITE_PORT)</literal>
+     Each is taken from it's respective URI component.</para>
+
+     <para>The option <literal>timeout</literal> sets the timeout timer used by the method, 
+     this applies to all things including connection timeout and data timeout.</para>
+
+     <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>
+
+     <para>It is possible to proxy FTP over HTTP by setting the <envar>ftp_proxy</envar>
+     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>
+
+     <para>The setting <literal>ForceExtended</literal> controls the use of RFC2428 
+     <literal>EPSV</literal> and <literal>EPRT</literal> 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.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>cdrom</term>
+     <listitem><para>CDROM URIs; the only setting for CDROM URIs is the mount point, 
+     <literal>cdrom::Mount</literal> which must be the mount point for the CDROM drive 
+     as specified in <filename>/etc/fstab</filename>. 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.</para></listitem>
+     </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1><title>Directories</title>
+
+   <para>The <literal>Dir::State</literal> section has directories that pertain to local 
+   state information. <literal>lists</literal> is the directory to place downloaded 
+   package lists in and <literal>status</literal> is the name of the dpkg status file.
+   <literal>preferences</literal> is the name of the APT preferences file.
+   <literal>Dir::State</literal> contains the default directory to prefix on all sub 
+   items if they do not start with <filename>/</filename> or <filename>./</filename>.</para>
+
+   <para><literal>Dir::Cache</literal> contains locations pertaining to local cache 
+   information, such as the two package caches <literal>srcpkgcache</literal> and 
+   <literal>pkgcache</literal> as well as the location to place downloaded archives, 
+   <literal>Dir::Cache::archives</literal>. 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</literal> the default
+   directory is contained in <literal>Dir::Cache</literal></para>
+
+   <para><literal>Dir::Etc</literal> contains the location of configuration files, 
+   <literal>sourcelist</literal> gives the location of the sourcelist and 
+   <literal>main</literal> is the default configuration file (setting has no effect,
+   unless it is done from the config file specified by 
+   <envar>APT_CONFIG</envar>.</para>
+
+   <para>The <literal>Dir::Parts</literal> 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>
+
+   <para>Binary programs are pointed to by <literal>Dir::Bin</literal>. <literal>Dir::Bin::Methods</literal> 
+   specifies the location of the method handlers and <literal>gzip</literal>, 
+   <literal>dpkg</literal>, <literal>apt-get</literal> <literal>dpkg-source</literal> 
+   <literal>dpkg-buildpackage</literal> and <literal>apt-cache</literal> specify the location
+   of the respective programs.</para>
+ </refsect1>
+ 
+ <refsect1><title>APT in DSelect</title>
+   <para>   
+   When APT is used as a &dselect; method several configuration directives
+   control the default behaviour. These are in the <literal>DSelect</literal> section.</para>
+   
+   <variablelist>
+     <varlistentry><term>Clean</term>
+     <listitem><para>Cache Clean mode; this value may be one of always, prompt, auto,
+     pre-auto and never.  always and prompt will remove all packages from
+     the cache after upgrading, prompt (the default) does so conditionally. 
+     auto removes only those packages which are no longer downloadable
+     (replaced with a new version for instance).  pre-auto performs this
+     action before downloading new packages.</para></listitem>
+     </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.</para></listitem>
+     </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.</para></listitem>
+     </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.</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+ 
+ <refsect1><title>How APT calls dpkg</title>
+   <para>Several configuration directives control how APT invokes &dpkg;. These are 
+   in the <literal>DPkg</literal> section.</para>
+
+   <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 argument
+     to &dpkg;.</para></listitem>
+     </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</literal> this must be specified in list notation. The 
+     commands are invoked in order using <filename>/bin/sh</filename>, should any 
+     fail APT will abort.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>Pre-Install-Pkgs</term>
+     <listitem><para>This is a list of shell commands to run before invoking dpkg. Like
+     <literal>options</literal> this must be specified in list notation. The commands
+     are invoked in order using <filename>/bin/sh</filename>, 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>
+
+     <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</literal> to 2. <literal>cmd</literal> is a
+     command given to <literal>Pre-Install-Pkgs</literal>.</para></listitem>
+     </varlistentry>
+
+     <varlistentry><term>Run-Directory</term>
+     <listitem><para>APT chdirs to this directory before invoking dpkg, the default is 
+     <filename>/</filename>.</para></listitem>
+     </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.</para></listitem>
+     </varlistentry>
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>Debug options</title>
+   <para>Most of the options in the <literal>debug</literal> section are not interesting to 
+   the normal user, however <literal>Debug::pkgProblemResolver</literal> shows 
+   interesting output about the decisions dist-upgrade makes. 
+   <literal>Debug::NoLocking</literal> disables file locking so APT can do some 
+   operations as non-root and <literal>Debug::pkgDPkgPM</literal> will print out the 
+   command line for each dpkg invokation. <literal>Debug::IdentCdrom</literal> will 
+   disable the inclusion of statfs data in CDROM IDs.</para>
+ </refsect1>
+ 
+ <refsect1><title>Examples</title>
+   <para>&configureindex; contains a 
+   sample configuration file showing the default values for all possible 
+   options.</para>
+ </refsect1>
+ 
+ <refsect1><title>Files</title>
+   <para><filename>/etc/apt/apt.conf</filename></para>
+ </refsect1>
+ 
+ <refsect1><title>See Also</title>
+   <para>&apt-cache;, &apt-config;<!-- ? reading apt.conf -->, &apt-preferences;.</para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
+

doc/apt.ent

@@ -2,144 +2,182 @@
 
 <!-- Some common paths.. -->
 <!ENTITY docdir "/usr/share/doc/apt/">
-<!ENTITY configureindex "<filename>&docdir;examples/configure-index.gz</>">
-<!ENTITY aptconfdir "<filename>/etc/apt.conf</>">
+<!ENTITY configureindex "<filename>&docdir;examples/configure-index.gz</filename>">
+<!ENTITY aptconfdir "<filename>/etc/apt.conf</filename>">
 <!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-config "<CiteRefEntry>
-    <RefEntryTitle><command/apt-config/</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 apt-preferences "<CiteRefEntry>
-    <RefEntryTitle><command/apt_preferences/</RefEntryTitle>
-    <ManVolNum/5/
-  </CiteRefEntry>">
-
-<!ENTITY sources-list "<CiteRefEntry>
-    <RefEntryTitle><filename/sources.list/</RefEntryTitle>
-    <ManVolNum/5/
-  </CiteRefEntry>">
-
-<!ENTITY reportbug "<CiteRefEntry>
-    <RefEntryTitle><command/reportbug/</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>">
+<!ENTITY apt-conf "<citerefentry>
+    <refentrytitle><filename>apt.conf</filename></refentrytitle>
+    <manvolnum>5</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY apt-get "<citerefentry>
+    <refentrytitle><command>apt-get</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY apt-config "<citerefentry>
+    <refentrytitle><command>apt-config</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY apt-cdrom "<citerefentry>
+    <refentrytitle><command>apt-cdrom</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY apt-cache "<citerefentry>
+    <refentrytitle><command>apt-cache</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY apt-preferences "<citerefentry>
+    <refentrytitle><command>apt_preferences</command></refentrytitle>
+    <manvolnum>5</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY sources-list "<citerefentry>
+    <refentrytitle><filename>sources.list</filename></refentrytitle>
+    <manvolnum>5</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY reportbug "<citerefentry>
+    <refentrytitle><command>reportbug</command></refentrytitle>
+    <manvolnum>1</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY dpkg "<citerefentry>
+    <refentrytitle><command>dpkg</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY dpkg-buildpackage "<citerefentry>
+    <refentrytitle><command>dpkg-buildpackage</command></refentrytitle>
+    <manvolnum>1</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY gzip "<citerefentry>
+    <refentrytitle><command>gzip</command></refentrytitle>
+    <manvolnum>1</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY dpkg-scanpackages "<citerefentry>
+    <refentrytitle><command>dpkg-scanpackages</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY dpkg-scansources "<citerefentry>
+    <refentrytitle><command>dpkg-scansources</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
+
+<!ENTITY dselect "<citerefentry>
+    <refentrytitle><command>dselect</command></refentrytitle>
+    <manvolnum>8</manvolnum>
+  </citerefentry>"
+>
     
 <!-- Boiler plate docinfo section -->
 <!ENTITY apt-docinfo "
- <docinfo>
-   <address><email>apt@packages.debian.org</></address>
-   <author><firstname>Jason</> <surname>Gunthorpe</></>
-   <copyright><year>1998-2001</> <holder>Jason Gunthorpe</></>
-   <date>12 March 2001</>
- </docinfo>
+ <refentryinfo>
+   <address><email>apt@packages.debian.org</email></address>
+   <author><firstname>Jason</firstname> <surname>Gunthorpe</surname></author>
+   <copyright><year>1998-2001</year> <holder>Jason Gunthorpe</holder></copyright>
+   <date>14 December 2003</date>
+   <productname>Linux</productname>
+
+ </refentryinfo>
 "> 
 
 <!-- Boiler plate Bug reporting section -->
 <!ENTITY manbugs "
- <RefSect1><Title>Bugs</>
-   <para>
-   See the <ulink url='http://bugs.debian.org/src:apt'>APT bug page</>.  
+ <refsect1><title>Bugs</title>
+   <para><ulink url='http://bugs.debian.org/src:apt'>APT bug page</ulink>. 
    If you wish to report a bug in APT, please see
-   <filename>/usr/share/doc/debian/bug-reporting.txt</> or the &reportbug; command.
- </RefSect1>
+   <filename>/usr/share/doc/debian/bug-reporting.txt</filename> or the
+   &reportbug; command.
+   </para>
+ </refsect1>
 ">
 
 <!-- Boiler plate Author section -->
 <!ENTITY manauthor "
- <RefSect1><Title>Author</>
-   <para>
-   APT was written by the APT team <email>apt@packages.debian.org</>.
- </RefSect1>
+ <refsect1><title>Author</title>
+   <para>APT was written by the APT team <email>apt@packages.debian.org</email>.
+   </para>
+ </refsect1>
+">
+
+<!-- Should be used in every man page to get the date bottom center of
+     the man page -->
+<!ENTITY apt-preamble "
+  <refentryinfo>
+    <date>14 December 2003</date>
+    <productname>Linux</productname>
+  </refentryinfo>
 ">
 
 <!-- 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>-h</option></term>
+     <term><option>--help</option></term>
+     <listitem><para>Show a short usage summary.
+     </para>
+     </listitem>
+     </varlistentry>
      
-     <VarListEntry><term><option/-v/</><term><option/--version/</>
-     <ListItem><Para>
-     Show the program version.
-     </VarListEntry>
-
-     <VarListEntry><term><option/-c/</><term><option/--config-file/</>
-     <ListItem><Para>
-     Configuration File; Specify a configuration file to use. 
+     <varlistentry>
+      <term><option>-v</option></term>
+      <term><option>--version</option></term>
+      <listitem><para>Show the program version.
+     </para>
+     </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-c</option></term>
+      <term><option>--config-file</option></term>
+     <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>
+     </para>
+     </listitem>
+     </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>
+     <varlistentry>
+      <term><option>-o</option></term>
+      <term><option>--option</option></term>
+     <listitem><para>Set a Configuration Option; This will set an arbitary
+      configuration option. The syntax is <option>-o Foo::Bar=bar</option>.
+     </para>
+     </listitem>
+     </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
+   <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.
+   <option>-f-</option>,<option>--no-f</option>, <option>-f=no</option>
+   or several other variations.
    </para>
 ">
+

doc/apt_preferences.5.sgml

@@ -1,5 +1,6 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 
 <!ENTITY % aptent SYSTEM "apt.ent">
 %aptent;
@@ -7,29 +8,25 @@
 ]>
 
 <refentry>
- &apt-docinfo;
 
  <refmeta>
-   <refentrytitle>apt_preferences</>
-   <manvolnum>5</>
+   <refentrytitle>apt_preferences</refentrytitle>
+   <manvolnum>5</manvolnum>
  </refmeta>
 
  <!-- Man page title -->
  <refnamediv>
-    <refname>apt_preferences</>
-    <refpurpose>Preference control file for APT</>
+    <refname>apt_preferences</refname>
+    <refpurpose>Preference control file for APT</refpurpose>
  </refnamediv>
 
-<RefSect1>
-<Title>Description</Title>
-<para>
-The APT preferences file <filename>/etc/apt/preferences</>
+<refsect1>
+<title>Description</title>
+<para>The APT preferences file <filename>/etc/apt/preferences</filename>
 can be used to control which versions of packages will be selected
-for installation.
-</para>
+for installation.</para>
 
-<para>
-Several versions of a package may be available for installation when
+<para>Several versions of a package may be available for installation when
 the &sources-list; file contains references to more than one distribution
 (for example, <literal>stable</literal> and <literal>testing</literal>).
 APT assigns a priority to each version that is available.
@@ -37,21 +34,18 @@ Subject to dependency constraints, <command>apt-get</command> selects the
 version with the highest priority for installation.
 The APT preferences file overrides the priorities that APT assigns to
 package versions by default, thus giving the user control over which
-one is selected for installation.
-</para>
-<para>
-Several instances of the same version of a package may be available when
+one is selected for installation.</para>
+
+<para>Several instances of the same version of a package may be available when
 the &sources-list; file contains references to more than one source.
 In this case <command>apt-get</command> downloads the instance listed
 earliest in the &sources-list; file.
 The APT preferences file does not affect the choice of instance, only
-the choice of version.
-</para>
+the choice of version.</para>
 
-<RefSect2><Title>APT's Default Priority Assignments</>
+<refsect2><title>APT's Default Priority Assignments</title>
 
-<para>
-If there is no preferences file or if there is no entry in the file
+<para>If there is no preferences file or if there is no entry in the file
 that applies to a particular version then the priority assigned to that
 version is the priority of the distribution to which that version
 belongs.  It is possible to single out a distribution, "the target release",
@@ -59,6 +53,7 @@ which receives a higher priority than other distributions do by default.
 The target release can be set on the <command>apt-get</command> command
 line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>.
 For example,
+
 <programlisting>
 <command>apt-get install -t testing <replaceable>some-package</replaceable></command>
 </programlisting>
@@ -67,18 +62,20 @@ APT::Default-Release "stable";
 </programlisting>
 </para>
 
-<para>
-If the target release has been specified then APT uses the following
+<para>If the target release has been specified then APT uses the following
 algorithm to set the priorities of the versions of a package.  Assign:
+
 <variablelist>
 <varlistentry>
 <term>priority 100</term>
 <listitem><simpara>to the version that is already installed (if any).</simpara></listitem>
 </varlistentry>
+
 <varlistentry>
 <term>priority 500</term>
 <listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem>
 </varlistentry>
+
 <varlistentry>
 <term>priority 990</term>
 <listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem>
@@ -86,14 +83,11 @@ algorithm to set the priorities of the versions of a package.  Assign:
 </variablelist>
 </para>
 
-<para>
-If the target release has not been specified then APT simply assigns
+<para>If the target release has not been specified then APT simply assigns
 priority 100 to all installed package versions and priority 500 to all
-uninstalled package versions.
-</para>
+uninstalled package versions.</para>
 
-<para>
-APT then applies the following rules, listed in order of precedence,
+<para>APT then applies the following rules, listed in order of precedence,
 to determine which version of a package to install.
 <itemizedlist>
 <listitem><simpara>Never downgrade unless the priority of an available
@@ -108,52 +102,43 @@ install the most recent one (that is, the one with the higher version
 number).</simpara></listitem>
 <listitem><simpara>If two or more versions have the same priority and
 version number but either the packages differ in some of their metadata or the
-<literal/--reinstall/ option is given, install the uninstalled one.</simpara></listitem>
+<literal>--reinstall</literal> option is given, install the uninstalled one.</simpara></listitem>
 </itemizedlist>
 </para>
 
-<para>
-In a typical situation, the installed version of a package (priority 100)
+<para>In a typical situation, the installed version of a package (priority 100)
 is not as recent as one of the versions available from the sources listed in
 the &sources-list; file (priority 500 or 990).  Then the package will be upgraded
 when <command>apt-get install <replaceable>some-package</replaceable></command>
 or <command>apt-get upgrade</command> is executed.
 </para>
 
-<para>
-More rarely, the installed version of a package is <emphasis/more/ recent
+<para>More rarely, the installed version of a package is <emphasis>more</emphasis> recent
 than any of the other available versions.  The package will not be downgraded
 when <command>apt-get install <replaceable>some-package</replaceable></command>
-or <command>apt-get upgrade</command> is executed.
-</para>
+or <command>apt-get upgrade</command> is executed.</para>
 
-<para>
-Sometimes the installed version of a package is more recent than the
+<para>Sometimes the installed version of a package is more recent than the
 version belonging to the target release, but not as recent as a version
 belonging to some other distribution.  Such a package will indeed be upgraded
 when <command>apt-get install <replaceable>some-package</replaceable></command>
 or <command>apt-get upgrade</command> is executed,
-because at least <emphasis/one/ of the available versions has a higher
-priority than the installed version.
-</para>
-
-</RefSect2>
+because at least <emphasis>one</emphasis> of the available versions has a higher
+priority than the installed version.</para>
+</refsect2>
 
-<RefSect2><Title>The Effect of APT Preferences</>
+<refsect2><title>The Effect of APT Preferences</title>
 
-<para>
-The APT preferences file allows the system administrator to control the
+<para>The APT preferences file allows the system administrator to control the
 assignment of priorities.  The file consists of one or more multi-line records
 separated by blank lines.  Records can have one of two forms, a specific form
 and a general form.
 <itemizedlist>
 <listitem>
-<simpara>
-The specific form assigns a priority (a "Pin-Priority") to a
+<simpara>The specific form assigns a priority (a "Pin-Priority") to a
 specified package and specified version or version range.  For example,
 the following record assigns a high priority to all versions of
-the <filename/perl/ package whose version number begins with "<literal/5.8/".
-</simpara>
+the <filename>perl</filename> package whose version number begins with "<literal>5.8</literal>".</simpara>
 
 <programlisting>
 Package: perl
@@ -162,19 +147,15 @@ Pin-Priority: 1001
 </programlisting>
 </listitem>
 
-<listitem><simpara>
-The general form assigns a priority to all of the package versions in a
+<listitem><simpara>The general form assigns a priority to all of the package versions in a
 given distribution (that is, to all the versions of packages that are
-listed in a certain <filename/Release/ file) or to all of the package
+listed in a certain <filename>Release</filename> file) or to all of the package
 versions coming from a particular Internet site, as identified by the
-site's fully qualified domain name.
-</simpara>
+site's fully qualified domain name.</simpara>
 
-<simpara>
-This general-form entry in the APT preferences file applies only
+<simpara>This general-form entry in the APT preferences file applies only
 to groups of packages.  For example, the following record assigns a high
-priority to all package versions available from the local site.
-</simpara>
+priority to all package versions available from the local site.</simpara>
 
 <programlisting>
 Package: *
@@ -182,18 +163,14 @@ Pin: origin ""
 Pin-Priority: 999
 </programlisting>
 
-<simpara>
-A note of caution: the keyword used here is "<literal/origin/".
+<simpara>A note of caution: the keyword used here is "<literal>origin</literal>".
 This should not be confused with the Origin of a distribution as
-specified in a <filename/Release/ file.  What follows the "Origin:" tag
-in a <filename/Release/ file is not an Internet address
-but an author or vendor name, such as "Debian" or "Ximian".
-</simpara>
+specified in a <filename>Release</filename> file.  What follows the "Origin:" tag
+in a <filename>Release</filename> file is not an Internet address
+but an author or vendor name, such as "Debian" or "Ximian".</simpara>
 
-<simpara>
-The following record assigns a low priority to all package versions
-belonging to any distribution whose Archive name is "<literal/unstable/".
-</simpara>
+<simpara>The following record assigns a low priority to all package versions
+belonging to any distribution whose Archive name is "<literal>unstable</literal>".</simpara>
 
 <programlisting>
 Package: *
@@ -201,11 +178,9 @@ Pin: release a=unstable
 Pin-Priority: 50
 </programlisting>
 
-<simpara>
-The following record assigns a high priority to all package versions
-belonging to any release whose Archive name is "<literal/stable/"
-and whose release Version number is "<literal/3.0/".
-</simpara>
+<simpara>The following record assigns a high priority to all package versions
+belonging to any release whose Archive name is "<literal>stable</literal>"
+and whose release Version number is "<literal>3.0</literal>".</simpara>
 
 <programlisting>
 Package: *
@@ -216,10 +191,10 @@ Pin-Priority: 50
 </itemizedlist>
 </para>
 
-</RefSect2>
+</refsect2>
 
-<RefSect2>
-<Title>How APT Interprets Priorities</Title>
+<refsect2>
+<title>How APT Interprets Priorities</title>
 
 <para>
 Priorities (P) assigned in the APT preferences file must be positive
@@ -248,6 +223,7 @@ or the installed version is more recent</simpara></listitem>
 <listitem><simpara>causes a version to be installed
 unless there is a version available belonging to some other
 distribution or the installed version is more recent</simpara></listitem>
+</varlistentry>
 <varlistentry>
 <term>0 &lt; P &lt;=100</term>
 <listitem><simpara>causes a version to be installed
@@ -260,17 +236,14 @@ only if there is no installed version of the package</simpara></listitem>
 </variablelist>
 </para>
 
-<para>
-If any specific-form records match an available package version then the
+<para>If any specific-form records match an available package version then the
 first such record determines the priority of the package version.  
 Failing that,
 if any general-form records match an available package version then the
-first such record determines the priority of the package version.  
-</para>
+first such record determines the priority of the package version.</para>
 
-<para>
-For example, suppose the APT preferences file contains the three
-records presented earlier:
+<para>For example, suppose the APT preferences file contains the three
+records presented earlier:</para>
 
 <programlisting>
 Package: perl
@@ -286,38 +259,34 @@ Pin: release unstable
 Pin-Priority: 50
 </programlisting>
 
-Then:
-
+<para>Then:
 <itemizedlist>
-<listitem><simpara>The most recent available version of the <literal/perl/
+<listitem><simpara>The most recent available version of the <literal>perl</literal>
 package will be installed, so long as that version's version number begins
-with "<literal/5.8/".  If <emphasis/any/ 5.8* version of <literal/perl/ is
-available and the installed version is 5.9*, then <literal/perl/ will be
+with "<literal>5.8</literal>".  If <emphasis>any</emphasis> 5.8* version of <literal>perl</literal> is
+available and the installed version is 5.9*, then <literal>perl</literal> will be
 downgraded.</simpara></listitem>
-<listitem><simpara>A version of any package other than <literal/perl/
+<listitem><simpara>A version of any package other than <literal>perl</literal>
 that is available from the local system has priority over other versions,
 even versions belonging to the target release.
 </simpara></listitem>
 <listitem><simpara>A version of a package whose origin is not the local
 system but some other site listed in &sources-list; and which belongs to
-an <literal/unstable/ distribution is only installed if it is selected
+an <literal>unstable</literal> distribution is only installed if it is selected
 for installation and no version of the package is already installed.
 </simpara></listitem>
 </itemizedlist>
 </para>
-</RefSect2>
+</refsect2>
 
-<RefSect2>
-<Title>Determination of Package Version and Distribution Properties</Title>
+<refsect2>
+<title>Determination of Package Version and Distribution Properties</title>
 
-<para>
-The locations listed in the &sources-list; file should provide
+<para>The locations listed in the &sources-list; file should provide
 <filename>Packages</filename> and <filename>Release</filename> files
-to describe the packages available at that location.
-</para>
+to describe the packages available at that location. </para>
 
-<para>
-The <filename>Packages</filename> file is normally found in the directory
+<para>The <filename>Packages</filename> file is normally found in the directory
 <filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>:
 for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>.
 It consists of a series of multi-line records, one for each package available
@@ -325,35 +294,34 @@ in that directory.  Only two lines in each record are relevant for setting
 APT priorities:
 <variablelist>
 <varlistentry>
-<term>the <literal/Package:/ line</term>
+<term>the <literal>Package:</literal> line</term>
 <listitem><simpara>gives the package name</simpara></listitem>
 </varlistentry>
 <varlistentry>
-<term>the <literal/Version:/ line</term>
+<term>the <literal>Version:</literal> line</term>
 <listitem><simpara>gives the version number for the named package</simpara></listitem>
 </varlistentry>
 </variablelist>
 </para>
 
-<para>
-The <filename>Release</filename> file is normally found in the directory
+<para>The <filename>Release</filename> file is normally found in the directory
 <filename>.../dists/<replaceable>dist-name</replaceable></filename>:
 for example, <filename>.../dists/stable/Release</filename>,
 or <filename>.../dists/woody/Release</filename>.
-It consists of a single multi-line record which applies to <emphasis/all/ of
+It consists of a single multi-line record which applies to <emphasis>all</emphasis> of
 the packages in the directory tree below its parent.  Unlike the
-<filename/Packages/ file, nearly all of the lines in a <filename/Release/
+<filename>Packages</filename> file, nearly all of the lines in a <filename>Release</filename>
 file are relevant for setting APT priorities:
 
 <variablelist>
 <varlistentry>
-<term>the <literal/Archive:/ line</term>
+<term>the <literal>Archive:</literal> line</term>
 <listitem><simpara>names the archive to which all the packages
 in the directory tree belong.  For example, the line
 "Archive: stable"
 specifies that all of the packages in the directory
-tree below the parent of the <filename/Release/ file are in a
-<literal/stable/ archive.  Specifying this value in the APT preferences file
+tree below the parent of the <filename>Release</filename> file are in a
+<literal>stable</literal> archive.  Specifying this value in the APT preferences file
 would require the line:
 </simpara>
 <programlisting>
@@ -363,11 +331,11 @@ Pin: release a=stable
 </varlistentry>
 
 <varlistentry>
-<term>the <literal/Version:/ line</term>
+<term>the <literal>Version:</literal> line</term>
 <listitem><simpara>names the release version.  For example, the
 packages in the tree might belong to Debian GNU/Linux release
 version 3.0.  Note that there is normally no version number for the
-<literal/testing/ and <literal/unstable/ distributions because they
+<literal>testing</literal> and <literal>unstable</literal> distributions because they
 have not been released yet.  Specifying this in the APT preferences
 file would require one of the following lines.
 </simpara>
@@ -382,11 +350,11 @@ Pin: release 3.0
 </varlistentry>
 
 <varlistentry>
-<term>the <literal/Component:/ line</term>
+<term>the <literal>Component:</literal> line</term>
 <listitem><simpara>names the licensing component associated with the
-packages in the directory tree of the <filename/Release/ file.
+packages in the directory tree of the <filename>Release</filename> file.
 For example, the line "Component: main" specifies that
-all the packages in the directory tree are from the <literal/main/
+all the packages in the directory tree are from the <literal>main</literal>
 component, which entails that they are licensed under terms listed
 in the Debian Free Software Guidelines.  Specifying this component
 in the APT preferences file would require the line:
@@ -398,10 +366,10 @@ Pin: release c=main
 </varlistentry>
 
 <varlistentry>
-<term>the <literal/Origin:/ line</term>
+<term>the <literal>Origin:</literal> line</term>
 <listitem><simpara>names the originator of the packages in the
-directory tree of the <filename/Release/ file.  Most commonly, this is
-<literal/Debian/.  Specifying this origin in the APT preferences file
+directory tree of the <filename>Release</filename> file.  Most commonly, this is
+<literal>Debian</literal>.  Specifying this origin in the APT preferences file
 would require the line:
 </simpara>
 <programlisting>
@@ -411,10 +379,10 @@ Pin: release o=Debian
 </varlistentry>
 
 <varlistentry>
-<term>the <literal/Label:/ line</term>
+<term>the <literal>Label:</literal> line</term>
 <listitem><simpara>names the label of the packages in the directory tree
-of the <filename/Release/ file.  Most commonly, this is
-<literal/Debian/.  Specifying this label in the APT preferences file
+of the <filename>Release</filename> file.  Most commonly, this is
+<literal>Debian</literal>.  Specifying this label in the APT preferences file
 would require the line:
 </simpara>
 <programlisting>
@@ -425,48 +393,40 @@ Pin: release l=Debian
 </variablelist>
 </para>
 
-<para>
-All of the <filename>Packages</filename> and <filename>Release</filename>
+<para>All of the <filename>Packages</filename> and <filename>Release</filename>
 files retrieved from locations listed in the &sources-list; file are stored
 in the directory <filename>/var/lib/apt/lists</filename>, or in the file named
-by the variable <literal/Dir::State::Lists/ in the <filename/apt.conf/ file.
+by the variable <literal>Dir::State::Lists</literal> in the <filename>apt.conf</filename> file.
 For example, the file
 <filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename>
 contains the <filename>Release</filename> file retrieved from the site
-<literal/debian.lcs.mit.edu/ for <literal/binary-i386/ architecture
-files from the <literal/contrib/ component of the <literal/unstable/
-distribution.
-</para>
+<literal>debian.lcs.mit.edu</literal> for <literal>binary-i386</literal> architecture
+files from the <literal>contrib</literal> component of the <literal>unstable</literal>
+distribution.</para>
+</refsect2>
 
-</RefSect2>
+<refsect2>
+<title>Optional Lines in an APT Preferences Record</title>
 
-<RefSect2>
-<Title>Optional Lines in an APT Preferences Record</Title>
+<para>Each record in the APT preferences file can optionally begin with
+one or more lines beginning with the word <literal>Explanation:</literal>.
+This provides a place for comments.</para>
 
-<para>
-Each record in the APT preferences file can optionally begin with
-one or more lines beginning with the word <literal/Explanation:/.
-This provides a place for comments.
-</para>
-
-<para>
-The <literal/Pin-Priority:/ line in each APT preferences record is
+<para>The <literal>Pin-Priority:</literal> line in each APT preferences record is
 optional.  If omitted, APT assigs a priority of 1 less than the last value
-specified on a line beginning with <literal/Pin-Priority: release .../.
-</para>
-</RefSect2>
-</RefSect1>
+specified on a line beginning with <literal>Pin-Priority: release ...</literal>.</para>
+</refsect2>
+</refsect1>
 
-<RefSect1>
-<Title>Examples</Title>
-<RefSect2>
-<Title>Tracking Stable</Title>
+<refsect1>
+<title>Examples</title>
+<refsect2>
+<title>Tracking Stable</title>
 
-<para>
-The following APT preferences file will cause APT to assign a
+<para>The following APT preferences file will cause APT to assign a
 priority higher than the default (500) to all package versions belonging
-to a <literal/stable/ distribution and a prohibitively low priority to
-package versions belonging to other <literal/Debian/ distributions.
+to a <literal>stable</literal> distribution and a prohibitively low priority to
+package versions belonging to other <literal>Debian</literal> distributions.
 
 <programlisting>
 Explanation: Uninstall or do not install any Debian-originated
@@ -481,10 +441,9 @@ Pin-Priority: -10
 </programlisting>
 </para>
 
-<para>
-With a suitable &sources-list; file and the above preferences file,
+<para>With a suitable &sources-list; file and the above preferences file,
 any of the following commands will cause APT to upgrade to the
-latest <literal/stable/ version(s).
+latest <literal>stable</literal> version(s).
 
 <programlisting>
 apt-get install <replaceable>package-name</replaceable>
@@ -493,26 +452,25 @@ apt-get dist-upgrade
 </programlisting>
 </para>
 
-<para>
-The following command will cause APT to upgrade the specified
-package to the latest version from the <literal/testing/ distribution;
+<para>The following command will cause APT to upgrade the specified
+package to the latest version from the <literal>testing</literal> distribution;
 the package will not be upgraded again unless this command is given
 again.
 
 <programlisting>
 apt-get install <replaceable>package</replaceable>/testing
 </programlisting>
-</RefSect2>
+</para>
+</refsect2>
 
- <RefSect2>
- <Title>Tracking Testing or Unstable</Title>
+ <refsect2>
+ <title>Tracking Testing or Unstable</title>
 
-<para>
-The following APT preferences file will cause APT to assign
-a high priority to package versions from the <literal/testing/
+<para>The following APT preferences file will cause APT to assign
+a high priority to package versions from the <literal>testing</literal>
 distribution, a lower priority to package versions from the
-<literal/unstable/ distribution, and a prohibitively low priority
-to package versions from other <literal/Debian/ distributions.
+<literal>unstable</literal> distribution, and a prohibitively low priority
+to package versions from other <literal>Debian</literal> distributions.
 
 <programlisting>
 Package: *
@@ -529,10 +487,9 @@ Pin-Priority: -10
 </programlisting>
 </para>
 
-<para>
-With a suitable &sources-list; file and the above preferences file,
+<para>With a suitable &sources-list; file and the above preferences file,
 any of the following commands will cause APT to upgrade to the latest
-<literal/testing/ version(s).
+<literal>testing</literal> version(s).
 
 <programlisting>
 apt-get install <replaceable>package-name</replaceable>
@@ -542,11 +499,11 @@ apt-get dist-upgrade
 </para>
 
 <para>The following command will cause APT to upgrade the specified
-package to the latest version from the <literal/unstable/ distribution.
+package to the latest version from the <literal>unstable</literal> distribution.
 Thereafter, <command>apt-get upgrade</command> will upgrade
-the package to the most recent <literal/testing/ version if that is
+the package to the most recent <literal>testing</literal> version if that is
 more recent than the installed version, otherwise, to the most recent
-<literal/unstable/ version if that is more recent than the installed
+<literal>unstable</literal> version if that is more recent than the installed
 version.
 
 <programlisting>
@@ -554,17 +511,18 @@ apt-get install <replaceable>package</replaceable>/unstable
 </programlisting>
 </para>
 
-</RefSect2>
-</RefSect1>
+</refsect2>
+</refsect1>
 
-<RefSect1>
-<Title>See Also</Title>
+<refsect1>
+<title>See Also</title>
 <para>
 &apt-get; &apt-cache; &apt-conf; &sources-list;
 </para>
-</RefSect1>
+</refsect1>
 
  &manbugs;
  &manauthor;
 
 </refentry>
+

doc/makefile

@@ -11,12 +11,12 @@ SOURCE = dpkg-tech.sgml design.sgml files.sgml guide.sgml guide.it.sgml \
          cache.sgml method.sgml offline.sgml
 include $(DEBIANDOC_H)
 
-# Man pages
+# XML man pages
 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 \
-	 apt-extracttemplates.1 vendors.list.5
+         apt-config.8 apt_preferences.5 vendors.list.5 \
+         apt-sortpkgs.1 apt-ftparchive.1 apt-extracttemplates.1
 INCLUDES = apt.ent	 
-include $(SGML_MANPAGE_H)
+include $(XML_MANPAGE_H)
 
 # Examples
 SOURCE = examples/apt.conf examples/sources.list examples/configure-index 

doc/sources.list.5.sgml

@@ -1,199 +0,0 @@
-<!-- -*- 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/testing/, 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] [component2] [...]</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 architecture-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. APT also parallelizes 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 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>

doc/sources.list.5.xml

@@ -0,0 +1,211 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>sources.list</refentrytitle>
+   <manvolnum>5</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>sources.list</refname>
+    <refpurpose>Package resource list for APT</refpurpose>
+ </refnamediv>
+ 
+ <refsect1><title>Description</title>
+   <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</filename></para>
+
+   <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</literal> The first item, <literal>type</literal>
+   determines the format for <literal>args</literal> <literal>uri</literal> 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 #.</para>
+ </refsect1>
+ 
+ <refsect1><title>The deb and deb-src types</title>
+   <para>The <literal>deb</literal> type describes a typical two-level Debian
+   archive, <filename>distribution/component</filename>. Typically,
+   <literal>distribution</literal> is generally one of
+   <literal>stable</literal> <literal>unstable</literal> or 
+   <literal>testing</literal> while component is one of <literal>main</literal> 
+   <literal>contrib</literal> <literal>non-free</literal> or
+   <literal>non-us</literal> The 
+   <literal>deb-src</literal> type describes a debian distribution's source
+   code in the same form as the <literal>deb</literal> type.
+   A <literal>deb-src</literal> line is required to fetch source indexes.</para>
+
+
+   <para>The format for a <filename>sources.list</filename> entry using the
+   <literal>deb</literal> and <literal>deb-src</literal> types are:</para>
+
+   <literallayout>deb uri distribution [component1] [component2] [...]</literallayout>
+
+   <para>The URI for the <literal>deb</literal> type must specify the base of the
+   Debian distribution, from which APT will find the information it needs. 
+   <literal>distribution</literal> can specify an exact path, in which case the 
+   components must be omitted and <literal>distribution</literal> 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</literal> does not specify an exact path, at least
+   one <literal>component</literal> must be present.</para>
+
+   <para><literal>distribution</literal> may also contain a variable, 
+   <literal>$(ARCH)</literal>
+   which expands to the Debian architecture (i386, m68k, powerpc, ...)
+   used on the system. This permits architecture-independent
+   <filename>sources.list</filename> files to be used. In general this is only
+   of interest when specifying an exact path, <literal>APT</literal> will
+   automatically generate a URI with the current architecture otherwise.</para>
+
+   <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. APT also parallelizes connections to 
+   different hosts to more effectively deal with sites with low bandwidth.</para>
+
+   <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>
+
+   <para>Some examples:</para>
+   <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.</para></listitem>
+    </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.</para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>http</term>
+    <listitem><para>
+    The http scheme specifies an HTTP server for the archive. If an environment
+    variable <envar>http_proxy</envar> is set with the format 
+    http://server:port/, the proxy server specified in
+    <envar>http_proxy</envar> 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.</para></listitem>
+    </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</envar> 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.</para></listitem>
+    </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.</para></listitem>
+    </varlistentry>
+    
+    <varlistentry><term>rsh</term><term>ssh</term>
+    <listitem><para>
+    The rsh/ssh 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</command> and
+    <command>dd</command> 
+    commands to perform the file transfers from the remote.</para></listitem>
+    </varlistentry>
+  </variablelist>
+ </para>
+ </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.</para>
+   <literallayout>deb file:/home/jason/debian stable main contrib non-free</literallayout>
+
+   <para>As above, except this uses the unstable (development) distribution.</para>
+   <literallayout>deb file:/home/jason/debian unstable main contrib non-free</literallayout>
+
+   <para>Source line for the above</para>
+   <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.</para>
+   <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.</para>
+   <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</filename>.
+   a single FTP session will be used for both resource lines.</para>
+   <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.</para>
+   <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-i3866</filename> on i386 machines, 
+   <filename>unstable/binary-m68k</filename> 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>
+   </para>
+ </refsect1>
+ 
+ <refsect1><title>See Also</title>
+   <para>
+   &apt-cache; &apt-conf;
+   </para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
+

doc/vendors.list.5.sgml

@@ -1,104 +0,0 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-
-<!ENTITY % aptent SYSTEM "apt.ent">
-%aptent;
-
-]>
-
-<refentry>
- &apt-docinfo;
- 
- <refmeta>
-   <refentrytitle>vendors.list</>
-   <manvolnum>5</>
- </refmeta>
- 
- <!-- Man page title -->
- <refnamediv>
-    <refname>vendors.list</>
-    <refpurpose>Security key configuration for APT</>
- </refnamediv>
- 
- <RefSect1><Title>Description</>
-   <para>   
-   The package vendor list contains a list of all vendors
-   from whom you wish to  authenticate  downloaded  packages.
-   For each vendor listed, it must contain the corresponding
-   PGP key fingerprint, so that  APT  can  perform  signature
-   verification  of the release file and subsequent checking
-   of the checksums of each  downloaded  package.
-   To have authentication enabled, you must add the 
-   vendor identification string  (see  below) enclosed in
-   square braces to the sources.list line for all sites that mirror
-   the repository provided by that vendor.
-   <para>
-   The format of this file is similar  to  the  one  used  by
-   apt.conf.  It consists of an arbitrary number of blocks of
-   vendors, where each block starts with a string telling the
-   <replaceable/key_type/ and the <replaceable/vendor_id/.
-   <para>
-   Some vendors may have multiple blocks that define different
-   security policies for their distributions. Debian for instance
-   uses a different signing methodology for stable and unstable releases.
-   <para>
-   <replaceable/key_type/ is the type of the check required.
-   Currently, there is only one type available which is 
-   <literal/simple-key/.
-   <para>
-   <replaceable/vendor_id/ is the vendor identification string. It is an
-   arbitrary string you must supply to uniquely identifify a
-   vendor that's listed in this file.
-   
-   Example:
-<informalexample><programlisting>   
-simple-key "joe"
-{
-   Fingerprint "0987AB4378FSD872343298787ACC";
-   Name "Joe Shmoe &lt;joe@shmoe.com&gt;";
-}						    
-</programlisting></informalexample>
-   
- </RefSect1>
-
- <RefSect1><Title>The simple-key type</>
-   <para>   
-   This type of verification is used when the vendor has a single
-   secured key that must be used to sign the Release file. The
-   following items should be present
-   
-   <VariableList>
-     <VarListEntry><Term>Fingerprint</Term>
-     <ListItem><Para>
-     The PGP fingerprint for the key. The fingerprint should be
-     expressed in the standard notion with or without spaces.
-     The <option/--fingerprint/ option for 
-     <CiteRefEntry><RefEntryTitle><command/gpg/</RefEntryTitle><ManVolNum/1/</CiteRefEntry>
-     will show the fingerprint for the selected keys(s).
-     </VarListEntry>
-     
-     <VarListEntry><Term>Name</Term>
-     <ListItem><Para>
-     A string containing a description of the owner of
-     the  key  or vendor.  You may put the vendor name and it's
-     email. The string must be quoted with ".
-     </VarListEntry>
-     
-   </VariableList>
- </RefSect1>
-
- <RefSect1><Title>Files</>
-   <para>
-   <filename>/etc/apt/vendors.list</>
- </RefSect1>
- 
- <RefSect1><Title>See Also</>
-   <para>
-   &sources-list;
- </RefSect1>
-
- &manbugs;
- &manauthor;
- 
-</refentry>
-   

doc/vendors.list.5.xml

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!ENTITY % aptent SYSTEM "apt.ent">
+%aptent;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>vendors.list</refentrytitle>
+   <manvolnum>5</manvolnum>
+ </refmeta>
+ 
+ <!-- Man page title -->
+ <refnamediv>
+    <refname>vendors.list</refname>
+    <refpurpose>Security key configuration for APT</refpurpose>
+ </refnamediv>
+ 
+ <refsect1><title>Description</title>
+
+   <para>The package vendor list contains a list of all vendors
+   from whom you wish to  authenticate  downloaded  packages.
+   For each vendor listed, it must contain the corresponding
+   PGP key fingerprint, so that  APT  can  perform  signature
+   verification  of the release file and subsequent checking
+   of the checksums of each  downloaded  package.
+   To have authentication enabled, you must add the 
+   vendor identification string  (see  below) enclosed in
+   square braces to the sources.list line for all sites that mirror
+   the repository provided by that vendor.</para>
+
+   <para>The format of this file is similar  to  the  one  used  by
+   apt.conf.  It consists of an arbitrary number of blocks of
+   vendors, where each block starts with a string telling the
+   <replaceable>key_type</replaceable> and the
+   <replaceable>vendor_id</replaceable></para>
+
+   <para>Some vendors may have multiple blocks that define different
+   security policies for their distributions. Debian for instance
+   uses a different signing methodology for stable and unstable releases.</para>
+   <para><replaceable>key_type</replaceable> is the type of the check required.
+   Currently, there is only one type available which is 
+   <literal>simple-key</literal>.</para>
+
+   <para><replaceable>vendor_id</replaceable> is the vendor identification
+   string. It is an arbitrary string you must supply to uniquely identifify a
+   vendor that's listed in this file.
+   
+   Example:
+  </para> 
+<informalexample><programlisting>   
+simple-key "joe"
+{
+   Fingerprint "0987AB4378FSD872343298787ACC";
+   Name "Joe Shmoe &lt;joe@shmoe.com&gt;";
+}						    
+</programlisting></informalexample>
+ </refsect1>
+
+ <refsect1><title>The simple-key type</title>
+
+   <para>This type of verification is used when the vendor has a single
+   secured key that must be used to sign the Release file. The
+   following items should be present</para>
+   
+   <variablelist>
+     <varlistentry><term>Fingerprint</term>
+     <listitem><para>
+     The PGP fingerprint for the key. The fingerprint should be
+     expressed in the standard notion with or without spaces.
+     The <option>--fingerprint</option> option for 
+     <citerefentry><refentrytitle><command>gpg</command></refentrytitle><manvolnum>1</manvolnum></citerefentry>
+     will show the fingerprint for the selected keys(s).
+     </para>
+     </listitem>
+     </varlistentry>
+
+     <varlistentry><term>Name</term>
+     <listitem><para>
+     A string containing a description of the owner of
+     the  key  or vendor.  You may put the vendor name and it's
+     email. The string must be quoted with ".
+     </para>
+     </listitem>
+     </varlistentry>
+     
+   </variablelist>
+ </refsect1>
+
+ <refsect1><title>Files</title>
+   <para><filename>/etc/apt/vendors.list</filename></para>
+ </refsect1>
+ 
+ <refsect1><title>See Also</title>
+   <para>
+   &sources-list;
+   </para>
+ </refsect1>
+
+ &manbugs;
+ &manauthor;
+ 
+</refentry>
+