GNU bug report logs - #30349
27.0.50; Cuonfusing documentation about pipe processes

Previous Next

Full log

Message #16 received at 30349 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: p.stephani2 <at> gmail.com, 30349 <at> debbugs.gnu.org
Subject: Re: bug#30349: 27.0.50; Cuonfusing documentation about pipe processes
Date: Tue, 06 Feb 2018 05:54:43 +0200

> From: Noam Postavsky <npostavs <at> users.sourceforge.net>
> Date: Mon, 05 Feb 2018 19:53:12 -0500
> Cc: 30349 <at> debbugs.gnu.org
> 
> > ":buffer BUFFER -- BUFFER is the buffer (or buffer-name) to associate
> > with the process.  Process output goes at the end of that buffer,
> > unless you specify an output stream or filter function to handle the
> > output."
> >
> > => How do you specify an output stream?
> 
> I don't think there is such a thing.  That phrase seems to have been
> copied across all the make-*-process functions.

And is wrong in all of them?

Could it be that the phrase originally meant shell-style redirection?

>  @item :stop @var{stopped}
> -If @var{stopped} is non-@code{nil}, start the process in the
> -stopped state.
> +If @var{stopped} is non-@code{nil}, start the process in the stopped
> +state.  In the stopped state, a pipe process does not accept incoming
> +data, but you can send outgoing data.  The stopped state is cleared by
> +@code{continue-process} and set by @code{stop-process}.

In the last sentence, I'd swap the order of references to clearing and
setting the stopped state.  I'd also add a @pxref to where those two
functions are described.

>  :buffer BUFFER -- BUFFER is the buffer (or buffer-name) to associate
> -with the process.  Process output goes at end of that buffer, unless
> -you specify an output stream or filter function to handle the output.
> -BUFFER may be also nil, meaning that this process is not associated
> -with any buffer.
> +with the process.  The default filter function writes process output
> +at the end of that buffer.  BUFFER may be also nil, meaning that this
> +process is not associated with any buffer.

This goes too far in deleting stuff that is useful: the part of the
second sentence that follows "unless", which talks about specifying a
filter function, should be left alone.  Without it, "The default
filter function ..." surprises the reader, since it talks about the
default of something that wasn't mentioned before.

With those fixed, this is good for the release branch, thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.