* 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)

1 files changed, 0 insertions, 570 deletions

diff --git a/doc/apt_preferences.5.sgml b/doc/apt_preferences.5.sgml
deleted file mode 100644
index 817586548..000000000
--- a/doc/apt_preferences.5.sgml
+++ /dev/null
@@ -1,570 +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_preferences</>
-   <manvolnum>5</>
- </refmeta>
-
- <!-- Man page title -->
- <refnamediv>
-    <refname>apt_preferences</>
-    <refpurpose>Preference control file for APT</>
- </refnamediv>
-
-<RefSect1>
-<Title>Description</Title>
-<para>
-The APT preferences file <filename>/etc/apt/preferences</>
-can be used to control which versions of packages will be selected
-for installation.
-</para>
-
-<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.
-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
-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>
-
-<RefSect2><Title>APT's Default Priority Assignments</>
-
-<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",
-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>
-<programlisting>
-APT::Default-Release "stable";
-</programlisting>
-</para>
-
-<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>
-</varlistentry>
-</variablelist>
-</para>
-
-<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>
-
-<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
-version exceeds 1000.  ("Downgrading" is installing a less recent version
-of a package in place of a more recent version.  Note that none of APT's
-default priorities exceeds 1000; such high priorities can only be set in
-the preferences file.  Note also that downgrading a package
-can be risky.)</simpara></listitem>
-<listitem><simpara>Install the highest priority version.</simpara></listitem>
-<listitem><simpara>If two or more versions have the same priority,
-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>
-</itemizedlist>
-</para>
-
-<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
-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>
-
-<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>
-
-<RefSect2><Title>The Effect of APT Preferences</>
-
-<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
-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>
-
-<programlisting>
-Package: perl
-Pin: version 5.8*
-Pin-Priority: 1001
-</programlisting>
-</listitem>
-
-<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
-versions coming from a particular Internet site, as identified by the
-site's fully qualified domain name.
-</simpara>
-
-<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>
-
-<programlisting>
-Package: *
-Pin: origin ""
-Pin-Priority: 999
-</programlisting>
-
-<simpara>
-A note of caution: the keyword used here is "<literal/origin/".
-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>
-
-<simpara>
-The following record assigns a low priority to all package versions
-belonging to any distribution whose Archive name is "<literal/unstable/".
-</simpara>
-
-<programlisting>
-Package: *
-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>
-
-<programlisting>
-Package: *
-Pin: release a=unstable, v=3.0
-Pin-Priority: 50
-</programlisting>
-</listitem>
-</itemizedlist>
-</para>
-
-</RefSect2>
-
-<RefSect2>
-<Title>How APT Interprets Priorities</Title>
-
-<para>
-Priorities (P) assigned in the APT preferences file must be positive
-or negative integers.  They are interpreted as follows (roughly speaking):
-
-<variablelist>
-<varlistentry>
-<term>P &gt; 1000</term>
-<listitem><simpara>causes a version to be installed even if this
-constitutes a downgrade of the package</simpara></listitem>
-</varlistentry>
-<varlistentry>
-<term>990 &lt; P &lt;=1000</term>
-<listitem><simpara>causes a version to be installed
-even if it does not come from the target release,
-unless the installed version is more recent</simpara></listitem>
-</varlistentry>
-<varlistentry>
-<term>500 &lt; P &lt;=990</term>
-<listitem><simpara>causes a version to be installed
-unless there is a version available belonging to the target release
-or the installed version is more recent</simpara></listitem>
-</varlistentry>
-<varlistentry>
-<term>100 &lt; P &lt;=500</term>
-<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>
-<term>0 &lt; P &lt;=100</term>
-<listitem><simpara>causes a version to be installed
-only if there is no installed version of the package</simpara></listitem>
-</varlistentry>
-<varlistentry>
-<term>P &lt; 0</term>
-<listitem><simpara>prevents the version from being installed</simpara></listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<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>
-
-<para>
-For example, suppose the APT preferences file contains the three
-records presented earlier:
-
-<programlisting>
-Package: perl
-Pin: version 5.8*
-Pin-Priority: 1001
-
-Package: *
-Pin: origin ""
-Pin-Priority: 999
-
-Package: *
-Pin: release unstable
-Pin-Priority: 50
-</programlisting>
-
-Then:
-
-<itemizedlist>
-<listitem><simpara>The most recent available version of the <literal/perl/
-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
-downgraded.</simpara></listitem>
-<listitem><simpara>A version of any package other than <literal/perl/
-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
-for installation and no version of the package is already installed.
-</simpara></listitem>
-</itemizedlist>
-</para>
-</RefSect2>
-
-<RefSect2>
-<Title>Determination of Package Version and Distribution Properties</Title>
-
-<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>
-
-<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
-in that directory.  Only two lines in each record are relevant for setting
-APT priorities:
-<variablelist>
-<varlistentry>
-<term>the <literal/Package:/ line</term>
-<listitem><simpara>gives the package name</simpara></listitem>
-</varlistentry>
-<varlistentry>
-<term>the <literal/Version:/ 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
-<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
-the packages in the directory tree below its parent.  Unlike the
-<filename/Packages/ file, nearly all of the lines in a <filename/Release/
-file are relevant for setting APT priorities:
-
-<variablelist>
-<varlistentry>
-<term>the <literal/Archive:/ 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
-would require the line:
-</simpara>
-<programlisting>
-Pin: release a=stable
-</programlisting>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>the <literal/Version:/ 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
-have not been released yet.  Specifying this in the APT preferences
-file would require one of the following lines.
-</simpara>
-
-<programlisting>
-Pin: release v=3.0
-Pin: release a=stable, v=3.0
-Pin: release 3.0
-</programlisting>
-
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>the <literal/Component:/ line</term>
-<listitem><simpara>names the licensing component associated with the
-packages in the directory tree of the <filename/Release/ file.
-For example, the line "Component: main" specifies that
-all the packages in the directory tree are from the <literal/main/
-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:
-</simpara>
-<programlisting>
-Pin: release c=main
-</programlisting>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>the <literal/Origin:/ 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
-would require the line:
-</simpara>
-<programlisting>
-Pin: release o=Debian
-</programlisting>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>the <literal/Label:/ 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
-would require the line:
-</simpara>
-<programlisting>
-Pin: release l=Debian
-</programlisting>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<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.
-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>
-
-</RefSect2>
-
-<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:/.
-This provides a place for comments.
-</para>
-
-<para>
-The <literal/Pin-Priority:/ 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>
-
-<RefSect1>
-<Title>Examples</Title>
-<RefSect2>
-<Title>Tracking Stable</Title>
-
-<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.
-
-<programlisting>
-Explanation: Uninstall or do not install any Debian-originated
-Explanation: package versions other than those in the stable distro
-Package: *
-Pin: release a=stable
-Pin-Priority: 900
-
-Package: *
-Pin: release o=Debian
-Pin-Priority: -10
-</programlisting>
-</para>
-
-<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).
-
-<programlisting>
-apt-get install <replaceable>package-name</replaceable>
-apt-get upgrade
-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;
-the package will not be upgraded again unless this command is given
-again.
-
-<programlisting>
-apt-get install <replaceable>package</replaceable>/testing
-</programlisting>
-</RefSect2>
-
- <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/
-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.
-
-<programlisting>
-Package: *
-Pin: release a=testing
-Pin-Priority: 900
-
-Package: *
-Pin: release a=unstable
-Pin-Priority: 800
-
-Package: *
-Pin: release o=Debian
-Pin-Priority: -10
-</programlisting>
-</para>
-
-<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).
-
-<programlisting>
-apt-get install <replaceable>package-name</replaceable>
-apt-get upgrade
-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/unstable/ distribution.
-Thereafter, <command>apt-get upgrade</command> will upgrade
-the package to the most recent <literal/testing/ 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
-version.
-
-<programlisting>
-apt-get install <replaceable>package</replaceable>/unstable
-</programlisting>
-</para>
-
-</RefSect2>
-</RefSect1>
-
-<RefSect1>
-<Title>See Also</Title>
-<para>
-&apt-get; &apt-cache; &apt-conf; &sources-list;
-</para>
-</RefSect1>
-
- &manbugs;
- &manauthor;
-
-</refentry>