bug#30349: 27.0.50; Cuonfusing documentation about pipe processes

[Noam Postavsky]

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.

>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