From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Re: Undocumented hyperlinks in doc strings. Date: Mon, 13 Oct 2003 22:23:45 -0500 (CDT) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200310140323.h9E3Njf05047@raven.dms.auburn.edu> References: <200310090050.h990oIa15681@raven.dms.auburn.edu> <200310100327.h9A3REl20310@raven.dms.auburn.edu> <200310120334.h9C3Ygk26986@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1066102405 16769 80.91.224.253 (14 Oct 2003 03:33:25 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 14 Oct 2003 03:33:25 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Tue Oct 14 05:33:23 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1A9Fw3-0007WS-00 for ; Tue, 14 Oct 2003 05:33:23 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A9Fw3-0000ev-00 for ; Tue, 14 Oct 2003 05:33:23 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A9FsK-0002hp-0b for emacs-devel@quimby.gnus.org; Mon, 13 Oct 2003 23:29:32 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1A9Fry-0002g6-5p for emacs-devel@gnu.org; Mon, 13 Oct 2003 23:29:10 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1A9FrR-0002Sn-Qn for emacs-devel@gnu.org; Mon, 13 Oct 2003 23:29:08 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A9Fqw-00025h-0A; Mon, 13 Oct 2003 23:28:06 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id h9E3S4AJ005536; Mon, 13 Oct 2003 22:28:04 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id h9E3Njf05047; Mon, 13 Oct 2003 22:23:45 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: rms@gnu.org In-reply-to: (message from Richard Stallman on Mon, 13 Oct 2003 01:03:05 -0400) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:17072 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:17072 Richard Stallman wrote: In as far as the first one goes, one could replace the occurrences of [ \t\n]+ and [ \t\n]* (the latter probably would have to be changed to [ \t\n]+ anyway, for consistency) in my patch by [ \n]. (If one does not allow multiple spaces, it seems consistent not to allow tab either.) That would mean that the author would have to be careful about "space related sloppiness" like trailing whitespace or an inadvertent inappropriate double space inside a sentence. That is true. I am not sure which approach would actually do a better job in practice. I would be leaning toward keeping [ \t\n]+, although this is a close call and I am not really sure either. There is some more strange behavior in connection with these hyperlinks. Evaluate (defvar sillyvar nil "Documents the strange behavior of `button'. Also, the symbol `tool-bar-mode' and dynamic `use-mouse-action'.") and do C-h v sillyvar. Then in the *Help* buffer click with mouse-2 on `button'. The behavior in the next paragraph seems deliberate. I just describe it in detail, in case it would not be. In spite of my patch, we now see the face documentation of `button'. That is because, in the absence of a hyperlink, mouse-2 is bound to `help-follow-mouse' which will follow and list all available documentation regardless of any convention. `help-make-xrefs' is not involved here. Mouse-2 also will follow `tool-bar-mode' in spite of the `symbol' in front of it. (The `symbol' prevents the making of a hyperlink for the following symbol, but does not actually prevent mouse-2 from listing all available documentation for that symbol.) Mouse-2 will also follow the following `and', viewing it as the lisp special form. All the above is probably deliberate, but now things get more "exotic". In the face documentation of `button' click on [back]. Of course, we get the doc string of sillyvar back, but it has changed. Previously, `button' and `use-mouse-action' were not underlined, because they were not hyperlinks, but now they are underlined. One can check that neither `button' not `use-mouse-action' are defined as variables, before clicking once more on `button' with mouse-2 and getting: button's value is # Not documented as a variable. [back] What happens is that button is not defined as a global variable. However, when clicking on a hyperlink, mouse-2 is bound to `push-button', whose code contains: (let ((button (button-at (or pos (point))))) (if (not button) nil (button-activate button use-mouse-action) t)))) `button' and `use-mouse-action' now are dynamically bound. When we clicked on `back' in the face documentation `button' and `use-mouse-action' were dynamically `boundp' when `help-make-xrefs' was deciding whether a hyperlink should be made for them. In the *Help* buffer they were not boundp any more, but once we actually clicked on the hyperlink, `button' was boundp again, and its dynamic binding got displayed. `button' being a text property, we can not just avoid to use it in documentation strings. What about replacing: ((boundp sym) (help-xref-button 8 'help-variable sym)) by: ((and (boundp sym) (not (string= sym "button"))) (help-xref-button 8 'help-variable sym)) That would still make a hyperlink for: the variable `button' but not for a mere: `button'. `button' appears to be the only real problem. I do not believe that `use-mouse-action' is likely to actually occur in hyperlinks. Hence, it might not be worth worrying about. Out of curiosity one can click on the `use-mouse-action' hyperlink anyway and get: use-mouse-action's value is t Not documented as a variable. [back] Sincerely, Luc.