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

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Florian v. Savigny" <f.savigny <at> mailbox.org>
Cc: 37906 <at> debbugs.gnu.org
Subject: Re: bug#37906: 26.2; `call-process' docstring, section DESTINATION
Date: Fri, 25 Oct 2019 11:53:12 +0300

> Date: Thu, 24 Oct 2019 17:45:07 +0200 (CEST)
> From: "Florian v. Savigny" <f.savigny <at> 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.

Previous Next

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