Merge from emacs-24; up to 2012-12-06T01:39:03Z!monnier@iro.umontreal.ca

[bpt/emacs.git] / doc / lispref / buffers.texi

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index fa0cb11..7ed1876 100644 (file)
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -1,10 +1,9 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @c See the file elisp.texi for copying conditions.

-@setfilename ../../info/buffers
-@node Buffers, Windows, Backups and Auto-Saving, Top
+@node Buffers

 @chapter Buffers
 @cindex buffer
 
 @chapter Buffers
 @cindex buffer
 


@@ -35,7 +34,6 @@ not be displayed in any windows.
 @end menu
 
 @node Buffer Basics
 @end menu
 
 @node Buffer Basics

-@comment  node-name,  next,  previous,  up

 @section Buffer Basics
 
 @ifnottex
 @section Buffer Basics
 
 @ifnottex


@@ -589,7 +587,6 @@ current buffer is used.
 @end defun
 
 @node Modification Time
 @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
 @section Buffer Modification Time
 @cindex comparing file modification time
 @cindex modification time of buffer


@@ -637,7 +634,8 @@ file should not be done.
 @c Emacs 19 feature
 @defun visited-file-modtime
 This function returns the current buffer's recorded last file
 @c Emacs 19 feature
 @defun visited-file-modtime
 This function returns the current buffer's recorded last file

-modification time, as a list of the form @code{(@var{high} @var{low})}.
+modification time, as a list of the form @code{(@var{high} @var{low}
+@var{microsec} @var{picosec})}.

 (This is the same format that @code{file-attributes} uses to return
 time values; see @ref{File Attributes}.)
 
 (This is the same format that @code{file-attributes} uses to return
 time values; see @ref{File Attributes}.)
 


@@ -652,7 +650,7 @@ the last modification time of that directory, as recorded by Dired.
 For a new buffer visiting a not yet existing file, @var{high} is
 @minus{}1 and @var{low} is 65535, that is,
 @ifnottex
 For a new buffer visiting a not yet existing file, @var{high} is
 @minus{}1 and @var{low} is 65535, that is,
 @ifnottex

-@w{2**16 - 1.}
+@w{2**16 @minus{} 1.}

 @end ifnottex
 @tex
 @math{2^{16}-1}.
 @end ifnottex
 @tex
 @math{2^{16}-1}.


@@ -667,9 +665,8 @@ is not @code{nil}, and otherwise to the last modification time of the
 visited file.
 
 If @var{time} is neither @code{nil} nor zero, it should have the form
 visited file.
 
 If @var{time} is neither @code{nil} nor zero, it should have the form

-@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
-either case containing two integers, each of which holds 16 bits of the
-time.
+@code{(@var{high} @var{low} @var{microsec} @var{picosec})},
+the format used by @code{current-time} (@pxref{Time of Day}).

 
 This function is useful if the buffer was not read from the file
 normally, or if the file itself has been changed for some known benign
 
 This function is useful if the buffer was not read from the file
 normally, or if the file itself has been changed for some known benign


@@ -733,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
 @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
 
 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


@@ -745,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
 
 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
 @end deffn
 
 @defun barf-if-buffer-read-only


@@ -884,7 +886,7 @@ This buffer therefore becomes the least desirable candidate for
 @code{other-buffer} to return.  The argument can be either a buffer
 itself or the name of one.
 
 @code{other-buffer} to return.  The argument can be either a buffer
 itself or the name of one.
 

-This functions operates on each frame's @code{buffer-list} parameter as
+This function operates on each frame's @code{buffer-list} parameter as

 well as the fundamental buffer list; therefore, the buffer that you bury
 will come last in the value of @code{(buffer-list @var{frame})} and in
 the value of @code{(buffer-list)}.  In addition, it also puts the buffer
 well as the fundamental buffer list; therefore, the buffer that you bury
 will come last in the value of @code{(buffer-list @var{frame})} and in
 the value of @code{(buffer-list)}.  In addition, it also puts the buffer


@@ -894,15 +896,15 @@ History}) provided it is shown in that window.
 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
 current buffer.  In addition, if the current buffer is displayed in the
 selected window, this makes sure that the window is either deleted or
 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
 current buffer.  In addition, if the current buffer is displayed in the
 selected window, this makes sure that the window is either deleted or

-another buffer is shown in it.  More precisely, if the window is
-dedicated (@pxref{Dedicated Windows}) and there are other windows on its
-frame, the window is deleted.  If the window is both dedicated and the
-only window on its frame's terminal, the function specified by
-@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal
-with the window.  If the window is not dedicated to its buffer, it calls
-@code{switch-to-prev-buffer} (@pxref{Window History}) to show another
-buffer in that window.  If @var{buffer-or-name} is displayed in some
-other window, it remains displayed there.
+another buffer is shown in it.  More precisely, if the selected window
+is dedicated (@pxref{Dedicated Windows}) and there are other windows on
+its frame, the window is deleted.  If it is the only window on its frame
+and that frame is not the only frame on its terminal, the frame is
+``dismissed'' by calling the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}).  Otherwise,
+it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show
+another buffer in that window.  If @var{buffer-or-name} is displayed in
+some other window, it remains displayed there.

 
 To replace a buffer in all the windows that display it, use
 @code{replace-buffer-in-windows}, @xref{Buffers and Windows}.
 
 To replace a buffer in all the windows that display it, use
 @code{replace-buffer-in-windows}, @xref{Buffers and Windows}.


@@ -1235,4 +1237,3 @@ This function returns the current gap position in the current buffer.
 @defun gap-size
 This function returns the current gap size of the current buffer.
 @end defun
 @defun gap-size
 This function returns the current gap size of the current buffer.
 @end defun

-