From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Damien Cassou Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 06:32:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: 56809@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.16589899085938 (code B ref -1); Thu, 28 Jul 2022 06:32:02 +0000 Received: (at submit) by debbugs.gnu.org; 28 Jul 2022 06:31:48 +0000 Received: from localhost ([127.0.0.1]:57445 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGx3k-0001Xi-3a for submit@debbugs.gnu.org; Thu, 28 Jul 2022 02:31:48 -0400 Received: from lists.gnu.org ([209.51.188.17]:34034) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGx3f-0001XU-G2 for submit@debbugs.gnu.org; Thu, 28 Jul 2022 02:31:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57440) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGx3e-0007xx-MX for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 02:31:43 -0400 Received: from mail.choca.pics ([80.67.172.235]:58580) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGx3c-0007ZB-3X for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 02:31:41 -0400 Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 34B4818192DC8 for ; Thu, 28 Jul 2022 08:31:26 +0200 (CEST) Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10032) with ESMTP id 4rmDXGW01Q6X for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 6DC4B18192DCC for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) X-Virus-Scanned: amavisd-new at choca.pics Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10026) with ESMTP id Smws9_NjZEmh for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) Received: from localhost (240-68-190-109.dsl.ovh.fr [109.190.68.240]) by mail.choca.pics (Postfix) with ESMTPSA id 1A74E18192DC8 for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) From: Damien Cassou Date: Thu, 28 Jul 2022 08:31:24 +0200 Message-ID: <87edy5929v.fsf@cassou.me> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=80.67.172.235; envelope-from=damien@cassou.me; helo=mail.choca.pics X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.4 (-) 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.4 (--) --=-=-= Content-Type: text/plain Tags: patch Hi, I found the docstring of file-name-with-extension very confusing so I wrote another one. Best -- Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-lisp-files.el-file-name-with-extension-Improve-docst.patch >From dccdf3dec9a82d4ce05e9978b762d9538e11bdfd Mon Sep 17 00:00:00 2001 From: Damien Cassou Date: Thu, 28 Jul 2022 08:27:45 +0200 Subject: [PATCH] ; * lisp/files.el (file-name-with-extension): Improve docstring. --- lisp/files.el | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lisp/files.el b/lisp/files.el index 37ed796a68..39b8586a94 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -5119,13 +5119,13 @@ file-name-extension ""))))) (defun file-name-with-extension (filename extension) - "Set the EXTENSION of a FILENAME. + "Return a string resulting from the concatenation of FILENAME and EXTENSION. The extension (in a file name) is the part that begins with the last \".\". -Trims a leading dot from the EXTENSION so that either \"foo\" or -\".foo\" can be given. +If EXTENSION doesn't start with a \".\", one is inserted anyway +between FILENAME and EXTENSION. -Errors if the FILENAME or EXTENSION are empty, or if the given +Signal an error if FILENAME or EXTENSION are empty, or if the given FILENAME has the format of a directory. See also `file-name-sans-extension'." -- 2.36.0 --=-=-=-- From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 07:50:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Damien Cassou Cc: 56809@debbugs.gnu.org Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.165899456114898 (code B ref 56809); Thu, 28 Jul 2022 07:50:02 +0000 Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 07:49:21 +0000 Received: from localhost ([127.0.0.1]:57498 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGyGm-0003sB-C0 for submit@debbugs.gnu.org; Thu, 28 Jul 2022 03:49:21 -0400 Received: from eggs.gnu.org ([209.51.188.92]:57690) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGyGg-0003ru-CP for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 03:49:19 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:45604) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGyGa-00088X-05; Thu, 28 Jul 2022 03:49:08 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=BS6RE214RSmpeuboykNBgApxgwU2CoRfKBLTbI/ajT4=; b=BR0qhJ80YQ5l 7M58DHQsYHozAx2HUE1C3KgkIuyIqU4JQFKUyS6Rjc/U0kE8zul3l8Cy/ondvzmd2C/ZXMrKTJ19P i/3tF3BZzhZc4YK+Lcg/r8w6fH0FLVeRJp0mQhmgtZf5TEU1BFu5al8Yz1AzURC377TW/FCPwscI0 FztD/H7U+eeuBB4y/d9H27GWxQ762QBb7lElh00Q9/0G2zrXxHb3NHn6xem1anXCpAQoY0OXTIjCl 49QK7AFam7KcLRitWn8RjAo8p+TZQVfINRQUmltF9HwQVcevkkuRFNYMaISMyF37UpdGBlXBcr477 VwEKWp/QpknLxR3iJEmiQw==; Received: from [87.69.77.57] (port=2121 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGyGZ-0003Fq-AP; Thu, 28 Jul 2022 03:49:07 -0400 Date: Thu, 28 Jul 2022 10:49:16 +0300 Message-Id: <83ilnhad8j.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87edy5929v.fsf@cassou.me> (message from Damien Cassou on Thu, 28 Jul 2022 08:31:24 +0200) References: <87edy5929v.fsf@cassou.me> X-Spam-Score: -2.3 (--) 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 (---) > From: Damien Cassou > Date: Thu, 28 Jul 2022 08:31:24 +0200 > > I found the docstring of file-name-with-extension very confusing so I > wrote another one. Thanks. It definitely needed its wording and its grammar fixed. I've now fixed that on the emacs-28 release branch. The modified doc string says this: "Return FILENAME modified to have the specified EXTENSION. The extension (in a file name) is the part that begins with the last \".\". This function removes any existing extension from FILENAME, and then appends EXTENSION to it. EXTENSION may include the leading dot; if it doesn't, this function will provide it. It is an error if FILENAME or EXTENSION is empty, or if FILENAME is in the form of a directory name according to `directory-name-p'. See also `file-name-sans-extension'." Looks OK? From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Damien Cassou Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 08:36:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Eli Zaretskii Cc: 56809@debbugs.gnu.org Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.165899730619927 (code B ref 56809); Thu, 28 Jul 2022 08:36:02 +0000 Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 08:35:06 +0000 Received: from localhost ([127.0.0.1]:57539 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGyz3-0005BK-PI for submit@debbugs.gnu.org; Thu, 28 Jul 2022 04:35:06 -0400 Received: from mail.choca.pics ([80.67.172.235]:38684) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGyz2-0005BC-HO for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 04:35:05 -0400 Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 0915418192DC8; Thu, 28 Jul 2022 10:35:03 +0200 (CEST) Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10032) with ESMTP id EGzqBf-ilafi; Thu, 28 Jul 2022 10:35:02 +0200 (CEST) Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 76E6518192DCC; Thu, 28 Jul 2022 10:35:02 +0200 (CEST) X-Virus-Scanned: amavisd-new at choca.pics Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10026) with ESMTP id wtyzHwAL1ovX; Thu, 28 Jul 2022 10:35:02 +0200 (CEST) Received: from localhost (240-68-190-109.dsl.ovh.fr [109.190.68.240]) by mail.choca.pics (Postfix) with ESMTPSA id 2CEE318192DC8; Thu, 28 Jul 2022 10:35:02 +0200 (CEST) From: Damien Cassou In-Reply-To: <83ilnhad8j.fsf@gnu.org> References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> Date: Thu, 28 Jul 2022 10:35:01 +0200 Message-ID: <87bkt98wju.fsf@cassou.me> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) 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 (-) Eli Zaretskii writes: > Looks OK? looks better than my version :-). The only thing I don't really like is > "Return FILENAME modified to=E2=80=A6 Most readers will know that FILENAME is not going to be modified but the phrasing is still confusing in my opinion. I would prefer a version around the word "concatenate" or similar. Here is another version: Concatenate FILENAME without its extension and EXTENSION. It doesn't say that the result of the concatenation is returned but I'm fine having it implied. Your call. --=20 Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 08:58:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Damien Cassou Cc: 56809@debbugs.gnu.org Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.165899866322527 (code B ref 56809); Thu, 28 Jul 2022 08:58:01 +0000 Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 08:57:43 +0000 Received: from localhost ([127.0.0.1]:57565 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGzKx-0005rH-5n for submit@debbugs.gnu.org; Thu, 28 Jul 2022 04:57:43 -0400 Received: from eggs.gnu.org ([209.51.188.92]:44090) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGzKv-0005r0-NY for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 04:57:42 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:46670) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGzKo-0002TW-Kd; Thu, 28 Jul 2022 04:57:35 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=ay6EaM6D2GPUojmRdsR4LyhwR3ZCXdH3yDWuP2fLHTE=; b=m7XB4AsAo9LSu/JP4hFQ UUCTMWxtbdldYD0QQg+ImWm51CK3QP3Q1aWx/svEBE22NQLYqyLY4MvHvb4Mx45IsPPQbVYYk2JB1 jUuwZAZBYabKoPlFG5JrKL7QB2M1xrJ59lD5kqfgWd0rR/q3QCTymkkVRQtUmrnj30GQMi8quza9i GvGdguBePjWYESFfI1PpR3WMU7BTjzov5Ti+CXYdNqbKwlBEcEyuZqtCarP2zdCtqAggSrme8eqKc 6elnP6RpJDG6GJMrwONHJttNL2hAU+fnlFEywsO7qDLLilkH9FBWycoDDhPOHOwIUghWOnZPNsK3s spnmzzw70ePKYg==; Received: from [87.69.77.57] (port=2320 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGzKX-0004PK-Q1; Thu, 28 Jul 2022 04:57:21 -0400 Date: Thu, 28 Jul 2022 11:57:25 +0300 Message-Id: <837d3xaa2y.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87bkt98wju.fsf@cassou.me> (message from Damien Cassou on Thu, 28 Jul 2022 10:35:01 +0200) References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> <87bkt98wju.fsf@cassou.me> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) 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 (---) > From: Damien Cassou > Cc: 56809@debbugs.gnu.org > Date: Thu, 28 Jul 2022 10:35:01 +0200 > > Eli Zaretskii writes: > > Looks OK? > > looks better than my version :-). The only thing I don't really like is > > > "Return FILENAME modified to… > > Most readers will know that FILENAME is not going to be modified but the > phrasing is still confusing in my opinion. Why confusing? And what do you mean by "will know that FILENAME is not going to be modified"? > I would prefer a version > around the word "concatenate" or similar. Here is another version: > > Concatenate FILENAME without its extension and EXTENSION. I don't want to say how the function does its job: that's not what a doc string should describe. ("Concatenate" is also inaccurate, because if EXTENSION lacks the leading period, that's not really what's going on there.) So please help me understand why "modified" is problematic, and let's take it from there. Thanks. From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Damien Cassou Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 09:34:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Eli Zaretskii Cc: 56809@debbugs.gnu.org Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.165900078326595 (code B ref 56809); Thu, 28 Jul 2022 09:34:01 +0000 Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 09:33:03 +0000 Received: from localhost ([127.0.0.1]:57624 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGzt8-0006ut-Ij for submit@debbugs.gnu.org; Thu, 28 Jul 2022 05:33:02 -0400 Received: from mail.choca.pics ([80.67.172.235]:39526) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGzt5-0006uN-5X for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 05:33:00 -0400 Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id A903418192DC8; Thu, 28 Jul 2022 11:32:57 +0200 (CEST) Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10032) with ESMTP id 5P8CUmVkq2US; Thu, 28 Jul 2022 11:32:57 +0200 (CEST) Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id ECF9B18192DCC; Thu, 28 Jul 2022 11:32:56 +0200 (CEST) X-Virus-Scanned: amavisd-new at choca.pics Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10026) with ESMTP id 34CR0TCUpdWZ; Thu, 28 Jul 2022 11:32:56 +0200 (CEST) Received: from localhost (240-68-190-109.dsl.ovh.fr [109.190.68.240]) by mail.choca.pics (Postfix) with ESMTPSA id 9F13E18192DC8; Thu, 28 Jul 2022 11:32:56 +0200 (CEST) From: Damien Cassou In-Reply-To: <837d3xaa2y.fsf@gnu.org> References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> <87bkt98wju.fsf@cassou.me> <837d3xaa2y.fsf@gnu.org> Date: Thu, 28 Jul 2022 11:32:55 +0200 Message-ID: <878rod8tvc.fsf@cassou.me> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) 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 (-) Eli Zaretskii writes: >> From: Damien Cassou >> Eli Zaretskii writes: >>> Looks OK? >>=20 >> looks better than my version :-). The only thing I don't really like is >>=20 >>> "Return FILENAME modified to=E2=80=A6 >>=20 >> Most readers will know that FILENAME is not going to be modified but the >> phrasing is still confusing in my opinion. > > Why confusing? To me, "Return FILENAME modified" means that FILENAME is going to be modified but that is not true: FILENAME will still reference the same place in memory and this place won't be changed either. Said differently: I understand the sentence as "there is going to be some side-effects" even though there are none. > And what do you mean by "will know that FILENAME is not going to be > modified"? I meant that reasonably-knowledgeable elisp developers will know that the content of FILENAME isn't going to change after this function is executed. As a result, a docstring starting with "Return FILENAME modified to" will be correctly understood by most developers so you should take my feedback with a grain of salt. That being said, I like when things are clear and not subject to wrong interpretations so I would prefer a different phrasing. >> Concatenate FILENAME without its extension and EXTENSION. > I don't want to say how the function does its job To me "Concatenate" doesn't say how the function is implemented (which would be something like "Call `concatenate' to=E2=80=A6") but what the user should expect the result to look like (i.e., "the approximate concatenation of 2 strings"). > "Concatenate" is also inaccurate, because if EXTENSION lacks the > leading period, that's not really what's going on there. I agree it is inaccurate. The inaccuracy is acceptable to me in the first sentence as this sentence is only meant to give an idea of what the function is supposed to do. The rest of the docstring explains the details and why it's not a simple concatenation. I think the misunderstanding here is just because "Concatenate" is an implementation detail for you (so you expect it to correctly reflect the implementation) while it is just a user-visible result to me (so I don't really care if the implementation doesn't really concatenate). As a conclusion, I'm fine with the docstring and you should merge it and do more important stuff rather than discussing unimportant details with me =F0=9F=98=83. I'm sorry I made you loose your time. Best --=20 Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 09:41:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Damien Cassou Cc: 56809@debbugs.gnu.org Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.165900123927387 (code B ref 56809); Thu, 28 Jul 2022 09:41:02 +0000 Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 09:40:39 +0000 Received: from localhost ([127.0.0.1]:57633 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH00V-00077f-1R for submit@debbugs.gnu.org; Thu, 28 Jul 2022 05:40:39 -0400 Received: from eggs.gnu.org ([209.51.188.92]:53664) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH00R-00077Q-Ng for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 05:40:38 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:47320) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oH00L-0001Cy-Ku; Thu, 28 Jul 2022 05:40:29 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=1zKZlnBcXh2OYlxfPWds9AFI25vDpe7g4kcRg34g1+Q=; b=QuhOtnzJOJacudESSBTi Gp6E1MoN9pFz9lu5LyHsFeREa4xFH07Rc6EQnnfPgk6Maa9AVYHEeLQc/HJS0hd+gImDqln1IkenU U7sBdZalhqUaJp84luocv5FgrBsh2GelQ5opoPCE1cSG6EfnTQEyXYtX6IAKKy01ocqZhOUApsmjd R0gI0C287wUkMEI1sKP1N3tmWm3FAKFbSwIj/QkY1sG6oQgf1IPIWmZ5u71LAiXj6xteXoBarDuPO TEoZ16sy75E2biZz1VXWTqV2tp4SuxN+LvgTp6rXVVuanqEsd/fUf7a/HoNnYBM4SzsveNsXzmcw0 KGVo3PTKHAF7jA==; Received: from [87.69.77.57] (port=4972 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oH00L-0003af-3V; Thu, 28 Jul 2022 05:40:29 -0400 Date: Thu, 28 Jul 2022 12:40:37 +0300 Message-Id: <83zggt8tii.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <878rod8tvc.fsf@cassou.me> (message from Damien Cassou on Thu, 28 Jul 2022 11:32:55 +0200) References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> <87bkt98wju.fsf@cassou.me> <837d3xaa2y.fsf@gnu.org> <878rod8tvc.fsf@cassou.me> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) 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 (---) > From: Damien Cassou > Cc: 56809@debbugs.gnu.org > Date: Thu, 28 Jul 2022 11:32:55 +0200 > > >>> "Return FILENAME modified to… > >> > >> Most readers will know that FILENAME is not going to be modified but the > >> phrasing is still confusing in my opinion. > > > > Why confusing? > > To me, "Return FILENAME modified" means that FILENAME is going to be > modified but that is not true: FILENAME will still reference the same > place in memory and this place won't be changed either. Said > differently: I understand the sentence as "there is going to be some > side-effects" even though there are none. Well, the "return" part was supposed to prevent such an interpretation. Moreover, that sentence is just the summary; the doc string goes on to say This function removes any existing extension from FILENAME, and then appends EXTENSION to it. I could have the first sentence to say something like Return a file name made from the base name of FILENAME and EXTENSION. But is this really better? We'd need at least to explain what is a "base name" (and it's also a bit inaccurate, since "base name" generally means without the leading directories). > I agree it is inaccurate. The inaccuracy is acceptable to me in the > first sentence as this sentence is only meant to give an idea of what > the function is supposed to do. The rest of the docstring explains the > details and why it's not a simple concatenation. Well, the same is true for the "modified" part, isn't it? > As a conclusion, I'm fine with the docstring and you should merge it and > do more important stuff rather than discussing unimportant details with > me 😃. I'm sorry I made you loose your time. No need to be sorry, this is part of my job as a maintainer. Thanks. From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Visuwesh Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 10:35:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Damien Cassou Cc: Eli Zaretskii , 56809@debbugs.gnu.org Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.16590044871774 (code B ref 56809); Thu, 28 Jul 2022 10:35:01 +0000 Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 10:34:47 +0000 Received: from localhost ([127.0.0.1]:57709 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH0qt-0000SY-CZ for submit@debbugs.gnu.org; Thu, 28 Jul 2022 06:34:47 -0400 Received: from mail-pg1-f194.google.com ([209.85.215.194]:45637) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH0qq-0000SH-SE for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 06:34:46 -0400 Received: by mail-pg1-f194.google.com with SMTP id f65so1196077pgc.12 for <56809@debbugs.gnu.org>; Thu, 28 Jul 2022 03:34:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:in-reply-to:references:date:message-id :user-agent:mime-version:content-transfer-encoding; bh=Y9g9iRhR0y8TJ/2jj4bY1tO3ybO0Pi7Haga2FpgwIm4=; b=BxCVxWEhlHYGZMjH8U4EEAh+hm6WTCqQzjufrGYrBmW11AvvzjRqCrclf2+xjvi+vt FGu1LLsS4RODLQH2FkoJ6B1t77XF/c1Bdn7i4heYZxWIaYja4uLBTsxm3NspBRQT8pbk dzkN/JMHoSbId7sIrXM5zBt4873NakA8zptwJ30XS3Rc2FTymA9qYprDfSUOQWUrnkSn StvuiFC7jutXqES0+hnom1lEzMsDbsxdQDQbwhhHZFHHDwnnVXp/1l/LUS51nxvJ7mqQ yn53hcEQfdb6L4QwoJe1XSBZBJpltDrlt2s63qRJhaIektt77ZGE4pb/TkicZ9ZTLsbI zn9g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references:date :message-id:user-agent:mime-version:content-transfer-encoding; bh=Y9g9iRhR0y8TJ/2jj4bY1tO3ybO0Pi7Haga2FpgwIm4=; b=jt8sLUhiZWBFfUSLS08PkHBp1GvJzLZEeOJ9zRTiXqF+gwI81FjCQMMwFfZC5KVle9 3CB3HesdnWNoVjrbbrQaQnw1aPvSmSw1B8T4SgVVbqIssLoEbIJ0jwYP5yhUQ2D8NKkQ bfSoHnNKWgfHZqdpvSfwIj7NRRu39slten8JKJ/UYYmea4vPwuqP36b475DoAnwtzUrK AR1+S+PVhy7V1JIlTK01zzDwXKF3HRgMI6dSRFlOILRquihQ0G5H/+TOkfJw7tS4Ddly mpCARLeKbAzwXEE11VfJZ1Q60yD3uDFYw3s2BjB3HmAl8ndie86Bq2BDO7E13kKCHLaN lt9w== X-Gm-Message-State: AJIora/TgYFUHVVq+DLtLeL2+GYJ9Onsbj3QUOvXFxhMBh3K5iGOl/Vd qntRsOdYTAdA1J02tARwu78= X-Google-Smtp-Source: AGRyM1uTHx14t5EDzYTKAS584vHMv0IOwfAzpkxPwWlI+oCEdRyQz0/lG4pJ9rYH4N+Uq1zkhe9YhQ== X-Received: by 2002:aa7:9519:0:b0:528:c2e0:b7ae with SMTP id b25-20020aa79519000000b00528c2e0b7aemr26321648pfp.39.1659004478897; Thu, 28 Jul 2022 03:34:38 -0700 (PDT) Received: from localhost ([49.204.141.236]) by smtp.gmail.com with ESMTPSA id g2-20020a170902d1c200b0016dc6279ab8sm845836plb.159.2022.07.28.03.34.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 28 Jul 2022 03:34:37 -0700 (PDT) From: Visuwesh In-Reply-To: <87bkt98wju.fsf@cassou.me> (Damien Cassou's message of "Thu, 28 Jul 2022 10:35:01 +0200") References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> <87bkt98wju.fsf@cassou.me> Date: Thu, 28 Jul 2022 16:04:21 +0530 Message-ID: <87o7x9wmoi.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.0 (/) 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 (-) [=E0=AE=B5=E0=AE=BF=E0=AE=AF=E0=AE=BE=E0=AE=B4=E0=AE=A9=E0=AF=8D =E0=AE=9C= =E0=AF=82=E0=AE=B2=E0=AF=88 28, 2022] Damien Cassou wrote: >> "Return FILENAME modified to=E2=80=A6 > > Most readers will know that FILENAME is not going to be modified but the > phrasing is still confusing in my opinion. I would prefer a version > around the word "concatenate" or similar. Here is another version: > > Concatenate FILENAME without its extension and EXTENSION. I find this confusing. Eli's version looks better (the other one which mentions basename is no good either). From unknown Mon Aug 18 18:03:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#56809: file-name-with-extension: Improve docstring. Resent-From: Damien Cassou Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 12:03:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56809 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Eli Zaretskii Cc: 56809@debbugs.gnu.org Received: via spool by 56809-submit@debbugs.gnu.org id=B56809.165900972428433 (code B ref 56809); Thu, 28 Jul 2022 12:03:01 +0000 Received: (at 56809) by debbugs.gnu.org; 28 Jul 2022 12:02:04 +0000 Received: from localhost ([127.0.0.1]:57794 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH2DL-0007OX-Nl for submit@debbugs.gnu.org; Thu, 28 Jul 2022 08:02:03 -0400 Received: from mail.choca.pics ([80.67.172.235]:41500) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH2DH-0007O2-70 for 56809@debbugs.gnu.org; Thu, 28 Jul 2022 08:02:02 -0400 Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 9338918192DC8; Thu, 28 Jul 2022 14:01:57 +0200 (CEST) Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10032) with ESMTP id TaRYp3MwZzGf; Thu, 28 Jul 2022 14:01:57 +0200 (CEST) Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 2007D18192DCC; Thu, 28 Jul 2022 14:01:57 +0200 (CEST) X-Virus-Scanned: amavisd-new at choca.pics Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10026) with ESMTP id NcdS7oVKQ5mD; Thu, 28 Jul 2022 14:01:56 +0200 (CEST) Received: from localhost (153.226.95.79.rev.sfr.net [79.95.226.153]) by mail.choca.pics (Postfix) with ESMTPSA id CD66818192DC8; Thu, 28 Jul 2022 14:01:56 +0200 (CEST) From: Damien Cassou In-Reply-To: <83zggt8tii.fsf@gnu.org> References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> <87bkt98wju.fsf@cassou.me> <837d3xaa2y.fsf@gnu.org> <878rod8tvc.fsf@cassou.me> <83zggt8tii.fsf@gnu.org> Date: Thu, 28 Jul 2022 14:01:56 +0200 Message-ID: <8735el8myz.fsf@cassou.me> MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.0 (/) 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 (-) Eli Zaretskii writes: > Well, the "return" part was supposed to prevent such an > interpretation. Moreover, that sentence is just the summary. Feel free to merge your patch Eli, it's great. I don't want us to keep discussing on such a tiny detail. Thank you. -- Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill From unknown Mon Aug 18 18:03:01 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Damien Cassou Subject: bug#56809: closed (Re: bug#56809: file-name-with-extension: Improve docstring.) Message-ID: References: <83wnbx8ioo.fsf@gnu.org> <87edy5929v.fsf@cassou.me> X-Gnu-PR-Message: they-closed 56809 X-Gnu-PR-Package: emacs X-Gnu-PR-Keywords: patch Reply-To: 56809@debbugs.gnu.org Date: Thu, 28 Jul 2022 13:35:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1659015302-14653-1" This is a multi-part message in MIME format... ------------=_1659015302-14653-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #56809: file-name-with-extension: Improve docstring. which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 56809@debbugs.gnu.org. --=20 56809: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D56809 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1659015302-14653-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 56809-done) by debbugs.gnu.org; 28 Jul 2022 13:34:30 +0000 Received: from localhost ([127.0.0.1]:57884 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH3eo-0003nJ-Bz for submit@debbugs.gnu.org; Thu, 28 Jul 2022 09:34:30 -0400 Received: from eggs.gnu.org ([209.51.188.92]:49756) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH3em-0003n2-JX for 56809-done@debbugs.gnu.org; Thu, 28 Jul 2022 09:34:29 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:49868) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oH3eg-0003Ra-GX; Thu, 28 Jul 2022 09:34:22 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=wIcMF/ZGyhQe4MA/iEXN8oYqlCmJImYBUS6z4s3o2e8=; b=DsqFL8b7uwMR 5QO06i7QukBHeAjH21KIkWQP6y2bAGEsPgvKBTrb3NWmv5XQO+a3sfTQHkAavWH7+NhHXq+zxet4w Jr4lQEGByJTLvEPEUf7XC2Guk6CmT46c1vk6Tc14+nH12iapsOQrXzypyHrgO8jjEwRk/0JtVb23/ qlPsRO5rESZzOZhHAsNEB1/Gjm6+plQC2hIKuDBk4RdYqSsLvRAuwe8lVMb6OR29fN6GV70tB92T6 JYmKFDBiTNxuAaxxMFtnQttCZ0CzkfZ0+B/ybCFYvKZ9PBfAlxLXbvb0HyqoeCFZTzj6K5XMLUsK4 5t74+jStshX7CrX2fZn96A==; Received: from [87.69.77.57] (port=3717 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oH3eg-00056A-03; Thu, 28 Jul 2022 09:34:22 -0400 Date: Thu, 28 Jul 2022 16:34:31 +0300 Message-Id: <83wnbx8ioo.fsf@gnu.org> From: Eli Zaretskii To: Damien Cassou In-Reply-To: <8735el8myz.fsf@cassou.me> (message from Damien Cassou on Thu, 28 Jul 2022 14:01:56 +0200) Subject: Re: bug#56809: file-name-with-extension: Improve docstring. References: <87edy5929v.fsf@cassou.me> <83ilnhad8j.fsf@gnu.org> <87bkt98wju.fsf@cassou.me> <837d3xaa2y.fsf@gnu.org> <878rod8tvc.fsf@cassou.me> <83zggt8tii.fsf@gnu.org> <8735el8myz.fsf@cassou.me> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 56809-done Cc: 56809-done@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 (---) > From: Damien Cassou > Cc: 56809@debbugs.gnu.org > Date: Thu, 28 Jul 2022 14:01:56 +0200 > > Eli Zaretskii writes: > > Well, the "return" part was supposed to prevent such an > > interpretation. Moreover, that sentence is just the summary. > > Feel free to merge your patch Eli, it's great. I don't want us to keep > discussing on such a tiny detail. I already merged it to the emacs-28 (a.k.a. "release") branch. It will be merged to master soon enough. But if someone can come up with a better wording, mine is not carved in stone. Thanks, closing. ------------=_1659015302-14653-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 28 Jul 2022 06:31:48 +0000 Received: from localhost ([127.0.0.1]:57445 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGx3k-0001Xi-3a for submit@debbugs.gnu.org; Thu, 28 Jul 2022 02:31:48 -0400 Received: from lists.gnu.org ([209.51.188.17]:34034) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oGx3f-0001XU-G2 for submit@debbugs.gnu.org; Thu, 28 Jul 2022 02:31:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57440) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGx3e-0007xx-MX for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 02:31:43 -0400 Received: from mail.choca.pics ([80.67.172.235]:58580) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGx3c-0007ZB-3X for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 02:31:41 -0400 Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 34B4818192DC8 for ; Thu, 28 Jul 2022 08:31:26 +0200 (CEST) Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10032) with ESMTP id 4rmDXGW01Q6X for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) Received: from localhost (localhost.localdomain [IPv6:::1]) by mail.choca.pics (Postfix) with ESMTP id 6DC4B18192DCC for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) X-Virus-Scanned: amavisd-new at choca.pics Received: from mail.choca.pics ([IPv6:::1]) by localhost (mail.choca.pics [IPv6:::1]) (amavisd-new, port 10026) with ESMTP id Smws9_NjZEmh for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) Received: from localhost (240-68-190-109.dsl.ovh.fr [109.190.68.240]) by mail.choca.pics (Postfix) with ESMTPSA id 1A74E18192DC8 for ; Thu, 28 Jul 2022 08:31:25 +0200 (CEST) From: Damien Cassou To: bug-gnu-emacs@gnu.org Subject: file-name-with-extension: Improve docstring. Date: Thu, 28 Jul 2022 08:31:24 +0200 Message-ID: <87edy5929v.fsf@cassou.me> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=80.67.172.235; envelope-from=damien@cassou.me; helo=mail.choca.pics X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.4 (-) X-Debbugs-Envelope-To: submit 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.4 (--) --=-=-= Content-Type: text/plain Tags: patch Hi, I found the docstring of file-name-with-extension very confusing so I wrote another one. Best -- Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-lisp-files.el-file-name-with-extension-Improve-docst.patch >From dccdf3dec9a82d4ce05e9978b762d9538e11bdfd Mon Sep 17 00:00:00 2001 From: Damien Cassou Date: Thu, 28 Jul 2022 08:27:45 +0200 Subject: [PATCH] ; * lisp/files.el (file-name-with-extension): Improve docstring. --- lisp/files.el | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lisp/files.el b/lisp/files.el index 37ed796a68..39b8586a94 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -5119,13 +5119,13 @@ file-name-extension ""))))) (defun file-name-with-extension (filename extension) - "Set the EXTENSION of a FILENAME. + "Return a string resulting from the concatenation of FILENAME and EXTENSION. The extension (in a file name) is the part that begins with the last \".\". -Trims a leading dot from the EXTENSION so that either \"foo\" or -\".foo\" can be given. +If EXTENSION doesn't start with a \".\", one is inserted anyway +between FILENAME and EXTENSION. -Errors if the FILENAME or EXTENSION are empty, or if the given +Signal an error if FILENAME or EXTENSION are empty, or if the given FILENAME has the format of a directory. See also `file-name-sans-extension'." -- 2.36.0 --=-=-=-- ------------=_1659015302-14653-1--