From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#72915: Docstrings of add-hook and remove-hook improvement? Date: Sun, 1 Sep 2024 00:15:17 -0700 Message-ID: References: <87v7zgrhrt.fsf@posteo.net> <86y14c9dk3.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11502"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 72915@debbugs.gnu.org To: Eli Zaretskii , Tomas Nordin , Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Sep 01 09:17:14 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 1skepl-0002pv-Po for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 01 Sep 2024 09:17:14 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1skepc-0004sp-LA; Sun, 01 Sep 2024 03:17: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 1skepb-0004sf-9U for bug-gnu-emacs@gnu.org; Sun, 01 Sep 2024 03:17: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 1skepa-00079H-W5 for bug-gnu-emacs@gnu.org; Sun, 01 Sep 2024 03:17:03 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=Date:MIME-Version:References:In-Reply-To:From:To:Subject; bh=SxbkjHTXpt5rJZmd9pyHGLKM+gDx05MpQjUDW9jp5F0=; b=Q9ht0OXQEfWxK8Nb5Fzn5JpNSrAGxBP5L/27EmDG+9voLigxgzQ446JIDbvfBkEYu/jmjAEdvxWZHJQrXCuR5KrHK8X9oEGFCdus6GB1GBRKdBI1+lEMu+QI0ONTHMqibCfIjIDuoMVhWymMql9EXMn6oJZr+ivO0vyCNuuR7s9I3vNKCEdnUFgVHQ8IeK1hN5ua55vZrJy2r8UjDH/Jb+ebG2h92Bghsb8vbtIbxtsrlkSu899lRqAC4JfonBaXiWfhz5LUhDCGDbgEvDnLowP3cZekN4lulUHf7nInSn3mTz7OcpvjpogbAHvcEIoEbNdGNEhMMzKx5gYxwmyiew==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1skeqX-0005VF-U2 for bug-gnu-emacs@gnu.org; Sun, 01 Sep 2024 03:18:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 01 Sep 2024 07:18:01 +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.172517504621099 (code B ref 72915); Sun, 01 Sep 2024 07:18:01 +0000 Original-Received: (at 72915) by debbugs.gnu.org; 1 Sep 2024 07:17:26 +0000 Original-Received: from localhost ([127.0.0.1]:32982 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1skepy-0005UE-AE for submit@debbugs.gnu.org; Sun, 01 Sep 2024 03:17:26 -0400 Original-Received: from mail-ed1-f41.google.com ([209.85.208.41]:55704) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1skepv-0005Ty-Oz for 72915@debbugs.gnu.org; Sun, 01 Sep 2024 03:17:25 -0400 Original-Received: by mail-ed1-f41.google.com with SMTP id 4fb4d7f45d1cf-5bf01bdaff0so3064669a12.3 for <72915@debbugs.gnu.org>; Sun, 01 Sep 2024 00:16:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1725174919; x=1725779719; darn=debbugs.gnu.org; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:from:to:cc:subject:date:message-id:reply-to; bh=SxbkjHTXpt5rJZmd9pyHGLKM+gDx05MpQjUDW9jp5F0=; b=W0UCDDA0tAuabSxQZYrUnClBjmqxDuy8LhyJR/GMv+OpOqRI5y169Ye1WqgQ6sXKoU 3XDjwwaIv0uY102zLlCOO4Oxa6UQIv11i0X5+6NcWVhJ/CVQ9cBTcjPBzZHbjesPXldy q0Ap217EBjpAp8t4wyScBRfSge5poxdAclnCmBZC3v0Ja/rUq9dKuy0pwbER+tXwpJEU d1ta/EK/oCgMhAu+uO8ARN7zEV4DI/vJRhPGj1G+W4geJnLTft5u8pbFUUFfnIVVHIbD 8KjRuk2SzWr+aGZizFDHwjG7bvwb726KX4dyNxZxV0PPgGDTcriucZU/sk28g+5BWuW8 8ung== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725174919; x=1725779719; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=SxbkjHTXpt5rJZmd9pyHGLKM+gDx05MpQjUDW9jp5F0=; b=sXS6SUy8gtyj4XsdIfi6zgNuQz9LR5OO9Eijx1uLyxj4KUqWcEvYcPZl0NfjwlIhIw gMB+ZSuF0fcWoHQcnLJvOlgYDaGlmODUCqKUiGOfSXCp8zHL2+k+agGm8Cc1BD8HBeBf nOEm7+cZKdVWu/PyYA7qxgo52EcE347rcAXr+UFcv9k13yZevSqkFuKPol8+0y8ggMBq CTXnTFFZFgPpcbS77FtN7YIz1NXmGBlmll1IgtnZrc41swksuQNJdD6iaezWgzaA9mC8 bBPr9DP1W69L7/9Iw607LMDA4EWSG5p4z74ol6zqZsBLcMzD00+XZvpQp1HW00qMx4mL NA/g== X-Gm-Message-State: AOJu0YyF1krSg9rIoaMp+oko5eqnc3AwHXSsF2ElSMj75vgVefOxo8Ff HXrbt6S6uIQ5SnBh63zqDWnLSTD3gTQA1C8s+2nnhQRBTLRpw57EW1oJe7HARTLJHQVDSlQRs6b jah1crNOlHpYi1aJ8Zhm8HcdjCPA= X-Google-Smtp-Source: AGHT+IE7BMyH69Ud5fqFtZ+5JsuyKGKTLtzWIFmWnTbV1CpwfC2aUjowZJALY5NIr3XDX0Uj2d+eBXwEK/GhlLddLt0= X-Received: by 2002:a05:6402:2685:b0:5c2:54a3:6b3e with SMTP id 4fb4d7f45d1cf-5c254a36d72mr664271a12.16.1725174918378; Sun, 01 Sep 2024 00:15:18 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sun, 1 Sep 2024 00:15:17 -0700 In-Reply-To: <86y14c9dk3.fsf@gnu.org> 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:291043 Archived-At: Eli Zaretskii writes: >> From: Tomas Nordin >> Date: Sat, 31 Aug 2024 12:36:22 +0000 >> >> The following on top of emacs-30. >> >> diff --git a/lisp/subr.el b/lisp/subr.el >> index 28ba30f584e..e60c4119c60 100644 >> --- a/lisp/subr.el >> +++ b/lisp/subr.el >> @@ -2090,6 +2090,10 @@ add-hook >> "Add to the value of HOOK the function FUNCTION. >> FUNCTION is not added if already present. >> >> +HOOK should be a symbol. If HOOK is void, or if HOOK's value is a >> +single function, it is changed to a list of functions (containing only >> +FUNCTION in the void case). >> + >> The place where the function is added depends on the DEPTH >> parameter. DEPTH defaults to 0. By convention, it should be >> a number between -100 and 100 where 100 means that the function >> @@ -2108,10 +2112,6 @@ add-hook >> buffer-local value. That acts as a flag to run the hook >> functions of the global value as well as in the local value. >> >> -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. It makes no difference if HOOK is "first" set to nil from the POV of the end user, I think. The end result is that HOOK will be a list of functions. IOW, the point here is that `add-hook` will work even if HOOK is void, and that aspect is preserved in the above change. > >> "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. While the original is not ideal, I don't find this to be an improvement. Sorry. I'd suggest trying to reformulate it again, to make it more direct and avoid repeating the phrase "the value of". The wording in the manual is probably all that is needed here: This function removes FUNCTION from the hook variable HOOK. In other words, we either get to assume that the user knows what a hook is, or we can point the user to the relevant manual section to read about it.