Re: Request for Review: APT manpages

[David Kalnischkies <kalnischkies+debian@gmail.com>]

On Mon, May 28, 2012 at 8:17 PM, Justin B Rye <jbr@edlug.org.uk> wrote:
> 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.

It's kind of usual for the documentation to say "apt.conf" while meaning
apt.conf, apt.conf.d/ files, the file given by environment setting APT_CONF
and last not least the -c flag. Same for sources.list and it's little
brother sources.list.d (we kind of even use it for files like Release
 meaning InRelease and Release.gpg as well or for the other indexes all
 their compressed siblings).

The specific "file" here is unwanted surplus through
(the same at some other places in this "section").
Removed.


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

Reviews can really be heartless. One sentence earns a "good" and
the next one is covered in red… Changed.


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

Mhh. Yeah, the sentence is supposed to boldly smash the "fourth wall"
in the moment of least surprise as a highlight. So if you have no problem
as is with the passive i will keep it - also, because i am not sure if it
would be that nice to change from passive to active in a typo fix.


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

"the extension is nothing" sounds equally strange to my ears.
We have the very same wording in two more manpages,
maybe you convenience me in those.


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

(I think APT had first dibs on "origin" as the Release file is younger,
 but yeah, i guess we should just switch to "host" or something alike
 as this is what the value is in reality after all…)


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

(I replaced glob() with a reference to the manpage "glob(7)" instead.)


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

Just did this. We don't do guesses on the version number format,
so 5.1* would indeed match 5.14.


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

I wonder if we can get away in wheezy+1 by just referring in this section
to the repository format documentation which should define what Component
and co is and just enumerate what you have to do to match them.
(beside that the debian-policy uses "area" for "component" instead…)


Best regards

David Kalnischkies