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#34588: 27.0.50; Doc of write-contents-functions: arguments? Date: Sat, 23 Oct 2021 11:11:54 -0700 Message-ID: References: <87bm3715bu.fsf@web.de> <83y36agz88.fsf@gnu.org> <837edthkfd.fsf@gnu.org> <87y369ydil.fsf@web.de> <5C6E6C97.6000605@gmx.at> <87imxdxze6.fsf@web.de> 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="14316"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: Michael Heerdegen , 34588@debbugs.gnu.org To: Richard Stallman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Oct 23 20:13:14 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 1meLW6-0003Yg-2t for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 23 Oct 2021 20:13:14 +0200 Original-Received: from localhost ([::1]:35776 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1meLW4-00089R-Sh for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 23 Oct 2021 14:13:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:55182) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1meLVv-00086U-9X for bug-gnu-emacs@gnu.org; Sat, 23 Oct 2021 14:13:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:53886) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1meLVu-0006dp-N9 for bug-gnu-emacs@gnu.org; Sat, 23 Oct 2021 14:13:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1meLVu-0005dG-Iv for bug-gnu-emacs@gnu.org; Sat, 23 Oct 2021 14:13:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 23 Oct 2021 18:13:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34588 X-GNU-PR-Package: emacs Original-Received: via spool by 34588-submit@debbugs.gnu.org id=B34588.163501272721587 (code B ref 34588); Sat, 23 Oct 2021 18:13:02 +0000 Original-Received: (at 34588) by debbugs.gnu.org; 23 Oct 2021 18:12:07 +0000 Original-Received: from localhost ([127.0.0.1]:37199 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1meLV1-0005c7-2A for submit@debbugs.gnu.org; Sat, 23 Oct 2021 14:12:07 -0400 Original-Received: from mail-pj1-f49.google.com ([209.85.216.49]:37655) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1meLUu-0005b5-UY for 34588@debbugs.gnu.org; Sat, 23 Oct 2021 14:12:02 -0400 Original-Received: by mail-pj1-f49.google.com with SMTP id t5-20020a17090a4e4500b001a0a284fcc2so8168364pjl.2 for <34588@debbugs.gnu.org>; Sat, 23 Oct 2021 11:12:00 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:in-reply-to:references:user-agent :mime-version:date:message-id:subject:to:cc; bh=lUi52LoED6GjZwRJUdQj8w/FRKG9EiRt5Ay0zN3OYWo=; b=HaDvw8cXRnbkEcl1lwh/Une88CqlidHQNGHL5UG6YP0dtC/LEJSXqLcXTs8AT++dIq zVPfnySDhc86uZ2T0QIDVFIn8X0paXQp53Zwg1IBHKgrAsnuv/nX1q6oihfJD2xAhRLr EmiOo//ujWPtlUVicZaKllvLZquMwrq6O8B6XE5FMt8VxstPgMDEDcWZxGckHfe6EiQ6 DDD3MMtjYuEbTs4YqGq4DyGjW6ODm3sKFJumVVJD9Jw5pUR7L4FivztKVZheeYgSoexc 0Fzd3OpLl6D9xtA7tHV30wqGLnN6rVnj1Hm7zGfM2Wpg3yMyLOvzAaBnkMSUM3I6BAf2 n36Q== X-Gm-Message-State: AOAM531uLaLWjYnFGWlhWGNiT50fC2KQ/nxErI7MsD9bA7kW2MP3fuMl ycHQklVT82b9XzZ0xbfu43j+1JVlvgyxD4HGn9Q= X-Google-Smtp-Source: ABdhPJwI58/tpSb4VOHrUObNYa+B2dxxcWE9QPdApRLbJkoZJfyeacrIzdPCr7LhYxYeSu54iQLygZpgpzY3m5nlTyg= X-Received: by 2002:a17:90b:17d2:: with SMTP id me18mr23147021pjb.132.1635012715191; Sat, 23 Oct 2021 11:11:55 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sat, 23 Oct 2021 11:11:54 -0700 In-Reply-To: (Richard Stallman's message of "Thu, 21 Feb 2019 21:06:08 -0500") 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:218019 Archived-At: close 34588 28.1 thanks martin rudalics writes: >> Maybe Richard meant we should document that something should _not_ be >> called "-hook" when it is called with >> `run-hook-with-args-until-success'? That _would_ have answered my >> question, and stating that as a convention would make sense to me. > > The Elisp manual already says that as > > If the hook variable's name does not end with `-hook', that > indicates it is probably an "abnormal hook". That means the hook > functions are called with arguments, or their return values are used in > some way. The hook's documentation says how the functions are called. > You can use `add-hook' to add a function to an abnormal hook, but you > must write the function to follow the hook's calling convention. By > convention, abnormal hook names end in `-functions'. > > and > > The variables whose names end in `-functions' are usually "abnormal > hooks" (some old code may also use the deprecated `-hooks' suffix); > their values are lists of functions, but these functions are called in > a special way (they are passed arguments, or their return values are > used). The variables whose names end in `-function' have single > functions as their values. > > and for 'write-contents-functions' it says that > > If any of the functions in this hook returns non-`nil', the file > is considered already written and the rest are not called and > neither are the functions in `write-file-functions'. > > so the naming convention is preserved and everything should have been > clear. I believe that due to how the documentation is written, > readers intuitively pay less attention to the "or their return values > are used in some way" and "or their return values are used" phrases. I clarified this to: "That means one of two things: either that the hook functions are called with arguments, or that their their return values are used in some way." And: "Their values are lists of functions, but these functions are called in a special way: they are either passed arguments, or their return values are used in some way." This change has been pushed to emacs-28 (commit 4fd5c8df67). I believe this is sufficiently clear, so I'm closing this bug report. Feel free to install any further tweaks. Thanks.