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

[Florian v. Savigny]

Dear Emacs maintainers,

since this pertains to documentation only, I have left out all the unnecessary 
debugging information. 

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:

-------------------------------------------------------------------------------------------
Third argument DESTINATION specifies how to handle program’s standard
and standard error output. Its general form is a two-element list 
(STDOUT STDERR), but there are shorthand notations for common uses (see below):

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.e. take (get-buffer-create "buffer") to mean '("buffer" t).
-------------------------------------------------------------------------------------------

Best regards,


Florian v. Savigny 
Siebenpfeiffer Str. 25 
66482 Zweibrücken 

0175 - 365 24 17