From debbugs-submit-bounces@debbugs.gnu.org Thu Oct 24 12:59:09 2019 Received: (at submit) by debbugs.gnu.org; 24 Oct 2019 16:59:09 +0000 Received: from localhost ([127.0.0.1]:36867 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iNgS4-0006Uh-Pk for submit@debbugs.gnu.org; Thu, 24 Oct 2019 12:59:09 -0400 Received: from lists.gnu.org ([209.51.188.17]:56439) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iNfIg-0002SL-9j for submit@debbugs.gnu.org; Thu, 24 Oct 2019 11:45:22 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50214) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iNfIe-0000Uo-4C for bug-gnu-emacs@gnu.org; Thu, 24 Oct 2019 11:45:22 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,URIBL_BLOCKED autolearn=disabled version=3.3.2 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iNfIb-0002WY-Ou for bug-gnu-emacs@gnu.org; Thu, 24 Oct 2019 11:45:19 -0400 Received: from mx2a.mailbox.org ([2001:67c:2050:104:0:2:25:2]:26740) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1iNfIb-0002Ut-4n for bug-gnu-emacs@gnu.org; Thu, 24 Oct 2019 11:45:17 -0400 Received: from smtp2.mailbox.org (smtp2.mailbox.org [80.241.60.241]) (using TLSv1.2 with cipher ECDHE-RSA-CHACHA20-POLY1305 (256/256 bits)) (No client certificate requested) by mx2a.mailbox.org (Postfix) with ESMTPS id 0D0C6A1CA1 for ; Thu, 24 Oct 2019 17:45:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=mailbox.org; h= content-transfer-encoding:content-type:content-type:mime-version :subject:subject:message-id:from:from:date:date:received; s= mail20150812; t=1571931907; bh=37fZx9ENDz3WBRQ+7H8FdKvNNygxcxTMw 8bklSsAahU=; b=B54fuY5E3NwfVXi6td8ENCCiDZcWeXQrBoHWoM7+GBEBZULWT g4Yk8y7VvV6jBjP9L9vkIvGyJkzZ79GEVjNJ5rJRuG3fQTkcxxpNvIDdXBKxRZxf nI/WTrbaO27W9+9eW/8C8KSwzHPaxe7nDYxPTjhaPULzsvg3U4rqVa39l7vJCF63 BDxzAplfyuvWYnsy6CTtcl3+w6XGShgQAWBGipVIL7wXBhH3O//9wKCc7tbha3d/ mdF1SutBC1IonXcr8vxKLkl1JpvdanUxvyqP76BuOgVPtn4h0grEftXbetlsqSyW FCYKV9Kc+x2PqjQh48FcI1tGOIVij+sVkNLSw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailbox.org; s=mail20150812; t=1571931909; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=BN+meENbKlzP9EZFyhx71szmfsX8WRm48hCLtuzbFAI=; b=yld9v4XNymcQ/vrVxl0Tu8RWFy3S1k6xHY6jMB7U8ocR2+0iwslcIW36D0+MfmULoOnFXJ eGsb6LkeTPojLjuFgLlgky6RLpur1qYmmW2V4FzXDlTB3NqNnortSVJIvovTShQqn/AFHT CSWT08NQOxFm4hcP06HNst+/KQm4EHm15r0nCqnvJNMaCqxhDZB5zz4MSsK27WahrrQ+17 2yOiEJt0mlrFCquxlhb6ugqY0dOZOMHEM9CJO7+kUJCki2RINCrzVDYhNB0CM9LSGpsxsj e+DVP72cfmp3Dd5+hrSmGOKL0cLsn2Lm11x0Hp+2JSsDHAevRx+u+FYTBWKnjA== X-Virus-Scanned: amavisd-new at heinlein-support.de Received: from smtp2.mailbox.org ([80.241.60.241]) by gerste.heinlein-support.de (gerste.heinlein-support.de [91.198.250.173]) (amavisd-new, port 10030) with ESMTP id psTwAoxeWotL for ; Thu, 24 Oct 2019 17:45:07 +0200 (CEST) Date: Thu, 24 Oct 2019 17:45:07 +0200 (CEST) From: "Florian v. Savigny" To: bug-gnu-emacs@gnu.org Message-ID: <1640869770.32054.1571931907572@office.mailbox.org> Subject: 26.2; `call-process' docstring, section DESTINATION MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Priority: 3 Importance: Normal X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2001:67c:2050:104:0:2:25:2 X-Spam-Score: -0.3 (/) X-Debbugs-Envelope-To: submit X-Mailman-Approved-At: Thu, 24 Oct 2019 12:59:07 -0400 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) Dear Emacs maintainers, since this pertains to documentation only, I have left out all the unnecess= ary debugging information.=20 The docstring of `call-process', which is extremely confusing (and partly w= rong) as regards the DESTINATION argument, seems to have been in its presen= t form for what must have been at least 15 years. Although the relevant sec= tion in the Emacs Lisp Info does a much better job (even though I still fin= d the choice of "REAL-" for standard out puzzling), I would strongly sugges= t that the docstring be rewritten, too. (That would probably have considera= bly sped up my understanding of Elisp in particular and *nix systems in gen= eral.) Apart from the confusion, the docstring specifically does not acknowledge t= hat e.g. (nil nil) as the DESTINATION (which might be a style somebody choo= ses to be more explicit about the the use of stdout and stderr) is perfectl= y acceptable, and also e.g. (nil "file"). Even '(0 "file") will be accepted= and work as expected.=20 The following would be my suggestion as to how the relevant section could b= e rephrased: ---------------------------------------------------------------------------= ---------------- Third argument DESTINATION specifies how to handle program=E2=80=99s standa= rd and standard error output. Its general form is a two-element list=20 (STDOUT STDERR), but there are shorthand notations for common uses (see bel= ow): STDOUT can be: - 0: discard it and return immediately, i.e. do not even wait for the progr= am 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 bef= ore 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_nam= e". 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 li= st.=20 I.e. take (get-buffer-create "buffer") to mean '("buffer" t). ---------------------------------------------------------------------------= ---------------- Best regards, Florian v. Savigny=20 Siebenpfeiffer Str. 25=20 66482 Zweibr=C3=BCcken=20 0175 - 365 24 17 From debbugs-submit-bounces@debbugs.gnu.org Fri Oct 25 04:53:35 2019 Received: (at 37906) by debbugs.gnu.org; 25 Oct 2019 08:53:35 +0000 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 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 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 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 Date: Fri, 25 Oct 2019 11:53:12 +0300 Message-Id: <83pnilw6iv.fsf@gnu.org> From: Eli Zaretskii To: "Florian v. Savigny" In-reply-to: <1640869770.32054.1571931907572@office.mailbox.org> (f.savigny@mailbox.org) Subject: Re: bug#37906: 26.2; `call-process' docstring, section DESTINATION References: <1640869770.32054.1571931907572@office.mailbox.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37906 Cc: 37906@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > 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. From debbugs-submit-bounces@debbugs.gnu.org Mon Oct 28 11:48:22 2019 Received: (at control) by debbugs.gnu.org; 28 Oct 2019 15:48:22 +0000 Received: from localhost ([127.0.0.1]:46237 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iP7Fm-0002fa-60 for submit@debbugs.gnu.org; Mon, 28 Oct 2019 11:48:22 -0400 Received: from quimby.gnus.org ([80.91.231.51]:42310) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iP7Fk-0002fR-02 for control@debbugs.gnu.org; Mon, 28 Oct 2019 11:48:20 -0400 Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=marnie) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iP7Fh-0000my-8r for control@debbugs.gnu.org; Mon, 28 Oct 2019 16:48:19 +0100 Date: Mon, 28 Oct 2019 16:48:16 +0100 Message-Id: <87sgnc98hr.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #37906 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: tags 37906 + moreinfo quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) tags 37906 + moreinfo quit From debbugs-submit-bounces@debbugs.gnu.org Wed Oct 30 11:58:50 2019 Received: (at 37906) by debbugs.gnu.org; 30 Oct 2019 15:58:50 +0000 Received: from localhost ([127.0.0.1]:51292 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iPqMz-0000Lm-HK for submit@debbugs.gnu.org; Wed, 30 Oct 2019 11:58:50 -0400 Received: from mout-u-107.mailbox.org ([91.198.250.252]:50428) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iPq6x-0006La-Bz for 37906@debbugs.gnu.org; Wed, 30 Oct 2019 11:42:17 -0400 Received: from smtp1.mailbox.org (smtp1.mailbox.org [80.241.60.240]) (using TLSv1.2 with cipher ECDHE-RSA-CHACHA20-POLY1305 (256/256 bits)) (No client certificate requested) by mout-u-107.mailbox.org (Postfix) with ESMTPS id 473CPX6lK0zKnGb; Wed, 30 Oct 2019 16:42:08 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=mailbox.org; h= content-transfer-encoding:content-type:content-type:mime-version :subject:subject:references:in-reply-to:message-id:from:from :date:date:received; s=mail20150812; t=1572450125; bh=VfdqemyTZa mVQuVzCkEeKsillRmw1zImRrJgJ9V1e+4=; b=T64R2fk7fScfmHPJ42Fqgpd5A1 fo588KeF7jmBL+pq1v8KcGxhXFFGLluXPa+OnFysBg1WpqDOy+EvHU5HrlPvoKxw zUT7fRzEoFHGalzPqrPtvJgcrO1zvQBk+fwXOm0dJn5plEyZ/gnFb9e/le8LUNrz 99YY3z4G1XJ79SVud5Q02768r7HrThKz7mssm+R4x82R+/JJsioVNSVdyDaImoJY XIlDgjM7DyREcNuNGuhcAw4ud0lj0GsJE8JUoPRIjPGaduyjmT+f+oB6wmAxKovU ost8P6sLIURlUX/57pRytrhtKgVSnCWXZxUeuCOAMXQ1N1Qu/OFJW4yNJ49g== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailbox.org; s=mail20150812; t=1572450127; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZxvOKrKV+R758tckeVDCP7KnlK3dtx4zdqZ0Ug0JAs0=; b=qUDIBnO8zErqB/HbW+t7E2Bn+GMxJKJBB32rvhSk3OhwPuNP7ioA2V4Skx9SqXDlEVmLcU /TM+loXI8lq70FLs/of+2yqTqupU6339+gjAWsFbIJWkZ36/r5f755LsGMr3beAS90sX3U atlxy0+65c6d+iOa+6yJAC8ablwt7if8N2J6GpMzgSplek7Iwvj1Q6Oxrr4jo4JmSZiwXt t/DzunoibwOI7yFARYg9m223NgphdlZJqv+rbwaw9QHUIizOT+ZXJ0WhARU4Ei9VTLwKys TtiZC7KiQeEIw6nx/LYGqIpQueSGeAqm5VmQk5rcRaz/hV75c6COfoKKzi3rtQ== X-Virus-Scanned: amavisd-new at heinlein-support.de Received: from smtp1.mailbox.org ([80.241.60.240]) by hefe.heinlein-support.de (hefe.heinlein-support.de [91.198.250.172]) (amavisd-new, port 10030) with ESMTP id 0FkiZCq4PIKa; Wed, 30 Oct 2019 16:42:05 +0100 (CET) Date: Wed, 30 Oct 2019 16:42:03 +0100 (CET) From: "Florian v. Savigny" To: Eli Zaretskii Message-ID: <1888117473.80356.1572450123334@office.mailbox.org> In-Reply-To: <83pnilw6iv.fsf@gnu.org> References: <1640869770.32054.1571931907572@office.mailbox.org> <83pnilw6iv.fsf@gnu.org> Subject: Re: bug#37906: 26.2; `call-process' docstring, section DESTINATION MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Priority: 3 Importance: Normal X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 37906 X-Mailman-Approved-At: Wed, 30 Oct 2019 11:58:46 -0400 Cc: 37906@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Dear Eli, I am pasting here my reply to your reply from last Friday. I realised I had= replied only to your personal E-mail address, which is probably not the ap= propriate thing to do -- I would like to apologise for that! The reply I am pasting is quite lengthy, a fact for which I would like to a= pologise, but which also underlines and illustrates that I *truly* found th= e docstring confusing. In the mean time since, however, I have realised that (I think) I CAN now n= ail down the root cause for our disparate perceptions (you finding the docs= tring clear, me finding it very confusing): Once you approach `call-process' with a different idea of what the "usual c= ase" is, as you have put it, the docstring becomes much harder to interpret= . The (actually firm) idea that I had in mind when I did "C-h f call-proces= s" was that normally, a function would keep the two output streams separate= and treat them equally, and that led to a slew of misunderstandings. (One = of the misunderstandings being that for a long time, I thought that just sp= ecifing a single value, or scalar or however it is called in Lisp, meant th= at STDERR would be discarded.) I do not want to argue what the "true" usual case is or might be. But I do = want to argue that if such an assumption is made, it should be made explici= tly (e.g. by saying, "... by default, stdout and stderr are mixed together = like on the terminal ... To handle them separately, do XY ...", or the like= ) because not doing so is tantamount to a firm assumption what the user ass= umes (and perhaps how she wants to use `call-process'), and excludes those = users for whom this assumption is wrong. Once you KNOW how the function works, it is easy to interpret the docstring= correctly. But it should be the other way round: Once you have read the do= cstring once (without having resorted to the Elisp manual), it is easy to u= se the function correctly. At least that should, as I understand it, be the= goal. As I have specified below, I think I have now found a new solution w= hich should be understandable to more people with different expectations th= an the current official one (and is even shorter), and is unambiguous. (Or = at least I hope so.) Best regards, Florian My reply from Sunday follows here: ... I hope I can be forgiven for having assumed that my suggested alternative description would speak for itself and make glaringly obvious what's (in my opinion) amiss with the docstring. I had worked through the docstring and tested the function's behaviour for something like six hours before being really confident how it behaves. And I remembered how I had read this docstring before, about 15 years ago, more or less as a complete newbie, and thought something like, "if only I had understood this back then". In other words, having to explain what I find hard to understand was about the last thing I expected, and at first, I had no idea of how to do this in writing. The only idea I was finally able to come up with is to go through the docstring step by step. I apologise this will be somewhat lengthy, but then the interface is not exactly trivial. In fact, the root (and perhaps the bigger part) of the confusion seems to me the inconsistent interface, which for most things runs counter to the everyday expectation of consistency. Nil is about the only thing tha= t has a consistent meaning; it always means "discard". But otherwise: - t means "current buffer" for stdout, but "mix with stdout" for stderr - a string means a buffer name for stdout, but a file name for stderr - as a corollary, :file is used for stdout, but not for a stderr file - only stdout has 0, such that (0 "file") is possible, but ((:file "file) 0) is not. Obviously nothing much can be done about this interface. But because of that, the documentation has to make up for that, and be extra clear and explicit. I have broken up the docstring into mouthfuls of information, and have added enumeration and itemisation to that end. I have added a comment after each mouthful as I chew on it. || like this: On working through this again, I realised (again by testing) that my understanding of the "buffer"/"buffer name" issue was still not correct. It's actually much simpler than I thought, and I have been able to come up with a new suggestion which is surprisingly short, satisfies my sense of clarity, and keeps the order you prefer. (See the end of the mail.) My first suggestion was also partly wrong. --------------------------- begin ordeal ------------------------------- Third argument DESTINATION specifies how to handle program=E2=80=99s output= . 1. If DESTINATION is a buffer, or t that stands for the current buffer, it means insert output in that buffer before point. || - ... or a buffer /name/ || (That new buffers are created even if there is not output is || also something that a newbie won't suspect. In other words, that || (s)he may have to clean up afterwards.) || || - It says only "output". Does it mean "standard output", or || "standard output mixed with standard error", in other words, "all || output, mixed"?=20 2. If DESTINATION is nil, it means discard output; 0 means discard and don=E2=80=99t wait for the program to terminate. || - It should be "all output", if you don't use the two-argument list. || || - The oddly dropped-in feature of making call-process asynchronous || via this argument certainly does not help clarity, but that is || nothing that the docstring can change. It's a bit like turning || the hindmost knob (but only that one) on your electric stove to || 1/2 (but only to that position) also turns on the central heating || for the appartment. (I know, I'm exaggerating, but still.) || || But what the docstring could say is: What happens to the || exit status if we don't wait for the program to terminate? =20 3. If DESTINATION is =E2=80=98(:file FILE)=E2=80=99, where FILE is a file n= ame string, it means that output should be written to that file (if the file already exists it is overwritten). || - Again, "all output" or "standard output"? (If used alone.) 4. DESTINATION can also have the form (REAL-BUFFER STDERR-FILE); in that case, || Why these odd placeholders, especially REAL-BUFFER? ||=20 || - stdout is REAL, why? As opposed to stderr being unreal, or || virtual??? And it can also be, as discussed above, a buffer name, || or t, or nil, or a file name, not only a BUFFER. || || - STDERR-FILE can not only be a FILE, but also t or nil. (nil is || not confusing, but t can mean stderr goes to a buffer rather than || a file.) =20 a) REAL-BUFFER says what to do with standard output, as above, while || "As above" is correct if, in what I have numbered 1. to 3., it says || "standard output", which would however be incorrect again when 1 to 3 ar= e || used alone. (I guess this is why the docstring tries to get away by sayi= ng "output" || above. But this is definitely too imprecise for "single use".) b) STDERR-FILE says what to do with standard error in the child. STDERR-FILE may be =20 - nil (discard standard error output), - t (mix it with ordinary output), or - a file name string. || The file is also overwritten, like in the case of stdout. -------------------------- end ordeal -------------------------------- So, my new suggestion would be: ---------------------------------------------------------------------- If DESTINATION is a single item, lump the program's standard output and standard error together: If it is a buffer or buffer name (or t for current buffer), insert all output in that buffer before point. If it is nil or 0, discard all output; with 0 also don=E2=80=99t wait for the program to terminate. If it is =E2=80=98(:file FILENAME)=E2=80=99 write all= output to that file (overwrite it if it already exists). If DESTINATION is a two-element list (STDOUT STDERR), keep the output streams separate. STDOUT can take the same values as detailed above (which then apply only to stdout, however). STDERR, in contrast, may only be nil (discard it), t (mix it with stdout), or the name of a file to write it to (which also gets overwritten.) ---------------------------------------------------------------------- t for STDERR is, as I just realised, completely redundant, because it specifies precisely what happens when DESTINATION is a single item. Perhaps it would be better to leave this out, if nobody needs it? I dearly hope that at the very least, my own understanding of the DESTINATION argument is completely correct now. Best regards, and thank you for bearing with me. Florian > Eli Zaretskii hat am 25. Oktober 2019 um 10:53 geschrieben= : >=20 >=20 > > Date: Thu, 24 Oct 2019 17:45:07 +0200 (CEST) > > From: "Florian v. Savigny" > >=20 > > The docstring of `call-process', which is extremely confusing (and part= ly wrong) as regards the DESTINATION argument, seems to have been in its pr= esent 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 su= ggest that the docstring be rewritten, too. (That would probably have consi= derably sped up my understanding of Elisp in particular and *nix systems in= general.) > >=20 > > Apart from the confusion, the docstring specifically does not acknowled= ge 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 perf= ectly acceptable, and also e.g. (nil "file"). Even '(0 "file") will be acce= pted and work as expected.=20 > >=20 > > The following would be my suggestion as to how the relevant section cou= ld be rephrased: >=20 > Thank you for your report. >=20 > 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. >=20 > E.g., the (nil nil) and (nil "file") forms are described as follows: >=20 > DESTINATION can also have the form (REAL-BUFFER STDERR-FILE); in that c= ase, > 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. >=20 > The "as above" part on the second line means that REAL-BUFFER can be > any of the values mentioned above, which includes nil. >=20 > > STDOUT can be: > > - 0: discard it and return immediately, i.e. do not even wait for the p= rogram 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 out= put). > > - 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. > >=20 > > 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 ex= ists, > > otherwise creating it. > >=20 > > 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). > >=20 > > 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.=20 >=20 > 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". >=20 > 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. Florian v. Savigny Siebenpfeiffer Str. 25 66482 Zweibr=C3=BCcken 0175 - 365 24 17 From debbugs-submit-bounces@debbugs.gnu.org Wed Aug 12 21:33:59 2020 Received: (at control) by debbugs.gnu.org; 13 Aug 2020 01:33:59 +0000 Received: from localhost ([127.0.0.1]:46280 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k627z-000730-B3 for submit@debbugs.gnu.org; Wed, 12 Aug 2020 21:33:59 -0400 Received: from mail-yb1-f175.google.com ([209.85.219.175]:37446) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k627y-00072a-L0 for control@debbugs.gnu.org; Wed, 12 Aug 2020 21:33:58 -0400 Received: by mail-yb1-f175.google.com with SMTP id e14so2433980ybf.4 for ; Wed, 12 Aug 2020 18:33:58 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:in-reply-to:references:user-agent :mime-version:date:message-id:subject:to; bh=ZMD3GUPiySMVfRS3c5z5tN9Qoy5u8ClieeX5bxfCBIM=; b=ZT0oF0ozPN6PweUvGxqyz3hVdX+J+wh8GN2oRqJmT741nsZzmjiVscVpkD8EC6EXGT IvF0U/FssT0z5x5WIokTpJlpyfoj5DuDRna20xWpa+Uht0llRHSfgaA4EO4LB0b0uVla sYq1+gPUWSZ/UV22jL+9QZklMfThACMw3l9HyU2d0UxirCag79HrVGSJ1Vu4gFEQtJ80 iLQlwyUIPsBrmSJmwmMy7nv3xoQDylCo4HlE3xcf/IyiwIblkS7nIY0jCUfdcue/3o99 bhLGgQEkVhK7mtTGLaiLVNbcRVFYHxg981KAtabUBegD110RXOJRcjq7iyDO7kR99OKr 591Q== X-Gm-Message-State: AOAM531BP66pPySooYqxnQMiVXiW/kXbRElWGIA0wMdOQluzubyOiKJW PZ4RTSJlRFqPWUQCh7xGGAsqyyLB8isuJ79Q2CCJRJCvieM= X-Google-Smtp-Source: ABdhPJz25wOcNYB5uOqiTTQrVyXwlrzs9QYwzkbb/jS0RYkFJAEkTH00IsAODE3lWE7+iTwCk3luXaBnSA6vjhGBnvU= X-Received: by 2002:a25:9843:: with SMTP id k3mr3285479ybo.466.1597282433158; Wed, 12 Aug 2020 18:33:53 -0700 (PDT) Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Wed, 12 Aug 2020 18:33:52 -0700 From: Stefan Kangas In-Reply-To: <87sgnc98hr.fsf@gnus.org> (Lars Ingebrigtsen's message of "Mon, 28 Oct 2019 16:48:16 +0100") References: <87sgnc98hr.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Date: Wed, 12 Aug 2020 18:33:52 -0700 Message-ID: Subject: Re: control message for bug #37906 To: control Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) tags 37906 - moreinfo thanks From debbugs-submit-bounces@debbugs.gnu.org Mon Aug 30 22:15:19 2021 Received: (at 37906) by debbugs.gnu.org; 31 Aug 2021 02:15:19 +0000 Received: from localhost ([127.0.0.1]:60745 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mKtIw-0003df-LX for submit@debbugs.gnu.org; Mon, 30 Aug 2021 22:15:19 -0400 Received: from quimby.gnus.org ([95.216.78.240]:41642) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mKtIq-0003Qf-HV for 37906@debbugs.gnu.org; Mon, 30 Aug 2021 22:15:12 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=DjrxyYU1skEDMplmnv5FukF2iy8bwIkH6KcpYpYZQvI=; b=FS4ClOuC25IF/y42zT6ENyKim0 Xwt03yTa1HF8teMmrXEuDEkKB8v+nU9nj0r/suH8RizDfzizVn2vG57c3z60qY0gTidtdWRhY1vn9 B4XbOJJ8vlbA0eVwOvzAsPF9Cbh9q/cFDMNGnlfOSXJAXLdj3V1E8Js3u+4N3Y6/Szkw=; Received: from [84.212.220.105] (helo=elva) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mKtIf-0005gX-MW; Tue, 31 Aug 2021 04:15:01 +0200 From: Lars Ingebrigtsen To: "Florian v. Savigny" Subject: Re: bug#37906: 26.2; `call-process' docstring, section DESTINATION References: <1640869770.32054.1571931907572@office.mailbox.org> <83pnilw6iv.fsf@gnu.org> <1888117473.80356.1572450123334@office.mailbox.org> Date: Tue, 31 Aug 2021 04:14:57 +0200 In-Reply-To: <1888117473.80356.1572450123334@office.mailbox.org> (Florian v. Savigny's message of "Wed, 30 Oct 2019 16:42:03 +0100 (CET)") Message-ID: <87a6ky5pi6.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: "Florian v. Savigny" writes: > I do not want to argue what the "true" usual case is or might be. But > I do want to argue that if such an assumption is made, it should be > made explicitly (e.g. by saying, "... by default, stdout [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37906 Cc: Eli Zaretskii , 37906@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) "Florian v. Savigny" writes: > I do not want to argue what the "true" usual case is or might be. But > I do want to argue that if such an assumption is made, it should be > made explicitly (e.g. by saying, "... by default, stdout and stderr > are mixed together like on the terminal ... I've now amended the doc string of call-process in Emacs 28 to explicitly say that we mean both stdout and stderr when we talk about "output". -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Mon Aug 30 22:15:19 2021 Received: (at control) by debbugs.gnu.org; 31 Aug 2021 02:15:19 +0000 Received: from localhost ([127.0.0.1]:60747 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mKtJ1-0003iq-1P for submit@debbugs.gnu.org; Mon, 30 Aug 2021 22:15:19 -0400 Received: from quimby.gnus.org ([95.216.78.240]:41658) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mKtIu-0003VZ-PA for control@debbugs.gnu.org; Mon, 30 Aug 2021 22:15:16 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Subject:From:To:Message-Id:Date:Sender:Reply-To:Cc: MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=PfOok+CBx+h4fd9EOCYpS/Bdg6o6g8P4JjJ0VCIFwT4=; b=o1+t2NUZsoT3/MSHKhoSm7GseN SLDFZkqXuAPYztiOlv0Boc/z3gjyCkdwHyxJb9US0LGbYBAGLnM8VfFc9JV27jFXrR2eGKi0TN/0Q qv55FtPP8xkCVab1A84kgi5L2AicgZWC1LpW+dmj4duPrn9F4iQjPb8aIvwnOkRmqXXs=; Received: from [84.212.220.105] (helo=elva) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mKtIl-0005kx-SQ for control@debbugs.gnu.org; Tue, 31 Aug 2021 04:15:07 +0200 Date: Tue, 31 Aug 2021 04:15:03 +0200 Message-Id: <878s0i5pi0.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #37906 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: close 37906 28.1 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) close 37906 28.1 quit From unknown Mon Aug 18 17:58:00 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 28 Sep 2021 11:24:05 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator