save-buffers documentation

[Aaron Hawley]

In GNU Emacs 21.3.1 (i386-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2004-10-16 on raven, modified by Debian
configured using `configure '--build=i386-linux' '--host=i386-linux' 
'--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib' 
'--localstatedir=/var/lib' '--infodir=/usr/share/info' 
'--mandir=/usr/share/man' '--with-pop=yes' '--with-x=yes' 
'--with-x-toolkit=athena' 'CFLAGS=-DDEBIAN -g -O2' 'build_alias=i386-linux' 
'host_alias=i386-linux''
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: C
  locale-coding-system: nil
  default-enable-multibyte-characters: t

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

When visiting the `save-buffer' help screen, I found the first section
of the function's documentation string to be confusing.  Below is a
patch against CVS that offers some rough suggestions.  The existing
documentation in its current state (in my version of Emacs) is below
the patch.

Thanks for GNU Emacs. /a

--- files.el.~1.745.~   2005-02-09 10:50:42.000000000 -0500
+++ files.el    2005-03-11 12:58:13.000000000 -0500
@@ -3102,14 +3102,14 @@
             ancestor))))))
 
 (defun save-buffer (&optional args)
-  "Save current buffer in visited file if modified.  Versions described below.
+  "Save current buffer in visited file if modified.  Variations are described 
below.
 By default, makes the previous version into a backup file
  if previously requested or if this is the first save.
-With 1 \\[universal-argument], marks this version
+Combined with one \\[universal-argument], marks this version
  to become a backup when the next save is done.
-With 2 \\[universal-argument]'s,
+Combined with two \\[universal-argument]'s,
  unconditionally makes the previous version into a backup file.
-With 3 \\[universal-argument]'s, marks this version
+Combined with three \\[universal-argument]'s, marks this version
  to become a backup when the next save is done,
  and unconditionally makes the previous version into a backup file.


     C-x C-s runs the command save-buffer
        which is an interactive compiled Lisp function in `files'.
        (save-buffer &optional ARGS)

        Save current buffer in visited file if modified.  Versions
         described below.
        By default, makes the previous version into a backup file
         if previously requested or if this is the first save.
        With 1 C-u, marks this version
         to become a backup when the next save is done.
        With 2 C-u's,
         unconditionally makes the previous version into a backup
         file.
        With 3 C-u's, marks this version
         to become a backup when the next save is done,
         and unconditionally makes the previous version into a backup
         file.
        With argument of 0, never make the previous version into a
         backup file.


Recent input:
C-h k C-x C-s 

Recent messages:
Type C-x 1 to remove help window.  C-M-v to scroll the help.
Loading emacsbug...done