Subject: RE: bug#23926: defcustom with STANDARD=<non-pure-expression> gives confusing results

From: Drew Adams <[email-masked]>
Date: Sun, 10 Jul 2016 10:23:13 -0700 (PDT)

> IOW, let's try to be clear with the labelling in `C-h v' -
> consistent with the names used in Customize.  And let's try to
> let users of `C-h v' get more info about what they're looking
> at, to dispel confusion and answer questions.
> 
> I think we should also have `C-h v' provide the underlying
> Lisp expression, at least on demand, just as Customize does.
> It's not great to show only a value without any indication
> of what it comes from.
...
> That is what needs to be made clear to users, I think, when
> showing them a value.  Let them know that it is called the
> "standard value", and it is the result of re-evaluating, in
> the current context, the defining Lisp sexp for the option
> (which is used in the defcustom).
> 
> All of this is important for clarity.  In particular, I think
> it is important that users understand the following, which is
> I guess what is behind Eli saying that the behavior is as
> expected:
> 
> ;; The reason for storing values unevaluated: This is so you can have
> ;; values that depend on the environment.  For example, you can have a
> ;; variable that has one value when Emacs is running under a window
> ;; system, and another value on a tty.  Since the evaluation is only done
> ;; when the variable is first initialized, this is only relevant for the
> ;; saved (and standard) values, but affect others values for
> ;; compatibility.
> 
> The premise of that last sentence is wrong, of course.  It is done
> each time you use `C-h v' - to show you the "original" value.
> 
> But the main point here is that it is a _feature_, not a bug, that
> the "standard value" is recomputed at any time from the original sexp.
> Why/how this is a feature is explained well in that paragraph.
> 
> But without such an explanation, and especially just showing a
> value in `C-h v' and calling it the "original" value, we hurt
> instead of help users.
> 
> ;; You can see (and modify and save) this unevaluated value by selecting
> ;; "Show Saved Lisp Expression" from the Lisp interface.  This will
> ;; give you the unevaluated saved value, if any, otherwise the
> ;; unevaluated standard value.
> 
> And that's the other piece that helps understanding.  I think
> `C-h v' should show users that Lisp sexp - at least on demand.
> 
> That will also help understanding of the standard value that is
> shown (and should be labeled as such): `C-h v' can say that this
> is the result of re-evaluating the Lisp sexp.

Here are a couple proposals for how to fix the `C-h v' part of
this bug.  Others are welcome.

1. Not print the "original value" at all, as was the case before
   Emacs 24.  Let users get such info from Customize.

2. Like #1, but give users a hint that such info is in fact
   available from Customize.  My suggestion here would be to not
   only remove printing the "original value" but to change the text
   "You can customize this variable.", where `customize' is a link to
   Customize, with this text, all of it a link with the same target:

      Customize or inspect

   (or possibly "Inspect or customize").  The point is for the
   link text to indicate that the target (Customize for the option)
   is not only for changing the value but also for finding out more
   about the option and its customization.

3. Like #1 and #3, but also provide a (toggle) link to show the
   defining Lisp sexp for the default value or, if it is shown,
   to reevaluate it and show the result:

      Show Lisp sexp defining the default value

   (if not shown) and

      Reevaluate

   (if shown - displayed just above it, in place of "Show Lisp sexp
   defining the default value").

I think any of these would improve the `C-h v' doc, especially for
this situation where the Lisp sexp can return different values.

If you decide to go for any of these approaches I could work on
a patch.

(Note that this mail is only about the `C-h v' part of the bug.
It does not address the part that concerns how the Customize UI
talks about the state - see my previous message about that part.)