Subject: Bug#1012872: software-properties-common: add-apt-repository man page appears garbled, confusing and incomplete

From: Ross Boylan <[email-masked]>
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-masked]

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