From ad27e857bb7a623e137407c45b65744b3fc35ca5 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: * doc/emacs/arevert-xtra.texi: * doc/emacs/buffers.texi: * doc/emacs/emacs.texi: * doc/emacs/emacs-xtra.texi: Add node 'Auto-revert' and move general information on that topic there. Sort paragraphs in that node in a rough least-to-most specific order. Include the old 'Autorevert' node into that node when building the on-line manual. --- 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 | 67 +++++++++++++++++++++---------------- 5 files changed, 45 insertions(+), 37 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..76be4c112f 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 + 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}. @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,7 +1010,7 @@ 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 @@ -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