master 1529643: Add a bit more clarification around standard error processes.

[Philipp Stephani]

branch: master
commit 152964362f905ba4f6d60d8c082330b739b8bc8e
Author: Philipp Stephani <phst@google.com>
Commit: Philipp Stephani <phst@google.com>

    Add a bit more clarification around standard error processes.
    
    * doc/lispref/processes.texi (Asynchronous Processes): Document
    how to obtain the standard error process that Emacs creates.
    (Accepting Output): Add an example how to wait for standard error in
    case Emacs has created a standard error process.
---
 doc/lispref/processes.texi | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 535cebe..6dedaa3 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -729,7 +729,9 @@ coding systems (@pxref{Default Coding Systems}).  On the 
other hand,
 it will use @var{query-flag} as its query-on-exit flag (@pxref{Query
 Before Exit}).  It will be associated with the @var{stderr} buffer
 (@pxref{Process Buffers}) and send its output (which is the standard
-error of the main process) there.
+error of the main process) there.  To get the process object for the
+standard error process, pass the @var{stderr} buffer to
+@code{get-buffer-process}.
 
 If @var{stderr} is a pipe process, Emacs will use it as standard error
 process for the new process.
@@ -1942,6 +1944,29 @@ code:
 (while (accept-process-output stderr-process))
 @end example
 
+If you passed a buffer to the @var{stderr} argument of
+@code{make-process}, you still have to wait for the standard error
+process, like so:
+
+@example
+(let* ((stdout (generate-new-buffer "stdout"))
+       (stderr (generate-new-buffer "stderr"))
+       (process (make-process :name "test"
+                              :command '("my-program")
+                              :buffer stdout
+                              :stderr stderr))
+       (stderr-process (get-buffer-process stderr)))
+  (unless (and process stderr-process)
+    (error "Process unexpectedly nil"))
+  (while (accept-process-output process))
+  (while (accept-process-output stderr-process)))
+@end example
+
+@noindent
+Only when both @code{accept-process-output} forms return @code{nil},
+you can be sure that the process has exited and Emacs has read all its
+output.
+
 Reading pending standard error from a process running on a remote host
 is not possible this way.