* lisp/help-fns.el (describe-command): New command.
(help-fns--describe-function-or-command-prompt): New helper
function to prompt for a function or function. (Bug#46627)
(describe-function): Use above new helper function.
* lisp/help.el (help-map): Bind above new command to `C-h x'.
(help-for-help): Add this new command to the help summary.
* lisp/menu-bar.el (menu-bar-describe-menu): Add the new command to
the help menu.
* doc/emacs/help.texi (Help Summary, Name Help): Document
'describe-command', and update documentation on 'describe-function'.
* etc/tutorials/TUTORIAL: Change reference from 'describe-function' to
'describe-command'.
(@code{view-echo-area-messages}). @xref{Misc Help}.
@item C-h f @var{function} @key{RET}
Display documentation on the Lisp function named @var{function}
-(@code{describe-function}). Since commands are Lisp functions,
-this works for commands too. @xref{Name Help}.
+(@code{describe-function}). Since commands are Lisp functions, this
+works for commands too, but you can also use @code{C-h x}. @xref{Name Help}.
@item C-h h
Display the @file{HELLO} file, which shows examples of various character
sets.
@item C-h w @var{command} @key{RET}
Show which keys run the command named @var{command} (@code{where-is}).
@xref{Key Help}.
+@item C-h x @var{command} @key{RET}
+Display documentation on the named @var{command}
+(@code{describe-command}). @xref{Name Help}.
@item C-h C @var{coding} @key{RET}
Describe the coding system @var{coding}
(@code{describe-coding-system}). @xref{Coding Systems}.
@node Name Help
@section Help by Command or Variable Name
-@kindex C-h f
-@findex describe-function
- @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
-displays the documentation of Lisp function @var{function}, in a
-window. Since commands are Lisp functions, you can use this method to
-view the documentation of any command whose name you know. For
-example,
+@kindex C-h x
+@findex describe-command
+ @kbd{C-h x @var{command} @key{RET}} (@code{describe-command})
+displays the documentation of the named @var{command}, in a
+window. For example,
@example
-C-h f auto-fill-mode @key{RET}
+C-h x auto-fill-mode @key{RET}
@end example
@noindent
-displays the documentation of @code{auto-fill-mode}. This is the only
-way to get the documentation of a command that is not bound to any key
+displays the documentation of @code{auto-fill-mode}. This is how you
+would get the documentation of a command that is not bound to any key
(one which you would normally run using @kbd{M-x}).
- @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp
-program. For example, if you have just written the expression
+@kindex C-h f
+@findex describe-function
+ @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
+displays the documentation of Lisp @var{function}. This command is
+intended for Lisp functions that you use in a Lisp program. For
+example, if you have just written the expression
@code{(make-vector len)} and want to check that you are using
-@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
-Because @kbd{C-h f} allows all function names, not just command names,
-you may find that some of your favorite completion abbreviations that
-work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is
-unique among command names may not be unique among all function names.
+@code{make-vector} properly, type @w{@kbd{C-h f make-vector @key{RET}}}.
+Additionally, since all commands are Lisp functions, you can also use
+this command to view the documentation of any command.
If you type @kbd{C-h f @key{RET}}, it describes the function called
by the innermost Lisp expression in the buffer around point,
(That name appears as the default while you enter the argument.) For
example, if point is located following the text @samp{(make-vector
(car x)}, the innermost list containing point is the one that starts
-with @samp{(make-vector}, so @kbd{C-h f @key{RET}} describes the
+with @samp{(make-vector}, so @w{@kbd{C-h f @key{RET}}} describes the
function @code{make-vector}.
@kbd{C-h f} is also useful just to verify that you spelled a
---
*** 'g' ('revert-buffer') in 'help-mode' no longer requires confirmation.
++++
+*** New command 'describe-command' shows help for a command.
+This can be used instead of 'describe-function' for interactive
+commands and is globally bound to `C-h x'.
+
+++
*** New command 'describe-keymap' describes keybindings in a keymap.
Here are some other useful C-h options:
- C-h f Describe a function. You type in the name of the
- function.
+ C-h x Describe a command. You type in the name of the
+ command.
->> Try typing C-h f previous-line <Return>.
+>> Try typing C-h x previous-line <Return>.
This displays all the information Emacs has about the
function which implements the C-p command.
Functions on `help-fns-describe-function-functions' can use this
to get buffer-local values.")
+(defun help-fns--describe-function-or-command-prompt (&optional want-command)
+ "Prompt for a function from `describe-function' or `describe-command'.
+If optional argument WANT-COMMAND is non-nil, prompt for an
+interactive command."
+ (let* ((fn (if want-command
+ (caar command-history)
+ (function-called-at-point)))
+ (prompt (format-prompt (if want-command
+ "Describe command"
+ "Describe function")
+ fn))
+ (enable-recursive-minibuffers t)
+ (val (completing-read
+ prompt
+ #'help--symbol-completion-table
+ (lambda (f) (if want-command
+ (commandp f)
+ (or (fboundp f) (get f 'function-documentation))))
+ t nil nil
+ (and fn (symbol-name fn)))))
+ (unless (equal val "")
+ (setq fn (intern val)))
+ ;; These error messages are intended to be less technical for the
+ ;; `describe-command' case, as they are directed at users that are
+ ;; not necessarily ELisp programmers.
+ (unless (and fn (symbolp fn))
+ (user-error (if want-command
+ "You didn't specify a command's symbol"
+ "You didn't specify a function symbol")))
+ (unless (or (fboundp fn) (get fn 'function-documentation))
+ (user-error (if want-command
+ "Symbol is not a command: %s"
+ "Symbol's function definition is void: %s")
+ fn))
+ (list fn)))
+
;;;###autoload
(defun describe-function (function)
"Display the full documentation of FUNCTION (a symbol).
When called from lisp, FUNCTION may also be a function object."
- (interactive
- (let* ((fn (function-called-at-point))
- (enable-recursive-minibuffers t)
- (val (completing-read
- (format-prompt "Describe function" fn)
- #'help--symbol-completion-table
- (lambda (f) (or (fboundp f) (get f 'function-documentation)))
- t nil nil
- (and fn (symbol-name fn)))))
- (unless (equal val "")
- (setq fn (intern val)))
- (unless (and fn (symbolp fn))
- (user-error "You didn't specify a function symbol"))
- (unless (or (fboundp fn) (get fn 'function-documentation))
- (user-error "Symbol's function definition is void: %s" fn))
- (list fn)))
+ (interactive (help-fns--describe-function-or-command-prompt))
;; We save describe-function-orig-buffer on the help xref stack, so
;; it is restored by the back/forward buttons. 'help-buffer'
(describe-function-1 function)
(with-current-buffer standard-output
;; Return the text we displayed.
- (buffer-string))))
- ))
+ (buffer-string))))))
+;;;###autoload
+(defun describe-command (command)
+ "Display the full documentation of COMMAND (a symbol).
+When called from lisp, COMMAND may also be a function object."
+ (interactive (help-fns--describe-function-or-command-prompt 'is-command))
+ (describe-function command))
;; Could be this, if we make symbol-file do the work below.
;; (defun help-C-file-name (subr-or-var kind)
(define-key map "t" 'help-with-tutorial)
(define-key map "v" 'describe-variable)
(define-key map "w" 'where-is)
+ (define-key map "x" 'describe-command)
(define-key map "q" 'help-quit)
map)
"Keymap for characters following the Help key.")
"Search for commands (see also \\[apropos])")
("apropos-documentation"
"Search documentation of functions, variables, and other items")
+ ("describe-command" "Show help for command")
("describe-function" "Show help for function")
("describe-variable" "Show help for variable")
("describe-symbol" "Show help for function or variable"))
(bindings--define-key menu [describe-function]
'(menu-item "Describe Function..." describe-function
:help "Display documentation of function/command"))
+ (bindings--define-key menu [describe-command]
+ '(menu-item "Describe Command..." describe-command
+ :help "Display documentation of command"))
(bindings--define-key menu [shortdoc-display-group]
'(menu-item "Function Group Overview..." shortdoc-display-group
:help "Display a function overview for a specific topic"))
projects / emacs.git / commitdiff