bug#24287: Process filters received stderr output, not documented

[Eli Zaretskii <eliz@gnu.org>]

> From: Clément Pit--Claudel <clement.pit@gmail.com>
> Date: Tue, 23 Aug 2016 17:47:16 -0400
> 
> > That is described in the parent section:
> > 
> >      It is impossible to separate the standard output and standard error
> >   streams of the subprocess, because Emacs normally spawns the subprocess
> >   inside a pseudo-TTY, and a pseudo-TTY has only one output channel.  If
> >   you want to keep the output to those streams separate, you should
> >   redirect one of them to a file—for example, by using an appropriate
> >   shell command.
> 
> Hi Eli,
> 
> Am I misunderstanding something?  This section sounds misleading, at least for Emacs 25 (I'm not sure about Emacs 24).  The documentation of make-process (which is new in Emacs 25, right?) says:
> 
>      :stderr STDERR
>           Associate STDERR with the standard error of the process.
>           STDERR is either a buffer or a pipe process created with
>           ‘make-pipe-process’.
> 
> The docstring of start-process was updated accordingly:
> 
>     If you want to separate standard output from standard error, use
>     ‘make-process’ or invoke the command through a shell and redirect
>     one of them using the shell syntax.
> 
> Both of these suggest that the impossibility that the manual mention only applies to the pty case (the manual recommends against using PTYs for non-user-facing processes anyway).  What about something like this:
> 
>     It is impossible to separate the standard output and standard error streams
>     of a subprocess spawned inside a pseudo-TTY, as pseudo-TTYs have only one
>     output channel.  If you want to keep the output to those streams separate,
>     you should either use `make-process' with the :stderr argument, or redirect
>     one of the streams to a file—for example, by using
>     start-process-shell-command with an appropriate redirection.
> 
> Additionally, we could update the documentation of make-process: right now, it starts with "This function is like ‘start-process’, but takes keyword arguments.", but from what I understand it can actually do more than start-process. What about this:
> 
>      This function is like ‘start-process’, but takes keyword arguments, and can
>      separate output to standard output and standard error.

Actually, the situation was much worse than those minor changes could
handle.  The documentation of process-related APIs was not reviewed in
its entirety for quite some time, and as result bit-rotted quite a
lot.  I fixed that.

This is what happens and will continue to happen if people will not
volunteer to review documentation during the pretest, certainly when a
major version is about to be released.  For Emacs 25.1, only a single
individual volunteered, and a single *.texi file was reviewed.  I
expect the accuracy and the overall quality of our documentation to go
downhill if we don't see more volunteers.

> Btw, was there a way in Emacs 24 to separate these streams if the process was run after setting process-connection-type to nil? (I can't think of one).

No, I don't think so.