From 3b9fc1d288cb7168db3f1352f6e261266dbe4349 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 The amount of information on auto-revert has grown to deserve a section of its own (bug#35418). * doc/emacs/files.texi (Files): Adjust menu. (Reverting, Auto Revert): Add node `Auto Revert' and move general information on that topic there from `Reverting'. Sort paragraphs in `Auto Revert' in a rough least-to-most specific order. Include the old `Autorevert' text and subsections into that node when building the on-line manual. (Autorevert): Remove. * doc/emacs/arevert-xtra.texi (Autorevert): Remove node and section lines. * 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 | 3 +- doc/emacs/buffers.texi | 4 +-- doc/emacs/emacs-xtra.texi | 4 ++- doc/emacs/emacs.texi | 4 +-- doc/emacs/files.texi | 71 +++++++++++++++++++++---------------- 5 files changed, 47 insertions(+), 39 deletions(-) diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index cd7c1ff895..8cc5b053b5 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -4,8 +4,7 @@ @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 +@c The including file must provide its own @node and @section lines. Global Auto Revert Mode normally only reverts file buffers. There are two ways to auto-revert certain non-file buffers: by enabling Auto 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..84bbdb84d0 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. @@ -111,6 +111,8 @@ Introduction @raisesections @include picture-xtra.texi +@node Non-File Buffers +@section Auto Reverting Non-File Buffers @include arevert-xtra.texi @include dired-xtra.texi 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..7f5e16a845 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,10 +1010,10 @@ Reverting @vindex auto-revert-avoid-polling @vindex auto-revert-notify-exclude-dir-regexp - By default, Auto-Revert mode will poll files for changes + 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 +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 @@ -1002,19 +1022,7 @@ Reverting @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 @@ -1022,6 +1030,7 @@ Reverting peculiarities when visiting files under version control. @ifnottex +@c The node text continues here. @include arevert-xtra.texi @end ifnottex -- 2.20.1