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.
[...]
> <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.
> <listitem><para><literal>dist-upgrade</literal> in addition to performing the function of
> <literal>upgrade</literal>, also intelligently handles changing dependencies
> with new versions of packages; <command>apt-get</command> has a "smart" conflict
> resolution system, and it will attempt to upgrade the most important
> packages at the expense of less important ones if necessary.
> So, <literal>dist-upgrade</literal> command may remove some packages.
This is the first bit that's felt significantly unidiomatic. Make it
The <literal>dist-upgrade</literal> command may therefore remove some packages.
[...]
>
> <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>).
> 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.)
>
> <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).
> <para>Both of the version selection mechanisms can downgrade packages and must
> be used with care.</para>
>
> <para>This is also the target to use if you want to upgrade one or
> more already-installed packages without upgrading every package
[...]
"Target" is a makeism, and may therefore be rather unfriendly to
non-developers, but never mind.
> <varlistentry><term><option>remove</option></term>
> <listitem><para><literal>remove</literal> is identical to <literal>install</literal> except that packages are
> removed instead of installed. Note the removing a package leaves its
Typo: s/the/that/
> configuration files in system. If a plus sign is appended to the package
s/in/on the/
> name (with no intervening space), the identified package will be
> installed instead of removed.</para></listitem>
> </varlistentry>
[...]
> <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>
> <para>Source packages are tracked separately
> from binary packages via <literal>deb-src</literal> type lines
They aren't just "deb-src type lines", they're deb-src lines.
> 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
version is awkward... besides, getting a source version different from
the binary package version you would have got with "apt-get install"
may be intentional (I deliberately set up my sources.list to let me
fetch and patch unstable sources on my stable desktop). Maybe:
[...]; otherwise you will probably get either the wrong
(too old/too new) source versions or none at all.
[...]
> <para>Note that source packages are not tracked like binary packages, they
> exist only in the current directory and are similar to downloading source
> tar balls.</para></listitem>
Well, that's not true - if I cd somewhere else they're not in my
current directory any longer, are they? And once I'm being pedantic:
source packages aren't similar to downloading source tarballs; it's
downloading them that's similar to (and involves) downloading source
tarballs. Rephrase it:
Note that source packages are not installed and tracked in the dpkg
database like binary packages; they are simply downloaded to the
current directory, like source tarballs.
[...]
> <varlistentry><term><option>changelog</option></term>
> <listitem><para><literal>changelog</literal> downloads a package changelog and displays
> it through <command>sensible-pager</command>. The server name and base
> directory is defined in the <literal>APT::Changelogs::Server</literal>
> variable (e. g. <ulink url="http://packages.debian.org/changelogs";>packages.debian.org/changelogs</ulink> for
^
Space surplus.
[...]
> <varlistentry><term><option>-m</option></term><term><option>--ignore-missing</option></term>
> <term><option>--fix-missing</option></term>
> <listitem><para>Ignore missing packages; If packages cannot be retrieved or fail the
^
Capitalisation surplus.
[...]
> <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.
Using a second q will make it even quieter.
> <option>-q=#</option> to set the quiet level, overriding the configuration file.
> Note that quiet level 2 implies <option>-y</option>, you should never use -qq
^
Run-on sentence; use semicolon.
> without a no-action modifier such as -d, --print-uris or -s as APT may
> decided to do something you did not expect.
^
Spurious past tense.
[...]
> <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>.
> <para>Simulate prints out
> a series of lines each one representing a dpkg operation, Configure (Conf),
> Remove (Remv), Unpack (Inst). Square brackets indicate broken packages
> and empty set of square brackets meaning breaks that are of no consequence
> (rare).</para></listitem>
> </varlistentry>
Another paragraph I'd rather just rewrite slightly:
Simulated runs print out a series of lines, each representing a dpkg
operation: configure (Conf), remove (Remv), or unpack (Inst). Square
brackets indicate broken packages, and empty square brackets
indicate breaks that are of no consequence (rare).
"Square brackets" is slightly un-en_US, but saying plain "brackets"
would risk confusing en_GB users, so never mind.
[...]
> <varlistentry><term><option>--ignore-hold</option></term>
> <listitem><para>Ignore package Holds; This causes <command>apt-get</command> to ignore a hold
^ ^
Capitalisation surplus (also in a couple more cases below).
[...]
> <varlistentry><term><option>--print-uris</option></term>
> <listitem><para>Instead of fetching the files to install their URIs are printed. Each
> URI will have the path, the destination file name, the size and the expected
> md5 hash. Note that the file name to write to will not always match
^^
Capitalisation deficit.
[...]
> <varlistentry><term><option>--list-cleanup</option></term>
> <listitem><para>This option defaults to on, use <literal>--no-list-cleanup</literal> to turn it
> off. When on <command>apt-get</command> will automatically manage the contents of
Rephrase slightly:
This option is on by default; use <literal>--no-list-cleanup</literal> to turn
it off. When it is on, [...]
[...]
> <varlistentry><term><option>-t</option></term>
> <term><option>--target-release</option></term>
> <term><option>--default-release</option></term>
> <listitem><para>This option controls the default input to the policy engine, it creates
s/,/;/ as usual.
> a default pin at priority 990 using the specified release string.
> This overrides the general settings in <filename>/etc/apt/preferences</filename>.
> Specifically pinned packages are not affected by the value
> of this option. In short, this option
> lets you have simple control over which distribution packages will be
> retrieved from. Some common examples might be
> <option>-t '2.1*'</option>, <option>-t unstable</option>
> or <option>-t sid</option>.
I'm not convinced Slink pins are common any longer, but I'll leave it
for now.
[...]
> <varlistentry><term><option>--trivial-only</option></term>
> <listitem><para>
> Only perform operations that are 'trivial'. Logically this can be considered
> related to <option>--assume-yes</option>, where <option>--assume-yes</option> will answer
^
> yes to any prompt, <option>--trivial-only</option> will answer no.
> Configuration Item: <literal>APT::Get::Trivial-Only</literal>.</para></listitem>
> </varlistentry>
[...]
> <varlistentry><term><option>--auto-remove</option></term>
> <listitem><para>If the command is either <literal>install</literal> or <literal>remove</literal>,
> then this option acts like running <literal>autoremove</literal> command, removing the unused
^the ^^^
Shuffle the articles.
> dependency packages. Configuration Item: <literal>APT::Get::AutomaticRemove</literal>.
[...]
>
> <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")
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- old/apt-get.8.xml 2012-05-21 10:41:17.000000000 +0100
+++ new/apt-get.8.xml 2012-05-26 17:47:53.771380015 +0100
@@ -86,7 +86,7 @@
with new versions of packages; <command>apt-get</command> has a "smart" conflict
resolution system, and it will attempt to upgrade the most important
packages at the expense of less important ones if necessary.
- So, <literal>dist-upgrade</literal> command may remove some packages.
+ The <literal>dist-upgrade</literal> command may therefore remove some packages.
The <filename>/etc/apt/sources.list</filename> file contains a list of locations
from which to retrieve desired package files.
See also &apt-preferences; for a mechanism for
@@ -98,9 +98,9 @@
<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
+ filename (for instance, on a Debian GNU/Linux system,
+ libc6 would be the argument provided, not, say,
+ <literal>libc6_2.13-32_amd64.deb</literal>). All packages required
by the package(s) specified for installation will also
be retrieved and installed.
The <filename>/etc/apt/sources.list</filename> file is
@@ -117,8 +117,8 @@
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>
+ following the package name with a slash and the archive name (stable,
+ testing, unstable) or distribution (by version or codename).</para>
<para>Both of the version selection mechanisms can downgrade packages and must
be used with care.</para>
@@ -149,8 +149,8 @@
<varlistentry><term><option>remove</option></term>
<listitem><para><literal>remove</literal> is identical to <literal>install</literal> except that packages are
- removed instead of installed. Note the removing a package leaves its
- configuration files in system. If a plus sign is appended to the package
+ removed instead of installed. Note that removing a package leaves its
+ configuration files on the system. If a plus sign is appended to the package
name (with no intervening space), the identified package will be
installed instead of removed.</para></listitem>
</varlistentry>
@@ -164,17 +164,16 @@
<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>
+ newest available version of that source package while where possible respecting the
+ default release, which can be set with the option <literal>APT::Default-Release</literal>,
+ or overriden by the <option>-t</option> option or per package with the
+ <literal>/release</literal> syntax.</para>
<para>Source packages are tracked separately
- from binary packages via <literal>deb-src</literal> type lines
+ from binary packages via <literal>deb-src</literal> lines
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>
+ for each repository you want to get sources from; otherwise you will probably
+ get either the wrong (too old/too new) source versions or none at all.</para>
<para>If the <option>--compile</option> option is specified
then the package will be compiled to a binary .deb using
@@ -189,9 +188,9 @@
package name and version, implicitly enabling the
<literal>APT::Get::Only-Source</literal> option.</para>
- <para>Note that source packages are not tracked like binary packages, they
- exist only in the current directory and are similar to downloading source
- tar balls.</para></listitem>
+ <para>Note that source packages are not installed and tracked in the dpkg
+ database like binary packages; they are simply downloaded to the current
+ directory, like source tarballs.</para></listitem>
</varlistentry>
<varlistentry><term><option>build-dep</option></term>
@@ -241,7 +240,7 @@
<listitem><para><literal>changelog</literal> downloads a package changelog and displays
it through <command>sensible-pager</command>. The server name and base
directory is defined in the <literal>APT::Changelogs::Server</literal>
- variable (e. g. <ulink url="http://packages.debian.org/changelogs";>packages.debian.org/changelogs</ulink> for
+ variable (e.g. <ulink url="http://packages.debian.org/changelogs";>packages.debian.org/changelogs</ulink> for
Debian or <ulink url="http://changelogs.ubuntu.com/changelogs";>changelogs.ubuntu.com/changelogs</ulink> for
Ubuntu).
By default it displays the changelog for the version that is
@@ -291,7 +290,7 @@
<varlistentry><term><option>-m</option></term><term><option>--ignore-missing</option></term>
<term><option>--fix-missing</option></term>
- <listitem><para>Ignore missing packages; If packages cannot be retrieved or fail the
+ <listitem><para>Ignore missing packages; if packages cannot be retrieved or fail the
integrity check after retrieval (corrupted package files), hold back
those packages and handle the result. Use of this option together with
<option>-f</option> may produce an error in some situations. If a package is
@@ -310,11 +309,11 @@
<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
+ Using a second q will make it even quieter. You can also use
<option>-q=#</option> to set the quiet level, overriding the configuration file.
- Note that quiet level 2 implies <option>-y</option>, you should never use -qq
+ Note that quiet level 2 implies <option>-y</option>; you should never use -qq
without a no-action modifier such as -d, --print-uris or -s as APT may
- decided to do something you did not expect.
+ decide to do something you did not expect.
Configuration Item: <literal>quiet</literal>.</para></listitem>
</varlistentry>
@@ -328,17 +327,18 @@
actually change the system.
Configuration Item: <literal>APT::Get::Simulate</literal>.</para>
- <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>
-
- <para>Simulate prints out
- a series of lines each one representing a dpkg operation, Configure (Conf),
- Remove (Remv), Unpack (Inst). Square brackets indicate broken packages
- and empty set of square brackets meaning breaks that are of no consequence
- (rare).</para></listitem>
+ <para>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>.</para>
+
+ <para>Simulated runs print out a series of lines, each representing a dpkg
+ operation: configure (Conf), remove (Remv), or unpack (Inst). Square
+ brackets indicate broken packages, and empty square brackets
+ indicate breaks that are of no consequence (rare).</para></listitem>
</varlistentry>
<varlistentry><term><option>-y</option></term><term><option>--yes</option></term>
@@ -383,21 +383,21 @@
</varlistentry>
<varlistentry><term><option>--ignore-hold</option></term>
- <listitem><para>Ignore package Holds; This causes <command>apt-get</command> to ignore a hold
+ <listitem><para>Ignore package holds; this causes <command>apt-get</command> to ignore a hold
placed on a package. This may be useful in conjunction with
<literal>dist-upgrade</literal> to override a large number of undesired holds.
Configuration Item: <literal>APT::Ignore-Hold</literal>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--no-upgrade</option></term>
- <listitem><para>Do not upgrade packages; When used in conjunction with <literal>install</literal>,
+ <listitem><para>Do not upgrade packages; when used in conjunction with <literal>install</literal>,
<literal>no-upgrade</literal> will prevent packages on the command line
from being upgraded if they are already installed.
Configuration Item: <literal>APT::Get::Upgrade</literal>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--only-upgrade</option></term>
- <listitem><para>Do not install new packages; When used in conjunction
+ <listitem><para>Do not install new packages; when used in conjunction
with <literal>install</literal>, <literal>only-upgrade</literal> will
install upgrades for already installed packages only and ignore requests
to install new packages.
@@ -405,7 +405,7 @@
</varlistentry>
<varlistentry><term><option>--force-yes</option></term>
- <listitem><para>Force yes; This is a dangerous option that will cause apt to continue
+ <listitem><para>Force yes; this is a dangerous option that will cause apt to continue
without prompting if it is doing something potentially harmful. It
should not be used except in very special situations. Using
<literal>force-yes</literal> can potentially destroy your system!
@@ -415,7 +415,7 @@
<varlistentry><term><option>--print-uris</option></term>
<listitem><para>Instead of fetching the files to install their URIs are printed. Each
URI will have the path, the destination file name, the size and the expected
- md5 hash. Note that the file name to write to will not always match
+ MD5 hash. Note that the file name to write to will not always match
the file name on the remote site! This also works with the
<literal>source</literal> and <literal>update</literal> commands. When used with the
<literal>update</literal> command the MD5 and size are not included, and it is
@@ -432,13 +432,13 @@
</varlistentry>
<varlistentry><term><option>--reinstall</option></term>
- <listitem><para>Re-Install packages that are already installed and at the newest version.
+ <listitem><para>Re-install packages that are already installed and at the newest version.
Configuration Item: <literal>APT::Get::ReInstall</literal>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--list-cleanup</option></term>
- <listitem><para>This option defaults to on, use <literal>--no-list-cleanup</literal> to turn it
- off. When on <command>apt-get</command> will automatically manage the contents of
+ <listitem><para>This option is on by default; use <literal>--no-list-cleanup</literal> to turn
+ it off. When it is on, <command>apt-get</command> will automatically manage the contents of
<filename>&statedir;/lists</filename> to ensure that obsolete files are erased.
The only reason to turn it off is if you frequently change your source
list.
@@ -448,7 +448,7 @@
<varlistentry><term><option>-t</option></term>
<term><option>--target-release</option></term>
<term><option>--default-release</option></term>
- <listitem><para>This option controls the default input to the policy engine, it creates
+ <listitem><para>This option controls the default input to the policy engine; it creates
a default pin at priority 990 using the specified release string.
This overrides the general settings in <filename>/etc/apt/preferences</filename>.
Specifically pinned packages are not affected by the value
@@ -464,7 +464,7 @@
<varlistentry><term><option>--trivial-only</option></term>
<listitem><para>
Only perform operations that are 'trivial'. Logically this can be considered
- related to <option>--assume-yes</option>, where <option>--assume-yes</option> will answer
+ related to <option>--assume-yes</option>; where <option>--assume-yes</option> will answer
yes to any prompt, <option>--trivial-only</option> will answer no.
Configuration Item: <literal>APT::Get::Trivial-Only</literal>.</para></listitem>
</varlistentry>
@@ -477,7 +477,7 @@
<varlistentry><term><option>--auto-remove</option></term>
<listitem><para>If the command is either <literal>install</literal> or <literal>remove</literal>,
- then this option acts like running <literal>autoremove</literal> command, removing the unused
+ then this option acts like running the <literal>autoremove</literal> command, removing unused
dependency packages. Configuration Item: <literal>APT::Get::AutomaticRemove</literal>.
</para></listitem>
</varlistentry>
Attachment:
apt-get.8.xml
Description: XML document