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: Reducing mouse-dependency In Emacs. Date: Sat, 9 Aug 2003 22:42:33 -0500 (CDT) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200308100342.h7A3gXV19877@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1060487103 27748 80.91.224.253 (10 Aug 2003 03:45:03 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 10 Aug 2003 03:45:03 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sun Aug 10 05:45:01 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 19lh8f-0000ey-00 for ; Sun, 10 Aug 2003 05:45:01 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 19lhFI-0001JM-00 for ; Sun, 10 Aug 2003 05:51:52 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.20) id 19lh8a-0008Ms-UV for emacs-devel@quimby.gnus.org; Sat, 09 Aug 2003 23:44:56 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.20) id 19lh8T-0008HR-GE for emacs-devel@gnu.org; Sat, 09 Aug 2003 23:44:49 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.20) id 19lh7x-0007c8-8F for emacs-devel@gnu.org; Sat, 09 Aug 2003 23:44:48 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.20) id 19lh7w-0007c4-W0 for emacs-devel@gnu.org; Sat, 09 Aug 2003 23:44:17 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.9/8.12.9) with ESMTP id h7A3iFeQ006280 for ; Sat, 9 Aug 2003 22:44:15 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id h7A3gXV19877; Sat, 9 Aug 2003 22:42:33 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: emacs-devel@gnu.org 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:15861 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:15861 Text properties like `mouse-face' and `help-echo' are, as presently conceived, not only completely useless to the blind, but to any non mouse oriented user. Unfortunately, quite a bit of documentation relies exclusively on those type of features. A disturbing recent trend, already pointed out by others, is to rely more and more on such mouse-exclusive features. I propose to complement `mouse-face' and `help-echo' with two new text properties, `short-help' and `long-help', which would be strings or evaluate to strings. The idea would be that `help-echo' could rely on the fact that the user is busy using the mouse, `short-help' on the fact that he is using the keyboard (if it makes a difference) and `long-help' would provide more thorough documentation, in a more limited number of situations. `help-echo' would be the one that would always be present if any one of the three is, with `short-help' defaulting to it. Below is a function, `print-local-help' (which could be bound to some help key sequence, say C-h C-l, as implemented below) that first looks for a `short-help' property and, if none is found, for `help-echo' and prints the resulting string in the echo area. `long-help' would be for documenting more elaborate and potentially confusing features like keymap or local-map text-properties. `long-help' would be accessed by giving `print-local-help' a numeric argument. This would display the help in a help-buffer with all the usual features available, including the ones provided by `substitute-command-keys' to print out keymaps, the usual links and a completely functional "back" button. This could be used for all kinds of information, including how to customize the keymap provided by the text property. (Hopefully, that would encourage authors to make sure that such keymaps are easily customizable.) Two other functions `next-help-echo-region' and `previous-help-echo-region' would carry one forward and backward to the beginning of successive regions with non-nil `help-echo' properties. (They are bound to C-tab and C-M-tab in the implementation below.) I believe that this would allow for efficient use of local documentation contained in text properties in a mouse-independent way. If there is interest in the functionality below, then there is one issue I still might need to address. Below, I only handle `help-echo' properties that are strings or evaluate to strings. Strictly speaking, the ((stringp echo) (message echo)) clause should be replaced by an (echo (help-echo-string echo)) clause, where `help-echo-string' would be a function computing the string corresponding to the help-echo property if that property is a function. Is there already an Elisp function with that functionality? If not are help-echo properties that are functions used in practice in ordinary buffers? (The only example I know of is used in the mode line.) If there is interest in the functionality, then I could, if necessary, provide a function of this type myself. I do not necessarily propose to put those functions in a separate file. (It would be too short.) Maybe there is a natural place they could go. ===File ~/local-help.el===================================== ;; The next variable and function are needed for xref info related to ;; print-local-help. (defvar print-local-help-long "") (defun print-local-help-setup-xref () (help-setup-xref (list #'(lambda () (print-local-help-setup-xref) (with-output-to-temp-buffer (help-buffer) (princ (substitute-command-keys print-local-help-long))))) (interactive-p))) (defun print-local-help (arg) "Display help related text or overlay properties. Normally, this displays a short help message in the echo area, namely the value of the `short-help' text or overlay property at point. If there is no `short-help' property at point, but there is a `help-echo' property whose value is a string, then that is printed instead. If a numeric argument is given and there is a `long-help' text or overlay property at point, then that is displayed in a temporary help buffer, after `substitute-command-keys' is called on the string." (interactive "P") (let ((short (get-char-property (point) 'short-help)) (echo (get-char-property (point) 'help-echo))) (setq print-local-help-long (get-char-property (point) 'long-help)) (print-local-help-setup-xref) (cond ((and arg print-local-help-long) (with-output-to-temp-buffer (help-buffer) (princ (substitute-command-keys print-local-help-long)) (print-help-return-message))) (short (message short)) ((stringp echo) (message echo)) (print-local-help-long (message (substitute-command-keys "Only long help is available. Type C-u \\[print-local-help]"))) (t (message "No local help at point"))))) (defun next-help-echo-region () "Go to the start of the next region with non-nil help-echo property. Adjacent areas with different non-nil help-echo properties are considered different regions." (interactive) (let ((pos (next-single-char-property-change (point) 'help-echo))) (if (get-char-property pos 'help-echo) (goto-char pos) (setq pos (next-single-char-property-change pos 'help-echo)) (if (= pos (point-max)) (message "No further help-echo regions in this buffer") (goto-char pos))))) (defun previous-help-echo-region () "Move back to the start of a region with non-nil help-echo property. Adjacent areas with different non-nil help-echo properties are considered different regions." (interactive) (let ((pos (previous-single-char-property-change (point) 'help-echo))) (if (get-char-property pos 'help-echo) (goto-char pos) (setq pos (previous-single-char-property-change pos 'help-echo)) (if (get-char-property pos 'help-echo) (goto-char pos) (message "No prior help-echo regions in this buffer"))))) (global-set-key "\C-h\C-l" 'print-local-help) (global-set-key [C-tab] 'next-help-echo-region) (global-set-key [C-M-tab] 'previous-help-echo-region) ============================================================