4 files changed, 42 insertions, 18 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 311a28a3e39..fc2b7fe073a 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+2012-07-13  Chong Yidong  <cyd@gnu.org>
+
+        * buffers.texi (Misc Buffer): Document view-read-only.
+
 2012-07-07  Chong Yidong  <cyd@gnu.org>
 
         * custom.texi (Init File): Index site-lisp (Bug#11435).
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 159bf894834..24bb0e83778 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -232,11 +232,14 @@ have special commands to operate on the text; also by visiting a file
 whose access control says you cannot write it.
 
 @findex toggle-read-only
+@vindex view-read-only
  The command @kbd{C-x C-q} (@code{toggle-read-only}) makes a read-only
 buffer writable, and makes a writable buffer read-only.  This works by
 setting the variable @code{buffer-read-only}, which has a local value
 in each buffer and makes the buffer read-only if its value is
-non-@code{nil}.
+non-@code{nil}.  If you change the option @code{view-read-only} to a
+non-@code{nil} value, making the buffer read-only with @kbd{C-x C-q}
+also enables View mode in the buffer (@pxref{View Mode}).
 
 @findex rename-buffer
   @kbd{M-x rename-buffer} changes the name of the current buffer.  You
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 1faf9e04ec1..d7875a7de90 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-07-13  Chong Yidong  <cyd@gnu.org>
+
+        * buffers.texi (Read Only Buffers): Document toggle-read-only
+        changes.  Reword to account for the fact that read-only is
+        currently not supported in overlay properties.
+
 2012-07-07  Chong Yidong  <cyd@gnu.org>
 
         * loading.texi (Library Search): Index site-lisp directories.
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 072ffeb4321..6ad329f3a30 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -730,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
@@ -742,18 +740,31 @@ 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 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
+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.
 @end deffn
 
 @defun barf-if-buffer-read-only