GNU bug report logs - #37906
26.2; `call-process' docstring, section DESTINATION

Previous Next

Full log

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Florian v. Savigny" <f.savigny <at> mailbox.org>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.2; `call-process' docstring, section DESTINATION
Date: Thu, 24 Oct 2019 17:45:07 +0200 (CEST)

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.