> A *lot* of source code contains easy-to-miss bugs like this:
>
> (message (format "File: %s" file))
I guess one of the reasons of such bugs is the misleading argument
name `string' of the function `message'. This name doesn't suggest
that it is actually a format string used by the function `format'.
I propose to rename the argument name `string' to `format-string' in
docstrings of `message...' functions and in the Emacs Lisp Reference
Manual.
Index: src/editfns.c
===================================================================
RCS file: /cvsroot/emacs/emacs/src/editfns.c,v
retrieving revision 1.398
diff -c -r1.398 editfns.c
*** src/editfns.c 19 Sep 2005 08:13:14 -0000 1.398
--- src/editfns.c 20 Sep 2005 05:04:02 -0000
***************
*** 3124,3130 ****
any existing message; this lets the minibuffer contents show. See
also `current-message'.
! usage: (message STRING &rest ARGS) */)
(nargs, args)
int nargs;
Lisp_Object *args;
--- 3124,3130 ----
any existing message; this lets the minibuffer contents show. See
also `current-message'.
! usage: (message FORMAT-STRING &rest ARGS) */)
(nargs, args)
int nargs;
Lisp_Object *args;
***************
*** 3154,3160 ****
If the first argument is nil or the empty string, clear any existing
message; let the minibuffer contents show.
! usage: (message-box STRING &rest ARGS) */)
(nargs, args)
int nargs;
Lisp_Object *args;
--- 3154,3160 ----
If the first argument is nil or the empty string, clear any existing
message; let the minibuffer contents show.
! usage: (message-box FORMAT-STRING &rest ARGS) */)
(nargs, args)
int nargs;
Lisp_Object *args;
***************
*** 3216,3222 ****
If the first argument is nil or the empty string, clear any existing
message; let the minibuffer contents show.
! usage: (message-or-box STRING &rest ARGS) */)
(nargs, args)
int nargs;
Lisp_Object *args;
--- 3216,3222 ----
If the first argument is nil or the empty string, clear any existing
message; let the minibuffer contents show.
! usage: (message-or-box FORMAT-STRING &rest ARGS) */)
(nargs, args)
int nargs;
Lisp_Object *args;
***************
*** 3281,3288 ****
: SBYTES (STRING))
DEFUN ("format", Fformat, Sformat, 1, MANY, 0,
! doc: /* Format a string out of a control-string and arguments.
! The first argument is a control string.
The other arguments are substituted into it to make the result, a string.
It may contain %-sequences meaning to substitute the next argument.
%s means print a string argument. Actually, prints any object, with `princ'.
--- 3281,3288 ----
: SBYTES (STRING))
DEFUN ("format", Fformat, Sformat, 1, MANY, 0,
! doc: /* Format a string out of a format-string and arguments.
! The first argument is a format control string.
The other arguments are substituted into it to make the result, a string.
It may contain %-sequences meaning to substitute the next argument.
%s means print a string argument. Actually, prints any object, with `princ'.
Index: lispref/display.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/display.texi,v
retrieving revision 1.187
diff -c -r1.187 display.texi
*** lispref/display.texi 18 Sep 2005 14:03:55 -0000 1.187
--- lispref/display.texi 20 Sep 2005 05:02:59 -0000
***************
*** 208,216 ****
This section describes the functions for explicitly producing echo
area messages. Many other Emacs features display messages there, too.
! @defun message string &rest arguments
! This function displays a message in the echo area. The
! argument @var{string} is similar to a C language @code{printf} control
string. See @code{format} in @ref{Formatting Strings}, for the details
on the conversion specifications. @code{message} returns the
constructed string.
--- 208,216 ----
This section describes the functions for explicitly producing echo
area messages. Many other Emacs features display messages there, too.
! @defun message format-string &rest arguments
! This function displays a message in the echo area. The argument
! @var{format-string} is similar to a C language @code{printf} format
string. See @code{format} in @ref{Formatting Strings}, for the details
on the conversion specifications. @code{message} returns the
constructed string.
***************
*** 218,231 ****
In batch mode, @code{message} prints the message text on the standard
error stream, followed by a newline.
! If @var{string}, or strings among the @var{arguments}, have @code{face}
! text properties, these affect the way the message is displayed.
@c Emacs 19 feature
! If @var{string} is @code{nil}, @code{message} clears the echo area; if
! the echo area has been expanded automatically, this brings it back to
! its normal size. If the minibuffer is active, this brings the
! minibuffer contents back onto the screen immediately.
@example
@group
--- 218,232 ----
In batch mode, @code{message} prints the message text on the standard
error stream, followed by a newline.
! If @var{format-string}, or strings among the @var{arguments}, have
! @code{face} text properties, these affect the way the message is displayed.
@c Emacs 19 feature
! If @var{format-string} is @code{nil} or the empty string,
! @code{message} clears the echo area; if the echo area has been
! expanded automatically, this brings it back to its normal size.
! If the minibuffer is active, this brings the minibuffer contents back
! onto the screen immediately.
@example
@group
***************
*** 254,260 ****
the previous echo area contents.
@end defmac
! @defun message-or-box string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area. If this function is called in
a command that was invoked using the mouse---more precisely, if
--- 255,261 ----
the previous echo area contents.
@end defmac
! @defun message-or-box format-string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area. If this function is called in
a command that was invoked using the mouse---more precisely, if
***************
*** 268,274 ****
@code{last-nonmenu-event} to a suitable value around the call.
@end defun
! @defun message-box string &rest arguments
This function displays a message like @code{message}, but uses a dialog
box (or a pop-up menu) whenever that is possible. If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
--- 269,275 ----
@code{last-nonmenu-event} to a suitable value around the call.
@end defun
! @defun message-box format-string &rest arguments
This function displays a message like @code{message}, but uses a dialog
box (or a pop-up menu) whenever that is possible. If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
--
Juri Linkov
http://www.jurta.org/emacs/
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
