From: Lars Ingebrigtsen <larsi@gnus.org>
To: "Basil L. Contovounesios" <contovob@tcd.ie>
Cc: emacs-devel@gnu.org
Subject: Re: Perhaps rearrange *Help* buffer a bit?
Date: Tue, 09 Jul 2019 00:38:42 +0200 [thread overview]
Message-ID: <m37e8sywwd.fsf@gnus.org> (raw)
In-Reply-To: <871rz0i5ik.fsf@tcd.ie> (Basil L. Contovounesios's message of "Mon, 08 Jul 2019 22:24:35 +0100")
"Basil L. Contovounesios" <contovob@tcd.ie> 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
next prev parent reply other threads:[~2019-07-08 22:38 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-07-08 20:18 Perhaps rearrange *Help* buffer a bit? Lars Ingebrigtsen
2019-07-08 20:29 ` Drew Adams
2019-07-08 20:31 ` Drew Adams
2019-07-08 21:14 ` Stefan Monnier
[not found] ` <m3bly4yxgq.fsf@gnus.org>
[not found] ` <jwv5zocaz3r.fsf-monnier+emacs@gnu.org>
2019-07-09 13:58 ` Lars Ingebrigtsen
2019-07-09 14:18 ` Stefan Monnier
2019-07-10 3:58 ` Howard Melman
2019-07-10 11:27 ` Lars Ingebrigtsen
2019-07-10 12:59 ` Howard Melman
2019-07-10 14:06 ` Drew Adams
2019-07-08 21:24 ` Basil L. Contovounesios
2019-07-08 22:38 ` Lars Ingebrigtsen [this message]
2019-07-09 0:02 ` Eric Abrahamsen
2019-07-09 0:59 ` Basil L. Contovounesios
2019-07-09 3:26 ` Eric Abrahamsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m37e8sywwd.fsf@gnus.org \
--to=larsi@gnus.org \
--cc=contovob@tcd.ie \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).