RE: 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.

    I think in order to know what should be done, we have to take
    into account what it is used for.  IIRC defvaralias was introduced
    specifically to deal with renaming variables and deprecating
    the old name, and AFAIK there hasn't been any other use of it yet.

    So it makes sense for C-h v to omit the "obsolete" name.

1. defvaralias hasn't even been introduced yet - Emacs 22 is not yet
released. It is not correct to speak of what it is (can be, will be) for,
beyond what its designer might have had in mind. Things are often used in
unexpected ways, not all of which are improper. It is incorrect to identify
"what it is used for" with why it "was introduced", especially since what it
is used for cannot be determined yet.

2. I have used `defvaralias' to provide an alias (!) - no connection with
deprecation. I have two libraries, one of which (eyedropper.el) is a
rudimentary version the other (palette.el), providing only some of its
functionality. The rudimentary library is for Emacs versions before Emacs
22, but that is irrelevant - one might simply be a lightweight, reduced
version of the other.

Some other libraries use (require) the eyedropper functionality, calling
functions defined in eyedropper.el and named using prefix `eyedrop-'.
Library palette.el redefines the eyedropper commands, providing them with
additional bells and whistles. Because the other libraries use functions
that start with `eyedrop-', library palette.el provides `eyedrop-' aliases
to its fancier versions (which are defined with prefix `palette-'). If you
use Emacs 22 and you have palette.el loaded, then you can use the other
libraries as is and take advantage of the palette.el versions, thanks to the
aliases.

3. Regardless of the possible uses to which `defvaralias' will actually be
put in practice ("wet and see", as the French say en anglais), the doc
string should reflect what `defvaralias' actually *does*. It is for this
reason that I sent my email. Doc and help should mention that the alias and
its target are value *synonyms* - see my email for the explanation, reasons,
and consequences. If changing the value of one also changes the value of the
other, then each should be referenced in the doc for the other.

4. There is a separate function for defining an alias that is intended to be
used to deprecate an existing variable: `define-obsolete-variable-alias'.
The existence of `define-obsolete-variable-alias' argues all the more
strongly for agnosticism on the part of `defvaralias' wrt its possible use
to alias an obsolete variable. Nothing prevents you from using `defvaralias'
with such an intention (e.g. as a preliminary step before ultimately
deprecating), but nothing requires `defvaralias' to be associated in any way
with deprecation. On its own, it simply does not deprecate anything.

If the intention of `defvaralias' is "specifically to deal with renaming
variables and deprecating the old name", as you say, then why introduce
`define-obsolete-variable-alias'? The `define-obsolete-variable-alias' doc
string explains that it is equivalent to `defvaralias' plus
`make-obsolete-variable'. That pretty much puts a hole through the argument
that `defvaralias' was introduced to rename AND deprecate. It is
`define-obsolete-variable-alias' that is intended for that use.

Also, there is nothing in the doc string of `defvaralias' that suggests that
it is intended to deprecate an obsolete name (good). The Elisp manual's
introduction at node Variable Aliases does suggest that, but the description
of the function itself does not. I suggest removing that misconceived
suggestion from the intro, and leaving the doc of `defvaralias' 100%
agnostic wrt obsolescence - it in no way deprecates a variable, so we should
not suggest that it does.

See my original email for more explanation.