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.

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 28d6d28..4716c1c 100644 (file)
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,10 @@
+2012-09-23  Chong Yidong  <cyd@gnu.org>
+
+       * buffers.texi (Misc Buffer): Replace toggle-read-only with
+       read-only-mode.
+
+       * files.texi (Visiting): Likewise.
+

 2012-09-22  Paul Eggert  <eggert@cs.ucla.edu>
 
        * trouble.texi (Crashing): Document ulimit -c.
 2012-09-22  Paul Eggert  <eggert@cs.ucla.edu>
 
        * trouble.texi (Crashing): Document ulimit -c.

diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 24bb0e8..dfd8f79 100644 (file)
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -212,7 +212,7 @@ unless they visit files: such buffers are used internally by Emacs.
 
 @table @kbd
 @item C-x C-q
 
 @table @kbd
 @item C-x C-q

-Toggle read-only status of buffer (@code{toggle-read-only}).
+Toggle read-only status of buffer (@code{read-only-mode}).

 @item M-x rename-buffer @key{RET} @var{name} @key{RET}
 Change the name of the current buffer.
 @item M-x rename-uniquely
 @item M-x rename-buffer @key{RET} @var{name} @key{RET}
 Change the name of the current buffer.
 @item M-x rename-uniquely


@@ -231,9 +231,9 @@ buffers are usually made by subsystems such as Dired and Rmail that
 have special commands to operate on the text; also by visiting a file
 whose access control says you cannot write it.
 
 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
+@findex read-only-mode

 @vindex view-read-only
 @vindex view-read-only

- The command @kbd{C-x C-q} (@code{toggle-read-only}) makes a read-only
+ The command @kbd{C-x C-q} (@code{read-only-mode}) 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
 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

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 422100e..c1cebc4 100644 (file)
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -246,7 +246,7 @@ Archives}, for more about these features.
 or that is marked read-only, Emacs makes the buffer read-only too, so
 that you won't go ahead and make changes that you'll have trouble
 saving afterward.  You can make the buffer writable with @kbd{C-x C-q}
 or that is marked read-only, Emacs makes the buffer read-only too, so
 that you won't go ahead and make changes that you'll have trouble
 saving afterward.  You can make the buffer writable with @kbd{C-x C-q}

-(@code{toggle-read-only}).  @xref{Misc Buffer}.
+(@code{read-only-mode}).  @xref{Misc Buffer}.

 
 @kindex C-x C-r
 @findex find-file-read-only
 
 @kindex C-x C-r
 @findex find-file-read-only

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b813ac6..82fb5eb 100644 (file)
--- 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.
 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 04aa28e..935a491 100644 (file)
--- 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
 @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
 @end deffn
 
 @defun auto-save-file-name-p filename

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 6ad329f..b9666a7 100644 (file)
--- 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
 
 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}.
 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
 @end deffn
 
 @defun barf-if-buffer-read-only

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index f6ec0ae..40dfcae 100644 (file)
--- 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
 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
 
 @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))
 (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
 
 (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
 
 @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
 
 @node Toolkit Differences
 @subsubsection Toolkit Differences

diff --git a/etc/NEWS b/etc/NEWS
index ebeab85..dc60aaa 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -94,7 +94,7 @@ respectively, without exiting from the prompt.
 next and previous path separator, respectively.
 
 ** Mode line changes
 next and previous path separator, respectively.
 
 ** Mode line changes

-
+---

 *** New option `mode-line-default-help-echo' specifies the help text
 (shown in a tooltip or in the echo area) for any part of the mode line
 that does not have its own specialized help text.
 *** New option `mode-line-default-help-echo' specifies the help text
 (shown in a tooltip or in the echo area) for any part of the mode line
 that does not have its own specialized help text.


@@ -143,6 +143,7 @@ or expression to evaluate.
 ** In the Package Menu, newly-available packages are listed as "new",
 and sorted above the other "available" packages by default.
 
 ** In the Package Menu, newly-available packages are listed as "new",
 and sorted above the other "available" packages by default.
 

++++

 ** `C-x C-q' is now bound to the new minor mode `read-only-mode'.
 This minor mode replaces `toggle-read-only', which is now obsolete.
 
 ** `C-x C-q' is now bound to the new minor mode `read-only-mode'.
 This minor mode replaces `toggle-read-only', which is now obsolete.