Commit ab642288 authored by Mattias Engdegård's avatar Mattias Engdegård
Browse files

Reorganise (auto-)revert nodes in the manual

Put all information about auto-revert into a section of its own, and
organise the text in a more logical way.  Previously it was mainly
described in the section about reverting (bug#35418).

* doc/emacs/files.texi (Files): Adjust menu.
(Reverting, Auto Revert, Autorevert): Add node `Auto Revert' and move
text on that topic from `Reverting', rearranged.  Turn the old
`Autorevert' node into a subsection under `Auto Revert'.
* doc/emacs/arevert-xtra.texi (Autorevert): Rename and turn into
subsubsection.
* doc/emacs/buffers.texi (Several Buffers): Adjust references.
* doc/emacs/emacs.texi (Top): Adjust menu.
* doc/emacs/emacs-xtra.texi (Top): Adjust menu.
(Non-File Buffers): Add node and section lines.
parent b5aeb86a
Pipeline #1567 failed with stage
in 62 minutes and 4 seconds
......@@ -4,8 +4,9 @@
@c
@c This file is included either in emacs-xtra.texi (when producing the
@c printed version) or in the main Emacs manual (for the on-line version).
@node Autorevert
@section Auto Reverting Non-File Buffers
@node Non-File Buffers
@subsection Auto Reverting Non-File Buffers
Global Auto Revert Mode normally only reverts file buffers. There are
two ways to auto-revert certain non-file buffers: by enabling Auto
......@@ -43,7 +44,7 @@ explained in the corresponding sections.
@end menu
@node Auto Reverting the Buffer Menu
@subsection Auto Reverting the Buffer Menu
@subsubsection Auto Reverting the Buffer Menu
If auto-reverting of non-file buffers is enabled, the Buffer Menu
@iftex
......@@ -65,7 +66,7 @@ adding marks sets the buffer's modified flag prevents Auto Revert from
automatically erasing the marks.
@node Auto Reverting Dired
@subsection Auto Reverting Dired buffers
@subsubsection Auto Reverting Dired buffers
Dired buffers only auto-revert when the file list of the buffer's main
directory changes (e.g., when a new file is added or deleted). They
......
......@@ -568,10 +568,10 @@ mode in this buffer, as long as it is not marked modified. Global
Auto Revert mode applies to the @file{*Buffer List*} buffer only if
@code{global-auto-revert-non-file-buffers} is non-@code{nil}.
@iftex
@inforef{Autorevert,, emacs-xtra}, for details.
@inforef{Auto Reverting the Buffer Menu,, emacs-xtra}, for details.
@end iftex
@ifnottex
@xref{Autorevert, global-auto-revert-non-file-buffers}, for details.
@xref{Auto Reverting the Buffer Menu, global-auto-revert-non-file-buffers}, for details.
@end ifnottex
@node Indirect Buffers
......
......@@ -59,7 +59,7 @@ modify this GNU manual.''
* Picture Mode:: Editing pictures made up of characters using
the quarter-plane screen model.
* Autorevert:: Auto Reverting non-file buffers.
* Non-File Buffers:: Auto Reverting non-file buffers.
* Subdir Switches:: Subdirectory switches in Dired.
* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
* Emerge:: A convenient way of merging two versions of a program.
......
......@@ -443,9 +443,7 @@ File Handling
* Visiting:: Visiting a file prepares Emacs to edit the file.
* Saving:: Saving makes your changes permanent.
* Reverting:: Reverting cancels all the changes not saved.
@ifnottex
* Autorevert:: Auto Reverting non-file buffers.
@end ifnottex
* Auto Revert:: Keeping buffers automatically up-to-date.
* Auto Save:: Auto Save periodically protects against loss of data.
* File Aliases:: Handling multiple names for one file.
* Directories:: Creating, deleting, and listing file directories.
......
......@@ -25,9 +25,7 @@ on file directories.
* Visiting:: Visiting a file prepares Emacs to edit the file.
* Saving:: Saving makes your changes permanent.
* Reverting:: Reverting cancels all the changes not saved.
@ifnottex
* Autorevert:: Auto Reverting non-file buffers.
@end ifnottex
* Auto Revert:: Keeping buffers automatically up-to-date.
* Auto Save:: Auto Save periodically protects against loss of data.
* File Aliases:: Handling multiple names for one file.
* Directories:: Creating, deleting, and listing file directories.
......@@ -955,6 +953,11 @@ revert it automatically if it has changed---provided the buffer itself
is not modified. (If you have edited the text, it would be wrong to
discard your changes.)
You can also tell Emacs to revert buffers automatically when their
visited files change on disk; @pxref{Auto Revert}.
@node Auto Revert
@section Auto Revert: Keeping buffers automatically up-to-date
@cindex Global Auto Revert mode
@cindex mode, Global Auto Revert
@cindex Auto Revert mode
......@@ -962,22 +965,39 @@ discard your changes.)
@findex global-auto-revert-mode
@findex auto-revert-mode
@findex auto-revert-tail-mode
@vindex auto-revert-interval
@vindex auto-revert-remote-files
A buffer can get out of sync with respect to its visited file on
disk if that file is changed by another program. To keep it up to
date, you can enable Auto Revert mode by typing @kbd{M-x auto-revert-mode}.
This automatically reverts the buffer when its visited file changes on
disk. To do the same for all file buffers, type
@kbd{M-x global-auto-revert-mode} to enable Global Auto Revert mode.
Auto Revert will not revert a buffer if it has unsaved changes, or if
its file on disk is deleted or renamed.
One use of Auto Revert mode is to ``tail'' a file such as a system
log, so that changes made to that file by other programs are
continuously displayed. To do this, just move the point to the end of
the buffer, and it will stay there as the file contents change.
However, if you are sure that the file will only change by growing at
the end, use Auto Revert Tail mode instead
(@code{auto-revert-tail-mode}). It is more efficient for this.
Auto Revert Tail mode also works for remote files.
@vindex auto-revert-verbose
You can also tell Emacs to revert buffers periodically. To do this
for a specific buffer, enable the minor mode Auto-Revert mode by
typing @kbd{M-x auto-revert-mode}. This automatically reverts the
current buffer when its visited file changes on disk. To do the same
for all file buffers, type @kbd{M-x global-auto-revert-mode} to enable
Global Auto-Revert mode. These minor modes do not check or revert
remote files, because that is usually too slow. This behavior can be
changed by setting the variable @code{auto-revert-remote-files} to
non-@code{nil}.
When a buffer is auto-reverted, a message is generated. This can be
suppressed by setting @code{auto-revert-verbose} to @code{nil}.
@vindex auto-revert-remote-files
The Auto Revert modes do not check or revert remote files, because
that is usually too slow. This behavior can be changed by setting the
variable @code{auto-revert-remote-files} to non-@code{nil}.
@cindex file notifications
@vindex auto-revert-use-notify
By default, Auto-Revert mode works using @dfn{file notifications},
@vindex auto-revert-interval
By default, Auto Revert mode works using @dfn{file notifications},
whereby changes in the filesystem are reported to Emacs by the OS.
You can disable use of file notifications by customizing the variable
@code{auto-revert-use-notify} to a @code{nil} value, then Emacs will
......@@ -990,31 +1010,20 @@ default.
@vindex auto-revert-avoid-polling
@vindex auto-revert-notify-exclude-dir-regexp
By default, Auto-Revert mode will poll files for changes
periodically even when file notifications are used. Such polling is
usually unnecessary, and turning it off may save power by relying on
notifications only. To do so, set the variable
By default, Auto Revert mode will poll files for changes
periodically even when file notifications are used. Polling is
unnecessary in many cases, and turning it off may save power by
relying on notifications only. To do so, set the variable
@code{auto-revert-avoid-polling} to non-@code{nil}. However,
notification is ineffective on certain file systems; mainly network
file system on Unix-like machines, where files can be altered from
other machines. To force polling when
other machines. For such file systems, polling may be necessary.
To force polling when
@code{auto-revert-avoid-polling} is non-@code{nil}, set
@code{auto-revert-notify-exclude-dir-regexp} to match files that
should be excluded from using notification.
One use of Auto-Revert mode is to ``tail'' a file such as a system
log, so that changes made to that file by other programs are
continuously displayed. To do this, just move the point to the end of
the buffer, and it will stay there as the file contents change.
However, if you are sure that the file will only change by growing at
the end, use Auto-Revert Tail mode instead
(@code{auto-revert-tail-mode}). It is more efficient for this.
Auto-Revert Tail mode works also for remote files.
When a buffer is auto-reverted, a message is generated. This can be
suppressed by setting @code{auto-revert-verbose} to @code{nil}.
In Dired buffers (@pxref{Dired}), Auto-Revert mode refreshes the
In Dired buffers (@pxref{Dired}), Auto Revert mode refreshes the
buffer when a file is created or deleted in the buffer's directory.
@xref{VC Undo}, for commands to revert to earlier versions of files
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment