bug#37906: 26.2; `call-process' docstring, section DESTINATION

[Eli Zaretskii]

> Date: Thu, 24 Oct 2019 17:45:07 +0200 (CEST)
> From: "Florian v. Savigny" <f.savigny@mailbox.org>
> 
> The docstring of `call-process', which is extremely confusing (and partly 
> wrong) as regards the DESTINATION argument, seems to have been in its present 
> form for what must have been at least 15 years. Although the relevant section 
> in the Emacs Lisp Info does a much better job (even though I still find the 
> choice of "REAL-" for standard out puzzling), I would strongly suggest that 
> the docstring be rewritten, too. (That would probably have considerably sped 
> up my understanding of Elisp in particular and *nix systems in general.)
> 
> Apart from the confusion, the docstring specifically does not acknowledge 
> that e.g. (nil nil) as the DESTINATION (which might be a style somebody 
> chooses to be more explicit about the the use of stdout and stderr) is 
> perfectly acceptable, and also e.g. (nil "file"). Even '(0 "file") will be 
> accepted and work as expected. 
> 
> The following would be my suggestion as to how the relevant section could be 
> rephrased:

Thank you for your report.

Could you please elaborate on what are the confusing parts of the
current doc string?  I've re-read it now, and I think it is clear and
describes all the possible options.

E.g., the (nil nil) and (nil "file") forms are described as follows:

  DESTINATION can also have the form (REAL-BUFFER STDERR-FILE); in that case,
   REAL-BUFFER says what to do with standard output, as above,
   while STDERR-FILE says what to do with standard error in the child.
   STDERR-FILE may be nil (discard standard error output),
   t (mix it with ordinary output), or a file name string.

The "as above" part on the second line means that REAL-BUFFER can be
any of the values mentioned above, which includes nil.

> STDOUT can be:
> - 0: discard it and return immediately, i.e. do not even wait for the program 
> to terminate
> - nil: discard it.
> - t: insert it into the current buffer before point.
> - a buffer name (i.e. a string): insert it into the buffer of that name 
> before point.
>   If that buffer does not exist yet, create it (even if there is no output).
> - a list (:file "some_file_name"): Write it to a file called "some_file_name".
>   If the "some_file_name" exists, overwrite it, otherwise, create it.
> 
> STDERR can be:
> - nil: discard it.
> - t: direct it where stdout goes (mix it with stdout).
> - a file name: Write it to a file of that name, overwriting it if it exists,
>   otherwise creating it.
> 
> As shorthand for the list (STDOUT nil), i. e. when the user wants to
> discard STDERR, also accept STDOUT without a list, as detailed above.
> I.e. take e.g. '(:file "some_file_name") as '((:file "some_file_name") nil).
> 
> Finally, as shorthand for '("buffer" t) (i.e. insert stdout in "buffer"
> and stderr, too), accept also the buffer of the name "buffer", without a 
> list. 

I'm not sure this is an improvement.  For starters, it is longer.
More importantly, it reverses the usual case and the rare case: most
uses of call-process use what you call "shorthand", so this order
change causes the reader to have to read more, and then requires
him/her to understand what you mean by "shorthand".

So I suggest to start by describing the confusing parts.  Perhaps we
can then arrive at text that will be clearer, but without the adverse
effects mentioned above.