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: C-h help cleanup and improvements Date: Fri, 02 Mar 2007 00:32:51 +0100 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1172791946 27174 80.91.229.12 (1 Mar 2007 23:32:26 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 1 Mar 2007 23:32:26 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Mar 02 00:32:20 2007 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 1HMul0-0008NW-0Q for ged-emacs-devel@m.gmane.org; Fri, 02 Mar 2007 00:32:18 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HMukz-0001Sk-2U for ged-emacs-devel@m.gmane.org; Thu, 01 Mar 2007 18:32:17 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1HMukn-0001Se-UA for emacs-devel@gnu.org; Thu, 01 Mar 2007 18:32:05 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1HMukk-0001SS-PU for emacs-devel@gnu.org; Thu, 01 Mar 2007 18:32:05 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HMukk-0001SP-MY for emacs-devel@gnu.org; Thu, 01 Mar 2007 18:32:02 -0500 Original-Received: from pfepa.post.tele.dk ([195.41.46.235]) by monty-python.gnu.org with esmtp (Exim 4.52) id 1HMukj-0004Um-Tb for emacs-devel@gnu.org; Thu, 01 Mar 2007 18:32:02 -0500 Original-Received: from kfs-l.imdomain.dk.cua.dk (0x503e2644.bynxx19.adsl-dhcp.tele.dk [80.62.38.68]) by pfepa.post.tele.dk (Postfix) with SMTP id 37749FAC02B for ; Fri, 2 Mar 2007 00:32:00 +0100 (CET) User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.94 (gnu/linux) X-detected-kernel: Linux 2.6, seldom 2.4 (older, 4) 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:67174 Archived-At: Having looked at the C-h bindings and the C-h C-h help output, the current text and bindings can be improved. I know this is not the time, but below is a patch which IMO is an improvement. - It cleans up the formatting of the C-h C-h help screen. Specifically, I have removed the comand names, and added explicit arguments where applicable. - It enables goto-address in all static help files. - C-h C-p => PROBLEMS Every time I need to look at the PROBLEMS file, I enter C-h C-p and end up with the GNU Project description. - C-h g => THE-GNU-PROJECT This is about GNU, not "project". So C-h g is better than C-h C-p. It breaks the rule that fixed files should use a C- key, but C-h C-g is not an option. Also, I rename describe-project to describe-gnu-project so that "apropos gnu" will find it. - C-h C-e => MORE.STUFF (external packages) I think this deserves a C-h binding. - C-h C-d => DEBUG I think we need a handy binding for the debugging information. So we can refer users to use C-h C-d instead of viewing the DEBUG file which may be harder to find. - C-h C-o => DISTRIB (ordering information) I think C-o better matches "ordering" (despite the file name) And C-d is now used for debugging above. *** help.el 28 Feb 2007 23:33:46 +0100 1.326 --- help.el 02 Mar 2007 00:12:38 +0100 *************** *** 47,58 **** (define-key map "?" 'help-for-help) (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) --- 47,59 ---- (define-key map "?" 'help-for-help) (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-todo) (define-key map "\C-w" 'describe-no-warranty) *************** *** 72,77 **** --- 73,79 ---- (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) *************** *** 178,239 **** (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-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) --- 180,230 ---- (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-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 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) *************** *** 279,300 **** ;;; `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." --- 270,294 ---- ;;; `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." *************** *** 397,403 **** (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. --- 391,397 ---- (defun view-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. *************** *** 409,416 **** (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." --- 403,409 ---- (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." *************** *** 421,427 **** (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. --- 414,430 ---- (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. -- Kim F. Storm http://www.cua.dk