Yet another round of improvements in the manual

* doc/emacs/misc.texi (Document View): Improve wording.  Reported
by lyr3 <lyr3@protonmail.com> in emacs-manual-bugs@gnu.org.

* doc/emacs/files.texi (Recover): Fix a typo.  Reported by Jorge
<jorge+list@disroot.org> in emacs-manual-bugs@gnu.org.

* doc/emacs/anti.texi (Antinews): Fix typos.  Reported by Justin
Heyes-Jones <justinhj@gmail.com> in emacs-manual-bugs@gnu.org.

* doc/emacs/mini.texi (Basic Minibuffer): Clarify wording.
Reported by Vivishek Sudhir <vivishek.sudhir@gmail.com> in
emacs-manual-bugs@gnu.org.

* doc/emacs/cmdargs.texi (MS-Windows Registry): Improve wording
regarding registry keys.

* doc/emacs/macos.texi (Mac OS / GNUstep): Sayu "NeXT Inc."
Reported by Cena Mayo <cenazoic@gmail.com> in
emacs-manual-bugs@gnu.org.

* doc/emacs/screen.texi (Screen): More accurate wording.
Suggested by Miloš Polakovič <milos@alphamail.org> in
emacs-manual-bugs@gnu.org.

* doc/emacs/indent.texi (Just Spaces): Minor wording change.
Suggested by David Bonnafous <dbonnafo@gmail.com> in
emacs-manual-bugs@gnu.org.

* doc/emacs/text.texi (TeX Mode, TeX Editing): Improve and
simplify wording.  Suggested by root@vxid.pw <root@vxid.pw> in
emacs-manual-bugs@gnu.org.

* doc/emacs/cmdargs.texi (Window Size X): Minor wording change.

* doc/emacs/display.texi (Highlight Interactively): Fill text.
(Optional Mode Line): Fix typos.  Suggested by Alberto Sartori
<alberto.sartori@sissa.it> in emacs-manual-bugs@gnu.org.

* doc/emacs/building.texi (Debugger Operation): Clarify wording.

* doc/emacs/files.texi (Directories, Comparing Files, Diff Mode)
(Remote Files, File Names, Visiting, Backup Deletion)
(Customize Save, Interlocking): Improve wording and accuracy of
the text.
* doc/emacs/maintaining.texi (VC With A Merging VCS): Don't say
"his".
* doc/emacs/arevert-xtra.texi (Auto Reverting Dired): Minor
wording changes.
(Supporting additional buffers): Moved to ...
* doc/lispref/backups.texi (Reverting): ... here.
* doc/emacs/emacs.texi (Top): Remove "Supporting additional
buffers" from master menu.
* doc/emacs/files.texi (Reverting): Mention use of file
notifications.  Suggested by Michael Albinus
<michael.albinus@gmx.de> in emacs-manual-bugs@gnu.org.

* doc/emacs/rmail.texi (Rmail Motion): Clarify what '-' does to
'M-s'.  Suggested by Arthur Milchior <arthur@milchior.fr> in
emacs-manual-bugs@gnu.org.

* doc/emacs/cmdargs.texi (Initial Options): Capitalize "Emacs".
(Action Arguments): Fix a typo.
(Emacs Invocation): Replace em-dash with a comma.  Suggested by
Justin Heyes-Jones <justinhj@gmail.com> in
emacs-manual-bugs@gnu.org.

* doc/emacs/m-x.texi (M-x): Add an example.  Suggested by Alberto
Sartori <alberto.sartori@sissa.it> in emacs-manual-bugs@gnu.org.

* doc/emacs/calendar.texi (Calendar/Diary, Calendar Unit Motion):
Minor wording changes.

1 files changed, 72 insertions, 8 deletions

diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 8ca10d7905c..8ce8f6180d1 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -775,16 +775,80 @@ after inserting the modified contents.  A custom @code{revert-buffer-function}
 may or may not run this hook.
 @end defvar
 
-@c FIXME?  Move this section from arevert-xtra to here?
+Emacs can revert buffers automatically.  It does that by default for
+buffers visiting files.  The following describes how to add support
+for auto-reverting new types of buffers.
+
+First, such buffers must have a suitable @code{revert-buffer-function}
+and @code{buffer-stale-function} defined.
+
 @defvar buffer-stale-function
 The value of this variable specifies a function to call to check
 whether a buffer needs reverting.  The default value only handles
 buffers that are visiting files, by checking their modification time.
-Buffers that are not visiting files require a custom function
-@iftex
-(@pxref{Supporting additional buffers,,, emacs-xtra,  Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Supporting additional buffers,,, emacs}).
-@end ifnottex
+Buffers that are not visiting files require a custom function of one
+optional argument @var{noconfirm}.  The function should return
+non-@code{nil} if the buffer should be reverted.  The buffer is
+current when this function is called.
+
+While this function is mainly intended for use in auto-reverting, it
+could be used for other purposes as well.  For instance, if
+auto-reverting is not enabled, it could be used to warn the user that
+the buffer needs reverting.  The idea behind the @var{noconfirm}
+argument is that it should be @code{t} if the buffer is going to be
+reverted without asking the user and @code{nil} if the function is
+just going to be used to warn the user that the buffer is out of date.
+In particular, for use in auto-reverting, @var{noconfirm} is @code{t}.
+If the function is only going to be used for auto-reverting, you can
+ignore the @var{noconfirm} argument.
+
+If you just want to automatically auto-revert every
+@code{auto-revert-interval} seconds (like the Buffer Menu), use:
+
+@example
+(setq-local buffer-stale-function
+     #'(lambda (&optional noconfirm) 'fast))
+@end example
+
+@noindent
+in the buffer's mode function.
+
+The special return value @samp{fast} tells the caller that the need
+for reverting was not checked, but that reverting the buffer is fast.
+It also tells Auto Revert not to print any revert messages, even if
+@code{auto-revert-verbose} is non-@code{nil}.  This is important, as
+getting revert messages every @code{auto-revert-interval} seconds can
+be very annoying.  The information provided by this return value could
+also be useful if the function is consulted for purposes other than
+auto-reverting.
 @end defvar
+
+Once the buffer has a suitable @code{revert-buffer-function} and
+@code{buffer-stale-function}, several problems usually remain.
+
+The buffer will only auto-revert if it is marked unmodified.  Hence,
+you will have to make sure that various functions mark the buffer
+modified if and only if either the buffer contains information that
+might be lost by reverting, or there is reason to believe that the user
+might be inconvenienced by auto-reverting, because he is actively
+working on the buffer.  The user can always override this by manually
+adjusting the modified status of the buffer.  To support this, calling
+the @code{revert-buffer-function} on a buffer that is marked
+unmodified should always keep the buffer marked unmodified.
+
+It is important to assure that point does not continuously jump around
+as a consequence of auto-reverting.  Of course, moving point might be
+inevitable if the buffer radically changes.
+
+You should make sure that the @code{revert-buffer-function} does not
+print messages that unnecessarily duplicate Auto Revert's own messages,
+displayed if @code{auto-revert-verbose} is @code{t}, and effectively
+override a @code{nil} value for @code{auto-revert-verbose}.  Hence,
+adapting a mode for auto-reverting often involves getting rid of such
+messages.  This is especially important for buffers that automatically
+revert every @code{auto-revert-interval} seconds.
+
+If the new auto-reverting is part of Emacs, you should mention it
+in the documentation string of @code{global-auto-revert-non-file-buffers}.
+
+Similarly, you should document the additions in the Emacs manual.