Getting more info on a variable in Customize buffers

[Drew Adams]

Customize is the preferred way to alter user variables. It also provides
information about user variables. But it seems to me that it is in some ways
less helpful than `C-h v'.

If I do `C-h v ediff-before-setup-windows-hook', the *Help* buffer gives me,
in addition to the variable's value and the doc string: 1) a link to
Customize the variable and 2) a link to the source code. And I can search on
the variable name in Info and in the source code to learn more about the
variable.

However:

1) If I click Customize in the *Help* buffer from `C-h v', I arrive at a
Customize buffer for only that variable, where there is no link to the
custom group of the variable, so I can't see how it might be related to
other variables in the group. It might be that what I really need is a
similarly named variable, but I can't browse the group to find it. In fact,
I can't even see what custom group the variable belongs to (no group name is
indicated).

2) If I somehow get to the Customize group (ediff-hook) to customize the
same variable, without coming from the `C-h v' *Help* buffer:

2a) The variable name does not appear as such. Instead, the name is
prettified using title-case and replacing dashes with spaces. A variable
with a mixed-case name like `Info-enable-edit' is indistiguishable in this
format from one that is all lowercase. There is nothing that indicates to a
user what the real name of the variable is and that the displayed name is a
transformation of the real name.

This is important because it is the real variable name that is the user's
link to more information; the title-case headline name is, at best, just a
pretty face. It is only with the real variable name that you can use apropos
or search the Info doc or the source code or even the rest of the Customize
buffer (for references from other doc strings). It is the real variable name
that serves everywhere to refer to the variable. If you understand that
there _is_ a variable named similarly to the pretty title (already not that
obvious), and you understand the name transformation (again, not that
obvious), then you can search for more information on the variable. But you
can't use `C-s C-w' to grab the name for searching, and you can't use `C-h
v' with the cursor on the pretty name to pick up the real name.

For me, it would be more useful to show the real variable name than the
title-case headline-style pretty name.

2b) There is no link to the source code that defines the variable. You need
to derive the real variable name from the pretty name and type that into
`C-h v', just to get a link to the source code. Getting to the definition of
a variable or function is one of the great strengths of Emacs over other
programs. Doc strings are great, but they don't always substitute for
looking at the real definitions. In Emacs, there is a progression from doc
to code, and the two reinforce each other. Lack of a link to the defining
code is an obstacle to that reinforcement.

2c) The variable value does not appear in its Lisp form. In some cases, it
is possible to see the Lisp form, but in other cases it cannot be seen.
Since many Emacs users also program Emacs Lisp, it would be good to provide
a link (button) that displays the Lisp value, exactly as shown in `C-v'.
Yes, Customize was designed so you don't have to be a Lisp programmer, but
it wouldn't hurt to make Lisp info available on demand.


All of this means that you are handicapped using Customize: you have less
information accessible to help you understand a variable and its relations
to commands and other variables. Customize should provide more information
than `C-h v', not less, even if that info is revealed only on demand.

The variable name is the most important piece of info in the Customize
buffer. With it, you can obtain most of the other info displayed there (`C-h
v'). If there is one thing the Customize buffer should show clearly,
literally, it's the variable name.

So, I suggest:

 - To the Customize buffer for a group containing a variable, we add:
   1) the real variable name, in such a way that it can be copied
      for pasting and searching and picked up by variable-at-point
   2) a link to the variable definition in the source code
   3) a button to display the Lisp value of the variable (Hide/
      Show/Show Lisp would do the trick).
   4) perhaps a link to the variable's explanation in Info
      (when appropriate)

   These could all be hidden under the More button, but it would be
   better if the variable name were not hidden, so it can be the
   target of a search. Alternatively, if the real name were hidden
   under More, we could add a single button to expand all the More
   buttons, to enable search across all the More information. Expand
   All for values might also be useful (though less so), for the same
   reason.

 - To the Customize buffer for an individual variable only, we add:
   1) everything listed above for the Customize group buffer
   2) a link to the Customize group buffer

Alternatively, we could eliminate the Customize buffer for an individual
variable altogether. Clicking the Customize link in *Help* would instead
take you to the correct entry in the Customize group buffer. That would have
the advantage of providing more context and related information.