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>