From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: storm@cua.dk (Kim F. Storm) Newsgroups: gmane.emacs.devel Subject: Online help and help-for-help improvements Date: Thu, 28 Feb 2008 13:04:11 +0100 Message-ID: <87myplmgn8.fsf@kfs-lx.rd.rdm> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1204200285 8843 80.91.229.12 (28 Feb 2008 12:04:45 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 28 Feb 2008 12:04:45 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Feb 28 13:04:59 2008 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1JUhVQ-0006JQ-P0 for ged-emacs-devel@m.gmane.org; Thu, 28 Feb 2008 13:04:58 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JUhUu-00016a-1y for ged-emacs-devel@m.gmane.org; Thu, 28 Feb 2008 07:04:24 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1JUhUp-00015S-JJ for emacs-devel@gnu.org; Thu, 28 Feb 2008 07:04:19 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1JUhUk-00010z-Mi for emacs-devel@gnu.org; Thu, 28 Feb 2008 07:04:18 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JUhUk-00010t-KW for emacs-devel@gnu.org; Thu, 28 Feb 2008 07:04:14 -0500 Original-Received: from mail-relay.sonofon.dk ([212.88.64.25]) by monty-python.gnu.org with smtp (Exim 4.60) (envelope-from ) id 1JUhUj-0000wO-JT for emacs-devel@gnu.org; Thu, 28 Feb 2008 07:04:14 -0500 Original-Received: (qmail 31489 invoked from network); 28 Feb 2008 12:04:11 -0000 Original-Received: from unknown (HELO kfs-lx.rd.rdm.cua.dk) (213.83.150.21) by 0 with SMTP; 28 Feb 2008 12:04:11 -0000 User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1 (gnu/linux) X-detected-kernel: by monty-python.gnu.org: FreeBSD 4.6-4.9 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:90717 Archived-At: Here is a patch which improves the online help in the following ways: - the output from C-h C-h is much easier to read and use. - better mnemonics for some common help items: C-h C-d => DEBUG (new) C-h C-e => extra aka. MORE.STUFF (new) C-h C-o => ordering (DISTRIB) [was C-h C-d] C-h C-p => PROBLEMS [was C-h C-e] C-h g => THE-GNU-PROJECT (illogical on C-h C-p, but C-h C-g is no good) Code simplified by using new view-help-file function. Comments? 2008-02-28 Kim F. Storm * help.el (view-emacs-todo): Rename from view-todo. (describe-gnu-project): Rename from describe-project. Users changed. (view-help-file): New helper function. (describe-distribution, describe-copying, describe-gnu-project) (view-todo, view-order-manuals, view-emacs-problems): Use it. (view-emacs-debugging, view-external-packages): New commands. (help-map): Move describe-distribution to C-h C-o (ordering). Move view-emacs-problems to C-h C-p (problems). Bind view-emacs-debugging to C-h C-d (debugging). Bind view-external-packages to C-h C-e (extras). (help-for-help-internal): Cleanup and align descriptions. Remove command names to reduce clutter. * startup.el (startup-echo-area-message): Check for about-emacs. 2008-02-28 Kim F. Storm * help.texi (Help Files): Move describe-gnu-project to C-h g. Move describe-distribution to C-h C-o. Move view-emacs-problems to C-h C-p. Add view-emacs-debugging on C-h C-d. Add view-external-packages on C-h C-e. Add view-order-manuals on C-h C-m. Index: help.el =================================================================== RCS file: /cvsroot/emacs/emacs/lisp/help.el,v retrieving revision 1.336 diff -c -r1.336 help.el *** help.el 12 Feb 2008 07:10:49 -0000 1.336 --- help.el 28 Feb 2008 11:55:30 -0000 *************** *** 55,61 **** ;; `with-output-to-temp-buffer'. `with-help-window' has this point ;; nowhere before exiting. Currently used by `view-lossage' to assert ;; that the last keystrokes are always visible. ! (defvar help-window-point-marker (make-marker) "Marker to override default `window-point' of `help-window'.") (defvar help-map --- 55,61 ---- ;; `with-output-to-temp-buffer'. `with-help-window' has this point ;; nowhere before exiting. Currently used by `view-lossage' to assert ;; that the last keystrokes are always visible. ! (defvar help-window-point-marker (make-marker) "Marker to override default `window-point' of `help-window'.") (defvar help-map *************** *** 68,80 **** (define-key map "\C-a" 'about-emacs) (define-key map "\C-c" 'describe-copying) ! (define-key map "\C-d" 'describe-distribution) ! (define-key map "\C-e" 'view-emacs-problems) (define-key map "\C-f" 'view-emacs-FAQ) (define-key map "\C-m" 'view-order-manuals) (define-key map "\C-n" 'view-emacs-news) ! (define-key map "\C-p" 'describe-project) ! (define-key map "\C-t" 'view-todo) (define-key map "\C-w" 'describe-no-warranty) ;; This does not fit the pattern, but it is natural given the C-\ command. --- 68,81 ---- (define-key map "\C-a" 'about-emacs) (define-key map "\C-c" 'describe-copying) ! (define-key map "\C-d" 'view-emacs-debugging) ! (define-key map "\C-e" 'view-external-packages) (define-key map "\C-f" 'view-emacs-FAQ) (define-key map "\C-m" 'view-order-manuals) (define-key map "\C-n" 'view-emacs-news) ! (define-key map "\C-o" 'describe-distribution) ! (define-key map "\C-p" 'view-emacs-problems) ! (define-key map "\C-t" 'view-emacs-todo) (define-key map "\C-w" 'describe-no-warranty) ;; This does not fit the pattern, but it is natural given the C-\ command. *************** *** 93,98 **** --- 94,100 ---- (define-key map "d" 'apropos-documentation) (define-key map "e" 'view-echo-area-messages) (define-key map "f" 'describe-function) + (define-key map "g" 'describe-gnu-project) (define-key map "h" 'view-hello-file) (define-key map "i" 'info) *************** *** 201,263 **** (defalias 'help-for-help 'help-for-help-internal) ;; It can't find this, but nobody will look. (make-help-screen help-for-help-internal ! "a b c C e f F i I k C-k l L m p r s t v w C-c C-d C-f C-n C-p C-t C-w . or ? :" "You have typed %THIS-KEY%, the help character. Type a Help option: \(Use SPC or DEL to scroll through this text. Type \\\\[help-quit] to exit the Help command.) ! a command-apropos. Type a list of words or a regexp; it shows a list of ! commands whose names match. See also the apropos command. ! b describe-bindings. Display a table of all key bindings. ! c describe-key-briefly. Type a key sequence; ! it displays the command name run by that key sequence. ! C describe-coding-system. Type the name of the coding system to describe, ! or just RET to describe the ones currently in use. ! d apropos-documentation. Type a pattern (a list of words or a regexp), and ! it shows a list of functions, variables, and other items whose ! documentation matches that pattern. See also the apropos command. ! e view-echo-area-messages. Go to the buffer that logs echo-area messages. ! f describe-function. Type a function name and you see its documentation. ! F Info-goto-emacs-command-node. Type a command name; ! it goes to the on-line manual's section that describes the command. ! h Display the HELLO file which illustrates various scripts. ! i info. The Info documentation reader: read on-line manuals. ! I describe-input-method. Describe a specific input method (if you type ! its name) or the current input method (if you type just RET). ! k describe-key. Type a key sequence; ! it displays the full documentation for that key sequence. ! K Info-goto-emacs-key-command-node. Type a key sequence; ! it goes to the on-line manual's section that describes ! the command bound to that key. ! l view-lossage. Show last 100 characters you typed. ! L describe-language-environment. This describes either a ! specific language environment (if you type its name) ! or the current language environment (if you type just RET). ! m describe-mode. Display documentation of current minor modes, ! and the current major mode, including their special commands. ! n view-emacs-news. Display news of recent Emacs changes. ! p finder-by-keyword. Find packages matching a given topic keyword. ! r info-emacs-manual. Display the Emacs manual in Info mode. ! s describe-syntax. Display contents of syntax table, plus explanations. ! S info-lookup-symbol. Type a symbol; it goes to that symbol in the ! on-line manual for the programming language used in this buffer. ! t help-with-tutorial. Select the Emacs learn-by-doing tutorial. ! v describe-variable. Type name of a variable; ! it displays the variable's documentation and value. ! w where-is. Type a command name; it displays which keystrokes ! invoke that command. ! . display-local-help. Display any available local help at point ! in the echo area. ! ! C-a Display information about Emacs. ! C-c Display Emacs copying permission (GNU General Public License). ! C-d Display Emacs ordering information. ! C-e Display info about Emacs problems. ! C-f Display the Emacs FAQ. ! C-m Display how to order printed Emacs manuals. ! C-n Display news of recent Emacs changes. ! C-p Display information about the GNU project. ! C-t Display the Emacs TODO list. ! C-w Display information on absence of warranty for GNU Emacs." help-map) --- 203,254 ---- (defalias 'help-for-help 'help-for-help-internal) ;; It can't find this, but nobody will look. (make-help-screen help-for-help-internal ! "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?" "You have typed %THIS-KEY%, the help character. Type a Help option: \(Use SPC or DEL to scroll through this text. Type \\\\[help-quit] to exit the Help command.) ! a PATTERN Show a list of commands whose name matches the PATTERN (a list ! of words or a regexp). See also the `apropos' command. ! b Display a table of all key bindings. ! c KEYS Display the command name run by the given key sequence. ! C CODING Describe the given coding system, or RET for current ones. ! d PATTERN Show a list of functions, variables, and other items whose ! documentation matches the PATTERN (a list of words or a regexp). ! e Go to the buffer that logs echo-area messages (*Messages*). ! f FUNCTION Display documentation for the given function. ! F COMMAND Show the on-line manual's section that describes the command. ! g Display information about the GNU project. ! h Display the HELLO file which illustrates various scripts. ! i Start the Info documentation reader: read on-line manuals. ! I METHOD Describe a specific input method, or RET for current. ! k KEYS Display the full documentation for the key sequence. ! K KEYS Show the on-line manual's section for the command bound to KEYS. ! l Show last 100 characters you typed (lossage). ! L LANG-ENV Describes a specific language environment, or RET for current. ! m Display documentation of current minor modes and current major mode, ! including their special commands. ! n Display news of recent Emacs changes. ! p TOPIC Find packages matching a given topic keyword. ! r Display the Emacs manual in Info mode. ! s Display contents of current syntax table, plus explanations. ! S SYMBOL Show the section for the given symbol in the on-line manual ! for the programming language used in this buffer. ! t Start the Emacs learn-by-doing tutorial. ! v VARIABLE Display the given variable's documentation and value. ! w COMMAND Display which keystrokes invoke the given command (where-is). ! . Display any available local help at point in the echo area. ! ! C-a Display information about Emacs. ! C-c Display Emacs copying permission (GNU General Public License). ! C-d Display instructions for debugging GNU Emacs. ! C-e Display external packages and information about Emacs. ! C-f Display the Emacs FAQ. ! C-m Display how to order printed Emacs manuals. ! C-n Display news of recent Emacs changes. ! C-o Display Emacs ordering and distribution information. ! C-p Display info about Emacs problems. ! C-t Display the Emacs TODO list. ! C-w Display information on absence of warranty for GNU Emacs." help-map) *************** *** 303,324 **** ;;; `User' help functions (defun describe-distribution () "Display info on how to obtain the latest version of GNU Emacs." (interactive) ! (view-file (expand-file-name "DISTRIB" data-directory))) (defun describe-copying () "Display info on how you may redistribute copies of GNU Emacs." (interactive) ! (view-file (expand-file-name "COPYING" data-directory)) ! (goto-char (point-min))) ! (defun describe-project () "Display info on the GNU project." (interactive) ! (view-file (expand-file-name "THE-GNU-PROJECT" data-directory)) ! (goto-char (point-min))) (defun describe-no-warranty () "Display info on all the kinds of warranty Emacs does NOT have." --- 294,318 ---- ;;; `User' help functions + (defun view-help-file (file &optional dir) + (view-file (expand-file-name file (or dir data-directory))) + (goto-address) + (goto-char (point-min))) + (defun describe-distribution () "Display info on how to obtain the latest version of GNU Emacs." (interactive) ! (view-help-file "DISTRIB")) (defun describe-copying () "Display info on how you may redistribute copies of GNU Emacs." (interactive) ! (view-help-file "COPYING")) ! (defun describe-gnu-project () "Display info on the GNU project." (interactive) ! (view-help-file "THE-GNU-PROJECT")) (defun describe-no-warranty () "Display info on all the kinds of warranty Emacs does NOT have." *************** *** 418,427 **** (point))))))) ! (defun view-todo (&optional arg) "Display the Emacs TODO list." (interactive "P") ! (view-file (expand-file-name "TODO" data-directory))) (defun view-echo-area-messages () "View the log of recent echo-area messages: the `*Messages*' buffer. --- 412,421 ---- (point))))))) ! (defun view-emacs-todo (&optional arg) "Display the Emacs TODO list." (interactive "P") ! (view-help-file "TODO")) (defun view-echo-area-messages () "View the log of recent echo-area messages: the `*Messages*' buffer. *************** *** 433,440 **** (defun view-order-manuals () "Display the Emacs ORDERS file." (interactive) ! (view-file (expand-file-name "ORDERS" data-directory)) ! (goto-address)) (defun view-emacs-FAQ () "Display the Emacs Frequently Asked Questions (FAQ) file." --- 427,433 ---- (defun view-order-manuals () "Display the Emacs ORDERS file." (interactive) ! (view-help-file "ORDERS")) (defun view-emacs-FAQ () "Display the Emacs Frequently Asked Questions (FAQ) file." *************** *** 445,451 **** (defun view-emacs-problems () "Display info on known problems with Emacs and possible workarounds." (interactive) ! (view-file (expand-file-name "PROBLEMS" data-directory))) (defun view-lossage () "Display last 100 input keystrokes. --- 438,454 ---- (defun view-emacs-problems () "Display info on known problems with Emacs and possible workarounds." (interactive) ! (view-help-file "PROBLEMS")) ! ! (defun view-emacs-debugging () ! "Display info on how to debug Emacs problems." ! (interactive) ! (view-help-file "DEBUG")) ! ! (defun view-external-packages () ! "Display external packages and information about Emacs." ! (interactive) ! (view-help-file "MORE.STUFF")) (defun view-lossage () "Display last 100 input keystrokes. *** menu-bar.el 24 Feb 2008 20:00:16 +0100 1.319 --- menu-bar.el 28 Feb 2008 12:18:52 +0100 *************** *** 1352,1358 **** :help "Read the Introduction to Emacs Lisp Programming")) (define-key menu-bar-help-menu [about-gnu-project] ! '(menu-item "About GNU" describe-project :help "About the GNU System, GNU Project, and GNU/Linux")) (define-key menu-bar-help-menu [about-emacs] '(menu-item "About Emacs" about-emacs --- 1352,1358 ---- :help "Read the Introduction to Emacs Lisp Programming")) (define-key menu-bar-help-menu [about-gnu-project] ! '(menu-item "About GNU" describe-gnu-project :help "About the GNU System, GNU Project, and GNU/Linux")) (define-key menu-bar-help-menu [about-emacs] '(menu-item "About Emacs" about-emacs *** startup.el 18 Feb 2008 11:31:27 +0100 1.480 --- startup.el 28 Feb 2008 12:58:49 +0100 *************** *** 1180,1186 **** '("GNU/Linux" (lambda (button) (browse-url "http://www.gnu.org/gnu/linux-and-gnu.html")) "Browse http://www.gnu.org/gnu/linux-and-gnu.html") ! '("GNU" (lambda (button) (describe-project)) "Display info on the GNU project"))) " operating system.\n" :face variable-pitch "To quit a partially entered command, type " --- 1180,1186 ---- '("GNU/Linux" (lambda (button) (browse-url "http://www.gnu.org/gnu/linux-and-gnu.html")) "Browse http://www.gnu.org/gnu/linux-and-gnu.html") ! '("GNU" (lambda (button) (describe-gnu-project)) "Display info on the GNU project"))) " operating system.\n" :face variable-pitch "To quit a partially entered command, type " *************** *** 1239,1245 **** '("GNU/Linux" (lambda (button) (browse-url "http://www.gnu.org/gnu/linux-and-gnu.html")) "Browse http://www.gnu.org/gnu/linux-and-gnu.html") ! '("GNU" (lambda (button) (describe-project)) "Display info on the GNU project."))) " operating system.\n" :face (lambda () --- 1239,1245 ---- '("GNU/Linux" (lambda (button) (browse-url "http://www.gnu.org/gnu/linux-and-gnu.html")) "Browse http://www.gnu.org/gnu/linux-and-gnu.html") ! '("GNU" (lambda (button) (describe-gnu-project)) "Display info on the GNU project."))) " operating system.\n" :face (lambda () *************** *** 1265,1271 **** (goto-char (point-min)))) "\tHow to contribute improvements to Emacs\n" "\n" ! :link ("GNU and Freedom" (lambda (button) (describe-project))) "\tWhy we developed GNU Emacs, and the GNU operating system\n" :link ("Absence of Warranty" (lambda (button) (describe-no-warranty))) "\tGNU Emacs comes with " --- 1265,1271 ---- (goto-char (point-min)))) "\tHow to contribute improvements to Emacs\n" "\n" ! :link ("GNU and Freedom" (lambda (button) (describe-gnu-project))) "\tWhy we developed GNU Emacs, and the GNU operating system\n" :link ("Absence of Warranty" (lambda (button) (describe-no-warranty))) "\tGNU Emacs comes with " *************** *** 1871,1877 **** (insert "\tHow to contribute improvements to Emacs\n\n") (insert-button "GNU and Freedom" ! 'action (lambda (button) (describe-project)) 'follow-link t) (insert "\t\tWhy we developed GNU Emacs and the GNU system\n") --- 1871,1877 ---- (insert "\tHow to contribute improvements to Emacs\n\n") (insert-button "GNU and Freedom" ! 'action (lambda (button) (describe-gnu-project)) 'follow-link t) (insert "\t\tWhy we developed GNU Emacs and the GNU system\n") *************** *** 1896,1902 **** (insert "\tBuying printed manuals from the FSF\n")) (defun startup-echo-area-message () ! (if (eq (key-binding "\C-h\C-p") 'describe-project) "For information about GNU Emacs and the GNU system, type C-h C-a." (substitute-command-keys "For information about GNU Emacs and the GNU system, type \ --- 1896,1902 ---- (insert "\tBuying printed manuals from the FSF\n")) (defun startup-echo-area-message () ! (if (eq (key-binding "\C-h\C-a") 'about-emacs) "For information about GNU Emacs and the GNU system, type C-h C-a." (substitute-command-keys "For information about GNU Emacs and the GNU system, type \ *** help.texi 25 Jan 2008 00:03:13 +0100 1.4 --- help.texi 28 Feb 2008 12:53:20 +0100 *************** *** 591,612 **** The Emacs help commands described above display dynamic help based on the current state within Emacs, or refer to manuals. Other help ! commands display pre-written, static help files. These commands all ! have the form @kbd{C-h C-@var{char}}; that is, @kbd{C-h} followed by a ! control character. @kindex C-h C-c @findex describe-copying @kindex C-h C-d ! @findex describe-distribution @kindex C-h C-e ! @findex view-emacs-problems @kindex C-h C-f @findex view-emacs-FAQ @kindex C-h C-n @findex view-emacs-news @kindex C-h C-p ! @findex describe-project @kindex C-h C-t @findex view-emacs-todo @kindex C-h C-w --- 591,619 ---- The Emacs help commands described above display dynamic help based on the current state within Emacs, or refer to manuals. Other help ! commands display pre-written, static help files. ! ! Except for @kbd{C-h g}, these commands all have the form @kbd{C-h ! C-@var{char}}; that is, @kbd{C-h} followed by a control character. @kindex C-h C-c @findex describe-copying @kindex C-h C-d ! @findex view-emacs-debugging @kindex C-h C-e ! @findex view-external-packages @kindex C-h C-f @findex view-emacs-FAQ + @kindex C-h g + @findex describe-gnu-project + @kindex C-h C-m + @findex view-order-manuals @kindex C-h C-n @findex view-emacs-news + @kindex C-h C-o + @findex describe-distribution @kindex C-h C-p ! @findex view-emacs-problems @kindex C-h C-t @findex view-emacs-todo @kindex C-h C-w *************** *** 617,637 **** Display the Emacs copying conditions (@code{describe-copying}). These are the rules under which you can copy and redistribute Emacs. @item C-h C-d ! Display how to download or order the latest version of ! Emacs and other GNU software (@code{describe-distribution}). ! @item C-h C-e ! Display the list of known Emacs problems, sometimes with suggested ! workarounds (@code{view-emacs-problems}). @item C-h C-f Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). @item C-h C-n Display the Emacs ``news'' file, which lists new features in the most recent version of Emacs (@code{view-emacs-news}). @item C-h C-p ! Display general information about the GNU Project ! (@code{describe-project}). @item C-h C-t ! Display the Emacs to-do list (@code{view-todo}). @item C-h C-w Display the full details on the complete absence of warranty for GNU Emacs (@code{describe-no-warranty}). --- 624,649 ---- Display the Emacs copying conditions (@code{describe-copying}). These are the rules under which you can copy and redistribute Emacs. @item C-h C-d ! Display how to debug Emacs problems (@code{view-emacs-debugging}). @item C-h C-f Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). + @item C-h g + Display general information about the GNU Project + (@code{describe-gnu-project}). + @item C-h C-m + Display how to order printed copies of Emacs manuals + (@code{view-order-manuals}). @item C-h C-n Display the Emacs ``news'' file, which lists new features in the most recent version of Emacs (@code{view-emacs-news}). + @item C-h C-o + Display how to order or download the latest version of + Emacs and other GNU software (@code{describe-distribution}). @item C-h C-p ! Display the list of known Emacs problems, sometimes with suggested ! workarounds (@code{view-emacs-problems}). @item C-h C-t ! Display the Emacs to-do list (@code{view-emacs-todo}). @item C-h C-w Display the full details on the complete absence of warranty for GNU Emacs (@code{describe-no-warranty}). -- Kim F. Storm http://www.cua.dk