procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Yet another round of improvements in the manual

Browse source 
* 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.
This commit is contained in:
Eli Zaretskii 2018-02-07 22:24:13 +02:00
parent c787a49682
commit 5fe81923e5
18 changed files with 230 additions and 232 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
doc/emacs/anti.texi
View file

@ -47,7 +47,7 @@ development will make that unnecessary.
@item @item
The @option{--fg-daemon} is gone, leaving only @option{--daemon}. No The @option{--fg-daemon} is gone, leaving only @option{--daemon}. No
need to procrastinate on the dilemma whether you do or don't want the need to procrastinate on the dilemma whether you do or do not want the
new shiny ``headless Emacs'' thingy. Hail, simplicity! new shiny ``headless Emacs'' thingy. Hail, simplicity!
@item @item
@ -71,10 +71,10 @@ The double-buffering feature of Emacs display on X has been removed.
We decided that its complexity and a few random surprising We decided that its complexity and a few random surprising
side-effects aren't justified by the gains, even though those gains side-effects aren't justified by the gains, even though those gains
were hailed in some quarters. Yes, Emacs 25.2 will flicker in some were hailed in some quarters. Yes, Emacs 25.2 will flicker in some
use cases, but we are sure Emacs users will be able to suck it, a they use cases, but we are sure Emacs users will be able to suck it, as
have been doing for years. Since this feature is gone, we've also they have been doing for years. Since this feature is gone, we've
removed the @code{inhibit-double-buffering} frame parameter, which is also removed the @code{inhibit-double-buffering} frame parameter,
now unnecessary. which is now unnecessary.
@item @item
Non-breaking hyphens and ASCII characters displayed instead of Non-breaking hyphens and ASCII characters displayed instead of

110
doc/emacs/arevert-xtra.texi
View file

@ -40,7 +40,6 @@ explained in the corresponding sections.
@menu @menu
* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. * Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu.
* Auto Reverting Dired:: Auto Revert of Dired buffers. * Auto Reverting Dired:: Auto Revert of Dired buffers.
* Supporting additional buffers:: How to add more Auto Revert support.
@end menu @end menu
@node Auto Reverting the Buffer Menu @node Auto Reverting the Buffer Menu
@ -68,13 +67,9 @@ automatically erasing the marks.
@node Auto Reverting Dired @node Auto Reverting Dired
@subsection Auto Reverting Dired buffers @subsection Auto Reverting Dired buffers
Auto-reverting Dired buffers currently works on GNU or Unix style
operating systems. It may not work satisfactorily on some other
systems.
Dired buffers only auto-revert when the file list of the buffer's main Dired buffers only auto-revert when the file list of the buffer's main
directory changes (e.g., when a new file is added). They do not directory changes (e.g., when a new file is added or deleted). They
auto-revert when information about a particular file changes do not auto-revert when information about a particular file changes
(e.g., when the size changes) or when inserted subdirectories change. (e.g., when the size changes) or when inserted subdirectories change.
To be sure that @emph{all} listed information is up to date, you have To be sure that @emph{all} listed information is up to date, you have
to manually revert using @kbd{g}, @emph{even} if auto-reverting is to manually revert using @kbd{g}, @emph{even} if auto-reverting is
@ -98,99 +93,10 @@ If you want auto-reverting to resume in the presence of marks and
flags, mark the buffer non-modified using @kbd{M-~}. However, adding, flags, mark the buffer non-modified using @kbd{M-~}. However, adding,
deleting or changing marks or flags will mark it modified again. deleting or changing marks or flags will mark it modified again.
Remote Dired buffers are not auto-reverted (because it may be slow). Remote Dired buffers are currently not auto-reverted. Neither are
Neither are Dired buffers for which you used shell wildcards or file Dired buffers for which you used shell wildcards or file arguments to
arguments to list only some of the files. @file{*Find*} and list only some of the files. @file{*Find*} and @file{*Locate*}
@file{*Locate*} buffers do not auto-revert either. buffers do not auto-revert either.
@c FIXME? This should be in the elisp manual? Note that auto-reverting Dired buffers may not work satisfactorily on
@node Supporting additional buffers some systems.
@subsection Adding Support for Auto-Reverting additional Buffers.
This section is intended for Elisp programmers who would like to add
support for auto-reverting new types of buffers.
To support auto-reverting the buffer must first of all have a suitable
@code{revert-buffer-function}. @xref{Definition of
revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}.
In addition, it must have a suitable @code{buffer-stale-function}.
@c FIXME only defvar in all of doc/emacs!
@defvar buffer-stale-function
The value of this variable is a function to check whether a
buffer needs reverting. This should be a function with 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}.
@ifinfo
Similarly, you should add a node to this chapter's menu. This node
@end ifinfo
@ifnotinfo
Similarly, you should add a section to this chapter. This section
@end ifnotinfo
should at the very least make clear whether enabling auto-reverting
for the buffer reliably assures that all information in the buffer is
completely up to date (or will be after @code{auto-revert-interval}
seconds).

15
doc/emacs/building.texi
View file

@ -607,15 +607,16 @@ to recompile and restart the program.
@vindex gud-tooltip-echo-area @vindex gud-tooltip-echo-area
GUD Tooltip mode is a global minor mode that adds tooltip support to GUD Tooltip mode is a global minor mode that adds tooltip support to
GUD@. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is GUD@. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is
disabled by default. If enabled, you can move the mouse cursor over a disabled by default. If enabled, you can move the mouse pointer over a
variable, a function, or a macro (collectively called variable, a function, or a macro (collectively called
@dfn{identifiers}) to show their values in tooltips @dfn{identifiers}) to show their values in tooltips
(@pxref{Tooltips}). Alternatively, mark an identifier or an (@pxref{Tooltips}). If just placing the mouse pointer over an
expression by dragging the mouse over it, then leave the mouse in the expression doesn't show the value of the expression you had in mind,
marked area to have the value of the expression displayed in a you can tell Emacs more explicitly what expression to evaluate by
tooltip. The GUD Tooltip mode takes effect in the GUD interaction dragging the mouse over the expression, then leaving the mouse inside
buffer, and in all source buffers with major modes listed in the the marked area. The GUD Tooltip mode takes effect in the GUD
variable @code{gud-tooltip-modes}. If the variable interaction buffer, and in all source buffers with major modes listed
in the variable @code{gud-tooltip-modes}. If the variable
@code{gud-tooltip-echo-area} is non-@code{nil}, or if you turned off @code{gud-tooltip-echo-area} is non-@code{nil}, or if you turned off
the tooltip mode, values are shown in the echo area instead of a the tooltip mode, values are shown in the echo area instead of a
tooltip. tooltip.

11
doc/emacs/calendar.texi
View file

@ -12,7 +12,7 @@ planned or past events. It also has facilities for managing your
appointments, and keeping track of how much time you spend working on appointments, and keeping track of how much time you spend working on
certain projects. certain projects.
To enter the calendar, type @kbd{M-x calendar}; this displays a To enter the calendar, type @kbd{M-x calendar}. This displays a
three-month calendar centered on the current month, with point on the three-month calendar centered on the current month, with point on the
current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it
prompts you for the month and year to be the center of the three-month prompts you for the month and year to be the center of the three-month
@ -126,10 +126,11 @@ whole year.
The easiest way to remember these commands is to consider months and The easiest way to remember these commands is to consider months and
years analogous to paragraphs and pages of text, respectively. But years analogous to paragraphs and pages of text, respectively. But
the commands themselves are not quite analogous. The ordinary Emacs the calendar movement commands themselves do not quite parallel those
paragraph commands move to the beginning or end of a paragraph, for movement through text: the ordinary Emacs paragraph commands move
whereas these month and year commands move by an entire month or an to the beginning or end of a paragraph, whereas these month and year
entire year, keeping the same date within the month or year. commands move by an entire month or an entire year, keeping the same
date within the month or year.
All these commands accept a numeric argument as a repeat count. All these commands accept a numeric argument as a repeat count.
For convenience, the digit keys and the minus sign specify numeric For convenience, the digit keys and the minus sign specify numeric

35
doc/emacs/cmdargs.texi
View file

@ -41,10 +41,11 @@ corresponding long form.
type. However, you don't have to spell out the whole option name; any type. However, you don't have to spell out the whole option name; any
unambiguous abbreviation is enough. When a long option takes an unambiguous abbreviation is enough. When a long option takes an
argument, you can use either a space or an equal sign to separate the argument, you can use either a space or an equal sign to separate the
option name and the argument. Thus, you can write either option name and the argument. Thus, for the option @samp{--display},
@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}. you can write either @samp{--display sugar-bombs:0.0} or
We recommend an equal sign because it makes the relationship clearer, @samp{--display=sugar-bombs:0.0}. We recommend an equal sign because
and the tables below always show an equal sign. it makes the relationship clearer, and the tables below always show an
equal sign.
@cindex initial options (command line) @cindex initial options (command line)
@cindex action options (command line) @cindex action options (command line)
@ -104,7 +105,7 @@ If the startup buffer is disabled (@pxref{Entering Emacs}), then
starting Emacs with one file argument displays the buffer visiting starting Emacs with one file argument displays the buffer visiting
@var{file} in a single window. With two file arguments, Emacs @var{file} in a single window. With two file arguments, Emacs
displays the files in two different windows. With more than two file displays the files in two different windows. With more than two file
argument, Emacs displays the last file specified in one window, plus arguments, Emacs displays the last file specified in one window, plus
another window with a Buffer Menu showing all the other files another window with a Buffer Menu showing all the other files
(@pxref{Several Buffers}). To inhibit using the Buffer Menu for this, (@pxref{Several Buffers}). To inhibit using the Buffer Menu for this,
change the variable @code{inhibit-startup-buffer-menu} to @code{t}. change the variable @code{inhibit-startup-buffer-menu} to @code{t}.
@ -326,7 +327,7 @@ in your initialization file (@pxref{Entering Emacs}).
@opindex -Q @opindex -Q
@itemx --quick @itemx --quick
@opindex --quick @opindex --quick
Start emacs with minimum customizations. This is similar to using @samp{-q}, Start Emacs with minimum customizations. This is similar to using @samp{-q},
@samp{--no-site-file}, @samp{--no-site-lisp}, and @samp{--no-splash} @samp{--no-site-file}, @samp{--no-site-lisp}, and @samp{--no-splash}
together. This also stops Emacs from processing X resources by together. This also stops Emacs from processing X resources by
setting @code{inhibit-x-resources} to @code{t} (@pxref{Resources}). setting @code{inhibit-x-resources} to @code{t} (@pxref{Resources}).
@ -337,7 +338,7 @@ setting @code{inhibit-x-resources} to @code{t} (@pxref{Resources}).
@opindex --daemon @opindex --daemon
@itemx --bg-daemon[=@var{name}] @itemx --bg-daemon[=@var{name}]
@itemx --fg-daemon[=@var{name}] @itemx --fg-daemon[=@var{name}]
Start Emacs as a daemon---after Emacs starts up, it starts the Emacs Start Emacs as a daemon: after Emacs starts up, it starts the Emacs
server without opening any frames. server without opening any frames.
(Optionally, you can specify an explicit @var{name} for the server.) (Optionally, you can specify an explicit @var{name} for the server.)
You can then use the @command{emacsclient} command to connect to Emacs You can then use the @command{emacsclient} command to connect to Emacs
@ -753,9 +754,10 @@ name under @file{/Software/GNU/Emacs}; first in the
there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs
still cannot determine the values, compiled-in defaults are used. still cannot determine the values, compiled-in defaults are used.
In addition to the environment variables above, you can also add many In addition to the environment variables above, you can also add
of the settings which on X belong in the @file{.Xdefaults} file settings to the @file{/Software/GNU/Emacs} registry key to specify X
(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key. resources (@pxref{X Resources}). Most of the settings you can specify
in your @file{.Xdefaults} file can be set from that registry key.
@node Display X @node Display X
@appendixsec Specifying the Display Name @appendixsec Specifying the Display Name
@ -886,7 +888,7 @@ Specify the color for the mouse cursor when the mouse is in the Emacs window.
@itemx --reverse-video @itemx --reverse-video
@opindex --reverse-video @opindex --reverse-video
@cindex reverse video, command-line argument @cindex reverse video, command-line argument
Reverse video---swap the foreground and background colors. Reverse video: swap the foreground and background colors.
@item --color=@var{mode} @item --color=@var{mode}
@opindex --color @opindex --color
@cindex standard colors on a character terminal @cindex standard colors on a character terminal
@ -1023,11 +1025,12 @@ width. If you start with an @samp{x} followed by an integer, Emacs
interprets it as the height. Thus, @samp{81} specifies just the interprets it as the height. Thus, @samp{81} specifies just the
width; @samp{x45} specifies just the height. width; @samp{x45} specifies just the height.
If you start with @samp{+} or @samp{-}, that introduces an offset, If you start the geometry with @samp{+} or @samp{-}, that introduces
which means both sizes are omitted. Thus, @samp{-3} specifies the an offset, which means both sizes are omitted. Thus, @samp{-3}
@var{xoffset} only. (If you give just one offset, it is always specifies the @var{xoffset} only. (If you give just one offset, it is
@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the always @var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset}
@var{yoffset}, placing the frame near the bottom left of the screen. and the @var{yoffset}, placing the frame near the bottom left of the
screen.
You can specify a default for any or all of the fields in your X You can specify a default for any or all of the fields in your X
resource file (@pxref{Resources}), and then override selected fields resource file (@pxref{Resources}), and then override selected fields

23
doc/emacs/display.texi
View file

@ -991,16 +991,15 @@ expressions to highlight in different ways.
@kindex M-s h u @kindex M-s h u
@kindex C-x w r @kindex C-x w r
@findex unhighlight-regexp @findex unhighlight-regexp
Unhighlight @var{regexp} (@code{unhighlight-regexp}). Unhighlight @var{regexp} (@code{unhighlight-regexp}). If you invoke
this from the menu, you select the expression to unhighlight from a
If you invoke this from the menu, you select the expression to list. If you invoke this from the keyboard, you use the minibuffer.
unhighlight from a list. If you invoke this from the keyboard, you It will show the most recently added regular expression; use @kbd{M-n}
use the minibuffer. It will show the most recently added regular to show the next older expression and @kbd{M-p} to select the next
expression; use @kbd{M-n} to show the next older expression and newer expression. (You can also type the expression by hand, with
@kbd{M-p} to select the next newer expression. (You can also type the completion.) When the expression you want to unhighlight appears in
expression by hand, with completion.) When the expression you want to the minibuffer, press @kbd{@key{RET}} to exit the minibuffer and
unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit unhighlight it.
the minibuffer and unhighlight it.
@item M-s h l @var{regexp} @key{RET} @var{face} @key{RET} @item M-s h l @var{regexp} @key{RET} @var{face} @key{RET}
@itemx C-x w l @var{regexp} @key{RET} @var{face} @key{RET} @itemx C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
@ -1393,13 +1392,13 @@ the option @code{display-time-mode}. The information added to the mode
line looks like this: line looks like this:
@example @example
@var{hh}:@var{mm}pm @var{l.ll} @var{hh}:@var{mm}PM @var{l.ll}
@end example @end example
@noindent @noindent
@vindex display-time-24hr-format @vindex display-time-24hr-format
Here @var{hh} and @var{mm} are the hour and minute, followed always by Here @var{hh} and @var{mm} are the hour and minute, followed always by
@samp{am} or @samp{pm}. @var{l.ll} is the average number, collected @samp{AM} or @samp{PM}. @var{l.ll} is the average number, collected
for the last few minutes, of processes in the whole system that were for the last few minutes, of processes in the whole system that were
either running or ready to run (i.e., were waiting for an available either running or ready to run (i.e., were waiting for an available
processor). (Some fields may be missing if your operating system processor). (Some fields may be missing if your operating system

1
doc/emacs/emacs.texi
View file

@ -482,7 +482,6 @@ Auto Reverting Non-File Buffers
* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. * Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu.
* Auto Reverting Dired:: Auto Revert of Dired buffers. * Auto Reverting Dired:: Auto Revert of Dired buffers.
* Supporting additional buffers:: How to add more Auto Revert support.
@end ifnottex @end ifnottex
Auto-Saving: Protection Against Disasters Auto-Saving: Protection Against Disasters

83
doc/emacs/files.texi
View file

@ -116,8 +116,8 @@ the @samp{$}; alternatively, it can be enclosed in braces after the
@file{/u/$@{FOO@}/test.c} are abbreviations for @file{/u/$@{FOO@}/test.c} are abbreviations for
@file{/u/rms/hacks/test.c}. If the environment variable is not @file{/u/rms/hacks/test.c}. If the environment variable is not
defined, no substitution occurs, so that the character @samp{$} stands defined, no substitution occurs, so that the character @samp{$} stands
for itself. Note that environment variables affect Emacs only if they for itself. Note that environment variables set outside Emacs affect
are applied before Emacs is started. Emacs only if they are applied before Emacs is started.
To access a file with @samp{$} in its name, if the @samp{$} causes To access a file with @samp{$} in its name, if the @samp{$} causes
expansion, type @samp{$$}. This pair is converted to a single expansion, type @samp{$$}. This pair is converted to a single
@ -167,7 +167,9 @@ minibuffer, you can abort the command by typing @kbd{C-g}. @xref{File
Names}, for details about entering file names into minibuffers. Names}, for details about entering file names into minibuffers.
If the specified file exists but the system does not allow you to If the specified file exists but the system does not allow you to
read it, an error message is displayed in the echo area. Otherwise, read it, an error message is displayed in the echo area (on GNU and
Unix systems you might be able to visit such a file using the
@samp{su} or @samp{sudo} methods; @pxref{Remote Files}). Otherwise,
you can tell that @kbd{C-x C-f} has completed successfully by the you can tell that @kbd{C-x C-f} has completed successfully by the
appearance of new text on the screen, and by the buffer name shown in appearance of new text on the screen, and by the buffer name shown in
the mode line (@pxref{Mode Line}). Emacs normally constructs the the mode line (@pxref{Mode Line}). Emacs normally constructs the
@ -291,7 +293,8 @@ see @ref{Drag and Drop}, and @ref{Misc Dired Features}.
On text-mode terminals and on graphical displays when Emacs was On text-mode terminals and on graphical displays when Emacs was
built without a GUI toolkit, you can visit files via the menu-bar built without a GUI toolkit, you can visit files via the menu-bar
@samp{File} menu, which has a @samp{Visit New File} item. @samp{File} menu, which has a @samp{Visit New File} and @samp{Open
File} items.
Each time you visit a file, Emacs automatically scans its contents Each time you visit a file, Emacs automatically scans its contents
to detect what character encoding and end-of-line convention it uses, to detect what character encoding and end-of-line convention it uses,
@ -638,7 +641,7 @@ you whether it should delete the excess backup versions. If it has
any other value, then Emacs never automatically deletes backups. any other value, then Emacs never automatically deletes backups.
Dired's @kbd{.} (Period) command can also be used to delete old versions. Dired's @kbd{.} (Period) command can also be used to delete old versions.
@xref{Dired Deletion}. @xref{Flagging Many Files}.
@node Backup Copying @node Backup Copying
@subsubsection Copying vs.@: Renaming @subsubsection Copying vs.@: Renaming
@ -738,7 +741,7 @@ survive a crash even if @code{fsync} works properly.
The @code{write-region-inhibit-fsync} variable controls whether The @code{write-region-inhibit-fsync} variable controls whether
Emacs invokes @code{fsync} after saving a file. The variable's Emacs invokes @code{fsync} after saving a file. The variable's
default value is @code{nil} when Emacs is interactive, and @code{t} default value is @code{nil} when Emacs is interactive, and @code{t}
when Emacs runs in batch mode (@pxref{Initial Options, batch mode}). when Emacs runs in batch mode (@pxref{Initial Options, Batch Mode}).
Emacs never uses @code{fsync} when writing auto-save files, as these Emacs never uses @code{fsync} when writing auto-save files, as these
files might lose data anyway. files might lose data anyway.
@ -751,7 +754,7 @@ files might lose data anyway.
Simultaneous editing occurs when two users visit the same file, both Simultaneous editing occurs when two users visit the same file, both
make changes, and then both save them. If nobody is informed that make changes, and then both save them. If nobody is informed that
this is happening, whichever user saves first would later find that this is happening, whichever user saves first would later find that
his changes were lost. their changes were lost.
On some systems, Emacs notices immediately when the second user starts On some systems, Emacs notices immediately when the second user starts
to change the file, and issues an immediate warning. On all systems, to change the file, and issues an immediate warning. On all systems,
@ -952,12 +955,25 @@ discard your changes.)
You can also tell Emacs to revert buffers periodically. To do this You can also tell Emacs to revert buffers periodically. To do this
for a specific buffer, enable the minor mode Auto-Revert mode by for a specific buffer, enable the minor mode Auto-Revert mode by
typing @kbd{M-x auto-revert-mode}. This automatically reverts the typing @kbd{M-x auto-revert-mode}. This automatically reverts the
current buffer every five seconds; you can change the interval through current buffer when its visited file changes on disk. To do the same
the variable @code{auto-revert-interval}. To do the same for all file for all file buffers, type @kbd{M-x global-auto-revert-mode} to enable
buffers, type @kbd{M-x global-auto-revert-mode} to enable Global Global Auto-Revert mode. These minor modes do not check or revert
Auto-Revert mode. These minor modes do not check or revert remote remote files, because that is usually too slow. This behavior can be
files, because that is usually too slow. This behavior can be changed changed by setting the variable @code{auto-revert-remote-files} to
by setting the variable @code{auto-revert-remote-files} to non-@code{nil}. non-@code{nil}.
@cindex file notifications
@vindex auto-revert-use-notify
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
check for file changes by polling every five seconds. You can change
the polling interval through the variable @code{auto-revert-interval}.
Not all systems support file notifications; where they are not
supported, @code{auto-revert-use-notify} will be @code{nil} by
default.
One use of Auto-Revert mode is to ``tail'' a file such as a system 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 log, so that changes made to that file by other programs are
@ -1159,7 +1175,7 @@ this---saving them---updates the files themselves.
@vindex auto-save-list-file-prefix @vindex auto-save-list-file-prefix
Emacs records information about interrupted sessions in files named Emacs records information about interrupted sessions in files named
@file{.saves-@var{pid}-@var{hostname}} in the directory @file{.saves-@var{pid}-@var{hostname}~} in the directory
@file{~/.emacs.d/auto-save-list/}. This directory is determined by @file{~/.emacs.d/auto-save-list/}. This directory is determined by
the variable @code{auto-save-list-file-prefix}. If you set the variable @code{auto-save-list-file-prefix}. If you set
@code{auto-save-list-file-prefix} to @code{nil}, sessions are not @code{auto-save-list-file-prefix} to @code{nil}, sessions are not
@ -1233,8 +1249,9 @@ named @file{/fsf}:
listing} is a list of all the files in a directory. Emacs provides listing} is a list of all the files in a directory. Emacs provides
commands to create and delete directories, and to make directory commands to create and delete directories, and to make directory
listings in brief format (file names only) and verbose format (sizes, listings in brief format (file names only) and verbose format (sizes,
dates, and authors included). Emacs also includes a directory browser dates, and other attributes included). Emacs also includes a
feature called Dired; see @ref{Dired}. directory browser feature called Dired, which you can invoke with
@kbd{C-x d}; see @ref{Dired}.
@table @kbd @table @kbd
@item C-x C-d @var{dir-or-pattern} @key{RET} @item C-x C-d @var{dir-or-pattern} @key{RET}
@ -1320,6 +1337,9 @@ information about the @command{diff} program.
The output of the @code{diff} command is shown using a major mode The output of the @code{diff} command is shown using a major mode
called Diff mode. @xref{Diff Mode}. called Diff mode. @xref{Diff Mode}.
A (much more sophisticated) alternative is @kbd{M-x ediff}
(@pxref{Top, Ediff, Ediff, ediff, The Ediff Manual}).
@findex diff-backup @findex diff-backup
The command @kbd{M-x diff-backup} compares a specified file with its The command @kbd{M-x diff-backup} compares a specified file with its
most recent backup. If you specify the name of a backup file, most recent backup. If you specify the name of a backup file,
@ -1336,10 +1356,10 @@ would make to the file if you save the buffer.
current window with that in the window that was the selected window current window with that in the window that was the selected window
before you selected the current one. (For more information about before you selected the current one. (For more information about
windows in Emacs, @ref{Windows}.) Comparison starts at point in each windows in Emacs, @ref{Windows}.) Comparison starts at point in each
window, after pushing each initial point value on the mark ring in its window, after pushing each initial point value on the mark ring
respective buffer. Then it moves point forward in each window, one (@pxref{Mark Ring}) in its respective buffer. Then it moves point
character at a time, until it reaches characters that don't match. forward in each window, one character at a time, until it reaches
Then the command exits. characters that don't match. Then the command exits.
If point in the two windows is followed by non-matching text when If point in the two windows is followed by non-matching text when
the command starts, @kbd{M-x compare-windows} tries heuristically to the command starts, @kbd{M-x compare-windows} tries heuristically to
@ -1353,8 +1373,9 @@ skips one matching range or finds the start of another.
whitespace. If the variable @code{compare-ignore-case} is whitespace. If the variable @code{compare-ignore-case} is
non-@code{nil}, the comparison ignores differences in case as well. non-@code{nil}, the comparison ignores differences in case as well.
If the variable @code{compare-ignore-whitespace} is non-@code{nil}, If the variable @code{compare-ignore-whitespace} is non-@code{nil},
@code{compare-windows} normally ignores changes in whitespace, and a @code{compare-windows} by default ignores changes in whitespace, but a
prefix argument turns that off. prefix argument turns that off for that single invocation of the
command.
@cindex Smerge mode @cindex Smerge mode
@findex smerge-mode @findex smerge-mode
@ -1424,7 +1445,7 @@ Move to the next hunk-start (@code{diff-hunk-next}).
This command has a side effect: it @dfn{refines} the hunk you move to, This command has a side effect: it @dfn{refines} the hunk you move to,
highlighting its changes with better granularity. To disable this highlighting its changes with better granularity. To disable this
feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor
mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by mode Diff Auto-Refine mode. To disable Diff Auto-Refine mode by
default, add this to your init file (@pxref{Hooks}): default, add this to your init file (@pxref{Hooks}):
@example @example
@ -1553,17 +1574,17 @@ modify the original source files rather than the patched source files.
@section Copying, Naming and Renaming Files @section Copying, Naming and Renaming Files
Emacs has several commands for copying, naming, and renaming files. Emacs has several commands for copying, naming, and renaming files.
All of them read two file names @var{old} and @var{new} using the All of them read two file names, @var{old} (or @var{target}) and
minibuffer, and then copy or adjust a file's name accordingly; they do @var{new}, using the minibuffer, and then copy or adjust a file's name
not accept wildcard file names. accordingly; they do not accept wildcard file names.
In all these commands, if the argument @var{new} is just a directory In all these commands, if the argument @var{new} is just a directory
name, the real new name is in that directory, with the same name (@pxref{Directory Names,,, elisp, the Emacs Lisp Reference
Manual}), the real new name is in that directory, with the same
non-directory component as @var{old}. For example, the command non-directory component as @var{old}. For example, the command
@w{@kbd{M-x rename-file @key{RET} ~/foo @key{RET} /tmp/ @key{RET}}} @w{@kbd{M-x rename-file @key{RET} ~/foo @key{RET} /tmp/ @key{RET}}}
renames @file{~/foo} to @file{/tmp/foo}. On GNU and other POSIX-like renames @file{~/foo} to @file{/tmp/foo}. On GNU and other POSIX-like
systems, directory names end in @samp{/}. @xref{Directory Names,,, systems, directory names end in @samp{/}.
elisp, the Emacs Lisp Reference Manual}.
All these commands ask for confirmation when the new file name already All these commands ask for confirmation when the new file name already
exists. exists.
@ -1816,8 +1837,8 @@ To carry out this request, Emacs uses a remote-login program such as
@command{ssh}. @command{ssh}.
You must always specify in the file name which method to use---for You must always specify in the file name which method to use---for
example, @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses example, @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses
@command{ssh}. When you specify the pseudo method @var{-} in the file @command{ssh}. When you specify the pseudo method @samp{-} in the
name, Emacs chooses the method as follows: file name, Emacs chooses the method as follows:
@enumerate @enumerate
@item @item

4
doc/emacs/indent.texi
View file

@ -201,8 +201,8 @@ are always displayed as empty spaces extending to the next
@node Just Spaces @node Just Spaces
@section Tabs vs.@: Spaces @section Tabs vs.@: Spaces
Normally, indentation commands insert (or remove) an optimal mix of Normally, indentation commands insert (or remove) a mix of space
space characters and tab characters to align to the desired column. characters and tab characters so as to align to the desired column.
Tab characters are displayed as a stretch of empty space extending to Tab characters are displayed as a stretch of empty space extending to
the next @dfn{display tab stop}. By default, there is one display tab the next @dfn{display tab stop}. By default, there is one display tab
stop every @code{tab-width} columns (the default is 8). @xref{Text stop every @code{tab-width} columns (the default is 8). @xref{Text

5
doc/emacs/m-x.texi
View file

@ -56,7 +56,10 @@ of entering the command name. This takes you back to command level.
To pass a numeric argument to the command you are invoking with To pass a numeric argument to the command you are invoking with
@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The @kbd{M-x}, specify the numeric argument before @kbd{M-x}. The
argument value appears in the prompt while the command name is being argument value appears in the prompt while the command name is being
read, and finally @kbd{M-x} passes the argument to that command. read, and finally @kbd{M-x} passes the argument to that command. For
example, to pass the numeric argument of 42 to the command
@code{forward-char} you can type @kbd{C-u 42 M-x forward-char
@key{RET}}.
@vindex suggest-key-bindings @vindex suggest-key-bindings
When the command you run with @kbd{M-x} has a key binding, Emacs When the command you run with @kbd{M-x} has a key binding, Emacs

4
doc/emacs/macos.texi
View file

@ -18,8 +18,8 @@ does not support versions before macOS 10.6.
@samp{Nextstep} internally, instead of ``Cocoa'' or ``macOS''; for @samp{Nextstep} internally, instead of ``Cocoa'' or ``macOS''; for
instance, most of the commands and variables described in this section instance, most of the commands and variables described in this section
begin with @samp{ns-}, which is short for @samp{Nextstep}. NeXTstep begin with @samp{ns-}, which is short for @samp{Nextstep}. NeXTstep
was an application interface released by NeXT Inc during the 1980s, of was an application interface released by NeXT Inc.@: during the 1980s,
which Cocoa is a direct descendant. Apart from Cocoa, there is of which Cocoa is a direct descendant. Apart from Cocoa, there is
another NeXTstep-style system: GNUstep, which is free software. As of another NeXTstep-style system: GNUstep, which is free software. As of
this writing, Emacs GNUstep support is alpha status (@pxref{GNUstep this writing, Emacs GNUstep support is alpha status (@pxref{GNUstep
Support}), but we hope to improve it in the future. Support}), but we hope to improve it in the future.

14
doc/emacs/maintaining.texi
View file

@ -542,13 +542,13 @@ been changed in the repository, offer to update it.
These rules also apply when you use RCS in its non-locking mode, These rules also apply when you use RCS in its non-locking mode,
except that changes are not automatically merged from the repository. except that changes are not automatically merged from the repository.
Nothing informs you if another user has committed changes in the same Nothing informs you if another user has committed changes in the same
file since you began editing it; when you commit your revision, his file since you began editing it; when you commit your revision, that
changes are removed (however, they remain in the repository and are other user's changes are removed (however, they remain in the
thus not irrevocably lost). Therefore, you must verify that the repository and are thus not irrevocably lost). Therefore, you must
current revision is unchanged before committing your changes. In verify that the current revision is unchanged before committing your
addition, locking is possible with RCS even in this mode: @kbd{C-x v changes. In addition, locking is possible with RCS even in this mode:
v} with an unmodified file locks the file, just as it does with RCS in @kbd{C-x v v} with an unmodified file locks the file, just as it does
its normal locking mode (@pxref{VC With A Locking VCS}). with RCS in its normal locking mode (@pxref{VC With A Locking VCS}).
@node VC With A Locking VCS @node VC With A Locking VCS
@subsubsection Basic Version Control with Locking @subsubsection Basic Version Control with Locking

4
doc/emacs/mini.texi
View file

@ -66,8 +66,8 @@ minibuffer-electric-default-mode}.
other uses of the echo area. If an error message or an informative other uses of the echo area. If an error message or an informative
message is emitted while the minibuffer is active, the message hides message is emitted while the minibuffer is active, the message hides
the minibuffer for a few seconds, or until you type something; then the minibuffer for a few seconds, or until you type something; then
the minibuffer comes back. While the minibuffer is in use, keystrokes the minibuffer comes back. While the minibuffer is in use, Emacs does
do not echo. not echo keystrokes.
@node Minibuffer File @node Minibuffer File
@section Minibuffers for File Names @section Minibuffers for File Names

4
doc/emacs/misc.texi
View file

@ -413,8 +413,8 @@ is needed. For OpenDocument and Microsoft Office documents, the
When you visit a document file that can be displayed with DocView When you visit a document file that can be displayed with DocView
mode, Emacs automatically uses DocView mode @footnote{The needed mode, Emacs automatically uses DocView mode @footnote{The needed
external tools for the document type must be available, and Emacs must external tools for the document type must be available, and Emacs must
be running in a graphical frame and have PNG image support. If any of be running in a graphical frame and have PNG image support. If these
these requirements is not fulfilled, Emacs falls back to another major requirements is not fulfilled, Emacs falls back to another major
mode.}. As an exception, when you visit a PostScript file, Emacs mode.}. As an exception, when you visit a PostScript file, Emacs
switches to PS mode, a major mode for editing PostScript files as switches to PS mode, a major mode for editing PostScript files as
text; however, it also enables DocView minor mode, so you can type text; however, it also enables DocView minor mode, so you can type

1
doc/emacs/rmail.texi
View file

@ -175,6 +175,7 @@ Move to the next message containing a match for @var{regexp}
@item - M-s @var{regexp} @key{RET} @item - M-s @var{regexp} @key{RET}
Move to the previous message containing a match for @var{regexp}. Move to the previous message containing a match for @var{regexp}.
(This is @kbd{M-s} with a negative argument.)
@end table @end table
@kindex n @r{(Rmail)} @kindex n @r{(Rmail)}

14
doc/emacs/screen.texi
View file

@ -30,13 +30,13 @@ display systems commonly use the word ``window'' with a different
meaning; but, as stated above, we refer to those graphical windows meaning; but, as stated above, we refer to those graphical windows
as ``frames''. as ``frames''.
An Emacs window is where the @dfn{buffer}---the text you are An Emacs window is where the @dfn{buffer}---the text or other
editing---is displayed. On a graphical display, the window possesses graphics you are editing or viewing---is displayed. On a graphical
a @dfn{scroll bar} on one side, which can be used to scroll through display, the window possesses a @dfn{scroll bar} on one side, which
the buffer. The last line of the window is a @dfn{mode line}. This can be used to scroll through the buffer. The last line of the window
displays various information about what is going on in the buffer, is a @dfn{mode line}. This displays various information about what is
such as whether there are unsaved changes, the editing modes that are going on in the buffer, such as whether there are unsaved changes, the
in use, the current line number, and so forth. editing modes that are in use, the current line number, and so forth.
When you start Emacs, there is normally only one window in the When you start Emacs, there is normally only one window in the
frame. However, you can subdivide this window horizontally or frame. However, you can subdivide this window horizontally or

44
doc/emacs/text.texi
View file

@ -1498,29 +1498,27 @@ This is an example.
@findex doctex-mode @findex doctex-mode
@findex bibtex-mode @findex bibtex-mode
Emacs provides special major modes for editing files written in @TeX{} is a powerful text formatter written by Donald Knuth; like
@TeX{} and its related formats. @TeX{} is a powerful text formatter GNU Emacs, it is free software. The @TeX{} format has several
written by Donald Knuth; like GNU Emacs, it is free software. variants, including @LaTeX{}, a simplified input format for @TeX{};
@LaTeX{} is a simplified input format for @TeX{}, implemented using Doc@TeX{}, a special file format in which the @LaTeX{} sources are
@TeX{} macros. Doc@TeX{} is a special file format in which the written, combining sources with documentation; and Sli@TeX{}, an
@LaTeX{} sources are written, combining sources with documentation. obsolete special form of @LaTeX{}@footnote{
Sli@TeX{} is an obsolete special form of @LaTeX{}.@footnote{It has It has been replaced by the @samp{slides} document class, which comes
been replaced by the @samp{slides} document class, which comes with with @LaTeX{}.}.
@LaTeX{}.}
@vindex tex-default-mode @vindex tex-default-mode
@TeX{} mode has four variants: Plain @TeX{} mode, @LaTeX{} mode, Emacs provides a @TeX{} major mode for each of these variants: Plain
Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ @TeX{} mode, @LaTeX{} mode, Doc@TeX{} mode, and Sli@TeX{} mode. Emacs
only slightly, and are designed for editing the four different selects the appropriate mode by looking at the contents of the buffer.
formats. Emacs selects the appropriate mode by looking at the (This is done by the @code{tex-mode} command, which is normally called
contents of the buffer. (This is done by the @code{tex-mode} command, automatically when you visit a @TeX{}-like file. @xref{Choosing
which is normally called automatically when you visit a @TeX{}-like Modes}.) If the contents are insufficient to determine this, Emacs
file. @xref{Choosing Modes}.) If the contents are insufficient to chooses the mode specified by the variable @code{tex-default-mode};
determine this, Emacs chooses the mode specified by the variable its default value is @code{latex-mode}. If Emacs does not guess
@code{tex-default-mode}; its default value is @code{latex-mode}. If right, you can select the correct variant of @TeX{} mode using the
Emacs does not guess right, you can select the correct variant of command @kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, @kbd{M-x
@TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}.
latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}.
The following sections document the features of @TeX{} mode and its The following sections document the features of @TeX{} mode and its
variants. There are several other @TeX{}-related Emacs packages, variants. There are several other @TeX{}-related Emacs packages,
@ -1618,7 +1616,9 @@ to keep braces balanced at all times, rather than inserting them
singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
braces. It leaves point between the two braces so you can insert the braces. It leaves point between the two braces so you can insert the
text that belongs inside. Afterward, use the command @kbd{C-c @}} text that belongs inside. Afterward, use the command @kbd{C-c @}}
(@code{up-list}) to move forward past the close brace. (@code{up-list}) to move forward past the close brace. You can also
invoke @kbd{C-c @{} after marking some text: then the command encloses
the marked text in braces.
@findex tex-validate-region @findex tex-validate-region
@findex tex-terminate-paragraph @findex tex-terminate-paragraph

80
doc/lispref/backups.texi
View file

@ -775,16 +775,80 @@ after inserting the modified contents. A custom @code{revert-buffer-function}
may or may not run this hook. may or may not run this hook.
@end defvar @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 @defvar buffer-stale-function
The value of this variable specifies a function to call to check The value of this variable specifies a function to call to check
whether a buffer needs reverting. The default value only handles whether a buffer needs reverting. The default value only handles
buffers that are visiting files, by checking their modification time. buffers that are visiting files, by checking their modification time.
Buffers that are not visiting files require a custom function Buffers that are not visiting files require a custom function of one
@iftex optional argument @var{noconfirm}. The function should return
(@pxref{Supporting additional buffers,,, emacs-xtra, Specialized Emacs Features}). non-@code{nil} if the buffer should be reverted. The buffer is
@end iftex current when this function is called.
@ifnottex
(@pxref{Supporting additional buffers,,, emacs}). While this function is mainly intended for use in auto-reverting, it
@end ifnottex 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 @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.