mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-04-27 08:43:40 -07:00
Code Issues Projects Releases Wiki Activity

; Fix wording of "File Notifications" in the ELisp manual

Browse source 
* doc/lispref/os.texi (File Notifications): Fix typos,
punctuation, and wording.
This commit is contained in:
Eli Zaretskii 2022-04-20 20:00:15 +03:00
parent e6c2a2497d
commit dbb2dd6939
1 changed files with 30 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

57
doc/lispref/os.texi
View file

@ -3088,21 +3088,21 @@ This function removes the tray notification given by its unique
@cindex watch, for filesystem events @cindex watch, for filesystem events
Several operating systems support watching of filesystems for changes Several operating systems support watching of filesystems for changes
of files. If configured properly, Emacs links a respective library to files or their attributes. If configured properly, Emacs links a
like @file{inotify}, @file{kqueue}, @file{gfilenotify}, or respective library like @file{inotify}, @file{kqueue},
@file{w32notify} statically. These libraries enable watching of @file{gfilenotify}, or @file{w32notify} statically. These libraries
filesystems on the local machine. enable watching of filesystems on the local machine.
It is also possible to watch filesystems on remote machines, It is also possible to watch filesystems on remote machines,
@pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual} @pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
This does not depend on one of the libraries linked to Emacs. This does not depend on one of the libraries linked to Emacs.
Since all these libraries emit different events on notified file Since all these libraries emit different events upon notified file
changes, there is the Emacs library @code{filenotify} which provides a changes, Emacs provides a special library @code{filenotify} which
unified interface. Lisp programs that want to receive file presents a unified interface to applications. Lisp programs that want
notifications should always use this library in preference to the to receive file notifications should always use this library in
native ones. preference to the native ones. This section documents the
@code{filenotify} library functions and variables.
@defun file-notify-add-watch file flags callback @defun file-notify-add-watch file flags callback
Add a watch for filesystem events pertaining to @var{file}. This Add a watch for filesystem events pertaining to @var{file}. This
@ -3110,31 +3110,33 @@ arranges for filesystem events pertaining to @var{file} to be reported
to Emacs. to Emacs.
The returned value is a descriptor for the added watch. Its type The returned value is a descriptor for the added watch. Its type
depends on the underlying library, it cannot be assumed to be an depends on the underlying library, and in general cannot be assumed to
integer as in the example below. It should be used for comparison by be an integer as in the example below. It should be used for
@code{equal} only. comparison by @code{equal} only.
If the @var{file} cannot be watched for some reason, this function If the @var{file} cannot be watched for some reason, this function
signals a @code{file-notify-error} error. signals a @code{file-notify-error} error.
Sometimes, mounted filesystems cannot be watched for file changes. Sometimes, mounted filesystems cannot be watched for file changes.
This is not detected by this function, a non-@code{nil} return value This is not detected by this function, and so a non-@code{nil} return
does not guarantee that changes on @var{file} will be notified. value does not guarantee that changes on @var{file} will be actually
notified.
@var{flags} is a list of conditions to set what will be watched for. @var{flags} is a list of conditions to set what will be watched for.
It can include the following symbols: It can include the following symbols:
@table @code @table @code
@item change @item change
watch for file changes watch for changes in file's contents
@item attribute-change @item attribute-change
watch for file attribute changes, like permissions or modification watch for changes in file attributes, like permissions or modification
time time
@end table @end table
If @var{file} is a directory, @code{change} watches for file creation If @var{file} is a directory, @code{change} watches for file creation
or deletion in that directory. Some of the file notification backends and deletion in that directory. Some of the native file notification
report also file changes. This does not work recursively. libraries also report file changes in that case. This does not work
recursively.
When any event happens, Emacs will call the @var{callback} function When any event happens, Emacs will call the @var{callback} function
passing it a single argument @var{event}, which is of the form passing it a single argument @var{event}, which is of the form
@ -3160,19 +3162,20 @@ reports attribute changes as well
@item attribute-changed @item attribute-changed
a @var{file} attribute was changed a @var{file} attribute was changed
@item stopped @item stopped
watching @var{file} has been stopped watching @var{file} has stopped
@end table @end table
Note that the @file{w32notify} library does not report Note that the @file{w32notify} library does not report
@code{attribute-changed} events. When some file's attribute, like @code{attribute-changed} events. When some file's attribute, like
permissions or modification time, has changed, this library reports a permissions or modification time, has changed, this library reports a
@code{changed} event. Likewise, the @file{kqueue} library does not @code{changed} event. Likewise, the @file{kqueue} library does not
report reliably file attribute changes when watching a directory. reliably report file attribute changes when watching a directory.
The @code{stopped} event reports, that watching the file has been The @code{stopped} event means that watching the file has been
stopped. This could be because @code{file-notify-rm-watch} was called discontinued. This could be because @code{file-notify-rm-watch} was
(see below), or because the file being watched was deleted, or due to called (see below), or because the file being watched was deleted, or
another error reported from the underlying library. due to another error reported from the underlying library which makes
further watching impossible.
@var{file} and @var{file1} are the name of the file(s) whose event is @var{file} and @var{file1} are the name of the file(s) whose event is
being reported. For example: being reported. For example:
@ -3216,7 +3219,7 @@ being reported. For example:
@end group @end group
@end example @end example
Whether the action @code{renamed} is returned, depends on the used Whether the action @code{renamed} is returned depends on the used
watch library. Otherwise, the actions @code{deleted} and watch library. Otherwise, the actions @code{deleted} and
@code{created} could be returned in a random order. @code{created} could be returned in a random order.