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

Previous Next

Full log

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

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Eli Zaretskii <eliz <at> gnu.org>
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 07:10:43 -0500

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

>> 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?

I think so.

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

Perhaps, but none of those functions support that, as far as I know.

>>  @item :stop @var{stopped}
>> +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.

Ok.

> 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.

Not entirely sure I follow, did you actually mean the part that
*precedes* "unless" should be left alone?  As in:

    :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 a filter function to handle the output.  [...]

Otherwise, mentioning both "the default filter function" and "unless you
specify a filter function" feels redundant to me:

    :buffer BUFFER -- BUFFER is the buffer (or buffer-name) to associate
    with the process.  The default filter function writes process output at
    the end of that buffer, unless you specify a filter function to handle
    the output.  [...]

Previous Next

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