Doc updates for read-only-mode.

[gnu-emacs] / doc / lispref / buffers.texi

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 165faf32b098687ae73cb7f72765ee7701778c9b..b9666a79f5b4455697e4466cd542aa61a057a784 100644 (file)
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
-@node Buffers, Windows, Backups and Auto-Saving, Top
+@node Buffers
 @chapter Buffers
 @cindex buffer
 
@@ -34,7 +34,6 @@ not be displayed in any windows.
 @end menu
 
 @node Buffer Basics
-@comment  node-name,  next,  previous,  up
 @section Buffer Basics
 
 @ifnottex
@@ -588,7 +587,6 @@ current buffer is used.
 @end defun
 
 @node Modification Time
-@comment  node-name,  next,  previous,  up
 @section Buffer Modification Time
 @cindex comparing file modification time
 @cindex modification time of buffer
@@ -732,11 +730,9 @@ The buffer is read-only if this variable is non-@code{nil}.
 @defvar inhibit-read-only
 If this variable is non-@code{nil}, then read-only buffers and,
 depending on the actual value, some or all read-only characters may be
-modified.  Read-only characters in a buffer are those that have
-non-@code{nil} @code{read-only} properties (either text properties or
-overlay properties).  @xref{Special Properties}, for more information
-about text properties.  @xref{Overlays}, for more information about
-overlays and their properties.
+modified.  Read-only characters in a buffer are those that have a
+non-@code{nil} @code{read-only} text property.  @xref{Special
+Properties}, for more information about text properties.
 
 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
 properties have no effect.  If @code{inhibit-read-only} is a list, then
@@ -744,18 +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
-This command toggles whether the current buffer is read-only.  It is
-intended for interactive use; do not use it in programs (it may have
-side-effects, such as enabling View mode, and does not affect
-read-only text properties).  To change the read-only state of a buffer in
-a program, explicitly set @code{buffer-read-only} to the proper value.
-To temporarily ignore a read-only state, bind @code{inhibit-read-only}.
-
-If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
-@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
-the numeric value of that prefix argument is positive and to
-@code{nil} otherwise.  @xref{Prefix Command Arguments}.
+@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 disabling Read Only mode, it disables View mode if View mode was
+enabled.
 @end deffn
 
 @defun barf-if-buffer-read-only