From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#34588: 27.0.50; Doc of write-contents-functions: arguments? Date: Thu, 21 Feb 2019 10:17:11 +0100 Message-ID: <5C6E6C97.6000605@gmx.at> References: <87bm3715bu.fsf@web.de> <83y36agz88.fsf@gnu.org> <837edthkfd.fsf@gnu.org> <87y369ydil.fsf@web.de> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="206121"; mail-complaints-to="usenet@blaine.gmane.org" Cc: rms@gnu.org, 34588@debbugs.gnu.org To: Michael Heerdegen , Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Feb 21 10:22:09 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gwkYS-000rJE-P4 for geb-bug-gnu-emacs@m.gmane.org; Thu, 21 Feb 2019 10:22:09 +0100 Original-Received: from localhost ([127.0.0.1]:56907 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gwkYR-0002gV-Pv for geb-bug-gnu-emacs@m.gmane.org; Thu, 21 Feb 2019 04:22:07 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:35933) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gwkUW-0008Tr-Vq for bug-gnu-emacs@gnu.org; Thu, 21 Feb 2019 04:18:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gwkUV-0006fb-5U for bug-gnu-emacs@gnu.org; Thu, 21 Feb 2019 04:18:04 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:58186) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gwkUV-0006fX-0m for bug-gnu-emacs@gnu.org; Thu, 21 Feb 2019 04:18:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gwkUU-0001Ik-IC for bug-gnu-emacs@gnu.org; Thu, 21 Feb 2019 04:18:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Feb 2019 09:18: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.15507406514965 (code B ref 34588); Thu, 21 Feb 2019 09:18:02 +0000 Original-Received: (at 34588) by debbugs.gnu.org; 21 Feb 2019 09:17:31 +0000 Original-Received: from localhost ([127.0.0.1]:58952 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gwkTy-0001I0-Rl for submit@debbugs.gnu.org; Thu, 21 Feb 2019 04:17:31 -0500 Original-Received: from mout.gmx.net ([212.227.15.18]:33167) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gwkTw-0001Hm-SG for 34588@debbugs.gnu.org; Thu, 21 Feb 2019 04:17:29 -0500 Original-Received: from [192.168.1.101] ([213.162.73.208]) by mail.gmx.com (mrgmx003 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MJjvw-1gve1E3w96-0017CV; Thu, 21 Feb 2019 10:17:21 +0100 In-Reply-To: <87y369ydil.fsf@web.de> X-Provags-ID: V03:K1:tyRNOmKiX/6wbJnqmLe/V8jYd6+tI597NQvsIrVf9P9IVUlp6rf hJcqJqB4cexH07lw/QVjCpZZ9mfSKKou2HJQu+NS4Wl9xxEK9xkxdDJ1QSfs4YxQN/8stdC /vPJwEpOi2IsJibJM0eE4NmD82OX6tYTfYfsyp6csQmg969ju7sYZv11JL4xHjea7cwnivT PWV7tk/iQyXK5fE5N3Fsg== X-UI-Out-Filterresults: notjunk:1;V03:K0:c/3OZqpjJnw=:/n99gg47p41wN6Cz8H8Eu9 VsoXYILaqp+w4GaVTchmF7wDUoUmeJ7E2v2frC+CyIEAYvOLFeDaJU+YrFN7gpwpjcaxmubxK XqSWmuFK91yhEhOmHUa4xzllF9s9tIMu7wCN6wO+AQtewfqcXgCY4Cq/yNhOIMokGl3WedY9T G1sIhsA8pLivcA5B4Csuc9n+qreZOCz0vtad2BUmwvDXgBDEJYAMpMVi665xs0o3Dcuvh2AyZ Lade7foRzxf26+k5x1PTAPnEupsmLR/U0vd0L3bvaleEQcini+YPD5jQibL9WkTzsnOiBTul+ sYPlR2xa4Ph11mkeWXtl6tBR/IRu4W3y6RQsgPp5xUvyOiLt5jt1giqpu63EqE/n1SLdF0MyR gAydTlyAn3HIv9GiqYQU01eXw4xhxcp3rBL5LCl+j1qcZ7dh1dtotRP6LC9Yx8tjQjMcbkxqk kYCAqevhWtGwmLKq1vM235yDEXzL1qtUeTCq7l+jzzUttSQWmLJMT5twT2R5ESHLEjfvHFo1f CkfCsNZ0CopQSBawBnaKKXWknNFNY0AljBC9Qq/deOwCacYovQcUCp7hwgBNSSreQIhA1Sd/a gINksodYZ5KGMd6N2k1+XPqAN0Fi6cCxaNJrh5YOyPmzDfIhkeqCAScH4/wrzLrCADjtXM3c/ 4t60w+dTlHLdJa3S6bFNQZ1BtOD/zkwut+YHBGQ6yy2MWmM9HG1rhX24hshryNoeKYtxB3JX1 wi6RB0uH7O2CYR1nQdfi9hY1pwA9brRxybxZt4Z5zhbtgL2uXcqXusD0IskoV5KsZiw6smLf X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:155613 Archived-At: > 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. martin