[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Online help and help-for-help improvements
|
From: |
Kim F. Storm |
|
Subject: |
Online help and help-for-help improvements |
|
Date: |
Thu, 28 Feb 2008 13:04:11 +0100 |
|
User-agent: |
Gnus/5.11 (Gnus v5.11) Emacs/22.1 (gnu/linux) |
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 <address@hidden>
* 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 <address@hidden>
* 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)
--- 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)
***************
*** 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 address@hidden; 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
! address@hidden; 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 <address@hidden> http://www.cua.dk