Online help and help-for-help improvements

Online help and help-for-help improvements

[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

Re: Online help and help-for-help improvements

[Juri Linkov]

> 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.

Yes, it is much easier to read now.  It removes command names
(not useful for users who read this help page), but maybe we
could put these command names on the `help-echo' property
over the help key letters?

Also using the verb `Display' at the beginning of every line
seems too superfluous, i.e. instead of

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."

can we have something like

C-a         Information about Emacs.
C-c         Emacs copying permission (GNU General Public License).
C-d         Instructions for debugging GNU Emacs.
C-e         External packages and information about Emacs.
C-f         Emacs FAQ.
C-m         How to order printed Emacs manuals.
C-n         News of recent Emacs changes.
C-o         Emacs ordering and distribution information.
C-p         Info about Emacs problems.
C-t         Emacs TODO list.
C-w         Information on absence of warranty for GNU Emacs."



> 	* startup.el (startup-echo-area-message): Check for about-emacs.

Could you please fix this also in the Emacs 22 branch?

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Online help and help-for-help improvements

[Chong Yidong]

storm@cua.dk (Kim F. Storm) writes:

> 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?

Looks OK to me, but the renamed functions should be accompanied by
aliases for the old names.

Re: Online help and help-for-help improvements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

>> 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.
>
> Yes, it is much easier to read now.  It removes command names
> (not useful for users who read this help page), but maybe we
> could put these command names on the `help-echo' property
> over the help key letters?

Maybe, but I don't see what benefit that would do.

> Also using the verb `Display' at the beginning of every line
> seems too superfluous, i.e. instead of

I'll change that.

>> 	* startup.el (startup-echo-area-message): Check for about-emacs.
>
> Could you please fix this also in the Emacs 22 branch?

I'd prefer if someone else would install the patch on the branch:


2008-02-28  Kim F. Storm  <storm@cua.dk>

	* startup.el (startup-echo-area-message): Check for about-emacs.


*** startup.el	18 Feb 2008 11:31:27 +0100	1.480
--- startup.el	28 Feb 2008 12:58:49 +0100	
***************
*** 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 \


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Juri Linkov]

>>> 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.
>>
>> Yes, it is much easier to read now.  It removes command names
>> (not useful for users who read this help page), but maybe we
>> could put these command names on the `help-echo' property
>> over the help key letters?
>
> Maybe, but I don't see what benefit that would do.
>
>> Also using the verb `Display' at the beginning of every line
>> seems too superfluous, i.e. instead of
>
> I'll change that.
>
>>> 	* startup.el (startup-echo-area-message): Check for about-emacs.
>>
>> Could you please fix this also in the Emacs 22 branch?
>
> I'd prefer if someone else would install the patch on the branch:

Installed.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Online help and help-for-help improvements

[Kim F. Storm]

Chong Yidong <cyd@stupidchicken.com> writes:

> Looks OK to me, but the renamed functions should be accompanied by
> aliases for the old names.

Who would use the old names?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

>>>> 	* startup.el (startup-echo-area-message): Check for about-emacs.
>>>
> Installed.

Thank you.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Chong Yidong]

storm@cua.dk (Kim F. Storm) writes:

> Chong Yidong <cyd@stupidchicken.com> writes:
>
>> Looks OK to me, but the renamed functions should be accompanied by
>> aliases for the old names.
>
> Who would use the old names?

According to Google, for example, there is a package called
neophyte.el that creates advice for describe-project, which you've
renamed to describe-gnu-project.

Re: Online help and help-for-help improvements

[Kim F. Storm]

Chong Yidong <cyd@stupidchicken.com> writes:

> According to Google, for example, there is a package called
> neophyte.el that creates advice for describe-project, which you've
> renamed to describe-gnu-project.

Ok, I'll add the aliases.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Reiner Steib]

On Fri, Feb 29 2008, Chong Yidong wrote:

> According to Google, for example, there is a package called
> neophyte.el that creates advice for describe-project, which you've
> renamed to describe-gnu-project.

If we talk about <http://web.springies.com/~ats/emacs/neophyte.el>,
IMHO there's no need to introduce compatibility aliases for external
packages that have been not been updated since more than 10 years[1].

Are there other packages that use the old names?

Bye, Reiner.

[1] Last modified 1996 according to `neophyte-version'.

    The download site written in the comment isn't even available anymore:
    ;; The latest version of this code is available from
    ;; ftp://hubert.wustl.edu/pub/elisp .
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Online help and help-for-help improvements

[Juri Linkov]

>> According to Google, for example, there is a package called
>> neophyte.el that creates advice for describe-project, which you've
>> renamed to describe-gnu-project.
>
> If we talk about <http://web.springies.com/~ats/emacs/neophyte.el>,
> IMHO there's no need to introduce compatibility aliases for external
> packages that have been not been updated since more than 10 years[1].
>
> Are there other packages that use the old names?

ISTR there was a policy to declare a function obsolete in the upcoming
release, that gives enough time for authors to fix external packages,
and after this release delete it in the next release.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Online help and help-for-help improvements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> ISTR there was a policy to declare a function obsolete in the upcoming
> release, that gives enough time for authors to fix external packages,
> and after this release delete it in the next release.

Where do you declare it obsolete ?  In a news group ?

How long before a release should you do that?

One way would be to simply add aliases for the new names
now for 22.2 release, and declare the old names obsolete

Then we can remove the old names from 23.x now.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Stefan Monnier]

> One way would be to simply add aliases for the new names
> now for 22.2 release, and declare the old names obsolete

That's fine, as long as we're sure that the new names are preferable.


        Stefan

Re: Online help and help-for-help improvements

[Kim F. Storm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> One way would be to simply add aliases for the new names
>> now for 22.2 release, and declare the old names obsolete
>
> That's fine, as long as we're sure that the new names are preferable.

They are!  Consider (new vs. old):

describe-gnu-project
         vs.
describe-project
         - which project?

(Compare to e.g. "describe-bindings" which describes current bindings,
 so I would expect describe-project describes the "current project"
 whatever that might be...)


view-emacs-todo
         vs.
view-todo
         - confusing wrt todo-mode.

Also, there's already view-emacs-FAQ, view-emacs-news, etc.
so view-emacs-todo is the correct name.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Stefan Monnier]

>>> One way would be to simply add aliases for the new names
>>> now for 22.2 release, and declare the old names obsolete
>> 
>> That's fine, as long as we're sure that the new names are preferable.

> They are!

Great!


        Stefan

Re: Online help and help-for-help improvements

[Kim F. Storm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>>> One way would be to simply add aliases for the new names
>>>> now for 22.2 release, and declare the old names obsolete
>>> 

Here's a patch for the Emacs 22 branch:

Index: etc/NEWS
===================================================================
RCS file: /cvsroot/emacs/emacs/etc/NEWS,v
retrieving revision 1.1465.2.66
diff -u -r1.1465.2.66 NEWS
--- etc/NEWS	3 Mar 2008 03:28:33 -0000	1.1465.2.66
+++ etc/NEWS	4 Mar 2008 18:11:41 -0000
@@ -42,8 +42,22 @@
 
 ** Support for GNU/kFreeBSD (GNU userland and FreeBSD kernel) was added.
 
 * Changes in Emacs 22.2
 
+** `describe-project' is renamed to `describe-gnu-project'.
+
+** `view-todo' is renamed to `view-emacs-news'.
+
 ** `find-name-dired' now uses -iname rather than -name
 for case-insensitive filesystems.  The default behavior is determined
 by the value of `read-file-name-completion-ignore-case'; if you don't

Index: lisp/help.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help.el,v
retrieving revision 1.327.2.4
diff -u -r1.327.2.4 help.el
--- lisp/help.el	7 Jan 2008 02:44:43 -0000	1.327.2.4
+++ lisp/help.el	4 Mar 2008 18:13:05 -0000
@@ -53,8 +53,8 @@
     (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-p" 'describe-gnu-project)
+    (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.
@@ -292,7 +292,10 @@
   (view-file (expand-file-name "COPYING" data-directory))
   (goto-char (point-min)))
 
-(defun describe-project ()
+(defalias 'describe-project 'describe-gnu-project
+  "Display info on the GNU project.
+This function is deprecated.  Use `describe-gnu-project' instead.")
+(defun describe-gnu-project ()
   "Display info on the GNU project."
   (interactive)
   (view-file (expand-file-name "THE-GNU-PROJECT" data-directory))
@@ -396,7 +399,10 @@
 	   (point)))))))
 
 
-(defun view-todo (&optional arg)
+(defalias 'view-todo 'view-emacs-todo
+  "Display the Emacs TODO list.
+This function is deprecated.  Use `view-emacs-todo' instead.")
+(defun view-emacs-todo (&optional arg)
   "Display the Emacs TODO list."
   (interactive "P")
   (view-file (expand-file-name "TODO" data-directory)))

Index: lisp/menu-bar.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/menu-bar.el,v
retrieving revision 1.302.2.8
diff -u -r1.302.2.8 menu-bar.el
--- lisp/menu-bar.el	7 Jan 2008 02:44:30 -0000	1.302.2.8
+++ lisp/menu-bar.el	4 Mar 2008 18:13:41 -0000
@@ -1341,7 +1341,7 @@
 	      :help "Read the Introduction to Emacs Lisp Programming"))
 
 (define-key menu-bar-help-menu [about-gnu-project]
-  '(menu-item "About GNU" describe-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

Index: lisp/startup.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/startup.el,v
retrieving revision 1.436.2.15
diff -u -r1.436.2.15 startup.el
--- lisp/startup.el	2 Mar 2008 16:17:57 -0000	1.436.2.15
+++ lisp/startup.el	4 Mar 2008 18:14:03 -0000
@@ -1148,7 +1148,7 @@
 	   '("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))
+	 '("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 "
@@ -1207,7 +1207,7 @@
 	   '("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))
+	 '("GNU" (lambda (button) (describe-gnu-project))
 	   "Display info on the GNU project.")))
      " operating system.\n"
      :face (lambda ()
@@ -1222,7 +1222,7 @@
      (lambda () emacs-copyright)
      "\n\n"
      :face variable-pitch
-     :link ("GNU and Freedom" (lambda (button) (describe-project)))
+     :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 "
@@ -1816,7 +1816,7 @@
   (insert "To follow a link, click Mouse-1 on it, or move to it and type RET.\n\n")
 
   (insert-button "GNU and Freedom"
-		 'action (lambda (button) (describe-project))
+		 'action (lambda (button) (describe-gnu-project))
 		 'follow-link t)
   (insert "\t\tWhy we developed GNU Emacs and the GNU system\n")
 

Index: man/help.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/Attic/help.texi,v
retrieving revision 1.53.2.1
diff -u -r1.53.2.1 help.texi
--- man/help.texi	9 Jan 2008 04:08:27 -0000	1.53.2.1
+++ man/help.texi	4 Mar 2008 18:14:27 -0000
@@ -606,7 +606,7 @@
 @kindex C-h C-n
 @findex view-emacs-news
 @kindex C-h C-p
-@findex describe-project
+@findex describe-gnu-project
 @kindex C-h C-t
 @findex view-emacs-todo
 @kindex C-h C-w
@@ -629,9 +629,9 @@
 recent version of Emacs (@code{view-emacs-news}).
 @item C-h C-p
 Display general information about the GNU Project
-(@code{describe-project}).
+(@code{describe-gnu-project}).
 @item C-h C-t
-Display the Emacs to-do list (@code{view-todo}).
+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

Re: Online help and help-for-help improvements

[Juri Linkov]

> +(defalias 'describe-project 'describe-gnu-project
> +  "Display info on the GNU project.
> +This function is deprecated.  Use `describe-gnu-project' instead.")
> [...]
> +(defalias 'view-todo 'view-emacs-todo
> +  "Display the Emacs TODO list.
> +This function is deprecated.  Use `view-emacs-todo' instead.")

Did you forget about `define-obsolete-function-alias'? ;)

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Online help and help-for-help improvements

[Reiner Steib]

On Tue, Mar 04 2008, Kim F. Storm wrote:

> Here's a patch for the Emacs 22 branch:
[...]
> +** `view-todo' is renamed to `view-emacs-news'.
            ^^^^                            ^^^^

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Online help and help-for-help improvements

[Chong Yidong]

storm@cua.dk (Kim F. Storm) writes:

> Here's a patch for the Emacs 22 branch:

Looks good.  Please check it in ASAP.

Thanks.

Re: Online help and help-for-help improvements

[Nick Roberts]

Chong Yidong writes:
 > storm@cua.dk (Kim F. Storm) writes:
 > 
 > > Here's a patch for the Emacs 22 branch:
 > 
 > Looks good.  Please check it in ASAP.

But Juri and Reiner have just said why it doesn't look good, and this is for
the release branch.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: Online help and help-for-help improvements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> Did you forget about `define-obsolete-function-alias'? ;)

Cannot forget what you don't know :-)

I'll change it -- thank you.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Kim F. Storm]

Reiner Steib <reinersteib+gmane@imap.cc> writes:

>> +** `view-todo' is renamed to `view-emacs-news'.

Thanks -- I'll fix that.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Kim F. Storm]

Chong Yidong <cyd@stupidchicken.com> writes:

> storm@cua.dk (Kim F. Storm) writes:
>
>> Here's a patch for the Emacs 22 branch:
>
> Looks good.  Please check it in ASAP.

Done - with the changes proposed by Juri and Reinar.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Online help and help-for-help improvements

[Chong Yidong]

storm@cua.dk (Kim F. Storm) writes:

>>> Here's a patch for the Emacs 22 branch:
>>
>> Looks good.  Please check it in ASAP.
>
> Done - with the changes proposed by Juri and Reinar.

Thanks.