bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Michael Heerdegen]

Hello,

I'm not sure why "write-contents-functions" isn't named "...-hook".
Anyway, since its named -functions, shouldn't we say what arguments the
members should accept? (AFAIK the answer is: functions are called with
no arguments).

You might argue that the thing is also called a "hook" in the docstring,
but it also seems to call the members of the variable "hooks" later in
the doc, as far as I understand it.  So for me it's all a bit unclear
and confusing.


Thanks,

Michael.

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Wed, 20 Feb 2019 04:55:49 +0100
> 
> I'm not sure why "write-contents-functions" isn't named "...-hook".

Because we need to call those functions with
run-hook-with-args-until-success, I guess.

> Anyway, since its named -functions, shouldn't we say what arguments the
> members should accept? (AFAIK the answer is: functions are called with
> no arguments).

I agree it would be good to say that in the doc string (yes, no
arguments is the right answer).

> You might argue that the thing is also called a "hook" in the docstring,
> but it also seems to call the members of the variable "hooks" later in
> the doc, as far as I understand it.  So for me it's all a bit unclear
> and confusing.

Is it less confusing now?

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> I agree it would be good to say that in the doc string (yes, no
> arguments is the right answer).

Ok, good.

> Is it less confusing now?

Yes, I'm fine with doing that to fix this.


Thanks,

Michael.

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I'm not sure why "write-contents-functions" isn't named "...-hook".

  > Because we need to call those functions with
  > run-hook-with-args-until-success, I guess.

This naming convention should be documented in the Emacs Lisp
Reference Manual.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: michael_heerdegen@web.de, 34588@debbugs.gnu.org
> Date: Wed, 20 Feb 2019 22:32:08 -0500
> 
>   > Because we need to call those functions with
>   > run-hook-with-args-until-success, I guess.
> 
> This naming convention should be documented in the Emacs Lisp
> Reference Manual.

It is, but this case goes against the convention, thus Michael's
question.

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > From: Richard Stallman <rms@gnu.org>
> > Cc: michael_heerdegen@web.de, 34588@debbugs.gnu.org
> > Date: Wed, 20 Feb 2019 22:32:08 -0500
> >
> >   > Because we need to call those functions with
> >   > run-hook-with-args-until-success, I guess.
> >
> > This naming convention should be documented in the Emacs Lisp
> > Reference Manual.
>
> It is, but this case goes against the convention, thus Michael's
> question.

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.

Michael.

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[martin rudalics]

 > 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.

martin

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Michael Heerdegen]

martin rudalics <rudalics@gmx.at> writes:

> 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.

Hmm, you're right, the explanation clearly tells it.  Dunno how to
improve it to let people pay more attention - more jokes maybe?

Michael.

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > 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.

  > Hmm, you're right, the explanation clearly tells it.  Dunno how to
  > improve it to let people pay more attention - more jokes maybe?

If people work on this, I think they will find a way.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Stefan Kangas]

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.