[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#37906: 26.2; `call-process' docstring, section DESTINATION
From: |
Eli Zaretskii |
Subject: |
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@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.