From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#25794: 24.5; Doc of `Info-selection-hook' Date: Sun, 19 Feb 2017 09:28:27 -0800 (PST) Message-ID: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1487525357 30937 195.159.176.226 (19 Feb 2017 17:29:17 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 19 Feb 2017 17:29:17 +0000 (UTC) To: 25794@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Feb 19 18:29:12 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cfVIK-0007NF-4k for geb-bug-gnu-emacs@m.gmane.org; Sun, 19 Feb 2017 18:29:08 +0100 Original-Received: from localhost ([::1]:34580 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cfVIO-0008TO-St for geb-bug-gnu-emacs@m.gmane.org; Sun, 19 Feb 2017 12:29:12 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38540) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cfVII-0008TH-7n for bug-gnu-emacs@gnu.org; Sun, 19 Feb 2017 12:29:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cfVIE-0007s3-9o for bug-gnu-emacs@gnu.org; Sun, 19 Feb 2017 12:29:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:48229) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cfVIE-0007ry-6Z for bug-gnu-emacs@gnu.org; Sun, 19 Feb 2017 12:29:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cfVID-0001bu-UP for bug-gnu-emacs@gnu.org; Sun, 19 Feb 2017 12:29:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 19 Feb 2017 17:29:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 25794 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.14875253296169 (code B ref -1); Sun, 19 Feb 2017 17:29:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 19 Feb 2017 17:28:49 +0000 Original-Received: from localhost ([127.0.0.1]:46428 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cfVI0-0001bR-Pi for submit@debbugs.gnu.org; Sun, 19 Feb 2017 12:28:49 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:47495) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cfVHy-0001bE-Tw for submit@debbugs.gnu.org; Sun, 19 Feb 2017 12:28:47 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cfVHs-0007jS-Gv for submit@debbugs.gnu.org; Sun, 19 Feb 2017 12:28:41 -0500 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:52744) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cfVHs-0007jE-EZ for submit@debbugs.gnu.org; Sun, 19 Feb 2017 12:28:40 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38457) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cfVHr-0008Rq-9U for bug-gnu-emacs@gnu.org; Sun, 19 Feb 2017 12:28:40 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cfVHn-0007hE-C6 for bug-gnu-emacs@gnu.org; Sun, 19 Feb 2017 12:28:39 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:18412) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cfVHn-0007gl-3y for bug-gnu-emacs@gnu.org; Sun, 19 Feb 2017 12:28:35 -0500 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v1JHSX6o017914 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 19 Feb 2017 17:28:33 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v1JHSWMn028484 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 19 Feb 2017 17:28:33 GMT Original-Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v1JHSWeE015506 for ; Sun, 19 Feb 2017 17:28:32 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x 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: 208.118.235.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:129541 Archived-At: This is a hook: a variable used by users to automatically invoke functions when something happens. Sure, it's true that "when something happens" means, more precisely, at certain places in the implementation (code). But a hook is a user-level thing, and hooks should be, first of all, presented to users as such. Their descriptions should make clear to users when they are used. That's not really the case for `Info-selection-hook', IMO. Why? Because users do not know what "when `Info-select-node' is called" means. They know nothing about non-interactive function `Info-select-node'. (Also, the doc string says "Hooks run" - that should be singular.) `Info-select-node' is an implementation detail. It is not at all clear to users when that function gets called. The doc for the hook should, first of all, say when the hook is run in terms of user-observable and user-understandable behavior. It is fine to ALSO then say something like "More precisely, the hook is run when `Info-select-node' is called." That can perhaps help users who consult the code to know better what the behavior is. In user-level terms, when is this hook run? Perhaps just say that it is run whenever an Info node (or page) is visited. Yes, it applies also to reversion and other revisits of a node, and it applies also to visiting a TOC, which is not really a node. Still, visiting a node is the best thing I can think of that describes the behavior to users. Perhaps you have a better idea? I think, too, that it would be OK to say that the hook runs _after_ a node is visited or near the end of visiting a node. But please say something that is more helpful than just "Hooks run when `Info-select-node' is called." In GNU Emacs 24.5.1 (i686-pc-mingw32) of 2015-04-11 on LEG570 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/usr --host=3Di686-pc-mingw32'