Bug#475341: documentation of `install'/`remove'; suggested replacement text
Package: apt
Version: 0.7.11
Severity: minor
[A related bug is #462962 `apt-get --no-install-recommends is not
documented in man page'.]
The fact that apt-get now automatically installs packages that are
merely recommended isn't documented, and the existing documentation for
`apt-get install' is misleading.
install is followed by one or more packages desired for installation.
[...] All packages required by the package(s) specified for
installation will also be retrieved and installed.
I interpret `required by the package(s)' as referring only to Depends,
not Recommends. As it explicitly mentions installation of not only the
specified packages but also their requirements, I take this to be the
complete set of packages that are installed by this command, not merely
a subset.
(One could argue whether or not this is the best interpretation, but
nevertheless it is the interpretation that I made of the documentation,
and I'm a native english speaker, and I suppose that many people will
have this erroneous interpretation. It would be good to avoid having
people come to the wrong impression about the behaviour if we can.)
It should be explicitly specified what the behaviour of `apt-get install
foo.*-' is, i.e. whether the trailing hyphen-minus is considered part of
the regular expression or a request to remove any packages matching the
specified regular expression. The current documentation is unclear
about this: it says that `install' "is followed by one or more
packages...", and that a hyphen may be appended to a `package name',
but then describes how "the given expression" may be interpreted as a
regexp. There is no definition of what "expression" means here (e.g.
whether it includes any specified plus/minus/slash/equals suffix),
and it is unclear whether such suffixes may be used with regular
expressions. The documentation that clarifies the meaning of `foo.*-'
should in particular draw attention to the meaning/legality of `foo.\+'.
The current documentation says `followed by one or more packages';
i.e. the current documentation doesn't document the command `apt-get
install' (with no following package names).
The current documentation says `is followed by one or more packages
desired for installation', making it unclear whether `apt-get install
foo-' is legal (or alternatively what its behaviour is, i.e. whether
"desired for installation" trumps the description of the hyphen suffix).
Less importantly, it might be good to draw attention to the behaviour
for alternates (`|') and virtual package names. Or at least somehow
draw attention to the fact that there may be other solutions besides
what apt-get suggests.
I suggest the following text; though note that I haven't checked the
behaviour for some of the issues raised above, so the below text may be
incorrect.
install REQUEST...
Installs or uninstalls packages according to the specified
requests.
Each REQUEST consists of a package name specification, optionally
immediately followed (with no intervening space) by a suffix (see
below).
In the usual case, REQUEST consists solely of a package name, and
represents a request to install or upgrade the package of the given
name.
More generally, the package name specification is first interpreted
as a package name. If no package of the specified name is
found[*1], and the given specification contains any of the
characters `.', `?' or `*' [fixme: what about `[' or `\' ? The
reason to include `\' is for `\+'. Note that if `\' is mentioned
then we should probably retract the test for `?'.],
then it is interpreted as a POSIX basic regular expression, and
refers to the set of package names in the database[*2] that match
this regular expression. Note that matching is done by substring
so `lo.*' matches `how-lo' and `lowest'. If this is undesired,
anchor the regular expression with a `^' or `$' character, or
create a more specific regular expression.
[fixme: Document the behaviour if no package names match this
regexp, i.e. whether it's silently treated as an empty set or
whether it's considered an error.]
[*1 fixme: What exactly does "no matching package is found" mean?
E.g. if the user requests to remove foo.bar and no foo.bar package
is installed but the package list does include a foo.bar package,
then does that count as found or not found? What if
/var/lib/dpkg/status includes a foo.bar package but its status is
config-files or purged? What if it's unremovable for some other
reason such as being Required or Essential?]
[*2 fixme: Similarly, define what "the database" means, i.e.
whether it includes /var/lib/dpkg/info, whether it includes lists
of available packages, and whether this is affected by whether the
package is requested for installation or removal.]
[fixme: Specify that the regular expression may not contain slash
characters, and specify any restrictions on hyphen-minus and plus
characters. Specify whether or not the regular expression is
allowed to contain `=' (as part of an equivalence class
expression). Should probably require the package name
specification to be a non-empty string. Consider making some
provision for expanding the possible suffixes, e.g. consider
specifying that behaviour is unspecified if the package name
specification includes any punctuation characters other than `.',
`+', `-', `^', `$', `:', `\', `(', `)', `[', `]', `{', `}', `?',
`*', `,', `|', possibly `=' (see above), and possibly `<' and `>'
(see below). (I.e. the punctuation characters allowed in package
names or that have special meaning in POSIX basic regular
expressions.) Single Unix Spec
(http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html)
doesn't seem to mention `\<' and `\>'; they seem to be covered only
by the sentence "The interpretation of an ordinary character
preceded by a backslash ('\') is undefined.". Consider explicitly
mentioning the behaviour of `\<', `\>', `\b', `\B', `\w' and `\W',
which are mentioned in the documentation of GNU grep but not
defined by the SUS page whose URL I gave above.]
The suffix after the package name specification may take the
following forms:
empty / not present: Install the specified package(s).
`+' (plus sign): Equivalent to empty / not present.
[fixme: Is there any difference? The existing documentation is
unclear on this, suggesting that `+' may have some special role
in conflict resolution. E.g. for `apt-get install a c' where
a Depends: b | c, I wonder whether both b and c might get
installed with a, where `apt-get install a +c' might install
just c with a.]
`-' (ASCII hyphen-minus sign): Uninstall the specified
package(s).
[Existing descriptions of equals and slash forms.]
The documentation of `remove' would correspondingly use the phrase
`package name specification' to be clear about the regexp possibility.
In the documentation of `remove', please explicitly specify the
behaviour if the suffix is `-': either say "if the suffix is either a
plus sign or hyphen/minus sign then the package is removed" or "if the
suffix is a plus sign then ...; if the suffix is a hyphen/minus sign
then ..." or "The suffix is not allowed to be hyphen/minus.".
Comments about how apt-get handles cases with multiple solutions might
go to a separate section, with pointers to it from the documentation for
individual actions: i.e. where documentation of individual actions say
"the dependencies/requirements/required", add "(see section Multiple
Solutions)". Said section would mention alternates (a | b), virtual
packages (Provides), and the upgrade/remove decision; and would also
mention the use of +/- as one way of specifying which solution to take.
One way of avoiding some of the problems mentioned above about regexps
(`=', uncertain behaviour in some cases with package names containing
`.') would be to use a clearly distinct syntax, such as requiring (or
allowing) the regexp to be surrounded by /.../ markers (noting that
slash suffix then becomes `/foo//testing').
pjrm.
Reply to: