Help buffer link on name of customizable thing (at start of buffer)

Help buffer link on name of customizable thing (at start of buffer)

[Drew Adams]

Suggestion for after the release -

In buffer *Help*, for help on a thing that is customizable, put the same
link on the name of the customizable thing (e.g. user variable or face), at
the beginning of the *Help* buffer, that is currently put on the word
"customize" at the bottom of the buffer.

Advantage: When you use, say, `C-v some-option', you can hit RET
immediately, to customize the thing, since the cursor is at `point-min' by
default. This is quicker than using, e.g., `M-x customize-option': instead
of `M-x customize-option RET foo RET', just use `C-h v foo RET RET'.

It also obviates any need for separate key bindings for `customize-this' and
`customize-that', as long as there is a binding for `describe-this' and
that. Being handy, this will quickly become a main entry point for
Customize, which is not a bad thing, IMO: a *Help* description, with the
current value shown, is a good place to start, before customizing something.

I don't see any reason not to do this. While the use of this link won't be
as obvious (but there would be a help tooltip) as the "You can customize
this variable" at the buffer bottom, users will learn and appreciate this
convenience.

We should also, obviously, keep the more explicit link at the bottom: "You
can customize this variable".

Also, the same form (i.e., the same *Help* buffer layout) should be used for
faces and user options. This is not the case now. Currently, `describe-face'
puts a "(customize this face)" link right after the face name, on the first
*Help* buffer line, whereas `describe-variable' puts a "You can customize
this variable" link at the bottom of the buffer, just before the [back]
button. The latter form is preferable, IMO.

Re: Help buffer link on name of customizable thing (at start of buffer)

[Richard Stallman]

    In buffer *Help*, for help on a thing that is customizable, put the same
    link on the name of the customizable thing (e.g. user variable or face), at
    the beginning of the *Help* buffer, that is currently put on the word
    "customize" at the bottom of the buffer.

    Advantage: When you use, say, `C-v some-option', you can hit RET
    immediately, to customize the thing, since the cursor is at `point-min' by
    default. This is quicker than using, e.g., `M-x customize-option': instead
    of `M-x customize-option RET foo RET', just use `C-h v foo RET RET'.

I see no harm in it.  Does anyone else object?

    Also, the same form (i.e., the same *Help* buffer layout) should be used for
    faces and user options. This is not the case now. Currently, `describe-face'
    puts a "(customize this face)" link right after the face name, on the first
    *Help* buffer line, whereas `describe-variable' puts a "You can customize
    this variable" link at the bottom of the buffer, just before the [back]
    button. The latter form is preferable, IMO.

I did describe-face that way for a reason.  The face-spec data is
usually big enough that it won't fit on the screen.  If we put "You
can customize this face" at the end, the user would not initially see
it.  For describe-variable, that CAN happen, but it is rare.

There is no problem in principle with putting at the top
for variables, just as it is for faces.

RE: Help buffer link on name of customizable thing (at start of buffer)

[Drew Adams]

        Also, the same form (i.e., the same *Help* buffer layout)
        should be used for faces and user options. This is not
        the case now. Currently, `describe-face'
        puts a "(customize this face)" link right after the face
        name, on the first *Help* buffer line, whereas
        `describe-variable' puts a "You can customize
        this variable" link at the bottom of the buffer, just
        before the [back] button. The latter form is preferable, IMO.

    I did describe-face that way for a reason.  The face-spec data is
    usually big enough that it won't fit on the screen.  If we put "You
    can customize this face" at the end, the user would not initially see
    it.  For describe-variable, that CAN happen, but it is rare.

Good point.

    There is no problem in principle with putting at the top
    for variables, just as it is for faces.

It would be good to treat them similarly, so people used to one don't have
to hunt with the other.