From e109c4a6514ce0e930f63df1ead56eda1703afcf Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 23 Sep 2012 18:46:50 +0800 Subject: [PATCH] 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. --- doc/emacs/ChangeLog | 7 +++++++ doc/emacs/buffers.texi | 6 +++--- doc/emacs/files.texi | 2 +- doc/lispref/ChangeLog | 10 ++++++++++ doc/lispref/backups.texi | 14 ++++++++------ doc/lispref/buffers.texi | 40 +++++++++++++++++----------------------- doc/lispref/keymaps.texi | 8 ++++---- etc/NEWS | 3 ++- 8 files changed, 52 insertions(+), 38 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 28d6d2865a..4716c1cedb 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,10 @@ +2012-09-23 Chong Yidong + + * buffers.texi (Misc Buffer): Replace toggle-read-only with + read-only-mode. + + * files.texi (Visiting): Likewise. + 2012-09-22 Paul Eggert * trouble.texi (Crashing): Document ulimit -c. diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 24bb0e8377..dfd8f79230 100644 --- 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 -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 @@ -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. -@findex toggle-read-only +@findex read-only-mode @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 diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 422100e27b..c1cebc424c 100644 --- 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} -(@code{toggle-read-only}). @xref{Misc Buffer}. +(@code{read-only-mode}). @xref{Misc Buffer}. @kindex C-x C-r @findex find-file-read-only diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index b813ac6bb1..82fb5eb497 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,13 @@ +2012-09-23 Chong Yidong + + * 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 * searching.texi (Replacing Match): Minor clarification. diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index 04aa28e9f0..935a49116c 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 6ad329f3a3..b9666a79f5 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 f6ec0ae5e5..40dfcaea04 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 diff --git a/etc/NEWS b/etc/NEWS index ebeab85e40..dc60aaa138 100644 --- 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 - +--- *** 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. ++++ ** `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. -- 2.20.1