[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Request for Review: APT manpages



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: application/xml

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

Reply to: