Doc updates for read-only-mode.

* buffers.texi (Misc Buffer): Replace toggle-read-only with
read-only-mode.

* files.texi (Visiting): Likewise.

* backups.texi (Auto-Saving): Refer to Minor Mode Conventions for
calling conventions.

* buffers.texi (Read Only Buffers): Document read-only-mode.

* keymaps.texi (Alias Menu Items): Replace toggle-read-only with
read-only-mode.

4 files changed, 39 insertions, 33 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b813ac6bb1c..82fb5eb4975 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2012-09-23  Chong Yidong  <cyd@gnu.org>
+
+        * buffers.texi (Read Only Buffers): Document read-only-mode.
+
+        * keymaps.texi (Alias Menu Items): Replace toggle-read-only with
+        read-only-mode.
+
+        * backups.texi (Auto-Saving): Refer to Minor Mode Conventions for
+        calling conventions.
+
 2012-09-22  Chong Yidong  <cyd@gnu.org>
 
         * searching.texi (Replacing Match): Minor clarification.
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 04aa28e9f04..935a49116cd 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -441,12 +441,14 @@ buffer-auto-save-file-name
 @end defvar
 
 @deffn Command auto-save-mode arg
-When used interactively without an argument, this command is a toggle
-switch: it turns on auto-saving of the current buffer if it is off,
-and vice versa.  When called from Lisp with no argument, it turns
-auto-saving on.  With an argument @var{arg}, it turns auto-saving on
-if the value of @var{arg} is @code{t}, a nonempty list, or a positive
-integer; otherwise, it turns auto-saving off.
+This is the mode command for Auto Save mode, a buffer-local minor
+mode.  When Auto Save mode is enabled, auto-saving is enabled in the
+buffer.  The calling convention is the same as for other minor mode
+commands (@pxref{Minor Mode Conventions}).
+
+Unlike most minor modes, there is no @code{auto-save-mode} variable.
+Auto Save mode is enabled if @code{buffer-auto-save-file-name} is
+non-@code{nil} and @code{buffer-saved-size} (see below) is non-zero.
 @end deffn
 
 @defun auto-save-file-name-p filename
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 6ad329f3a30..b9666a79f5b 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -740,31 +740,25 @@ properties have no effect.  If @code{inhibit-read-only} is a list, then
 of the list (comparison is done with @code{eq}).
 @end defvar
 
-@deffn Command toggle-read-only &optional arg message
-This command toggles whether the current buffer is read-only, by
-setting the variable @code{buffer-read-only}.  If @var{arg} is
-non-@code{nil}, it should be a raw prefix argument; the command then
-makes the buffer read-only if the numeric value of that prefix
-argument is positive, and makes the buffer writable otherwise.
-@xref{Prefix Command Arguments}.
-
-If called interactively, or if called from Lisp with @var{message} is
-non-@code{nil}, the command prints a message reporting the buffer's
-new read-only status.
-
-When making the buffer read-only, this command also enables View mode
+@deffn Command read-only-mode &optional arg
+This is the mode command for Read Only minor mode, a buffer-local
+minor mode.  When the mode is enabled, @code{buffer-read-only} is
+non-@code{nil} in the buffer; when disabled, @code{buffer-read-only}
+is @code{nil} in the buffer.  The calling convention is the same as
+for other minor mode commands (@pxref{Minor Mode Conventions}).
+
+This minor mode mainly serves as a wrapper for
+@code{buffer-read-only}; unlike most minor modes, there is no separate
+@code{read-only-mode} variable.  Even when Read Only mode is disabled,
+characters with non-@code{nil} @code{read-only} text properties remain
+read-only.  To temporarily ignore all read-only states, bind
+@code{inhibit-read-only}, as described above.
+
+When enabling Read Only mode, this mode command also enables View mode
 if the option @code{view-read-only} is non-@code{nil}.  @xref{Misc
 Buffer,,Miscellaneous Buffer Operations, emacs, The GNU Emacs Manual}.
-When making the buffer writable, it disables View mode if View mode
-was enabled.
-
-Lisp programs should only call @code{toggle-read-only} if they really
-intend to do the same thing as the user command, including possibly
-enabling or disabling View mode.  Note also that this command works by
-setting @code{buffer-read-only}, so even if you make the buffer
-writable, characters with non-@code{nil} @code{read-only} text
-properties will remain read-only.  To temporarily ignore all read-only
-states, bind @code{inhibit-read-only}, as described above.
+When disabling Read Only mode, it disables View mode if View mode was
+enabled.
 @end deffn
 
 @defun barf-if-buffer-read-only
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index f6ec0ae5e55..40dfcaea043 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2288,12 +2288,12 @@ command but with different enable conditions.  The best way to do this
 in Emacs now is with extended menu items; before that feature existed,
 it could be done by defining alias commands and using them in menu
 items.  Here's an example that makes two aliases for
-@code{toggle-read-only} and gives them different enable conditions:
+@code{read-only-mode} and gives them different enable conditions:
 
 @example
-(defalias 'make-read-only 'toggle-read-only)
+(defalias 'make-read-only 'read-only-mode)
 (put 'make-read-only 'menu-enable '(not buffer-read-only))
-(defalias 'make-writable 'toggle-read-only)
+(defalias 'make-writable 'read-only-mode)
 (put 'make-writable 'menu-enable 'buffer-read-only)
 @end example
 
@@ -2310,7 +2310,7 @@ itself).  To request this, give the alias symbol a non-@code{nil}
 
 @noindent
 causes menu items for @code{make-read-only} and @code{make-writable} to
-show the keyboard bindings for @code{toggle-read-only}.
+show the keyboard bindings for @code{read-only-mode}.
 
 @node Toolkit Differences
 @subsubsection Toolkit Differences