message's docstring

message's docstring

[Juanma Barranquero]

Two slight inconsistencies/problems in message's docstring:

1) It says:

 DEFUN ("message", Fmessage, Smessage, 1, MANY, 0,
       doc: /* Print a one-line message at the bottom of the screen.

Why "a one-line message"? There's nothing stopping

  (message "line 1\nline 2")

for working, or even

  (message "%s\n%s" "line1" "line2")

2) The docstring doesn't mention that the message is returned.
However, several modules do rely on it (files.el, for example, has
"(y-or-n-p (message ...))".

It is OK the following change, or there are policy issues here?

                    /L/e/k/t/u


Index: src/editfns.c
===================================================================
RCS file: /cvsroot/emacs/emacs/src/editfns.c,v
retrieving revision 1.428
diff -u -2 -r1.428 editfns.c
--- src/editfns.c	11 Sep 2006 08:26:47 -0000	1.428
+++ src/editfns.c	11 Nov 2006 23:48:16 -0000
@@ -3172,7 +3172,8 @@

 DEFUN ("message", Fmessage, Smessage, 1, MANY, 0,
-       doc: /* Print a one-line message at the bottom of the screen.
+       doc: /* Print a message at the bottom of the screen.
 The message also goes into the `*Messages*' buffer.
 \(In keyboard macros, that's all it does.)
+Return the message.

 The first argument is a format control string, and the rest are data

Re: message's docstring

[David Kastrup]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> Two slight inconsistencies/problems in message's docstring:
>
> 1) It says:
>
> DEFUN ("message", Fmessage, Smessage, 1, MANY, 0,
>       doc: /* Print a one-line message at the bottom of the screen.
>
> Why "a one-line message"? There's nothing stopping
>
>  (message "line 1\nline 2")
>
> for working, or even
>
>  (message "%s\n%s" "line1" "line2")
>
> 2) The docstring doesn't mention that the message is returned.
> However, several modules do rely on it (files.el, for example, has
> "(y-or-n-p (message ...))".

That sounds nonsensical.  Shouldn't this be
(y-or-n-p (format ...))
instead?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: message's docstring

[Juanma Barranquero]

On 11/12/06, David Kastrup <dak@gnu.org> wrote:

> That sounds nonsensical.  Shouldn't this be
> (y-or-n-p (format ...))
> instead?

Surely yes. But the fact that it did work till now is because message
returns the message string.

So, either we document it, or document that the result is irrelevant
(but it certainly doesn't look so, looking at the code).

                    /L/e/k/t/u

Re: message's docstring

[David Kastrup]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 11/12/06, David Kastrup <dak@gnu.org> wrote:
>
>> That sounds nonsensical.  Shouldn't this be
>> (y-or-n-p (format ...))
>> instead?
>
> Surely yes. But the fact that it did work till now is because message
> returns the message string.
>
> So, either we document it, or document that the result is irrelevant
> (but it certainly doesn't look so, looking at the code).

But we should let ourselves be governed rather by code working as
intended rather than stuff in need of fixing.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: message's docstring

[Juanma Barranquero]

On 11/12/06, David Kastrup <dak@gnu.org> wrote:

> But we should let ourselves be governed rather by code working as
> intended rather than stuff in need of fixing.

Sorry, I don't understand.

                    /L/e/k/t/u

Re: message's docstring

[David Kastrup]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 11/12/06, David Kastrup <dak@gnu.org> wrote:
>
>> But we should let ourselves be governed rather by code working as
>> intended rather than stuff in need of fixing.
>
> Sorry, I don't understand.

We should not try accommodating obvious bugs, but rather fix them.  Do
you have any instances where the return value of `message' would
actually get used without `message' being confused for `format'?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: message's docstring

[Juanma Barranquero]

On 11/12/06, David Kastrup <dak@gnu.org> wrote:

> We should not try accommodating obvious bugs, but rather fix them.  Do
> you have any instances where the return value of `message' would
> actually get used without `message' being confused for `format'?

The one that prompted me to look: in server.el there are cases like

  (server-log (message "Restarting server"))

to avoid

  (message "Restarting server")
  (server-log "Restarting server")

or a `let'. Not earthshaking, but useful.

But, as I said, the intended return of the message in `message' is
*quite* intentional:

  if (NILP (args[0])
      || (STRINGP (args[0])
	  && SBYTES (args[0]) == 0))
    {
      message (0);
      return args[0];
    }
  else
    {
      register Lisp_Object val;
      val = Fformat (nargs, args);
      message3 (val, SBYTES (val), STRING_MULTIBYTE (val));
      return val;
    }

I vote for keeping it and documenting it. Is a one-line in the
docstring, and the current behavior is at least fifteen years old.

                    /L/e/k/t/u

Re: message's docstring

[Richard Stallman]

We should fix the code that calls (y-or-n-p (message ...)),
but let's also document the return value of `message'.

Re: message's docstring

[Kevin Rodgers]

David Kastrup wrote:
> "Juanma Barranquero" <lekktu@gmail.com> writes:
>> 2) The docstring doesn't mention that the message is returned.
>> However, several modules do rely on it (files.el, for example, has
>> "(y-or-n-p (message ...))".
> 
> That sounds nonsensical.  Shouldn't this be
> (y-or-n-p (format ...))
> instead?

Perhaps the author wanted the prompt to be recorded in the *Messages*
buffer.

-- 
Kevin

Re: message's docstring

[Juanma Barranquero]

On 11/13/06, Kevin Rodgers <ihs_4664@yahoo.com> wrote:

> Perhaps the author wanted the prompt to be recorded in the *Messages*
> buffer.

After (y-or-n-p "Test: "), *messages* contains a line "Test: (y or n) ".

                    /L/e/k/t/u

Re: message's docstring

[Richard Stallman]

Please do make your change.  In addition, please change "Print" to
"Display".