* Online help and help-for-help improvements
@ 2008-02-28 12:04 Kim F. Storm
2008-02-28 21:04 ` Juri Linkov
2008-02-28 21:08 ` Chong Yidong
0 siblings, 2 replies; 24+ messages in thread
From: Kim F. Storm @ 2008-02-28 12:04 UTC (permalink / raw)
To: emacs-devel
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 12:04 Online help and help-for-help improvements Kim F. Storm
@ 2008-02-28 21:04 ` Juri Linkov
2008-02-28 22:49 ` Kim F. Storm
2008-02-28 21:08 ` Chong Yidong
1 sibling, 1 reply; 24+ messages in thread
From: Juri Linkov @ 2008-02-28 21:04 UTC (permalink / raw)
To: Kim F. Storm; +Cc: emacs-devel
> 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/
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 21:04 ` Juri Linkov
@ 2008-02-28 22:49 ` Kim F. Storm
2008-02-28 23:01 ` Juri Linkov
0 siblings, 1 reply; 24+ messages in thread
From: Kim F. Storm @ 2008-02-28 22:49 UTC (permalink / raw)
To: Juri Linkov; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 22:49 ` Kim F. Storm
@ 2008-02-28 23:01 ` Juri Linkov
2008-02-28 23:12 ` Kim F. Storm
0 siblings, 1 reply; 24+ messages in thread
From: Juri Linkov @ 2008-02-28 23:01 UTC (permalink / raw)
To: Kim F. Storm; +Cc: emacs-devel
>>> 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/
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 12:04 Online help and help-for-help improvements Kim F. Storm
2008-02-28 21:04 ` Juri Linkov
@ 2008-02-28 21:08 ` Chong Yidong
2008-02-28 23:01 ` Kim F. Storm
1 sibling, 1 reply; 24+ messages in thread
From: Chong Yidong @ 2008-02-28 21:08 UTC (permalink / raw)
To: Kim F. Storm; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 21:08 ` Chong Yidong
@ 2008-02-28 23:01 ` Kim F. Storm
2008-02-28 23:48 ` Chong Yidong
0 siblings, 1 reply; 24+ messages in thread
From: Kim F. Storm @ 2008-02-28 23:01 UTC (permalink / raw)
To: Chong Yidong; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 23:01 ` Kim F. Storm
@ 2008-02-28 23:48 ` Chong Yidong
2008-02-29 12:22 ` Kim F. Storm
2008-03-01 10:33 ` Reiner Steib
0 siblings, 2 replies; 24+ messages in thread
From: Chong Yidong @ 2008-02-28 23:48 UTC (permalink / raw)
To: Kim F. Storm; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 23:48 ` Chong Yidong
@ 2008-02-29 12:22 ` Kim F. Storm
2008-03-01 10:33 ` Reiner Steib
1 sibling, 0 replies; 24+ messages in thread
From: Kim F. Storm @ 2008-02-29 12:22 UTC (permalink / raw)
To: Chong Yidong; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-02-28 23:48 ` Chong Yidong
2008-02-29 12:22 ` Kim F. Storm
@ 2008-03-01 10:33 ` Reiner Steib
2008-03-02 2:59 ` Juri Linkov
1 sibling, 1 reply; 24+ messages in thread
From: Reiner Steib @ 2008-03-01 10:33 UTC (permalink / raw)
To: Chong Yidong; +Cc: emacs-devel, Kim F. Storm
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/
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-01 10:33 ` Reiner Steib
@ 2008-03-02 2:59 ` Juri Linkov
2008-03-03 13:37 ` Kim F. Storm
0 siblings, 1 reply; 24+ messages in thread
From: Juri Linkov @ 2008-03-02 2:59 UTC (permalink / raw)
To: Chong Yidong; +Cc: emacs-devel, Kim F. Storm
>> 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/
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-02 2:59 ` Juri Linkov
@ 2008-03-03 13:37 ` Kim F. Storm
2008-03-03 14:03 ` Stefan Monnier
0 siblings, 1 reply; 24+ messages in thread
From: Kim F. Storm @ 2008-03-03 13:37 UTC (permalink / raw)
To: Juri Linkov; +Cc: Chong Yidong, emacs-devel
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-03 13:37 ` Kim F. Storm
@ 2008-03-03 14:03 ` Stefan Monnier
2008-03-03 23:40 ` Kim F. Storm
0 siblings, 1 reply; 24+ messages in thread
From: Stefan Monnier @ 2008-03-03 14:03 UTC (permalink / raw)
To: Kim F. Storm; +Cc: Juri Linkov, Chong Yidong, emacs-devel
> 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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-03 14:03 ` Stefan Monnier
@ 2008-03-03 23:40 ` Kim F. Storm
2008-03-04 15:49 ` Stefan Monnier
0 siblings, 1 reply; 24+ messages in thread
From: Kim F. Storm @ 2008-03-03 23:40 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Juri Linkov, Chong Yidong, emacs-devel
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-03 23:40 ` Kim F. Storm
@ 2008-03-04 15:49 ` Stefan Monnier
2008-03-04 18:17 ` Kim F. Storm
0 siblings, 1 reply; 24+ messages in thread
From: Stefan Monnier @ 2008-03-04 15:49 UTC (permalink / raw)
To: Kim F. Storm; +Cc: Juri Linkov, Chong Yidong, emacs-devel
>>> 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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-04 15:49 ` Stefan Monnier
@ 2008-03-04 18:17 ` Kim F. Storm
2008-03-04 19:29 ` Juri Linkov
` (2 more replies)
0 siblings, 3 replies; 24+ messages in thread
From: Kim F. Storm @ 2008-03-04 18:17 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Juri Linkov, Chong Yidong, emacs-devel
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-04 18:17 ` Kim F. Storm
@ 2008-03-04 19:29 ` Juri Linkov
2008-03-05 0:29 ` Kim F. Storm
2008-03-04 19:40 ` Reiner Steib
2008-03-04 21:37 ` Chong Yidong
2 siblings, 1 reply; 24+ messages in thread
From: Juri Linkov @ 2008-03-04 19:29 UTC (permalink / raw)
To: Kim F. Storm; +Cc: Chong Yidong, Stefan Monnier, emacs-devel
> +(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/
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-04 18:17 ` Kim F. Storm
2008-03-04 19:29 ` Juri Linkov
@ 2008-03-04 19:40 ` Reiner Steib
2008-03-05 0:30 ` Kim F. Storm
2008-03-04 21:37 ` Chong Yidong
2 siblings, 1 reply; 24+ messages in thread
From: Reiner Steib @ 2008-03-04 19:40 UTC (permalink / raw)
To: Kim F. Storm; +Cc: emacs-devel
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/
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Online help and help-for-help improvements
2008-03-04 18:17 ` Kim F. Storm
2008-03-04 19:29 ` Juri Linkov
2008-03-04 19:40 ` Reiner Steib
@ 2008-03-04 21:37 ` Chong Yidong
2008-03-04 21:48 ` Nick Roberts
2008-03-06 0:09 ` Kim F. Storm
2 siblings, 2 replies; 24+ messages in thread
From: Chong Yidong @ 2008-03-04 21:37 UTC (permalink / raw)
To: Kim F. Storm; +Cc: Juri Linkov, Stefan Monnier, emacs-devel
storm@cua.dk (Kim F. Storm) writes:
> Here's a patch for the Emacs 22 branch:
Looks good. Please check it in ASAP.
Thanks.
^ permalink raw reply [flat|nested] 24+ messages in thread
end of thread, other threads:[~2008-03-06 15:18 UTC | newest]
Thread overview: 24+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2008-02-28 12:04 Online help and help-for-help improvements Kim F. Storm
2008-02-28 21:04 ` Juri Linkov
2008-02-28 22:49 ` Kim F. Storm
2008-02-28 23:01 ` Juri Linkov
2008-02-28 23:12 ` Kim F. Storm
2008-02-28 21:08 ` Chong Yidong
2008-02-28 23:01 ` Kim F. Storm
2008-02-28 23:48 ` Chong Yidong
2008-02-29 12:22 ` Kim F. Storm
2008-03-01 10:33 ` Reiner Steib
2008-03-02 2:59 ` Juri Linkov
2008-03-03 13:37 ` Kim F. Storm
2008-03-03 14:03 ` Stefan Monnier
2008-03-03 23:40 ` Kim F. Storm
2008-03-04 15:49 ` Stefan Monnier
2008-03-04 18:17 ` Kim F. Storm
2008-03-04 19:29 ` Juri Linkov
2008-03-05 0:29 ` Kim F. Storm
2008-03-04 19:40 ` Reiner Steib
2008-03-05 0:30 ` Kim F. Storm
2008-03-04 21:37 ` Chong Yidong
2008-03-04 21:48 ` Nick Roberts
2008-03-06 0:09 ` Kim F. Storm
2008-03-06 15:18 ` Chong Yidong
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.