diff options
author | Chong Yidong <cyd@gnu.org> | 2012-07-13 15:06:09 +0800 |
---|---|---|
committer | Chong Yidong <cyd@gnu.org> | 2012-07-13 15:06:09 +0800 |
commit | b68b33375caeb82a4b3418d43c75bc8ccd43633a (patch) | |
tree | 2e14569d03369d1de85cfd81bb5a404373ec1245 /doc/lispref/buffers.texi | |
parent | 1a95276708930fe579fff152c590df875c29570e (diff) |
Don't warn on toggle-read-only calls.
Clarify the documentation of toggle-read-only, and audit the code tree
for uses of toggle-read-only; where appropriate, switch to setting the
variable buffer-read-only or calling toggle-read-only with a (new)
second arg.
* lisp/files.el (toggle-read-only): Doc fix and code cleanup. New arg
to allow printing the message when called from Lisp.
* lisp/emacs-lisp/bytecomp.el (byte-compile-interactive-only-functions):
Remove toggle-read-only.
* lisp/bindings.el (mode-line-toggle-read-only):
* lisp/dired.el (dired-toggle-read-only):
* lisp/ibuffer.el (ibuffer-do-toggle-read-only): Call toggle-read-only
with non-nil second arg.
* lisp/bs.el (bs-toggle-readonly):
* lisp/buff-menu.el (Buffer-menu-toggle-read-only): Remove
with-no-warnings around toggle-read-only.
* lisp/ffap.el (ffap--toggle-read-only): Accept a list of buffers.
Remove with-no-warnings around toggle-read-only.
(ffap-read-only, ffap-read-only-other-window)
(ffap-read-only-other-frame): Callers changed.
* lisp/help-mode.el: Don't require view package.
(help-mode-finish): Set buffer-read-only instead of calling
toggle-read-only.
* lisp/emacs-lisp/eieio-custom.el (eieio-customize-object):
* lisp/vc/ediff.el (ediff-set-read-only-in-buf-A): Set buffer-read-only
directly.
* lisp/gnus/smime.el (smime-certificate-info): Set buffer-read-only directly,
instead of calling toggle-read-only with a (bogus) argument.
* doc/emacs/buffers.texi (Misc Buffer): Document view-read-only.
* doc/lispref/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.
Diffstat (limited to 'doc/lispref/buffers.texi')
-rw-r--r-- | doc/lispref/buffers.texi | 45 |
1 files changed, 28 insertions, 17 deletions
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 072ffeb432..6ad329f3a3 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 |