From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: xah lee Newsgroups: gmane.emacs.bugs Subject: bug#2473: usability issues on emacs's describe-mode Date: Wed, 25 Feb 2009 11:40:24 -0800 Message-ID: <3FD7E241-BEE3-43D6-B7F6-79A3758562FB@xahlee.org> Reply-To: xah lee , 2473@emacsbugs.donarmstrong.com NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 (Apple Message framework v753.1) Content-Type: text/plain; charset=UTF-8; delsp=yes; format=flowed Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1235637928 31416 80.91.229.12 (26 Feb 2009 08:45:28 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 26 Feb 2009 08:45:28 +0000 (UTC) To: bug-gnu-emacs@gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Feb 26 09:46:43 2009 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1LcbsT-00063g-2I for geb-bug-gnu-emacs@m.gmane.org; Thu, 26 Feb 2009 09:45:59 +0100 Original-Received: from localhost ([127.0.0.1]:48565 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Lcbr8-0005TY-Ax for geb-bug-gnu-emacs@m.gmane.org; Thu, 26 Feb 2009 03:44:34 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1LcPyt-0006Rk-CF for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 15:03:47 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1LcPyp-0006QG-Ol for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 15:03:46 -0500 Original-Received: from [199.232.76.173] (port=38315 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1LcPyp-0006QA-K6 for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 15:03:43 -0500 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:46577) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1LcPyo-0002of-5D for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 15:03:43 -0500 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n1PK3bU2030609; Wed, 25 Feb 2009 12:03:37 -0800 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.13.8/8.13.8/Submit) id n1PJj3ms024672; Wed, 25 Feb 2009 11:45:03 -0800 X-Loop: owner@emacsbugs.donarmstrong.com Resent-From: xah lee Resent-To: bug-submit-list@donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Wed, 25 Feb 2009 19:45:03 +0000 Resent-Message-ID: Resent-Sender: owner@emacsbugs.donarmstrong.com X-Emacs-PR-Message: report 2473 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by submit@emacsbugs.donarmstrong.com id=B.123559089124305 (code B ref -1); Wed, 25 Feb 2009 19:45:03 +0000 Original-Received: (at submit) by emacsbugs.donarmstrong.com; 25 Feb 2009 19:41:31 +0000 X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. Original-Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n1PJfQ1V024297 for ; Wed, 25 Feb 2009 11:41:27 -0800 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1LcPdF-0002is-FP for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 14:41:25 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1LcPdA-0002gx-2u for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 14:41:24 -0500 Original-Received: from [199.232.76.173] (port=41663 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1LcPd9-0002gr-PP for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 14:41:19 -0500 Original-Received: from mx20.gnu.org ([199.232.41.8]:53785) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1LcPd9-0005ay-5e for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 14:41:19 -0500 Original-Received: from mout.perfora.net ([74.208.4.195]) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1LcPcy-0008Gf-Nm for bug-gnu-emacs@gnu.org; Wed, 25 Feb 2009 14:41:08 -0500 Original-Received: from [192.168.1.3] (c-24-6-175-142.hsd1.ca.comcast.net [24.6.175.142]) by mrelay.perfora.net (node=mrus1) with ESMTP (Nemesis) id 0MKpCa-1LcPcp3ODZ-0001DG; Wed, 25 Feb 2009 14:41:02 -0500 X-Mailer: Apple Mail (2.753.1) X-Provags-ID: V01U2FsdGVkX1/5SLyOczPE0nDtqNpOJDA+4VQNm9Hp8zF2RO9 PdBjGky2hiv7pXPBpi4+d9jyX6eWbM9q/Gul7/m9hXJgAoRy+C 7GU2WsG3muMZAQnTAP59A== X-detected-kernel: by mx20.gnu.org: Genre and OS details not recognized. X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 3) Resent-Date: Wed, 25 Feb 2009 15:03:46 -0500 X-Mailman-Approved-At: Thu, 26 Feb 2009 03:44:26 -0500 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:25724 Archived-At: hi guys, Some problem i think on emacs describe-mode. http://xahlee.org/emacs/modernization_mode_doc.html Here's a plain text version. Following the text is some proposed code =20= solution (beta) that fixes 2 of the issues. -------------------------- Usability Problems Of Emacs's Mode Documentation Xah Lee, 2009-02-06 This page details some usability problems of Emacs's inline =20 documentation for its major-mode. Emacs has a command describe-mode (Ctrl+h m) that shows the inline =20 doc for the current mode. For example, if you are coding in =20 javascript, html, perl, or python, you can type =E2=80=9CCtrl+h m=E2=80=9D= to =20 quickly see a summarization of what functionalities you have while =20 coding in that lang, and what are the keyboard shortcuts. This is really a wonderful feature, but it is a shame that it has =20 some major usability problem, almost making this feature not usable. =20 The following gives some details. For example, when in w3m mode, which is a mode that allows you to =20 browse the web pages, i type =E2=80=9CCtrl+h m=E2=80=9D to read the = online doc =20 about the mode's features. The result page starts like this: Enabled minor modes: Abbrev Auto-Compression Blink-Cursor Command-Frequency Command-Frequency-Autosave Delete-Selection Desktop-Save Encoded-Kbd File-Name-Shadow Font-Lock Global-Font-=20 Lock Line-Number Menu-Bar Mouse-Wheel Recentf Shell-Dirtrack Show-Paren Tooltip Transient-Mark Unify-8859-On-Encoding Utf-Translate-Cjk (Information about these minor modes follows the major mode info.) It began by listing =E2=80=9Cminor-modes=E2=80=9D. (What Emacs calls = =E2=80=9Cminor =20 modes=E2=80=9D, is similar in concept to modern app's preference = settings =20 and add-ons features.) Here's a excerpt of the minor mode doc that comes after the major =20 mode doc: ^L Abbrev minor mode (indicator Abbrev): Toggle Abbrev mode in the current buffer. With optional argument ARG, turn abbrev mode on if ARG is positive, otherwise turn it off. In Abbrev mode, inserting an abbreviation causes it to expand and be replaced by its expansion. ^L Auto-Compression minor mode (no indicator): Toggle automatic file compression and uncompression. With prefix argument ARG, turn auto compression on if positive, =20 else off. Return the new status of auto compression (non-nil means on). ^L Blink-Cursor minor mode (no indicator): Toggle blinking cursor mode. With a numeric argument, turn blinking cursor mode on if ARG is =20 positive, otherwise turn it off. When blinking cursor mode is enabled, the cursor of the selected window blinks. Note that this command is effective only when Emacs displays through a window system, because then Emacs does its own cursor display. On a text-only terminal, this is not implemented. ^L Cua minor mode (no indicator): Toggle CUA key-binding mode. When enabled, using shifted movement keys will activate the region (and highlight the region using `transient-mark-mode'), and typed text replaces the active selection. Most of the minor modes, filled with emacs-specific technicalities =20 and terminologies, are not something emacs users need to know daily. =20 When user calls describe-mode, most of the time she really want to =20 know what functionality and shortcuts the major mode provides. But =20 these minor modes often fills more than 60% of the page. To me, it is really a pain to read (a emacs user for 10 years), and i =20= have learned the habit not even seeing them. I imagine it is very =20 confusing to new emacs users. Imagine, it has to annoy users about discussion such as Blink-Cursor, =20= Tooltip, Menu-Bar, Mouse-Wheel, Transient-Mark, Delete-Selection, =20 Font-Lock, Line-Number. Each of these is at least one paragraph long, =20= and some are emacs's non-intuitive and weired tech jargons. For =20 example, the standard feature of having selected text highlighted, is =20= in emacs called transient-mark-mode. The standard feature of typing =20 overriding selected text, is in emacs tech jargon called delete-=20 selection-mode. The standard feature of copy/cut/paste keys, is in =20 emacs called cua-mode. Syntax highlighting is called font-lock-mode. Does user really need to know, that he has Blinking Cursor on? And a =20 user needs to be told of the fact he has mouse wheel support on? And =20 menu bar, tooltip, syntax highlighting? Do users need explanation =20 what these do too? The emacs minor mode, also includes proper features such as: Show-=20 Paren, Recentf, Desktop-Save, Abbrev, Yas/Minor ... etc. For example, =20= show-paren-mode highlight matching parenthesis. =E2=80=9Crecentf-mode=E2=80= =9D =20 lets user open recently opened files. =E2=80=9Cdesktop-save-mode=E2=80=9D = =20 preserves opened files when emacs restarts. It is nice to be able to see what features are currently on, and what =20= extra functionality it supports, but perhaps a separate command =20 describe-minor-modes would be better. Minor mode listing also include a bunch that shows some technical =20 issues of emacs's current state that has little to do with daily use =20 of emacs. For example, it shows Shell-Dirtrack, Auto-Compression, =20 Encoded-Kbd, File-Name-Shadow, Unify-8859-On-Encoding, Utf-Translate-=20 Cjk. I have used emacs daily for 10 years, half of the minor mode =20 showing up in describe-mode i don't even know what exactly they are. Also, the page litters =E2=80=9C^L=E2=80=9D char (ascii 12) through out. = The =20 =E2=80=9C^L=E2=80=9D is a page break marker. Such practice is a = convention in the =20 1980s. Almost no software today does this, and very few professional =20 programers today understand what it is. This adds to the =20 incomprehensibility. I think the major usability problem with describe-mode is the listing =20= of minor modes. Though, the major mode's inline doc could also use =20 some improvement. Here's a excerpt of the inline doc for w3m: w3m mode: Major mode for browsing web. RET Display the page pointed to by the link under point. =20 You may use the prefix arg `2' or `C-u C-u' to make a new session. If w3m-use-form is t, `RET' and `' enable you =20 to enter forms. You may use the prefix arg `2' or `C-u C-u' to make a =20 new session. Display the page of the link in a new session. If the region is active, visit all the links within the =20 region. Display the page of the link in a new session by mouse. C-c C-c Submit the form at point. R Reload the current page. r Redisplay the current page. C t Redisplay the page, specifying a content type. C c Redisplay the current page, specifying a charset. C C Redisplay the current page and reset the user-specified =20= charset and content type. The notation for keyboard shortcuts, such as =E2=80=9CC-u C-u=E2=80=9D, = =E2=80=9CRET=E2=80=9D, =20 are hard to read. It becomes more confusing when there are shortcuts =20 that doesn't use a modifier such as =E2=80=9CC t=E2=80=9D. The = =E2=80=9C=E2=80=9D =20 and =E2=80=9CS-kp-enter=E2=80=9D are especially cryptic. Suggestions * describe-mode should just show the inline doc for the major mode. * Add a link to the bottom that point to the full doc of the =20 mode, if it exists. (the link may be to info doc, or call browse-url =20 to open a html doc on local disk, or to a url online of the mode's =20 doc website) * Get rid of convention of using ^L (ascii 12) for page break =20 marker. * Add a link at the bottom, to a page that shows inline doc of =20 minor modes. * Use curly quotes =E2=80=9C=E2=80=9D instead of the 1980's ascii = kludge `'. For detail about the key notation that adds up readability, see: =20 Emacs's M-=E2=80=B9key=E2=80=BA Notation vs Alt+=E2=80=B9key=E2=80=BA = Notation. The use of backtick char ` and single quote char ' for =E2=80=9Cmatching = =20 quotes=E2=80=9D is a 1980's kludge. They also adds to the readability = problem. It would also be helpful, if the keys are rendered as buttons. Note =20 that the button rendering is used in the help files in MS Windows and =20= Mac OS X too. And in Wikipedia's articles related to keys, it is also =20= used thru-out. e.g. Table of keyboard shortcuts. Here's a sample output for comparison: w3m mode: Major mode for browsing web. Enter Display the page pointed to by the link under point. You may use the prefix arg =E2=80=9C2=E2=80=9D or =E2=80=9CCtrl+u = Ctrl+u=E2=80=9D to make =20 a new session. If w3m-use-form is t, =E2=80=9CEnter=E2=80=9D and =E2=80=9Cmouse = middle button=E2=80=9D =20 enable you to enter forms. You may use the prefix arg =E2=80=9C2=E2=80=9D or =E2=80=9CCtrl+u = Ctrl+u=E2=80=9D to make =20 a new session. Keypad Shift+Enter Display the page of the link in a new session. If the region is active, visit all the links within the region. Shift+Mouse Middle Button Display the page of the link in a new =20= session by mouse. Ctrl+c Ctrl+c Submit the form at point. R Reload the current page. r Redisplay the current page. C t Redisplay the page, specifying a content type. C c Redisplay the current page, specifying a charset. C C Redisplay the current page and reset the user-specified =20= charset and content type. ------------------------- ;; code by Kevin Rodgers. 2009-02-25 (defun describe-major-mode () "Show inline doc for current major-mode." (interactive) (describe-function major-mode)) ;; display page delimiter =E2=80=9C^L=E2=80=9D as a horizontal line. = Code by =20 S=C3=A9bastien Vauban. 2009-02-25 (or standard-display-table (setq standard-display-table (make-display-table))) (aset standard-display-table ?\f (vconcat "\n" (make-vector 60 ?-) "^L=20= \n")) ;; Display the =E2=80=9C^L=E2=80=9D page break mark as a horizontal line ;; from http://www.emacswiki.org/emacs/OverlayControlL , 2009-02-25 ;; code by Andre Riemann (add-hook 'after-change-major-mode-hook (lambda () (font-lock-add-keywords nil `((,page-delimiter ;; variable with the regexp (usually "^\f" or =20= "^^L") 0 (prog1 nil ;; don't display ^L (compose-region (match-beginning 0) (match-end 0) "") ;; make an overlay (like in hl-line) (let ((pdl (make-overlay (line-beginning-position) (line-beginning-position 2)))) ;; :background has to be different from the background =20 color ;; gray1 here is just a little different from black (overlay-put pdl 'face '(:underline "gray30" :background =20= "gray1")) (overlay-put pdl 'modification-hooks ;; these arguments are received from =20 modification-hooks '((lambda (overlay after-p begin end =20 &optional length) (delete-overlay overlay)))) (overlay-put pdl 'insert-in-front-hooks '((lambda (overlay after-p begin end =20 &optional length) (delete-overlay overlay)))))) t))))) Xah =E2=88=91 http://xahlee.org/ =E2=98=84=