[PATCH] elisp manual patch: add to file notification documentation

[PATCH] elisp manual patch: add to file notification documentation

[Yoni Rabkin]

[-- Attachment #1: Type: text/plain, Size: 144 bytes --]


The following elisp manual documentation patch explains to the user how
to check if their emacs was compiled with file notification support.



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch-elisp-manual-add-file-notification-documentation.patch --]
[-- Type: text/x-diff, Size: 750 bytes --]

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 3e16ac0..2546074 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -3146,6 +3146,10 @@ respective library like @file{inotify}, @file{kqueue},
 @file{gfilenotify}, or @file{w32notify} statically.  These libraries
 enable watching of filesystems on the local machine.
 
+The variable @var{file-notify--library} is non-nil when Emacs has been
+compiled with file notification support, and value is the name of the
+low-level file notification package to be used for local file systems.
+
 It is also possible to watch filesystems on remote machines,
 @pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
 This does not depend on one of the libraries linked to Emacs.

Re: [PATCH] elisp manual patch: add to file notification documentation

[Stefan Kangas]

Yoni Rabkin <yoni@rabkins.net> writes:

> The following elisp manual documentation patch explains to the user how
> to check if their emacs was compiled with file notification support.

If this is supposed to be user-facing, shouldn't it be renamed to
`file-notify-library'?

> diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
> index 3e16ac0..2546074 100644
> --- a/doc/lispref/os.texi
> +++ b/doc/lispref/os.texi
> @@ -3146,6 +3146,10 @@ respective library like @file{inotify}, @file{kqueue},
>  @file{gfilenotify}, or @file{w32notify} statically.  These libraries
>  enable watching of filesystems on the local machine.
>
> +The variable @var{file-notify--library} is non-nil when Emacs has been
> +compiled with file notification support, and value is the name of the
> +low-level file notification package to be used for local file systems.
> +
>  It is also possible to watch filesystems on remote machines,
>  @pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
>  This does not depend on one of the libraries linked to Emacs.

Re: [PATCH] elisp manual patch: add to file notification documentation

[Michael Albinus]

Stefan Kangas <stefankangas@gmail.com> writes:

Hi,

>> The following elisp manual documentation patch explains to the user how
>> to check if their emacs was compiled with file notification support.
>
> If this is supposed to be user-facing, shouldn't it be renamed to
> `file-notify-library'?
>
>> +The variable @var{file-notify--library} is non-nil when Emacs has been
>> +compiled with file notification support, and value is the name of the
>> +low-level file notification package to be used for local file systems.

It isn't a variable but a constant. And no, it isn't designed to be
public.

Is this needed to be exposed? file-notify-add-watch returns an error, if
Emacs hasn't been compiled with file notification.

Best regards, Michael.

Re: [PATCH] elisp manual patch: add to file notification documentation

[Yoni Rabkin]

Stefan Kangas <stefankangas@gmail.com> writes:

> Yoni Rabkin <yoni@rabkins.net> writes:
>
>> The following elisp manual documentation patch explains to the user how
>> to check if their emacs was compiled with file notification support.
>
> If this is supposed to be user-facing, shouldn't it be renamed to
> `file-notify-library'?

Is the content of the elisp manual supposed to be user-facing? I guess
it depends on how you all define that term.

When I wrote "user" above, I was referring to the "user" of the elisp
manual, who is a person writing elisp.


>> diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
>> index 3e16ac0..2546074 100644
>> --- a/doc/lispref/os.texi
>> +++ b/doc/lispref/os.texi
>> @@ -3146,6 +3146,10 @@ respective library like @file{inotify}, @file{kqueue},
>>  @file{gfilenotify}, or @file{w32notify} statically.  These libraries
>>  enable watching of filesystems on the local machine.
>>
>> +The variable @var{file-notify--library} is non-nil when Emacs has been
>> +compiled with file notification support, and value is the name of the
>> +low-level file notification package to be used for local file systems.
>> +
>>  It is also possible to watch filesystems on remote machines,
>>  @pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
>>  This does not depend on one of the libraries linked to Emacs.
>

-- 
   "Cut your own wood and it will warm you twice"

Re: [PATCH] elisp manual patch: add to file notification documentation

[Yoni Rabkin]

Michael Albinus <michael.albinus@gmx.de> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
> Hi,
>
>>> The following elisp manual documentation patch explains to the user how
>>> to check if their emacs was compiled with file notification support.
>>
>> If this is supposed to be user-facing, shouldn't it be renamed to
>> `file-notify-library'?
>>
>>> +The variable @var{file-notify--library} is non-nil when Emacs has been
>>> +compiled with file notification support, and value is the name of the
>>> +low-level file notification package to be used for local file systems.
>
> It isn't a variable but a constant. And no, it isn't designed to be
> public.
>
> Is this needed to be exposed? file-notify-add-watch returns an error, if
> Emacs hasn't been compiled with file notification.

Kind of.

The documentation for `file-notify-add-watch' says: "If the file cannot
be watched for some reason, this function signals a `file-notify-error'
error."

I think that there is value in documenting a way for us to check if the
emacs we are running supports file notification, short of actually
trying to run `file-notify-add-watch', getting a generic
`file-notify-error', and reading the associated message to find out if
it is a simple problem, like a missing directory, or a difficult
problem, like a missing library.

-- 
   "Cut your own wood and it will warm you twice"

Re: [PATCH] elisp manual patch: add to file notification documentation

[Eli Zaretskii]

> From: Yoni Rabkin <yoni@rabkins.net>
> Cc: Stefan Kangas <stefankangas@gmail.com>, emacs-devel <emacs-devel@gnu.org>
> Date: Tue, 13 Dec 2022 12:34:25 -0500
> 
> I think that there is value in documenting a way for us to check if the
> emacs we are running supports file notification

You should be able to do that easily by looking at the value of the
variable system-configuration-features.

Re: [PATCH] elisp manual patch: add to file notification documentation

[Stefan Monnier]

> The documentation for `file-notify-add-watch' says: "If the file cannot
> be watched for some reason, this function signals a `file-notify-error'
> error."

If this error is not good enough, maybe we should improve it, e.g. it
could return different contents depending on whether the problem is
a lack of notification support in Emacs, or a lack of notification
support for this particular file/dir (e.g. via Tramp), etc...

> I think that there is value in documenting a way for us to check if the
> emacs we are running supports file notification, short of actually
> trying to run `file-notify-add-watch', getting a generic
> `file-notify-error', and reading the associated message to find out if
> it is a simple problem, like a missing directory, or a difficult
> problem, like a missing library.

I guess it depends what you intend to do with that info.

AFAIK all callers of `file-notify-add-watch` need to handle the case
where the addition fails, but I wonder how you intend to use the
specific kind of error in the rest of the code.

I guess you could also perform a dummy `file-notify-add-watch` on
something like $HOME as a way to check whether there is basic support
for file notifications.


        Stefan

Re: [PATCH] elisp manual patch: add to file notification documentation

[Stefan Kangas]

Yoni Rabkin <yoni@rabkins.net> writes:

>> If this is supposed to be user-facing, shouldn't it be renamed to
>> `file-notify-library'?
>
> Is the content of the elisp manual supposed to be user-facing? I guess
> it depends on how you all define that term.
>
> When I wrote "user" above, I was referring to the "user" of the elisp
> manual, who is a person writing elisp.

Yes, I also include ELisp developers when I say "user-facing" here.

This is in contrast to implementation details, that ELisp developers
must not rely upon.  The convention is to mark the names of such
implementation details either with two dashes "--" (new style) or
"-internal" (old style).

Re: [PATCH] elisp manual patch: add to file notification documentation

[Yoni Rabkin]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Yoni Rabkin <yoni@rabkins.net>
>> Cc: Stefan Kangas <stefankangas@gmail.com>, emacs-devel <emacs-devel@gnu.org>
>> Date: Tue, 13 Dec 2022 12:34:25 -0500
>> 
>> I think that there is value in documenting a way for us to check if the
>> emacs we are running supports file notification
>
> You should be able to do that easily by looking at the value of the
> variable system-configuration-features.

The documentation for `system-configuration-features' says:

"This is mainly intended for diagnostic purposes in bug reports.  Don't
rely on it for testing whether a feature you want to use is available."

-- 
   "Cut your own wood and it will warm you twice"

Re: [PATCH] elisp manual patch: add to file notification documentation

[Michael Albinus]

Yoni Rabkin <yoni@rabkins.net> writes:

Hi Yoni,

> I think that there is value in documenting a way for us to check if the
> emacs we are running supports file notification, short of actually
> trying to run `file-notify-add-watch', getting a generic
> `file-notify-error', and reading the associated message to find out if
> it is a simple problem, like a missing directory, or a difficult
> problem, like a missing library.

It's not that simple. Emacs might be compiled with file notification,
but it isn't possible for remote files. Emacs might be compiled without
file notification, but it is still possible for remote files.

And even if it is possible for local or remote files, it might not work
on NFS mounted file systems.

The value of file-notify--library is a vague approximation for being
able to use file notifications. That's the reason for being an internal
constant only.

Calling file-notify-add-watch gives you more precise results.

Best regards, Michael.

RE: [External] : Re: [PATCH] elisp manual patch: add to file notification documentation

[Drew Adams]

> >> The following elisp manual documentation patch explains
> >> to the user how to...
            ^^^^

user -> reader

Reader of the manual.

> > If this is supposed to be user-facing, shouldn't it be...
> 
> Is the content of the elisp manual supposed to be user-facing?
> I guess it depends on how you all define that term.
> 
> When I wrote "user" above, I was referring to the "user" of 
> the elisp manual, who is a person writing elisp.

And yes, users, including "end" users (at any level of
familiarity), can also use Lisp.

If you want to talk about both users of some code and
writers of some code, do that.  But yes, a user of `cons'
or `format' is a Lisp user, and in the case of Emacs
that's an Elisp user, which implies an Emacs user.

Re: [PATCH] elisp manual patch: add to file notification documentation

[Stefan Kangas]

Michael Albinus <michael.albinus@gmx.de> writes:

> It's not that simple. Emacs might be compiled with file notification,
> but it isn't possible for remote files. Emacs might be compiled without
> file notification, but it is still possible for remote files.
>
> And even if it is possible for local or remote files, it might not work
> on NFS mounted file systems.
>
> The value of file-notify--library is a vague approximation for being
> able to use file notifications. That's the reason for being an internal
> constant only.
>
> Calling file-notify-add-watch gives you more precise results.

Would it make sense to add something like the above to the docstring of
`file-notify--library'?

Re: [PATCH] elisp manual patch: add to file notification documentation

[Michael Albinus]

Stefan Kangas <stefankangas@gmail.com> writes:

>> It's not that simple. Emacs might be compiled with file notification,
>> but it isn't possible for remote files. Emacs might be compiled without
>> file notification, but it is still possible for remote files.
>>
>> And even if it is possible for local or remote files, it might not work
>> on NFS mounted file systems.
>>
>> The value of file-notify--library is a vague approximation for being
>> able to use file notifications. That's the reason for being an internal
>> constant only.
>>
>> Calling file-notify-add-watch gives you more precise results.
>
> Would it make sense to add something like the above to the docstring of
> `file-notify--library'?

After all, it's an internal constant. And it is about the local file
notification library only.

If you want to go into dirty details, you must even apply much more
analysis, in order to understand its behavior. gio, for example,
supports different backends, which behave differently.

See for example the functions file-notify--test-library and
file-notify--test-monitor in filenotify-tests.el. They are not perfect,
but good for now.

If we want to extend the documentation with this information, the manual
node "(elisp) File Notifications" would be the better place. But I'm not
sure whether this is of general interest.

Best regards, Michael.

Re: [PATCH] elisp manual patch: add to file notification documentation

[Eli Zaretskii]

> From: Yoni Rabkin <yoni@rabkins.net>
> Cc: michael.albinus@gmx.de,  stefankangas@gmail.com,  emacs-devel@gnu.org
> Date: Tue, 13 Dec 2022 13:23:20 -0500
> X-Spam-Status: No, score=-3.02
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > You should be able to do that easily by looking at the value of the
> > variable system-configuration-features.
> 
> The documentation for `system-configuration-features' says:
> 
> "This is mainly intended for diagnostic purposes in bug reports.  Don't
> rely on it for testing whether a feature you want to use is available."

I don't see why that text should avert you.  I'm telling you that you
can use it for this purpose.