From d6ed8ed396a8a698ad63a8a4f3460ecdf982c507 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: Rename node 'Autorevert' to 'Non-file buffers'. Add node 'Auto-revert' and move general information on that topic there. Shuffle text in that node into a rough least-to-most specific order. --- doc/emacs/arevert-xtra.texi | 2 +- doc/emacs/buffers.texi | 4 +-- doc/emacs/emacs.texi | 3 +- doc/emacs/files.texi | 61 ++++++++++++++++++++++--------------- 4 files changed, 42 insertions(+), 28 deletions(-) diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index cd7c1ff895..8575e1efdd 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -4,7 +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 +@node Non-file buffers @section Auto Reverting Non-File Buffers Global Auto Revert Mode normally only reverts file buffers. There are diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 27fcb7369a..66b21354c8 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{Non-file buffers,, emacs-xtra}, for details. @end iftex @ifnottex -@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. +@xref{Non-file buffers, global-auto-revert-non-file-buffers}, for details. @end ifnottex @node Indirect Buffers diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 58ec373029..75b12940ea 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -443,8 +443,9 @@ 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. +* Auto-revert:: Keeping buffers automatically up-to-date. @ifnottex -* Autorevert:: Auto Reverting non-file buffers. +* Non-file buffers:: Auto Reverting non-file buffers. @end ifnottex * Auto Save:: Auto Save periodically protects against loss of data. * File Aliases:: Handling multiple names for one file. diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 990b8f1679..93b2e79e70 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -25,8 +25,9 @@ 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. +* Auto-revert:: Keeping buffers automatically up-to-date. @ifnottex -* Autorevert:: Auto Reverting non-file buffers. +* Non-file buffers:: Auto Reverting non-file buffers. @end ifnottex * Auto Save:: Auto Save periodically protects against loss of data. * File Aliases:: Handling multiple names for one file. @@ -955,6 +956,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,21 +968,38 @@ 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 +@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 @@ -1002,24 +1025,14 @@ 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 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 under version control. @xref{VC Mode Line}, for Auto Revert peculiarities when visiting files under version control. +@xref{Non-file buffers} for auto-reverting buffers that do not visit +files. @ifnottex @include arevert-xtra.texi -- 2.20.1