bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Philipp]

I've found a few confusing items about pipe processes in the
documentation:


C-h f make-pipe-process says:

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


The manual says about pipe processes:

@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the process in the
stopped state.

=> What does "the stopped state" mean?  How can a pipe be "stopped"?


This is not a big issue, it probably just needs a bit of editorial work.



In GNU Emacs 27.0.50 (build 38, x86_64-apple-darwin17.4.0, NS appkit-1561.20 Version 10.13.3 (Build 17D47))
 of 2018-02-04 built on p
Windowing system distributor 'Apple', version 10.3.1561
Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Configured using:
 'configure --with-modules --without-pop --with-mailutils
 --enable-gcc-warnings=yes --enable-checking
 --enable-check-lisp-object-type 'CFLAGS=-ggdb3 -O0''

Configured features:
NOTIFY ACL GNUTLS LIBXML2 ZLIB TOOLKIT_SCROLL_BARS NS MODULES THREADS
JSON

Important settings:
  value of $LANG: de_DE.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny seq byte-opt gv
bytecomp byte-compile cconv cl-loaddefs cl-lib dired dired-loaddefs
format-spec rfc822 mml easymenu mml-sec password-cache epa derived epg
epg-config gnus-util rmail rmail-loaddefs mm-decode mm-bodies mm-encode
mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils elec-pair time-date
tooltip eldoc electric uniquify ediff-hook vc-hooks lisp-float-type
mwheel term/ns-win ns-win ucs-normalize mule-util term/common-win
tool-bar dnd fontset image regexp-opt fringe tabulated-list replace
newcomment text-mode elisp-mode lisp-mode prog-mode register page
menu-bar rfn-eshadow isearch timer select scroll-bar mouse jit-lock
font-lock syntax facemenu font-core term/tty-colors frame cl-generic
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray minibuffer
cl-preloaded nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote kqueue cocoa ns
multi-tty make-network-process emacs)

Memory information:
((conses 16 204848 7483)
 (symbols 48 20086 1)
 (miscs 40 56 123)
 (strings 32 28888 1926)
 (string-bytes 1 771549)
 (vectors 16 35247)
 (vector-slots 8 721886 14316)
 (floats 8 52 64)
 (intervals 56 205 0)
 (buffers 992 11))

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Eli Zaretskii]

> From: Philipp <p.stephani2@gmail.com>
> Date: Sun, 04 Feb 2018 17:29:30 +0100
> 
> The manual says about pipe processes:
> 
> @item :stop @var{stopped}
> If @var{stopped} is non-@code{nil}, start the process in the
> stopped state.
> 
> => What does "the stopped state" mean?  How can a pipe be "stopped"?

See stop-process and continue-process.

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Noam Postavsky]

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

tags 30349 + patch
quit

Philipp <p.stephani2@gmail.com> writes:

> C-h f make-pipe-process says:
>
> ":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.

> The manual says about pipe processes:
>
> @item :stop @var{stopped}
> If @var{stopped} is non-@code{nil}, start the process in the
> stopped state.
>
> => What does "the stopped state" mean?  How can a pipe be "stopped"?

The docstring explains it fine, may as well copy that part to the manual
I guess.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 4404 bytes --]

From 902ded87cb2e8079259c34a323afa84b11f84e8b Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Mon, 5 Feb 2018 19:36:27 -0500
Subject: [PATCH v1] Doc fixes for process functions (Bug#30349)

* doc/lispref/processes.texi (Asynchronous Processes): Explain what
the 'stopped' state means for a pipe process.
* src/process.c (Fmake_process, Fmake_pipe_process)
(Fmake_serial_process, Fmake_network_process): Remove meaningless
phrase "specify an output stream" from docstring.
---
 doc/lispref/processes.texi |  6 ++++--
 src/process.c              | 26 ++++++++++++--------------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 8a8425cb84..4706a9daa0 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -728,8 +728,10 @@ Asynchronous Processes
 @xref{Query Before Exit}.
 
 @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}.
 
 @item :filter @var{filter}
 Initialize the process filter to @var{filter}.  If not specified, a
diff --git a/src/process.c b/src/process.c
index 8a438cfeb8..e688510a41 100644
--- a/src/process.c
+++ b/src/process.c
@@ -1617,10 +1617,9 @@ DEFUN ("make-process", Fmake_process, Smake_process, 0, MANY, 0,
 to make it unique.
 
 :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.
 
 :command COMMAND -- COMMAND is a list starting with the program file
 name, followed by strings to give to the program as arguments.
@@ -2309,9 +2308,9 @@ DEFUN ("make-pipe-process", Fmake_pipe_process, Smake_pipe_process,
 :name NAME -- NAME is the name of the process.  It is modified if necessary to make it unique.
 
 :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.  If BUFFER is not given, the value of NAME is used.
+with the process.  The default filter function writes process output
+at the end of that buffer.  If BUFFER is not given, the value of NAME
+is used.
 
 :coding CODING -- If CODING is a symbol, it specifies the coding
 system used for both reading and writing for this process.  If CODING
@@ -3024,9 +3023,9 @@ DEFUN ("make-serial-process", Fmake_serial_process, Smake_serial_process,
 the value of PORT is used.
 
 :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.  If BUFFER is not given, the value of NAME is used.
+with the process.  The default filter function writes process output
+at the end of that buffer.  If BUFFER is not given, the value of NAME
+is used.
 
 :coding CODING -- If CODING is a symbol, it specifies the coding
 system used for both reading and writing for this process.  If CODING
@@ -3687,10 +3686,9 @@ DEFUN ("make-network-process", Fmake_network_process, Smake_network_process,
 to make it unique.
 
 :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.
 
 :host HOST -- HOST is name of the host to connect to, or its IP
 address.  The symbol `local' specifies the local host.  If specified
-- 
2.11.0

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Mon, 05 Feb 2018 19:53:12 -0500
> Cc: 30349@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.

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Noam Postavsky]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Noam Postavsky <npostavs@users.sourceforge.net>
>> Date: Mon, 05 Feb 2018 19:53:12 -0500
>> Cc: 30349@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.  [...]

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Basil L. Contovounesios]

Noam Postavsky <npostavs@users.sourceforge.net> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: Noam Postavsky <npostavs@users.sourceforge.net>
>>> Date: Mon, 05 Feb 2018 19:53:12 -0500
>>> Cc: 30349@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.

No relation to '(elisp) Output Streams'?

-- 
Basil

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Noam Postavsky]

On Tue, Feb 6, 2018 at 11:31 AM, Basil L. Contovounesios
<contovob@tcd.ie> wrote:

>>>> > ":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.
>
> No relation to '(elisp) Output Streams'?

I don't see anything in the process code that would be able to take an
Elisp stream.

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Cc: p.stephani2@gmail.com,  30349@debbugs.gnu.org
> Date: Tue, 06 Feb 2018 07:10:43 -0500
> 
> >> 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.

Did you look at Git history of how that text was introduced?  Maybe
that will tell us something.  Or maybe the discussions/bug report
around the time this text was written/modified will give a hint.
(Sorry I'm not doing this research myself, but I'm terribly busy these
days, and won't have time for it for another couple of days.)

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

Yes.  And then the sentence about the default filter function.

Thanks.

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Noam Postavsky]

On Tue, Feb 6, 2018 at 1:55 PM, Eli Zaretskii <eliz@gnu.org> wrote:

>> > Could it be that the phrase originally meant shell-style redirection?
>>
>> Perhaps, but none of those functions support that, as far as I know.
>
> Did you look at Git history of how that text was introduced?  Maybe
> that will tell us something.  Or maybe the discussions/bug report
> around the time this text was written/modified will give a hint.

Huh. I had assumed it was new in make-process, but actually the phrase
seems to have come from start-process where it was present since the
beginning [1: d0d6b7c].
I see it's also in start-process-shell-command, where it could refer
to shell redirection, so maybe it was copied from there?
Although, IMO, even in start-process-shell-command it doesn't really
make much sense: if you use shell redirection you haven't stopped the
output from going into BUFFER, there just happens not to be any
output.

[1: d0d6b7c]: 1992-03-14 20:40:04 +0000
  Initial revision
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=d0d6b7c506eb0f93e80db38d6c2affe0a2b49b4c

> (Sorry I'm not doing this research myself, but I'm terribly busy these
> days, and won't have time for it for another couple of days.)

No problem.

>>     :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.  [...]
>
> Yes.  And then the sentence about the default filter function.

Hmm, I know I have a personal tendency for terseness, but that really
seems redundant to me:

    :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.  The default
    filter function writes process output at the end of that buffer. [...]

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Tue, 6 Feb 2018 19:05:54 -0500
> Cc: Philipp Stephani <p.stephani2@gmail.com>, 30349@debbugs.gnu.org
> 
> Hmm, I know I have a personal tendency for terseness, but that really
> seems redundant to me:
> 
>     :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.  The default
>     filter function writes process output at the end of that buffer. [...]

You are right, it is redundant.

bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Noam Postavsky]

tags 30349 fixed
close 30349 26.1
quit

Noam Postavsky <npostavs@users.sourceforge.net> writes:

> I see it's also in start-process-shell-command, where it could refer
> to shell redirection, so maybe it was copied from there?
> Although, IMO, even in start-process-shell-command it doesn't really
> make much sense: if you use shell redirection you haven't stopped the
> output from going into BUFFER, there just happens not to be any
> output.

I've removed the phrase from several other make/start-foo functions, I
left it in start-process-shell-command, since it could make sense there.

[1: 04c5bd5b1f]: 2018-02-07 20:17:50 -0500
  Doc fixes for process functions (Bug#30349)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=04c5bd5b1f1dc07994d70caa640a07da6b5a54b5