Re: (message (format "File %s" file))

[Juri Linkov <juri@jurta.org>]

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