[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Bug#624618: apt: Maybe time to modernize APT package description

David Kalnischkies wrote:
>>  Package: apt
>>  Description: Debian's advanced package tool
>>  This package provides command-line utilities for package management,
>>  including apt-get, used for finding and fetching software upgrades,
>>  and apt-cache, used for interrogating the package database. It depends
>>  on dpkg as its back-end for installs, and can be used either directly
>>  or via high-level interfaces such as aptitude.
> The package apt provides more than just apt-get and apt-cache -
> even through these are arguable the most prominent.

True, it ought to lead with some description of APT providing a package
management infrastructure.
> That it depends on dpkg already says the Depends: and wouldn't be
> really a useful information for me as is i guess and while it indeed

(In fact of course apt doesn't have a "Depends:" on dpkg; but yes, I
just meant "built on top of".)

> provides a high-level interface i wouldn't pick one out of the endless
> possibilities as the preferences for one or the other varies between
> users and even between upgrade-instructions especially as a decent
> front-end can use the Suggests line, which mentions a few, a lot better
> than free form text to show other options.

The point of mentioning dpkg and aptitude (which when I wrote this a
few years ago was the officially recommended one) wasn't to suggest
installing them but simply to clarify apt's position as a sort of
> More in-deep, apt-get isn't usually used to find packages, but to manage
> them which is distinct from just "fetching software upgrades" which
> could describe unattended-upgrades. It does even a bit more with
> subcommands like source, but that is possibly to much of detail…

It "finds and fetches" them in the sense that I can ask to install
mplayer and APT will decide which of the versions available in the
various repositories is the one I want, and what *other* packages I
therefore need, and go and get them all.  Probably not the best way of
putting it, but that was the functionality that made APT such a win 
back in ninety-whatever.
> And kind of more personal: APT is not shouting but 'apt' is a normal word
> and a package name while 'APT' is a name for our large family of tools
> ranging from apt-get to software-center.
> (A lot of) backronyms are available - yours is one of more popular.

Are you saying APT was named by randomly pulling alphanumerics out of
a hat, and that the fact it looks like an appropriate three-letter
acronym rather than being called, say, "7kjR" is sheer coincidence?
That seems unlikely, and even if it was true, it would still be a
service to our users to turn a meaningless TLA that they've got to
memorise into a relevant and, um, *apt* name.

> Anyway, i don't feel like including APT or one of the expansions in
> the description as it would have no meaning.

Explaining its meaning would have no meaning?

> So, while i know quite good what i don't want to read in it, i have no real
> idea what should be in so the best i came up with so far is the following
> what isn't exactly at my liking either…

Well, I'll nitpick obviously, but I like it.

> (so, we can have now another laugh together - especially the folks
>  from d-10n-english as i always thought i should ask for review there
>  and not for suggestions of complete descriptions, but okay…)
> apt: package manager interface

Dpkg and aptitude are also package manager interfaces, so this doesn't
help very much to identify the package's function.  We don't have to
state that APT officially stands for Advanced Package Tool, but
"Debian's advanced package tool" makes a perfectly fine package
synopsis regardless (hence my comment about deniability, though I
don't see why it's so crucial to be able to pretend that it's
user-hostile gibberish).

> This package provides the common ground for searching and
> managing packages as well as information about packages
> other package managers can be depend upon.

I agree with the idea of introducing the APT infrastructure as a whole
first, but I'd rephrase it to be clearer about the layers (and leave
the features it provides for the next paragraph).  Maybe:

  APT provides mechanisms for package management tasks, relying on dpkg as
  a back-end and providing an infrastructure that other tools can build on.

Phrasing it as a description of APT rather than apt also means we can
recycle this as the boilerplate paragraph for other binary packages
(though perhaps it does want to mention some features in that case?)

> .
> This includes:
> - retrieval of information about packages
> - retrieval of packages and all dependent packages
>   needed to satisfy a request
> - authenticating the sources and validating the retrieved data
> - installation and removal of packages in the system

Now that you mention it, yes, it definitely deserves a bulletpoint for
the authentication part... but could we add a reference to "knowing
which version you need, and where to get it"?

  It supports:
   * searching for package information;
   * resolving package install requests, finding the appropriate version
     in the archives;
   * fetching packages along with all their required dependencies;
   * authenticating the sources and validating the retrieved data;
   * installing and removing packages on a working system.

> .
> It also provides various terminal-based tools on its own:

(Just say "command-line", since none of them are full-terminal text
user interfaces.)

> - apt-get for managing packages and retrieval of information

I suppose "apt-get update" does retrieve information, but it's a bit

> - apt-cache for querying available information
> - apt-cdrom to use removable media as a source for packages
> - apt-config as an interface to the configuration settings
> - apt-key as an interface to manage authentication keys

A second entire bulleted list makes this feel a bit long.  Maybe we
can reduce this to a paragraph specific to apt, along the lines of:

  This package also contains several command-line tools, of which the
  most prominent are apt-get (for managing packages and the package
  database) and apt-cache (for retrieving package information).

Or alternatively we could integrate the two lists into one... no,
that's too tricky for me to do right now.  Anyway, that's probably
enough input from me - other opinions?
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package

Reply to: