LC_COLLATE says it's apt_preferences.5.xml's turn:
[...]
> <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>
Now that there are .d/* fragments, should this perhaps be:
earliest in the &sources-list; file(s).
The APT preferences do not affect the choice of instance, only
the choice of version.</para>
...throughout? My patch doesn't bother, though.
> <para>Preferences are a strong power in the hands of a system administrator
> but they can become also their biggest nightmare if used without care!
"Singular they"... i.e. good idiomatic English.
> APT will not questioning the preferences so wrong settings will therefore
^^^ ~~ ^^^^ ~~~~~~~~~
Surplus -ing, redundant conjunctions; also, it's not so much that
they *will* as that they *can*.
APT will not question the preferences, so wrong settings can
> lead to uninstallable packages or wrong decisions while upgrading packages.
> Even more problems will arise if multiply distribution releases are mixed
^
> without a good understanding of the following paragraphs.
> Packages included in a specific release aren't tested in and
> therefore doesn't always work as expected in older or newer releases or
> together with other packages from different releases.
That would be clearer with extra punctuation around the
parenthetical - oh, and there's an agreement failure:
(and therefore don't always work as expected in) older or newer
releases, or together with other packages from different releases.
> You have been warned.</para>
If you're going to address the reader directly you might as well do
it earlier, too, and avoid that passive "if [...] releases are
mixed"; make it "if you mix..."
> <para>Note that the files in the <filename>/etc/apt/preferences.d</filename>
> directory are parsed in alphanumeric ascending order and need to obey the
> following naming convention: The files have either no or "<literal>pref</literal>"
> as filename extension and only contain alphanumeric, hyphen (-),
> underscore (_) and period (.) characters.
I don't like "Have no as filename extension";
following naming convention: the extension is "<literal>pref</literal>"
or nothing and filenames contain only alphanumeric, hyphen (-),
underscore (_) and period (.) characters.
> Otherwise APT will print a notice that it has ignored a file if the file
> doesn't match a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
> configuration list - in this case it will be silently ignored.</para>
Not a very clear way of putting it. Maybe
Otherwise APT will print a notice that it has ignored a file, unless that
file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
configuration list - in this case it will be silently ignored.</para>
[...]
> <varlistentry>
> <term>priority 1</term>
> <listitem><simpara>to the versions coming from archives which in their <filename>Release</filename>
> files are marked as "NotAutomatic: yes" but <emphasis>not</emphasis> as "ButAutomaticUpgrades: yes"
> like the debian <literal>experimental</literal> archive.</simpara></listitem>
D
(And again below)
[...]
> <simpara>The specific form assigns a priority (a "Pin-Priority") to one or more
> specified packages and specified version or version range. For example,
If I'm following this correctly I think it would be clearer as:
The specific form assigns a priority (a "Pin-Priority") to one or more
specified packages with a specified version or version range. For example,
(though it's getting a bit overspecified)
> the following record assigns a high priority to all versions of
> the <filename>perl</filename> package whose version number begins with "<literal>5.8</literal>".
> Multiple packages can be separated by spaces.</simpara>
The Perl 5.8 reference is cobwebby, but never mind.
[...]
> <simpara>This should <emphasis>not</emphasis> be confused with the Origin of a distribution as
> 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>
The perils of uncoordinated jargon (come to think of it I should add
this clarification to http://wiki.debian.org/Glossary#origin).
Also, the Ximian reference has been gathering cobwebs for almost a
decade.
[...]
> <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>
Cobwebby.
> <refsect2><title>Regular expressions and glob() syntax</title>
> <para>
> APT also supports pinning by glob() expressions and regular
> expressions surrounded by /. For example, the following
Add a comma to clarify that the glob expressions aren't surrounded
by slashes, and refer to the / character by name. In fact I'd also
subtract the brackets from "glob" (throughout), since end users
encounter it as a word for a wildcard pattern, not as a function.
[...]
> Pin: release n=karmic*
Slightly kobwebby.
> Pin-Priority: 990
> </programlisting>
>
> <para>
> If a regular expression occurs in a <literal>Package</literal> field,
> the behavior is the same as if this regular expression were replaced
> with a list of all package names it matches. It is undecided whether
> this will change in the future, thus you should always list wild-card
^
> pins first, so later specific pins override it.
Run-on sentence; use semicolon.
[...]
> <para>Then:
> <itemizedlist>
> <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</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>
Cobwebby, but also... Perl 5.9 as a Debian package? This also makes
me wonder about how 5.1* is interpreted - is it implicitly 5.1.x or
does it cover 5.14? (Perhaps we should just update it to refer to
5.10* versus 5.14* and avoid the issue.)
[...]
> <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
I haven't taken the "GNU/Linux" out because after all Woody didn't
have kfreebsd arches, but if that's updated it should go.
> <varlistentry>
> <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</filename> file.
> For example, the line "Component: main" specifies that
> 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:
Maybe this gives the impression that the DFSG is a big catalogue of
specific boilerplate licensing terms that packages can choose from;
in which case we'd be better off with something more like "entails
that they are licensed under terms compatible/compliant with" the
DFSG? Or maybe that makes it *too* vague - I'll leave it.
[...]
> Note that with this APT preference APT will follow the migration of a release
> from the archive <literal>testing</literal> to <literal>stable</literal> and
> later <literal>oldstable</literal>. If you want to follow for example the progress
> in <literal>testing</literal> notwithstanding the codename changes you should use
> the example configurations above.
"Notwithstanding" is a bit formal and legalistic, but I suppose it
fits.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Attachment:
apt_preferences.5.xml
Description: XML document
--- old/apt_preferences.5.xml 2012-05-21 10:41:17.000000000 +0100 +++ new/apt_preferences.5.xml 2012-05-28 12:46:06.843393048 +0100 @@ -58,22 +58,22 @@ <para>Preferences are a strong power in the hands of a system administrator but they can become also their biggest nightmare if used without care! -APT will not questioning the preferences so wrong settings will therefore +APT will not question the preferences, so wrong settings can lead to uninstallable packages or wrong decisions while upgrading packages. -Even more problems will arise if multiply distribution releases are mixed +Even more problems will arise if you mix multiple distribution releases without a good understanding of the following paragraphs. -Packages included in a specific release aren't tested in and -therefore doesn't always work as expected in older or newer releases or +Packages included in a specific release aren't tested in (and +therefore don't always work as expected in) older or newer releases, or together with other packages from different releases. You have been warned.</para> <para>Note that the files in the <filename>/etc/apt/preferences.d</filename> directory are parsed in alphanumeric ascending order and need to obey the -following naming convention: The files have either no or "<literal>pref</literal>" -as filename extension and only contain alphanumeric, hyphen (-), +following naming convention: the extension is "<literal>pref</literal>" +or nothing and filenames contain only alphanumeric, hyphen (-), underscore (_) and period (.) characters. -Otherwise APT will print a notice that it has ignored a file if the file -doesn't match a pattern in the <literal>Dir::Ignore-Files-Silently</literal> +Otherwise APT will print a notice that it has ignored a file, unless that +file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal> configuration list - in this case it will be silently ignored.</para> <refsect2><title>APT's Default Priority Assignments</title> @@ -106,14 +106,14 @@ <term>priority 1</term> <listitem><simpara>to the versions coming from archives which in their <filename>Release</filename> files are marked as "NotAutomatic: yes" but <emphasis>not</emphasis> as "ButAutomaticUpgrades: yes" -like the debian <literal>experimental</literal> archive.</simpara></listitem> +like the Debian <literal>experimental</literal> archive.</simpara></listitem> </varlistentry> <varlistentry> <term>priority 100</term> <listitem><simpara>to the version that is already installed (if any) and to the versions coming from archives which in their <filename>Release</filename> files are marked as "NotAutomatic: yes" and -"ButAutomaticUpgrades: yes" like the debian backports archive since <literal>squeeze-backports</literal>. +"ButAutomaticUpgrades: yes" like the Debian backports archive since <literal>squeeze-backports</literal>. </simpara></listitem> </varlistentry> @@ -185,7 +185,7 @@ <itemizedlist> <listitem> <simpara>The specific form assigns a priority (a "Pin-Priority") to one or more -specified packages and specified version or version range. For example, +specified packages with a specified version or version range. For example, the following record assigns a high priority to all versions of the <filename>perl</filename> package whose version number begins with "<literal>5.8</literal>". Multiple packages can be separated by spaces.</simpara> @@ -261,10 +261,10 @@ <refsect2><title>Regular expressions and glob() syntax</title> <para> -APT also supports pinning by glob() expressions and regular -expressions surrounded by /. For example, the following +APT also supports pinning by glob expressions, and regular +expressions surrounded by slashes. For example, the following example assigns the priority 500 to all packages from -experimental where the name starts with gnome (as a glob()-like +experimental where the name starts with gnome (as a glob-like expression) or contains the word kde (as a POSIX extended regular expression surrounded by slashes). </para> @@ -291,11 +291,11 @@ If a regular expression occurs in a <literal>Package</literal> field, the behavior is the same as if this regular expression were replaced with a list of all package names it matches. It is undecided whether -this will change in the future, thus you should always list wild-card +this will change in the future; thus you should always list wild-card pins first, so later specific pins override it. The pattern "<literal>*</literal>" in a Package field is not considered -a glob() expression in itself. +a glob expression in itself. </para> </refsect2>