Re: explanation of first column "v" is hiding

[Greg Wooledge <greg@wooledge.org>]

On Tue, Jul 27, 2021 at 03:38:31PM +1200, Richard Hector wrote:
> My main issue with aptitude documentation is that most of it isn't in the
> manpage, but in the 'aptitude reference manual' which is referred to without
> a link. The path given in the SEE ALSO section might be that, but it doesn't
> say so.

Agreed.  But it's a tricky line to walk, when you have a *lot* of
documentation.  It's reasonable to avoid writing bash(1)-sized man
pages, and to put the less-often-needed details in an external
reference.

However, I think the aptitude(8) man page has some room for improvement.

> But experience suggests that A means 'automatically installed' (and p stands
> for purged, which linguistically doesn't really mean 'maybe has been purged;
> maybe has never been installed').

See, it's *not just me*!  Nobody else can find the section that says
what the letters mean either.  Well, OK, not "nobody", but damned few
people know about it.

I know that "search" comes alphabetically before "why", but the most
common use of aptitude by people who only use it for one thing is
"aptitude why".  So, when there is *nothing* at all in the "why"
section that documents what the letters mean, most people will simply
assume it's not anywhere in the man page.

I would suggest taking the paragraph that describes what the letters
mean, which is currently under the "search" subcommand, and doing two
things to it:

1) Reformat it as a table.
2) Move it to a separate section, and drop a sentence in the "search"
   subcommand pointing to it.

Then, add that same sentence to the "why" subcommand, and to any other
subcommands that have the same single-letter output indicators.