From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#72915: Docstrings of add-hook and remove-hook improvement? Date: Sun, 01 Sep 2024 10:34:19 -0400 Message-ID: References: <87v7zgrhrt.fsf@posteo.net> <86y14c9dk3.fsf@gnu.org> Reply-To: Stefan Monnier Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17899"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: Tomas Nordin , 72915@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Sep 01 16:35:22 2024 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 1sklfm-0004WM-5Q for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 01 Sep 2024 16:35:22 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sklfU-0004YU-P1; Sun, 01 Sep 2024 10:35:04 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sklfT-0004Y7-1g for bug-gnu-emacs@gnu.org; Sun, 01 Sep 2024 10:35:03 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sklfS-0004p9-NP for bug-gnu-emacs@gnu.org; Sun, 01 Sep 2024 10:35:02 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:Date:References:In-Reply-To:From:To:Subject; bh=aMj0pNMCZoEUjFGnSW83hVvx7OAt5eSE8kztsqZojhc=; b=aXnsJLkJllHx0MMFs9PfUezdkJIdBX0cHuvpp3h80DUgfLYKByyGbixFACFXabm2dqlY8CRv//3e2/1NiiKBSefbuJvrN35LpVt5u+uPJE1FGHIdsm7a8Mv4ib2xWusi++ii83YyR7QaTtw8ZRnFnwqB76ql3JXKYUwyyxuyz3aKN4g898lXMDrGblm3WkiXQz5JqsOm9cLdhZbRa69nwVXOB8BZB3tFGo4gdoYg0jAwcL1iAqnWHIGKQTIEitvhBGpjOMhVhbtHGK2GXqyve1U5LTwV8aLTiAt/u38pKsQMTOte9qV1WO8oCFxoO2tTFac4enmZ4GLtmJVSpC3Jmg==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1sklgQ-0001km-8Z for bug-gnu-emacs@gnu.org; Sun, 01 Sep 2024 10:36:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 01 Sep 2024 14:36:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 72915 X-GNU-PR-Package: emacs Original-Received: via spool by 72915-submit@debbugs.gnu.org id=B72915.17252013286680 (code B ref 72915); Sun, 01 Sep 2024 14:36:02 +0000 Original-Received: (at 72915) by debbugs.gnu.org; 1 Sep 2024 14:35:28 +0000 Original-Received: from localhost ([127.0.0.1]:35943 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sklfs-0001jg-7y for submit@debbugs.gnu.org; Sun, 01 Sep 2024 10:35:28 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:9059) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sklfq-0001jU-Dv for 72915@debbugs.gnu.org; Sun, 01 Sep 2024 10:35:26 -0400 Original-Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 7BF1A80A1B; Sun, 1 Sep 2024 10:34:21 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1725201259; bh=USITyD8jfwe8TixjhAlCOpuni1gKTzBYUfTxxqQsWKI=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=jy8Rpq9sYrnDD2X3TJqRShvZlvDofTYkt3r7ZsGzKKCj7b9WBkdMun7m1FXIqeW9G wFh65VIe7OjTwVbajgeXNPXEwlMJ4WU1MwTkt1LoccafYMNeqMpuMhe6wqwFkMgicE s2+fRBU8TIuGohSOjR6rM2dLd/dB39aERfQX9VqrG5duEOIzGNS3t9s/jgsKqlAjkP O2/QqGUaUP2hfWAT/lnjlIWou/NQSC8vNDaQnu4vxXfG1didiCmqFpEg70CQ523r0g G1twCLMf6wdqnMjfztNsHa4Q/NgtKexPB30Fld4PxqpCy9oEiPZO3rLjVTb9F5uGeM RockB/GTA6elw== Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id E8C8A80348; Sun, 1 Sep 2024 10:34:19 -0400 (EDT) Original-Received: from pastel (104-195-234-246.cpe.teksavvy.com [104.195.234.246]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id BC15112016C; Sun, 1 Sep 2024 10:34:19 -0400 (EDT) In-Reply-To: <86y14c9dk3.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 01 Sep 2024 07:57:00 +0300") 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-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:291056 Archived-At: >> -HOOK should be a symbol. If HOOK is void, it is first set to >> -nil. If HOOK's value is a single function, it is changed to a >> -list of functions. > Is the bit about setting HOOK to nil incorrect? Because the new text > drops that part. That's an internal detail that's not observable to the caller anyway. >> "Remove from the value of HOOK the function FUNCTION. >> HOOK should be a symbol, and FUNCTION may be any valid function. If >> FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the >> -list of hooks to run in HOOK, then nothing is done. See `add-hook'. >> +list of functions to run in HOOK, then nothing is done. See `add-hook'. > > "list of functions to run in HOOK" is ambiguous wrt what "in HOOK" > refers to. I would rephrase: > > If FUNCTION is not the value of HOOK and is not a member of the list > that is the value of HOOK, do nothing. Maybe we can simplify the wording a bit by focusing less about whether the hook's value is a function or a list of functions, and talking about the "sequence" or "set" of functions (which can be represented by a list of functions or a function)? Something like: "Remove FUNCTION from HOOK's functions. HOOK should be a symbol, and FUNCTION may be any valid function. Does nothing if HOOK does not currently contain FUNCTION. Compares functions with `equal`, which means that it can be slow if FUNCTION is not a symbol. See `add-hook'. - Stefan