doc and help for defvaralias

["Drew Adams" <drew.adams@oracle.com>]

This email is about defvaralias; it is not about obsolete
variables (e.g. define-obsolete-variable-alias).
`defvaralias' does not make a variable obsolete; it just
defines an alias.

1. The doc string and Elisp manual doc for defvaralias is
incomplete, explaining only that setting the alias also sets
the variable that is the alias target.  The doc should
mention that the opposite is also true: setting the value of
what the alias points to also sets the alias value. One or
two simple "and vice versa"'s would suffice to make this
clear.

The intro to the Elisp manual section where defvaralias is
described does mention the bidirectionality in general
terms, but it should also be explicitly stated for
defvaralias.


2. defvaralias defines synonyms, for most intents and
purposes.  Yes, the alias and its target are
distinguishable, and that can be important in some contexts.
But they always have the same value - they are "value
synonyms".  Most code and, interactively, most users don't
care which is the alias and which is the "original" - they
use the two interchangeably, being interested only in the
value.

Doc and help should support this, while still distiguishing
the two for those who care.  Help on either should mention
both; in fact, it should mention all variables that are
linked by a defvaralias tree, forming an equivalence class
of sorts (symbols whose values are always equal).

For (defvaralias 'foo 'bar), `describe-variable' on foo says
that it is an alias for bar, but `describe-variable' on bar
says nothing about foo.  Help on bar should say something
like this:

 "`bar' has the following aliases: `foo'."

For (defvaralias 'foo 'bar) (defvaralias 'toto 'foo)
(defvaralias 'titi 'bar), help on bar should say something
like this:

 "`bar' has the following aliases: `foo', `toto', `titi'."

Similarly, help on foo, toto, or titi should say not only
what it is a direct alias for (bar, foo, and bar,
respectively). It should also list all other aliases:

 "`foo' has the following aliases: `bar', `toto', `titi'."

These help phrases use "alias" in the English sense of
"synonym".  When interpreted as a phrase about defvaralias
definitions, however, the phrases are not really accurate.
It is not true, for example, that a defvaralias was defined
pointing toto directly to bar; toto is not a defvaralias for
bar, so you might argue that it is misleading to say that
bar has toto as one of its aliases.

If you don't like "alias" in these help phrases, then we
could instead use "value synonyms" or just "synonyms".
Again, for most purposes, the details of the defvaralias
links are irrelevant: users will consider all of the linked
terms to be synonyms.

If you think it is important to also provide all of the
defvaralias dependency details in Help (none of it is
provided today), then both direct aliases and the
equivalence class of value synonyms could be listed
(separately).

Or, the defvaralias tree could simply be shown - that would
convey all of the info in a clear way:

 `foo' has synonyms:

   bar + foo - toto
       |
       + titi

In addition, we might detect cycles at that time, and,
instead of raising a `cyclic-variable-indirection' error,
Help could show the defvaralias graph - that would point out
precisely where the problem is.  (It might not be simple to
depict the graph, however.)

It is important to show the entire list of variables that
are equivalent for most purposes.  Showing the actual
(directional) defvaraliases would be only icing on the cake.
The current practice of showing nothing for help on the
"original" variable is in any case unhelpful.