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