doc and help for defvaralias

doc and help for defvaralias

[Drew Adams]

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.

Re: doc and help for defvaralias

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> 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'."

Why?

-Miles

-- 
Suburbia: where they tear out the trees and then name streets after them.

Re: doc and help for defvaralias

[Stefan Monnier]

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


        Stefan

RE: doc and help for defvaralias

[Drew Adams]

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

RE: doc and help for defvaralias

[Drew Adams]

Let me be clearer about the connection to variables in this use case:

    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

and using variables

    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

and variables

    that start with `eyedrop-', library palette.el provides
    `eyedrop-' aliases to its fancier versions (which are defined
    with prefix `palette-').

The point here was about variable aliases, but I didn't make that clear in
the use-case description. Libraries use the `eyedrop-' variables and in fact
get the `palette-' variables.

    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

of `eyedrop-' functions and variables,

    thanks to the aliases.

Re: doc and help for defvaralias

[Richard Stallman]

Given that we have both defvaralias and
define-obsolete-variable-alias, it is silly to assume that defvaralias
is only for variables that are obsolete.  When the reason for the
alias is that a name is obsolete, people should use
define-obsolete-variable-alias instead.

So I tend to agree with you about this question.