Subject: software-properties-common: add-apt-repository man page appears garbled, confusing and incomplete
Date: Wed, 15 Jun 2022 17:25:40 -0700
Package: software-properties-common
Version: 0.96.20.2-2.1rb1
Severity: normal
X-Debbugs-Cc: [email protected]
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
**Garbled**
The REPOSITORY STRING section of the man page refers to 3 forms. Usually I
would expect a "form" to be a particular form of the command line in the
SYNOPSIS, but there is only a single form given there.
The REPOSITORY STRING section, in the first sentence, says that REPOSITORY can
either be a line in the form ppa:... or a distribution component. That's 2
alternatives. Which also doesn't match 3 forms.
The first sentence says ppa: is added directly to sources.list, with a link to
that man page. But the sources.list man page has no references to ppa's (which
is probably why a couple of sentences later says that ppa: specifications are
rewritten before insertion to sources.list).
If we try to interpret the subsequent discussion of forms as relating to this,
we have the problem that there are 2 alternatives but 3 forms. And the second
form is a ppa, even though that was the first alternative in the opening
sentence. And the paragraph about the "second form" says the ppa will be
expanded, but the opening description says it is "a line that can be added
directly".
**Confusing**
It is not clear to me what is meant by a "distribution component", and I don't
know what it means that it will be "enabled for all sources".
There is a --massive-debug option, described as "print a lot of debug
information." It doesn't, at least when adding a repository.
And the addition of a ppa doesn't actually work, but that's a separate issue:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1012649
- --remove turns this command from "add" to "subtract". Using add-xxx to remove
is a bit confusing and surprising, though not unprecedented. Perhaps a rm-apt-
repository command could be added as a symlink, with the usual tricks so that
behavior of the program depends on how it's invoked.
**Incomplete**
When adding a ppa to sources.list a release gets inserted as well. It was
"kinetic" for all the ones I tried, including one repository that didn't have
anything for the kinetic release. The insertion of a release seems worth
mentioning along with how the release is chosen and how, if at all, one can
alter the choice. Perhaps this the "distribution component" referred to
earlier?
**Speculation**
The exact opening of the garbled section is
REPOSITORY can be either a line that can be added directly to
sources.list(5),
in the form ppa:<user>/<ppa-name> for adding Personal Package Archives, or a
distribution component to enable.
The material between commas, starting with "in the form ppa:" appears to be an
appositive, a way of rephrasing that which came before it (actually it
restricts the meaning). Given the previously noted fact that the thing before
(line that can be added directly) means something different from a ppa, I think
the intended meaning is
REPOSITORY can take 3 forms
1. a line that can be added directly to sources.list
2. ppa:<user>/<ppa-name> for adding Personal Package Archives
3. a distribution component to enable.
Then the 3 forms discussed in the rest of this section refer to those 3
alternatives, in that order.
This interpretation/rewrite resolves most of the issues in the **Garbled**
section, although it might be better if the SYNOPSIS actually did show 3 forms
directly.
- -- System Information:
Debian Release: 11.3
APT prefers stable-security
APT policy: (500, 'stable-security'), (500, 'stable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386
Kernel: Linux 5.10.0-15-amd64 (SMP w/8 CPU threads)
Kernel taint flags: TAINT_PROPRIETARY_MODULE, TAINT_OOT_MODULE,
TAINT_UNSIGNED_MODULE
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE not
set
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Versions of packages software-properties-common depends on:
ii ca-certificates 20210119
ii gir1.2-glib-2.0 1.66.1-1+b1
ii gir1.2-packagekitglib-1.0 1.2.2-2
ii python-apt-common 2.2.1
ii python3 3.9.2-3
ii python3-dbus 1.2.16-5
ii python3-gi 3.38.0-2
ii python3-software-properties 0.96.20.2-2.1rb1
Versions of packages software-properties-common recommends:
ii packagekit 1.2.2-2
software-properties-common suggests no packages.
-----BEGIN PGP SIGNATURE-----
iQFSBAEBCgA8FiEEreS674/HIyV9gBfdnAYPmOsbK2AFAmKqeHYeHHJvc3Nib3ls
YW5Ac3RhbmZvcmRhbHVtbmkub3JnAAoJEJwGD5jrGytg++UH/0eJe1VMqT3iuvkS
Vu3GcCldZofsuE9t+/uqfvnpXOhO50U/oJR8JUYA3uPHKxC5l7fQ2t/DcjTFWQ73
kliPkOGlYkGYNif+xgoOd68joShDl7MA9DZggRvghGjzj1nMeQ3gPbnbn0Y1guRh
br0l65Ypp1xicfT7M8050EPYapEBqFZexlmoVnzcT7Ub18IoiLi9iKAlYcnroYjz
dyrEQFJvAaZWWsCNrW1g27fa2wLjzWmBBmgESVkdEODp2ZzZxOnvlVrOKM9VEWRj
EEGtu6/DCWqjE5oTQnG571uzTqfAnhgcp4DmT4E8AkwhXQmUjOmFooz6LEdQHsol
WGR2hzk=
=u0JB
-----END PGP SIGNATURE-----
Debbugs is free software and licensed under the terms of the GNU General
Public License version 2. The current version can be obtained
from https://bugs.debian.org/debbugs-source/.