save-buffers documentation

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))))))
 \f
 (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

Re: save-buffers documentation

[Kevin Rodgers]

Aaron Hawley wrote:
 > 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.
 > -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

I think "Prefixed by" or "Prefixed with" would be more accurate than
"Combined with", and are consistent with the "prefix arg" terminology
used in Emacs.

Thanks,
-- 
Kevin Rodgers

Re: save-buffers documentation

[Aaron Hawley]

Here's another revision of the patch that uses instead "Prefixed with",
for consistency with other GNU Emacs doc-strings.  enjoy. /a


===File ~/gnu/files.el-save_buffer_doc_string.diff==========
--- files.el.~1.745.~	2005-02-09 10:50:42.000000000 -0500
+++ files.el	2005-03-17 11:28:05.000000000 -0500
@@ -3102,18 +3102,20 @@
             ancestor))))))
 \f
 (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
+Prefixed with one \\[universal-argument], marks this version
  to become a backup when the next save is done.
-With 2 \\[universal-argument]'s,
+Prefixed with two \\[universal-argument]'s,
  unconditionally makes the previous version into a backup file.
-With 3 \\[universal-argument]'s, marks this version
+Prefixed 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.
 
-With argument of 0, never make the previous version into a backup file.
+With prefix argument of 0, never make the previous version into a
+ backup file.
 
 If a file's name is FOO, the names of its numbered backup versions are
  FOO.~i~ for various integers i.  A non-numbered backup file is called FOO~.
============================================================