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.
