bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Ulrich Müller]

Section 13.9 "Accessing Function Cell Contents" of the GNU Emacs Lisp
Reference Manual emphasizes the distinction between void and nil
in function cells:

|    Note that void is not the same as ‘nil’ or the symbol ‘void’.
| The symbols ‘nil’ and ‘void’ are Lisp objects, and can be stored into
| a function cell just as any other object can be (and ‘void’ can be a
| valid function if you define it with ‘defun’).  A void function cell
| contains no object whatsoever.

|    You can test the voidness of a symbol's function definition with
| ‘fboundp’.  After you have given a symbol a function definition, you
| can make it void once more using ‘fmakunbound’.

Also, for "fboundp":

|      This function returns ‘t’ if the symbol has an object in its
|      function cell, ‘nil’ otherwise.  It does not check that the
|      object is a legitimate function.

It seems that the actual behavior does not reflect this, i.e. there
is no distinction between nil and void:

   (fmakunbound 'foo)
   (fboundp 'foo) ⇒ nil

   (fset 'foo nil)
   ;; according to the manual, the following should return t
   ;; because nil is a Lisp object:
   (fboundp 'foo) ⇒ nil

Is the manual wrong, or am I missing something?

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Eli Zaretskii]

> From: Ulrich Müller <ulm@gentoo.org>
> Date: Sat, 19 Oct 2024 16:37:33 +0200
> 
> Section 13.9 "Accessing Function Cell Contents" of the GNU Emacs Lisp
> Reference Manual emphasizes the distinction between void and nil
> in function cells:
> 
> |    Note that void is not the same as ‘nil’ or the symbol ‘void’.
> | The symbols ‘nil’ and ‘void’ are Lisp objects, and can be stored into
> | a function cell just as any other object can be (and ‘void’ can be a
> | valid function if you define it with ‘defun’).  A void function cell
> | contains no object whatsoever.
> 
> |    You can test the voidness of a symbol's function definition with
> | ‘fboundp’.  After you have given a symbol a function definition, you
> | can make it void once more using ‘fmakunbound’.
> 
> Also, for "fboundp":
> 
> |      This function returns ‘t’ if the symbol has an object in its
> |      function cell, ‘nil’ otherwise.  It does not check that the
> |      object is a legitimate function.
> 
> It seems that the actual behavior does not reflect this, i.e. there
> is no distinction between nil and void:
> 
>    (fmakunbound 'foo)
>    (fboundp 'foo) ⇒ nil
> 
>    (fset 'foo nil)
>    ;; according to the manual, the following should return t
>    ;; because nil is a Lisp object:
>    (fboundp 'foo) ⇒ nil
> 
> Is the manual wrong, or am I missing something?

I think the manual is wrong.  I think it tries to explain wrt void
functions the same it says about void variables, but we handle void
variables differently from void functions: void variables have a
distinct value in their value cell, whereas void functions have nil in
their function cell.

Stefan, am I right?

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Andreas Schwab]

On Okt 19 2024, Ulrich Müller wrote:

> Is the manual wrong, or am I missing something?

That changed in commit eadf1faa3cb, but the manual wasn't updated.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Ulrich Müller]

>>>>> On Sat, 19 Oct 2024, Andreas Schwab wrote:

> On Okt 19 2024, Ulrich Müller wrote:
>> Is the manual wrong, or am I missing something?

> That changed in commit eadf1faa3cb, but the manual wasn't updated.

Then the respective docstrings are also outdated, i.e. the term "void"
shouldn't occur in any of these:

   (fboundp SYMBOL)
   Return t if SYMBOL’s function definition is not void.

   (fmakunbound SYMBOL)
   Make SYMBOL’s function definition be void.
   Return SYMBOL.

   (symbol-function SYMBOL)
   Return SYMBOL’s function definition, or nil if that is void.

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> Section 13.9 "Accessing Function Cell Contents" of the GNU Emacs Lisp
>> Reference Manual emphasizes the distinction between void and nil
>> in function cells:
>> 
>> |    Note that void is not the same as ‘nil’ or the symbol ‘void’.
>> | The symbols ‘nil’ and ‘void’ are Lisp objects, and can be stored into
>> | a function cell just as any other object can be (and ‘void’ can be a
>> | valid function if you define it with ‘defun’).  A void function cell
>> | contains no object whatsoever.

Oops.  Looks like I missed this part when I changed it back around
Emacs-24.4:

    ** In 'symbol-function', nil and "unbound" are indistinguishable.
    'symbol-function' does not signal a 'void-function' error any more.
    To determine if a symbol's function definition is void, use 'fboundp'.

> I think the manual is wrong.

Indeed.  It was right for Emacs<24.4, tho.


        Stefan

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Ulrich Müller <ulm@gentoo.org>,
>   73886@debbugs.gnu.org
> Date: Sat, 19 Oct 2024 22:12:48 -0400
> 
> >> Section 13.9 "Accessing Function Cell Contents" of the GNU Emacs Lisp
> >> Reference Manual emphasizes the distinction between void and nil
> >> in function cells:
> >> 
> >> |    Note that void is not the same as ‘nil’ or the symbol ‘void’.
> >> | The symbols ‘nil’ and ‘void’ are Lisp objects, and can be stored into
> >> | a function cell just as any other object can be (and ‘void’ can be a
> >> | valid function if you define it with ‘defun’).  A void function cell
> >> | contains no object whatsoever.
> 
> Oops.  Looks like I missed this part when I changed it back around
> Emacs-24.4:
> 
>     ** In 'symbol-function', nil and "unbound" are indistinguishable.
>     'symbol-function' does not signal a 'void-function' error any more.
>     To determine if a symbol's function definition is void, use 'fboundp'.

Could you explain the rationale for that change?  I tried to look for
relevant discussions around that date, but came up empty-handed.

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> Oops.  Looks like I missed this part when I changed it back around
>> Emacs-24.4:
>> 
>>     ** In 'symbol-function', nil and "unbound" are indistinguishable.
>>     'symbol-function' does not signal a 'void-function' error any more.
>>     To determine if a symbol's function definition is void, use 'fboundp'.
>
> Could you explain the rationale for that change?  I tried to look for
> relevant discussions around that date, but came up empty-handed.

I can't remember discussing it, no.  It was a kind of "executive
decision".

Having a special "void" (`Qundefined`) non-value for the `symbol-value`
is needed for `boundp` since variables can contain *any* value, but not
for the `symbol-function` part where we can use any normal value (I
chose `nil`) to play this role as long as it doesn't collide with values
normally held in the `symbol-function` slot, like function names,
function values, cons cells, vectors, ...

The upside was a simplification in various chunks of code which used to
do things like `(and (fboundp SYM) (symbol-function SYM))` which can now
be simplified to `(symbol-function SYM)`.

I remember two "motivators", i.e. places where the need to pay attention
to the special void case annoyed me enough to look into this and make
the change, one was `nadvice.el` and the other was `cl-letf`.
[ So, it was no accident that the change happened in the same release as
  the addition of `nadvice.el`.  ]

In both cases the issue is that we want to deal with "places"
(generalized variables) and that abstraction works well for those places
which *always* contain a value, but not as well for those special places
that can be "unbound", so removing the "unbound" case from
`symbol-function` resulted in a welcome simplification.
For the same reason I dislike EIEIO's notion of `slot-boundp` and have
already considered marking it obsolete.



        Stefan

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: ulm@gentoo.org,  73886@debbugs.gnu.org
> Date: Sun, 20 Oct 2024 12:56:03 -0400
> 
> >> Oops.  Looks like I missed this part when I changed it back around
> >> Emacs-24.4:
> >> 
> >>     ** In 'symbol-function', nil and "unbound" are indistinguishable.
> >>     'symbol-function' does not signal a 'void-function' error any more.
> >>     To determine if a symbol's function definition is void, use 'fboundp'.
> >
> > Could you explain the rationale for that change?  I tried to look for
> > relevant discussions around that date, but came up empty-handed.
> 
> I can't remember discussing it, no.  It was a kind of "executive
> decision".
> 
> Having a special "void" (`Qundefined`) non-value for the `symbol-value`
> is needed for `boundp` since variables can contain *any* value, but not
> for the `symbol-function` part where we can use any normal value (I
> chose `nil`) to play this role as long as it doesn't collide with values
> normally held in the `symbol-function` slot, like function names,
> function values, cons cells, vectors, ...
> 
> The upside was a simplification in various chunks of code which used to
> do things like `(and (fboundp SYM) (symbol-function SYM))` which can now
> be simplified to `(symbol-function SYM)`.
> 
> I remember two "motivators", i.e. places where the need to pay attention
> to the special void case annoyed me enough to look into this and make
> the change, one was `nadvice.el` and the other was `cl-letf`.
> [ So, it was no accident that the change happened in the same release as
>   the addition of `nadvice.el`.  ]
> 
> In both cases the issue is that we want to deal with "places"
> (generalized variables) and that abstraction works well for those places
> which *always* contain a value, but not as well for those special places
> that can be "unbound", so removing the "unbound" case from
> `symbol-function` resulted in a welcome simplification.
> For the same reason I dislike EIEIO's notion of `slot-boundp` and have
> already considered marking it obsolete.

Thanks, I've now updated the documentation, and I'm closing this bug.

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Ulrich Müller]

>>>>> On Sun, 27 Oct 2024, Eli Zaretskii wrote:

> Thanks, I've now updated the documentation, and I'm closing this bug.

TBH, I find the new wording still confusing: "It is impossible to
distinguish between a function cell that is void and one set to nil."
After commit eadf1faa3cb5eea8c25a5166a9a97ebd63525c56 there are no void
function cells any more. They start out as nil and they always contain
a lisp object. So, differentiating between nil and void in the manual
seems a little artificial.

Also, there is the following paragraph in symbols.texi which probably
should be updated (regardless of what I said above):

|   The function cell or the value cell may be @dfn{void}, which means
| that the cell does not reference any object.  (This is not the same
| thing as holding the symbol @code{void}, nor the same as holding the
| symbol @code{nil}.)  Examining a function or value cell that is void
| results in an error, such as @samp{Symbol's value as variable is void}.

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Eli Zaretskii]

> From: Ulrich Müller <ulm@gentoo.org>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  73886-done@debbugs.gnu.org
> Date: Sun, 27 Oct 2024 14:40:36 +0100
> 
> >>>>> On Sun, 27 Oct 2024, Eli Zaretskii wrote:
> 
> > Thanks, I've now updated the documentation, and I'm closing this bug.
> 
> TBH, I find the new wording still confusing: "It is impossible to
> distinguish between a function cell that is void and one set to nil."
> After commit eadf1faa3cb5eea8c25a5166a9a97ebd63525c56 there are no void
> function cells any more.

A function that was not defined at all is void.

> They start out as nil and they always contain a lisp object.

That's an implementation detail.  The ELisp manual does not describe
the implementation, not on such a low level.  The previous text didn't
mention the implementation (the special symbol 'unbound') either.

> So, differentiating between nil and void in the manual seems a
> little artificial.

Which is what the text now says.

> Also, there is the following paragraph in symbols.texi which probably
> should be updated (regardless of what I said above):

Thanks, fixed.

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> > Thanks, I've now updated the documentation, and I'm closing this bug.
>> TBH, I find the new wording still confusing: "It is impossible to
>> distinguish between a function cell that is void and one set to nil."
>> After commit eadf1faa3cb5eea8c25a5166a9a97ebd63525c56 there are no void
>> function cells any more.
> A function that was not defined at all is void.

How 'bout the patch below, which tries to eliminate the notion that
a function cell ever contains "void", reducing "void function" to just
a terminology to describe the nil value in function cells?


        Stefan


diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index bfb8789d05b..3a6da5c31e6 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1511,10 +1511,6 @@ Function Cells
 This returns the object in the function cell of @var{symbol}.  It does
 not check that the returned object is a legitimate function.
 
-If the function cell is void, the return value is @code{nil}.  It is
-impossible to distinguish between a function cell that is void and one
-set to @code{nil}.
-
 @example
 @group
 (defun bar (n) (+ n 2))
@@ -1533,9 +1529,9 @@ Function Cells
 @end defun
 
 @cindex void function cell
-  If you have never given a symbol any function definition, we say
-that that symbol's function cell is @dfn{void}.  In other words, the
-function cell does not have any Lisp object in it.  If you try to call
+  If you have never given a symbol any function definition, its function
+cell contains the default value @code{nil} and we say
+that that symbol's function cell is @dfn{void}.  If you try to call
 the symbol as a function, Emacs signals a @code{void-function} error.
 
   Unlike with void variables (@pxref{Void Variables}), a symbol's
diff --git a/src/data.c b/src/data.c
index bf83755bff3..904eaf35c1a 100644
--- a/src/data.c
+++ b/src/data.c
@@ -756,7 +756,7 @@ DEFUN ("boundp", Fboundp, Sboundp, 1, 1, 0,
    breaking backward compatibility, as some users of fboundp may
    expect t in particular, rather than any true value.  */
 DEFUN ("fboundp", Ffboundp, Sfboundp, 1, 1, 0,
-       doc: /* Return t if SYMBOL's function definition is neither void nor nil.  */)
+       doc: /* Return t if SYMBOL's function definition is not nil.  */)
   (Lisp_Object symbol)
 {
   CHECK_SYMBOL (symbol);
@@ -785,7 +785,7 @@ DEFUN ("fmakunbound", Ffmakunbound, Sfmakunbound, 1, 1, 0,
        doc: /* Make SYMBOL's function definition be nil.
 Return SYMBOL.
 
-If a function definition is nil or void, trying to call a function by
+If a function definition is nil, trying to call a function by
 that name will cause a `void-function' error.  For more details, see
 Info node `(elisp) Function Cells'.
 
@@ -800,7 +800,7 @@ DEFUN ("fmakunbound", Ffmakunbound, Sfmakunbound, 1, 1, 0,
 }
 
 DEFUN ("symbol-function", Fsymbol_function, Ssymbol_function, 1, 1, 0,
-       doc: /* Return SYMBOL's function definition, or nil if that is void or nil.  */)
+       doc: /* Return SYMBOL's function definition.  */)
   (Lisp_Object symbol)
 {
   CHECK_SYMBOL (symbol);

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Ulrich Müller <ulm@gentoo.org>,
>   73886-done@debbugs.gnu.org
> Date: Sun, 27 Oct 2024 10:59:23 -0400
> 
> How 'bout the patch below, which tries to eliminate the notion that
> a function cell ever contains "void", reducing "void function" to just
> a terminology to describe the nil value in function cells?

Fine by me, with one exception:

> -If the function cell is void, the return value is @code{nil}.  It is
> -impossible to distinguish between a function cell that is void and one
> -set to @code{nil}.

I would leave the second sentence here alone, but if you don't want to
say "function cell is void", just say "function that is void".  I
would not recommend to never use "void function" because otherwise the
error message we show in those cases will not make sense.

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> -If the function cell is void, the return value is @code{nil}.  It is
>> -impossible to distinguish between a function cell that is void and one
>> -set to @code{nil}.
>
> I would leave the second sentence here alone, but if you don't want to
> say "function cell is void", just say "function that is void".  I
> would not recommend to never use "void function" because otherwise the
> error message we show in those cases will not make sense.

IMO, we should talk about a function being void, but not about its
function cell being void.  And I'd rather not suggest that
distinguishing void from nil is even a meaningful question.

How 'bout the patch below?


        Stefan


diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index bfb8789d05b..7fb9fb37c0a 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1510,10 +1510,7 @@ Function Cells
 @kindex void-function
 This returns the object in the function cell of @var{symbol}.  It does
 not check that the returned object is a legitimate function.
-
-If the function cell is void, the return value is @code{nil}.  It is
-impossible to distinguish between a function cell that is void and one
-set to @code{nil}.
+If the function is void, the return value is @code{nil}.
 
 @example
 @group
@@ -1533,9 +1530,9 @@ Function Cells
 @end defun
 
 @cindex void function cell
-  If you have never given a symbol any function definition, we say
-that that symbol's function cell is @dfn{void}.  In other words, the
-function cell does not have any Lisp object in it.  If you try to call
+  If you have never given a symbol any function definition, its function
+cell contains the default value @code{nil} and we say
+that that function is @dfn{void}.  If you try to call
 the symbol as a function, Emacs signals a @code{void-function} error.
 
   Unlike with void variables (@pxref{Void Variables}), a symbol's

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: ulm@gentoo.org,  73886@debbugs.gnu.org
> Date: Sun, 27 Oct 2024 13:10:23 -0400
> 
> IMO, we should talk about a function being void, but not about its
> function cell being void.  And I'd rather not suggest that
> distinguishing void from nil is even a meaningful question.
> 
> How 'bout the patch below?

Fine by me.

bug#73886: 29.4; Confusing info about void function cells in Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> How 'bout the patch below?
> Fine by me.

Thanks, pushed to `emacs-30`.


        Stefan