bug#22220: 24.5; no documentation for default process sentinel

bug#22220: 24.5; no documentation for default process sentinel

[Ram Bhamidipaty]

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

Emacs has the concept of a default process sentinel - but this is not documented in the emacs lisp reference manual.


[-- Attachment #2: Type: text/html, Size: 1812 bytes --]

bug#22220: 24.5; no documentation for default process sentinel

[Eli Zaretskii]

> From: Ram Bhamidipaty <rbhamidipaty@roku.com>
> Date: Tue, 22 Dec 2015 01:20:28 +0000
> 
> Emacs has the concept of a default process sentinel - but this is not
> documented in the emacs lisp reference manual.

The default sentinel is documented with the set-process-sentinel
function:

 -- Function: set-process-sentinel process sentinel
     This function associates SENTINEL with PROCESS.  If SENTINEL is
     `nil', then the process will have the default sentinel, which
     inserts a message in the process's buffer when the process status
     changes.

Maybe this is not prominent enough, and we should say this in a few
more places.  Other than that, what else do you think should be said
about the default sentinel?

Thanks.

bug#22220: 24.5; no documentation for default process sentinel

[Ram Bhamidipaty]

Hi there,

Thank you for responding.

It would be nice if the default process sentinel were explicitly documented - at least the name and formal description. 

-Ram


-----Original Message-----
From: Eli Zaretskii [mailto:eliz@gnu.org] 
Sent: Tuesday, December 22, 2015 9:13 AM
To: Ram Bhamidipaty <rbhamidipaty@roku.com>
Cc: 22220@debbugs.gnu.org
Subject: Re: bug#22220: 24.5; no documentation for default process sentinel

> From: Ram Bhamidipaty <rbhamidipaty@roku.com>
> Date: Tue, 22 Dec 2015 01:20:28 +0000
> 
> Emacs has the concept of a default process sentinel - but this is not
> documented in the emacs lisp reference manual.

The default sentinel is documented with the set-process-sentinel
function:

 -- Function: set-process-sentinel process sentinel
     This function associates SENTINEL with PROCESS.  If SENTINEL is
     `nil', then the process will have the default sentinel, which
     inserts a message in the process's buffer when the process status
     changes.

Maybe this is not prominent enough, and we should say this in a few
more places.  Other than that, what else do you think should be said
about the default sentinel?

Thanks.

bug#22220: 24.5; no documentation for default process sentinel

[Eli Zaretskii]

> From: Ram Bhamidipaty <rbhamidipaty@roku.com>
> CC: "22220@debbugs.gnu.org" <22220@debbugs.gnu.org>
> Date: Tue, 22 Dec 2015 23:25:28 +0000
> 
> It would be nice if the default process sentinel were explicitly documented - at least the name and formal description. 

The description is what I cited from the manual; there's nothing else
to be said about that, because that's all that the default sentinel
does.

As for the name, why is that important?  You can always get it
installed for the process using nil as the argument to
set-process-sentinel, and the implementation is in C, so how would the
name help?

bug#22220: 24.5; no documentation for default process sentinel

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

>> It would be nice if the default process sentinel were explicitly documented
>> - at least the name and formal description.

> As for the name, why is that important? You can always get it installed for
> the process using nil as the argument to set-process-sentinel, and the
> implementation is in C, so how would the name help?

I must admit to a similar confusion. Aside from the fact that more could be
said: does more need to be said?

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#22220: 24.5; no documentation for default process sentinel

[Ram Bhamidipaty]

This is what I ran into: I am working on some code using the emacs process facility. And I started seeing messages (from the default sentinel) that I did not expect. When I _skimmed_ through the sentinel section I did not notice that a default sentinel is added to all processes. I acknowledge that skimming the docs was not the right thing to do - since I missed the fact that there is a default sentinel.

From my point of view - I would have been nice - if the default sentinel info were a bit more prominent.

So - I proposed that the name and behavior of the default sentinel be documented. It might not be needed - in the sense that the name itself is not required - but if there were a block of text in the info section like "-- Function: xxx default-sentinel" that would be more prominent - and probably harder to miss.

-Ram

-----Original Message-----
From: John Wiegley [mailto:jwiegley@gmail.com] 
Sent: Wednesday, December 23, 2015 9:34 AM
To: Eli Zaretskii <eliz@gnu.org>
Cc: Ram Bhamidipaty <rbhamidipaty@roku.com>; 22220@debbugs.gnu.org
Subject: Re: bug#22220: 24.5; no documentation for default process sentinel

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

>> It would be nice if the default process sentinel were explicitly documented
>> - at least the name and formal description.

> As for the name, why is that important? You can always get it installed for
> the process using nil as the argument to set-process-sentinel, and the
> implementation is in C, so how would the name help?

I must admit to a similar confusion. Aside from the fact that more could be
said: does more need to be said?

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#22220: 24.5; no documentation for default process sentinel

[Eli Zaretskii]

> From: Ram Bhamidipaty <rbhamidipaty@roku.com>
> CC: "22220@debbugs.gnu.org" <22220@debbugs.gnu.org>
> Date: Wed, 23 Dec 2015 17:45:22 +0000
> 
> This is what I ran into: I am working on some code using the emacs process facility. And I started seeing messages (from the default sentinel) that I did not expect. When I _skimmed_ through the sentinel section I did not notice that a default sentinel is added to all processes. I acknowledge that skimming the docs was not the right thing to do - since I missed the fact that there is a default sentinel.

OK, I already have a patch that will mention the default sentinel in a
few more places, and I think it will fit that bill.  I will commit it
soon.

Thanks.

bug#22220: 24.5; no documentation for default process sentinel

[Ram Bhamidipaty]

:-) Thank you!
-Ram

-----Original Message-----
From: Eli Zaretskii [mailto:eliz@gnu.org] 
Sent: Wednesday, December 23, 2015 9:57 AM
To: Ram Bhamidipaty <rbhamidipaty@roku.com>
Cc: jwiegley@gmail.com; 22220@debbugs.gnu.org
Subject: Re: bug#22220: 24.5; no documentation for default process sentinel

> From: Ram Bhamidipaty <rbhamidipaty@roku.com>
> CC: "22220@debbugs.gnu.org" <22220@debbugs.gnu.org>
> Date: Wed, 23 Dec 2015 17:45:22 +0000
> 
> This is what I ran into: I am working on some code using the emacs process facility. And I started seeing messages (from the default sentinel) that I did not expect. When I _skimmed_ through the sentinel section I did not notice that a default sentinel is added to all processes. I acknowledge that skimming the docs was not the right thing to do - since I missed the fact that there is a default sentinel.

OK, I already have a patch that will mention the default sentinel in a
few more places, and I think it will fit that bill.  I will commit it
soon.

Thanks.

bug#22220: 24.5; no documentation for default process sentinel

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> OK, I already have a patch that will mention the default sentinel in a few
> more places, and I think it will fit that bill. I will commit it soon.

Thank you, Eli!

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#22220: 24.5; no documentation for default process sentinel

[Ram Bhamidipaty]

There is also a slight problem with the set-process-sentinel docs - there really isn't anything that says a process starts with a default sentinel - even if the set-process-sentinel function is not called.

The current docs set-process-sentinel docs just say what happens if the sentinel argument is nil. Careful reading certainly implies that the default sentinel will be given to a process - but surely this kind of information can be more explicit.

-Ram

-----Original Message-----
From: John Wiegley [mailto:jwiegley@gmail.com] 
Sent: Wednesday, December 23, 2015 9:34 AM
To: Eli Zaretskii <eliz@gnu.org>
Cc: Ram Bhamidipaty <rbhamidipaty@roku.com>; 22220@debbugs.gnu.org
Subject: Re: bug#22220: 24.5; no documentation for default process sentinel

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

>> It would be nice if the default process sentinel were explicitly documented
>> - at least the name and formal description.

> As for the name, why is that important? You can always get it installed for
> the process using nil as the argument to set-process-sentinel, and the
> implementation is in C, so how would the name help?

I must admit to a similar confusion. Aside from the fact that more could be
said: does more need to be said?

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#22220: 24.5; no documentation for default process sentinel

[Eli Zaretskii]

> From: Ram Bhamidipaty <rbhamidipaty@roku.com>
> CC: "22220@debbugs.gnu.org" <22220@debbugs.gnu.org>
> Date: Wed, 23 Dec 2015 17:54:12 +0000
> 
> There is also a slight problem with the set-process-sentinel docs - there really isn't anything that says a process starts with a default sentinel - even if the set-process-sentinel function is not called.

It's okay: the change I've just committed adds that as well.

> The current docs set-process-sentinel docs just say what happens if the sentinel argument is nil. Careful reading certainly implies that the default sentinel will be given to a process - but surely this kind of information can be more explicit.

It is now.