From ea7c087df14f302543ce9e2711cc8cbde09dbc30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= Date: Tue, 30 Apr 2019 22:35:56 +0200 Subject: [PATCH] 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. --- doc/emacs/arevert-xtra.texi | 9 +++-- doc/emacs/buffers.texi | 4 +- doc/emacs/emacs-xtra.texi | 2 +- doc/emacs/emacs.texi | 4 +- doc/emacs/files.texi | 75 +++++++++++++++++++++---------------- 5 files changed, 51 insertions(+), 43 deletions(-) diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index cd7c1ff895..9e01a10ace 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -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 @@ Autorevert @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 @@ Auto Reverting the Buffer Menu 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 diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 27fcb7369a..14a0a01ca8 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -568,10 +568,10 @@ Several Buffers 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 diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi index dcd8fae1b6..e9231b4e3a 100644 --- a/doc/emacs/emacs-xtra.texi +++ b/doc/emacs/emacs-xtra.texi @@ -59,7 +59,7 @@ Top * 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. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 58ec373029..a34cef221e 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -443,9 +443,7 @@ Top * 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. diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 990b8f1679..c51d076fa2 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -25,9 +25,7 @@ Files * 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 @@ Reverting 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 @@ Reverting @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 @@ Reverting @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 -- 2.20.1