Dear Maintainer,

The man pages do not make it clear that the full-upgrade and
dist-upgrade commands are aliases that perform the same operation.

In doc/apt.8.xml, only full-upgrade is mentioned but apt accepts both.

In doc/apt-get.8.xml, full-upgrade is not listed as an alias but is
mentioned under the update option where dist-upgrade is not.

Both man pages should list both commands as alternate terms, and all
references to the command in the synopsis and other sections should only
use the preferred term. Ideally, both documents would prefer the same
term, for consistency, but at least each should be self-consistent.

Regards,
Roy.

Well yes that is intentional, dist-upgrade is a misleading name, so
the more user-friendly apt(8) tool has it renamed to full-upgrade, but
of course we keep muscle memory compatibility modes.

We support various other typo/muscle memory aliases that aren't necessarily
documented.

That's weird but stuff happens.

I must say I don't care much about these nitpicks. The manual pages are
in total disarray and need to be rewritten from scratch, with one per
subcommand, they're not useful in their current shape.

There is no suggestion to change the commands, themselves, only to pick
a consistent approach in the documentation.

Perhaps they also should be.

If it were nitpicking, there wouldn't be as many questions on the
Internet like <https://askubuntu.com/q/770135>. Users don't know whether
there's a difference, and the man page won't tell them.

That seems a tad dramatic. They *are* useful and people are still taught
that man pages are the first thing they should consult.