Online help and help-for-help improvements

[storm@cua.dk (Kim F. Storm)]

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  <storm@cua.dk>

	* 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  <storm@cua.dk>

	* 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-map>\\[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)
  
  \f
--- 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-map>\\[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)
  
  \f
***************
*** 303,324 ****
  \f
  ;;; `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 ----
  \f
  ;;; `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 <storm@cua.dk> http://www.cua.dk