From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#37906: 26.2; `call-process' docstring, section DESTINATION Date: Fri, 25 Oct 2019 11:53:12 +0300 Message-ID: <83pnilw6iv.fsf@gnu.org> References: <1640869770.32054.1571931907572@office.mailbox.org> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="110842"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 37906@debbugs.gnu.org To: "Florian v. Savigny" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Oct 25 11:06:31 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iNvYF-000SaR-6I for geb-bug-gnu-emacs@m.gmane.org; Fri, 25 Oct 2019 11:06:31 +0200 Original-Received: from localhost ([::1]:57894 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iNvYD-0002aN-6s for geb-bug-gnu-emacs@m.gmane.org; Fri, 25 Oct 2019 05:06:29 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:53542) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iNvMB-00007v-VV for bug-gnu-emacs@gnu.org; Fri, 25 Oct 2019 04:54:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iNvMA-0007NZ-N4 for bug-gnu-emacs@gnu.org; Fri, 25 Oct 2019 04:54:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:56681) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iNvMA-0007NT-K2 for bug-gnu-emacs@gnu.org; Fri, 25 Oct 2019 04:54:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iNvMA-0000EZ-H4 for bug-gnu-emacs@gnu.org; Fri, 25 Oct 2019 04:54:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 25 Oct 2019 08:54:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 37906 X-GNU-PR-Package: emacs Original-Received: via spool by 37906-submit@debbugs.gnu.org id=B37906.1571993615860 (code B ref 37906); Fri, 25 Oct 2019 08:54:02 +0000 Original-Received: (at 37906) by debbugs.gnu.org; 25 Oct 2019 08:53:35 +0000 Original-Received: from localhost ([127.0.0.1]:37269 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iNvLj-0000Dn-0p for submit@debbugs.gnu.org; Fri, 25 Oct 2019 04:53:35 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:44394) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iNvLg-0000DZ-Ke for 37906@debbugs.gnu.org; Fri, 25 Oct 2019 04:53:33 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:34412) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iNvLa-0006xA-Lk; Fri, 25 Oct 2019 04:53:26 -0400 Original-Received: from [176.228.60.248] (port=1970 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iNvLa-0006qS-5S; Fri, 25 Oct 2019 04:53:26 -0400 In-reply-to: <1640869770.32054.1571931907572@office.mailbox.org> (f.savigny@mailbox.org) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:170152 Archived-At: > Date: Thu, 24 Oct 2019 17:45:07 +0200 (CEST) > From: "Florian v. Savigny" > > 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.