From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#52334: 26.3; Doc string of `process-file' Date: Mon, 6 Dec 2021 18:57:52 +0000 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27689"; mail-complaints-to="usenet@ciao.gmane.io" To: 52334@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Dec 06 20:01:00 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1muJES-00072t-Fh for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 06 Dec 2021 20:01:00 +0100 Original-Received: from localhost ([::1]:52954 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1muJER-0001wx-Dv for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 06 Dec 2021 14:00:59 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:41506) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1muJCY-0000Yz-Ui for bug-gnu-emacs@gnu.org; Mon, 06 Dec 2021 13:59:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52101) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1muJCX-0005xu-SU for bug-gnu-emacs@gnu.org; Mon, 06 Dec 2021 13:59:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1muJCX-0003dn-OS for bug-gnu-emacs@gnu.org; Mon, 06 Dec 2021 13:59:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 06 Dec 2021 18:59:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 52334 X-GNU-PR-Package: emacs X-Debbugs-Original-To: "bug-gnu-emacs@gnu.org" Original-Received: via spool by submit@debbugs.gnu.org id=B.163881708713919 (code B ref -1); Mon, 06 Dec 2021 18:59:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 6 Dec 2021 18:58:07 +0000 Original-Received: from localhost ([127.0.0.1]:35414 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1muJBf-0003cR-6L for submit@debbugs.gnu.org; Mon, 06 Dec 2021 13:58:07 -0500 Original-Received: from lists.gnu.org ([209.51.188.17]:52216) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1muJBd-0003cK-R0 for submit@debbugs.gnu.org; Mon, 06 Dec 2021 13:58:06 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:41426) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1muJBd-00007S-ER for bug-gnu-emacs@gnu.org; Mon, 06 Dec 2021 13:58:05 -0500 Original-Received: from mx0a-00069f02.pphosted.com ([205.220.165.32]:60324) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1muJBa-0005ZQ-Gm for bug-gnu-emacs@gnu.org; Mon, 06 Dec 2021 13:58:04 -0500 Original-Received: from pps.filterd (m0246629.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.16.1.2/8.16.1.2) with SMTP id 1B6GnaRB019187 for ; Mon, 6 Dec 2021 18:57:57 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : subject : date : message-id : content-type : content-transfer-encoding : mime-version; s=corp-2021-07-09; bh=It38P92jgqTbLPGgygvpToi7XAW0sSf7s8LD72pSgHs=; b=H9kY3caD16hOFfKtLR1ADMhB2Eb5rNgKjGL7j6mDjklhgqKQ9/qm9/CyZHAOD1Jcol9h vTwnMzvro0VOZ7UOlwOOzlYxbIQO2aNSwE/NVdGohVCZKO74dLsq2SEkZCELVx4hIVlT 5M7qU+Pk7/qP/q3ARAmS/ilK1URD4NTQ8WQ4HUOp0MBodi3kOap9Cwyai157dmBIIRFu APElVmor+4DCDNuWXy5Ik7/INulglmsXEU8Zl+n269nvRJxqkc6+DCkd1Pgd95Uy5shJ eEUZ3vMi382WyrUlduTumiZCKXHqpK7t0T2d8K4TyVIPZJpOL3qYl0sLWKSIgyRJZsnQ UQ== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by mx0b-00069f02.pphosted.com with ESMTP id 3csd2yaxtj-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 06 Dec 2021 18:57:56 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.1.2/8.16.1.2) with SMTP id 1B6IpCaE089316 for ; Mon, 6 Dec 2021 18:57:55 GMT Original-Received: from nam02-dm3-obe.outbound.protection.outlook.com (mail-dm3nam07lp2049.outbound.protection.outlook.com [104.47.56.49]) by aserp3030.oracle.com with ESMTP id 3csc4s6kru-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 06 Dec 2021 18:57:55 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=KyqUONLKBuoQMxmOA+4gWNgWSTVWItcumFHoCLgaR6lvLc7LIPxTYajIPKGM0i5zgmuvDvZ5hIm7pgBHM8CO0zIolvByfdW4LBtzV8HIORZIKQp2h27mP6jxdPn0nFf0UvW8VTd+r5LsyRjdyRCI/taQFaf3IEn0PzR6CgtXjib4SIOSVKpHKDCqS9IYiOuldzjUvAoW7Bto9kiaNKKA2PMU5PpeiGpYfJrh6/eIPwqHbDDjeUTpUdfU223RLMjVyIV0rgOm3I2ooilh0TzDed6AxhzA6eOui3SX0yIYi+w8+KZAO8Gx+K9MhJKkpdF7FvVReyIfB1nmSZd6TQWm6Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=It38P92jgqTbLPGgygvpToi7XAW0sSf7s8LD72pSgHs=; b=DQKrKXPmXKOKlU2R7IpGiOzmKxzz/upJZ0rhFfRQAjTVOgkd+/6ZL0AYwVpmzDcq+kjvyK+m5v6hpozLM2rfXTSSvrnxlOPHdJgZNsCuz3wxiRIk8/ovOGvlOCw6Q3Lb0X3CeW4NfXdzS165qV7hQoXbAc1eLEjZj5v+U2qYQ6Pyk5s5DhFLYuEDN4+LV7LBWeUUzidDgDR5Nvo9L2FpJSzRkeQHSBWMs2neKdU+zuqIgJCIVieSs/31lx1RpXypEVlZTCxFHqcszH653ApdSETpsz208jOBLA1m8dNMIurF6px0Pyy5yMHp2cZze8PPik47ESrgrVRwc6LXRCdX1w== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=It38P92jgqTbLPGgygvpToi7XAW0sSf7s8LD72pSgHs=; b=Hh0AFDZLbRN3w3fpQlOGZuKgcypadbaOpNDqOJ2D8Ln1kZD4t5XsWMgCLZquJL6mUVczVgfAl/SL+1txHJ/+QM7cgC/x6q3eD9LsB60TliO/0Qu/HE8aZgK6dEUV3H6v/MfbFyUIvSAtVEkp+ysUx1SMj3sceoKDq0gccbEgEcc= Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com (2603:10b6:a03:37e::19) by SJ0PR10MB5645.namprd10.prod.outlook.com (2603:10b6:a03:3e2::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4669.15; Mon, 6 Dec 2021 18:57:53 +0000 Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::4588:646c:e330:8bc0]) by SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::4588:646c:e330:8bc0%9]) with mapi id 15.20.4755.021; Mon, 6 Dec 2021 18:57:53 +0000 Thread-Topic: 26.3; Doc string of `process-file' Thread-Index: Adfq0wTj3ZS9PV+gQA+XeSjdPtP0Zw== Accept-Language: en-US Content-Language: en-US authentication-results: gnu.org; dkim=none (message not signed) header.d=none;gnu.org; dmarc=none action=none header.from=oracle.com; x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 19cd6d63-714c-48b1-43a3-08d9b8ea4e9a x-ms-traffictypediagnostic: SJ0PR10MB5645: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: KqtZ0Wyn1WGJjchuCC5UWqhphdrlR7ECypXtt6FPjjoLHQk7mfdV225YKo4Tes2An5a406Xmt4C2Yw6PpQwfF45U90I2WhEgHFLp5EqFuVlY6ZFJFyFzMxKtj13Jvm+R5cb3ieV+LnhFbUtcx2w7pJZfagIyXTNbCezm+emnprLD8twYbupUwI+eI3bPpQ58I2OKK3+sQXYv9IWaJTcu7FC5yAWu+rnCzb5LW4fyFOSUljnq1ydnYqfdTaGBYteML0s2XHz85ZLLrUJ+VxZiH1E1zmm8mPUf63LfWgK5rpJ3FEoYr9wpp93RGUUYWJiXn/m2D56H2J9MX10crn4hGZtFWrvzfE6zdT7m+AjxDbTUqJYRDtMO1hQb0kWQCoIkvu5PD1R1vVi9nSi5Kizrbj4anDRe5h0NmONavGxGY7XVaaGTAeBluW6SqfMI4meXwkrcVHA90jnEteLzHB2zReZAxAj98rVDSpFszASdUdxs4cRObHjusho7adXBw9eaIWU/uCK2l6svewWEjPVYV3hhWs9tQ0U/3gjfUfwUnhOf40MeSk+KUjO7uzEd4QvwfVLsuIL4iR09yJk8rcqoMhVfohM64Q6rzy5sPlbQeS1UAFE8E9Ezm68sb1WDZBI2U7QyAoZHnHI8W/13g1oCtAq4KiaOcAVcuQu9j51CIAlh575+ptIRnHV2WKg+GybdFDnZom8Il87RfAQjo82vtdZwkGpJSfg0joHaTcxam7Y= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SJ0PR10MB5488.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(366004)(52536014)(5660300002)(6916009)(38070700005)(55016003)(38100700002)(186003)(8936002)(26005)(66446008)(45080400002)(86362001)(8676002)(122000001)(71200400001)(66946007)(6506007)(508600001)(2906002)(7696005)(44832011)(33656002)(76116006)(9686003)(316002)(64756008)(66476007)(66556008)(81973001); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: PJHgvLV3JHw68KAE+D3J+07qUN5yOZgM5ASgN8DdEoLzY5le8j+24/XJt6IvFgB/LVyhFoC+d9yqv52AafSejoZtrW9RITkNt2g54APer+WvSJvt+TsXPzkaQOCbAs4mfjvp039AxaoFc8X2YpN7Co0oCLoYCmr131MwuNfYuAaMVMcZgKimXmqKkdVAD91vrZ//Zr7tJCUv00eShXcjydMqai9NrYfN7+wv4Wnh8t0r0rWYyJSZAP78f5F2ax31NYoadg3XTNnNnpKrxNek/0LIn1riVHkqaP+9py7/ogB7ZaP+NyUH/2ubjBo1rP5bW4CQwxFWw8npKaWYVOudNpZh1nz7MqKlopFAqg6dMECuSdbh2MULy7VPSGWfCIS2rlFDr/eXGfbA9PUz5FPs0qlOy4+KtRhaGZdqM8TtkuOq7T0MbuwQHLjTDDmRlX4E0yKX0wzCQJVdWfOzfoCaF0Y/4qeqnVwPuR3TGbPIYMu06+JLWAzieYpd/3hHwmXoJbJTpQeXxkq8hZYXpOjqOjxZeWIoT/lqsiPKLNFtn4wQ0IzprZbCAq+QvkhJcRxSdAzKAuQl3iDZnrfNIIcejOJeuyLkkemRcRnp6x7XrepZiwsCWphZH1sbntZskipcD2YsWI5sxS1zlk1BojABX+9cKyum5vKaMRpNwILDzPxTclSRF7FhQROnrv9dYGOXF9TcDn0XFU8gEVl9Fu8kpkg5GUuEVX5c1fPATPmIGdy/OOJs78MFbXT4fN eFmFYPh2Y66cR/7lrJ2Q52OnXMzuPfND4c256+Rvpam951YFz3NvrwALofDx26Rg+SgNt14ICGVsomFOa/8gfaiyG5V5Tl5YlR X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SJ0PR10MB5488.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 19cd6d63-714c-48b1-43a3-08d9b8ea4e9a X-MS-Exchange-CrossTenant-originalarrivaltime: 06 Dec 2021 18:57:52.8792 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: 5L79bzTjAf1VgiF/BNZGzAVTnB/WGcKzh3yFp+YpETXchbs+UL8mFiUacQj8VZJ1TYh+ix7COiWPOIAU56LnMA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ0PR10MB5645 X-Proofpoint-Virus-Version: vendor=nai engine=6300 definitions=10190 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 mlxlogscore=936 phishscore=0 bulkscore=0 malwarescore=0 spamscore=0 suspectscore=0 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2110150000 definitions=main-2112060113 X-Proofpoint-GUID: fX4hU_51xKWoM56BrQVS7tIYDfv-RmOx X-Proofpoint-ORIG-GUID: fX4hU_51xKWoM56BrQVS7tIYDfv-RmOx Received-SPF: pass client-ip=205.220.165.32; envelope-from=drew.adams@oracle.com; helo=mx0a-00069f02.pphosted.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:221781 Archived-At: 1. The doc string includes this: File names in INFILE and BUFFER are handled normally, but file names in ARGS should be relative to `default-directory'... This doesn't at all specify what args INFILE and BUFFER are. What does "handled normally" mean? Presumably it means that such file names are something from relative file names. That something isn't called out. But more importantly, what are INFILE and BUFFER, besides the hint that they can (but need not?) contain some (absolute?) file names? The mention of `call-process' might lead a reader to hope for a description of INFILE and BUFFER there, and then hope that the same applies to `process-file'. There's an INFILE arg described there, but no BUFFER arg. Please consider making the doc string of `process-file' complete. It should be standalone, or it should explicitly refer to some other doc for descriptions of some of its args. Maybe something like this (?): * For INFILE, repeat what `call-process' says: The program's input comes from file INFILE (nil means `null-device'). * For BUFFER, adjust what `call-process' says for a buffer DESTINATION: Output is inserted in BUFFER (current buffer if BUFFER is `t'). 2. Args DISPLAY and ARGS are also unspecified in the doc string. ___ I suggest that someone familiar with `process-file' and `call-process' fix the former's doc string. If it makes sense for it to refer to the doc string of `call-process', fine, but please do that explicitly and clearly. Someone with little knowledge should be able to grok what this function's args are about - what they can be and how they're handled. In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32) of 2019-08-29 Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd Windowing system distributor `Microsoft Corp.', version 10.0.19042 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3''