Re: Perhaps rearrange *Help* buffer a bit?

[Lars Ingebrigtsen]

"Basil L. Contovounesios" <address@hidden> writes:

> And in the case of variables, the trailing "You can _customize_ this
> variable" which indicates a user option.

Oh yeah, let's bikeshed the variable help buffers, too.  Here's a random
example:

---
gnus-summary-article-delete-hook is a variable defined in ‘gnus-sum.el’.
Its value is nil
Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*; global value is 
the same.

  This variable may be risky if used as a file-local variable.

Documentation:
A hook called after an article is deleted.

You can customize this variable.

This variable was introduced, or its default value was changed, in
version 22.1 of Emacs.
---

Let's see...  Along the lines of what Stefan bikeshod (that's the
correct past tense of "bikeshed"), we could have...

---
The value of `gnus-summary-article-delete-hook' value is
nil ...

Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*;
global value is the same.

A hook called after an article is deleted.
---

The "..." is a button that will reveal this text:

---
  `gnus-summary-article-delete-hook' is a variable defined in ‘gnus-sum.el’.
  This variable may be risky if used as a file-local variable.

  This variable was introduced, or its default value was changed, in
  version 22.1 of Emacs.

  You can customize this variable.
---

> And maybe also the indication of the presence of some advice on a named
> function: ":around advice: `some-function@my-advice'"
>
> And maybe some other usual suspects I'm forgetting about.

Probably; there's a lot of variations.  :-)

>> The first line is perhaps not vital for people to know either, but since
>> that's what I use to jump to function definitions, it's useful.  (But
>> perhaps a command that's just take us there is even better.)
>
> The first line also indicates whether a function is interactive,
> so I think it is useful for the average user.

That's true, so perhaps that line should stay at the start of the
buffer.

Let's look at one of these, and I choose at random:

---
insert-char is an interactive built-in function in ‘C source code’.

It is bound to C-x 8 RET.

(insert-char CHARACTER &optional COUNT INHERIT)

  Probably introduced at or before Emacs version 18.

[documentation here]
---

What about...

---
(insert-char CHARACTER &optional COUNT INHERIT) ...

This is an interactive function bound to C-x 8 RET.

[documentation here]
---


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no