Re: Request for Review: APT manpages
On Sat, May 26, 2012 at 6:59 PM, Justin B Rye <jbr@edlug.org.uk> wrote:
> apt-get.8.xml is much less problematic.
>
>> <refsect1><title>Description</title>
>> <para><command>apt-get</command> is the command-line tool for handling packages, and may be
>> considered the user's "back-end" to other tools using the APT
>> library. Several "front-end" interfaces exist, such as &dselect;,
>> &aptitude;, &synaptic; and &wajig;.</para>
>
> This is a great description, when compared with the apt package
> description's nonsense about being a *front-end* for the dpkg package
> manager.
JFYI: We changed "recently" the descriptions after some discussion here;
it neither includes dpkg nor front-end anymore. The old description probably
dates back to a time in which apt-get, apt-cache and co were considered
demo-applications to show what libapt-pkg could do - until the graphical
packagemanager was done, which was worked on right from the start but
never really happened in the end. I searched a while for this old data, but it
seems to be lost somewhere in the cvs -> arch transition as a bit of other
stuff - like many parts of the name choosing discussion… :/
> [...]
>> <varlistentry><term><option>update</option></term>
> [...]
>> <varlistentry><term><option>upgrade</option></term>
> [...]
>> <varlistentry><term><option>dselect-upgrade</option></term>
> [...]
>> <varlistentry><term><option>dist-upgrade</option></term>
>
> These are all pretty good, so I find myself wondering about things
> like: why are they in this order, particularly? It might once have
> been a sort of "order of importance", but if so, I can see one to
> demote.
Good idea, as moving paragraphs is a free action I just moved
dselect- below dist-upgrade. Not a really big demote, but moving
it away from the rest of the upgrade-commands doesn't feel right.
>> <varlistentry><term><option>install</option></term>
>> <listitem>
>> <para><literal>install</literal> is followed by one or more
>> packages desired for installation or upgrading.
>> Each package is a package name, not a fully qualified
>> filename (for instance, in a Debian GNU/Linux system,
>> libc6 would be the argument provided, not
>> <literal>libc6_1.9.6-2.deb</literal>). All packages required
>
> Ooh, a use of "Linux" where it's entitled to distinguish. This is of
> course very old, but more importantly, where's the arch in that
> filename? I'll update it to the version currently in Sid:
>
> not, say, <literal>libc6_2.13-32_amd64.deb</literal>).
True and true. I changed this to 'apt-utils' package instead of
'libc6' though. Available on all Debian systems (and more) and
I know it's version number at build-time.
To be a bit picky here: There is no immediate need for an architecture
here. The package could be called foo.deb, too, even if it includes
libc6… such an example is probably better of showing the most
likely filename though…
>> by the package(s) specified for installation will also
>> be retrieved and installed.
>> The <filename>/etc/apt/sources.list</filename> file is
>> used to locate the desired packages. If a hyphen is
>> appended to the package name (with no intervening space),
>> the identified package will be removed if it is installed.
>> Similarly a plus sign can be used to designate a
>> package to install. These latter features may be used
>> to override decisions made by apt-get's conflict
>> resolution system.
>> </para>
>
> (I've always wondered how the packages memtest86 and memtest86+ avoid
> breaking this.)
([Developers best friend: g++.] It is simple, the key is "If a hyphen is
appended to the package name". It just checks if what you have
given to it is a package name, and if not it will check if it is
a package name without + or -…)
>>
>> <para>A specific version of a package can be selected for installation by
>> following the package name with an equals and the version of the package
>> to select. This will cause that version to be located and selected for
>> install. Alternatively a specific distribution can be selected by
>> following the package name with a slash and the version of the
>> distribution or the Archive name (stable, testing, unstable).</para>
>
> Oh, I didn't know "apt-get install libc6/6.0.5" worked. But it
> doesn't exactly state that I can ask for an unnumbered codename like
> "/wheezy", too. I would suggest saying something like:
>
> Alternatively a specific distribution can be selected by
> following the package name with a slash and the archive name (stable,
> testing, unstable) or distribution (by version or codename).
Mhhh. I was never really happy with "archive name" for 'stable' and co -
and the author seems to agree with me as he wrote examples in brackets.
"Suite" isn't that much better, but it is used nowadays in that sense
(as the field is called like that now, it used to be Archive…).
I think I will leave it as is for now and after wheezy use whatever is
used in the final repository format documentation.
> [...]
>> <varlistentry><term><option>source</option></term>
>> <listitem><para><literal>source</literal> causes <command>apt-get</command> to fetch source packages. APT
>> will examine the available packages to decide which source package to
>> fetch. It will then find and download into the current directory the
>> newest available version of that source package while respecting the
>> default release, set with the option <literal>APT::Default-Release</literal>,
>> the <option>-t</option> option or per package with the
>> <literal>pkg/release</literal> syntax, if possible.</para>
>
> It isn't clear that the -t option and the pkg/release syntax override
> the default rather than providing other ways of setting it (the
> postposed "if possible" doesn't help). Make it:
>
> [...] while where possible respecting the default release, which can be
> set with the option <literal>APT::Default-Release</literal>, or
> overridden by the <option>-t</option> option or per package with the
> <literal>/release</literal> syntax.</para>
Mhh, in fact the -t option is the APT::Default-Release option.
So you are overriding with -t at most what you have set in a
configuration file (or an earlier "-o APT::Default-Release").
Not sure if it is that worthwhile to stress this though…
>> in the &sources-list; file. This means that you will need to add such a line
>> for each repository you want to get sources from. If you don't do this
>> you will properly get another (newer, older or none) source version than
>> the one you have installed or could install.</para>
>
> s/properly/probably/ - I can guess who wrote this! And a none source
You are properly [sic!] right.
That stuff happens if you let a dyslexic write documentation…
Probably not the last time, but I will try to use them properly now.
Bottom line: Feel free to point such stuff out directly then you see it -
it's nice to know that I already made a lasting impression,
but I would prefer it if it wouldn't be with such mistakes. ;)
>> <varlistentry><term><option>-q</option></term><term><option>--quiet</option></term>
>> <listitem><para>Quiet; produces output suitable for logging, omitting progress indicators.
>> More q's will produce more quiet up to a maximum of 2. You can also use
>
> I was prepared to put up with this up to a maximum of 0 times.
:)
I guess at some point there was a plan to have more levels,
but that point is passed long long ago and nobody will be willing
to "put up" with a change on that "level" now…
> Using a second q will make it even quieter.
Maybe "Adding" instead of "Using"? (and wrapping q in <literal>)
> [...]
>> <para>Simulation run as user will deactivate locking (<literal>Debug::NoLocking</literal>)
>> automatic. Also a notice will be displayed indicating that this is only a simulation,
>> if the option <literal>APT::Get::Show-User-Simulation-Note</literal> is set (Default: true).
>> Neither NoLocking nor the notice will be triggered if run as root (root should know what
>> he is doing without further warnings by <literal>apt-get</literal>).</para>
>
> Various problems.
>
> Simulated runs performed as a user will automatically deactivate locking
> (<literal>Debug::NoLocking</literal>), and if the option
> <literal>APT::Get::Show-User-Simulation-Note</literal> is set
> (as it is by default) a notice will also be displayed indicating that
> this is only a simulation. Runs performed as root do not trigger either
> NoLocking or the notice - superusers should know what they are doing
> without further warnings from <literal>apt-get</literal>.
(One of my first contributions to apt-get ~3 years ago --
and I think the first thing which got a manpage paragraph)
Just a remark: Somehow this "not trigger either … or …" sounds like it will
be decided randomly which of the two will not be triggered for my untrained
ears, hence the "neither … nor …" in my take instead.
>> <refsect1><title>See Also</title>
>> <para>&apt-cache;, &apt-cdrom;, &dpkg;, &dselect;, &sources-list;,
>> &apt-conf;, &apt-config;, &apt-secure;,
>> The APT User's guide in &guidesdir;, &apt-preferences;, the APT Howto.</para>
>> </refsect1>
>
> (The APT Howto is labelled "obsolete")
The label "dated" or "not maintained anymore" would be better.
It has no real successor and even though nobody updated it for quiet
a while the basic stuff is still true as APT doesn't change a lot
(at least not in a user-visible incompatible way).
At some point we should take that and merge it with the similar
dated APT Guide we have. If this will ever happen? I don't know…
Best regards
David Kalnischkies
P.S.: Sorry for the delay, I am currently a bit low on time,
but I will try to work on your other reviews for next week.
Reply to: