From: Stefan Kangas <stefan@marxist.se>
To: Richard Stallman <rms@gnu.org>
Cc: Michael Heerdegen <michael_heerdegen@web.de>, 34588@debbugs.gnu.org
Subject: bug#34588: 27.0.50; Doc of write-contents-functions: arguments?
Date: Sat, 23 Oct 2021 11:11:54 -0700 [thread overview]
Message-ID: <CADwFkmnaFaaJKJqEF_Q2UUB8kPV6WncYgfXq2pRfcPvTfDqcZw@mail.gmail.com> (raw)
In-Reply-To: <E1gx0E4-0000QR-Ba@fencepost.gnu.org> (Richard Stallman's message of "Thu, 21 Feb 2019 21:06:08 -0500")
close 34588 28.1
thanks
martin rudalics <rudalics@gmx.at> writes:
>> Maybe Richard meant we should document that something should _not_ be
>> called "-hook" when it is called with
>> `run-hook-with-args-until-success'? That _would_ have answered my
>> question, and stating that as a convention would make sense to me.
>
> The Elisp manual already says that as
>
> If the hook variable's name does not end with `-hook', that
> indicates it is probably an "abnormal hook". That means the hook
> functions are called with arguments, or their return values are used in
> some way. The hook's documentation says how the functions are called.
> You can use `add-hook' to add a function to an abnormal hook, but you
> must write the function to follow the hook's calling convention. By
> convention, abnormal hook names end in `-functions'.
>
> and
>
> The variables whose names end in `-functions' are usually "abnormal
> hooks" (some old code may also use the deprecated `-hooks' suffix);
> their values are lists of functions, but these functions are called in
> a special way (they are passed arguments, or their return values are
> used). The variables whose names end in `-function' have single
> functions as their values.
>
> and for 'write-contents-functions' it says that
>
> If any of the functions in this hook returns non-`nil', the file
> is considered already written and the rest are not called and
> neither are the functions in `write-file-functions'.
>
> so the naming convention is preserved and everything should have been
> clear. I believe that due to how the documentation is written,
> readers intuitively pay less attention to the "or their return values
> are used in some way" and "or their return values are used" phrases.
I clarified this to:
"That means one of two things: either that the hook functions are
called with arguments, or that their their return values are used in
some way."
And:
"Their values are lists of functions, but these functions are called
in a special way: they are either passed arguments, or their return
values are used in some way."
This change has been pushed to emacs-28 (commit 4fd5c8df67).
I believe this is sufficiently clear, so I'm closing this bug report.
Feel free to install any further tweaks. Thanks.
prev parent reply other threads:[~2021-10-23 18:11 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-02-20 3:55 bug#34588: 27.0.50; Doc of write-contents-functions: arguments? Michael Heerdegen
2019-02-20 17:13 ` Eli Zaretskii
2019-02-21 2:59 ` Michael Heerdegen
2019-02-21 3:32 ` Richard Stallman
2019-02-21 3:47 ` Eli Zaretskii
2019-02-21 4:24 ` Michael Heerdegen
2019-02-21 9:17 ` martin rudalics
2019-02-21 9:29 ` Michael Heerdegen
2019-02-22 2:06 ` Richard Stallman
2021-10-23 18:11 ` Stefan Kangas [this message]
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CADwFkmnaFaaJKJqEF_Q2UUB8kPV6WncYgfXq2pRfcPvTfDqcZw@mail.gmail.com \
--to=stefan@marxist.se \
--cc=34588@debbugs.gnu.org \
--cc=michael_heerdegen@web.de \
--cc=rms@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 external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.