From 6a570beb34d22f428f92bd1899dec55b63940e8b Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Fri, 19 Feb 2021 18:21:23 +0100 Subject: [PATCH] Add new help command 'describe-command' * 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. (describe-function): Use above new helper function. * lisp/help.el (help-map): Bind above new command to `C-h x'. (help-for-help-internal): Add this new binding 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-function', and update documentation on 'describe-command'. * etc/tutorials/TUTORIAL: Change reference from 'describe-function' to 'describe-command'. --- doc/emacs/help.texi | 47 +++++++++++++++++--------------- etc/NEWS | 4 +++ etc/tutorials/TUTORIAL | 6 ++-- lisp/help-fns.el | 62 ++++++++++++++++++++++++++++++------------ lisp/help.el | 4 ++- lisp/menu-bar.el | 3 ++ 6 files changed, 82 insertions(+), 44 deletions(-) diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 81cdeb4be5..1d0a65b8b1 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -107,8 +107,8 @@ Help Summary (@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. @@ -154,6 +154,9 @@ Help Summary @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}. @@ -233,40 +236,40 @@ Key Help @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. +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, @emph{provided} that function name is a valid, defined Lisp function. (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 -function @code{make-vector}. +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 function @code{make-vector}. @kbd{C-h f} is also useful just to verify that you spelled a function name correctly. If the minibuffer prompt for @kbd{C-h f} diff --git a/etc/NEWS b/etc/NEWS index ee8a68a259..9f84fc6c72 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -857,6 +857,10 @@ skipped. --- *** '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' that describes any +function. It is globally bound to `C-h x'. + +++ *** New command 'describe-keymap' describes keybindings in a keymap. diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL index 6194e55ea3..dcdb61f23e 100644 --- a/etc/tutorials/TUTORIAL +++ b/etc/tutorials/TUTORIAL @@ -1038,10 +1038,10 @@ then type C-x 1. 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 . +>> Try typing C-h x previous-line . This displays all the information Emacs has about the function which implements the C-p command. diff --git a/lisp/help-fns.el b/lisp/help-fns.el index ceb6bc0901..043c989946 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -174,26 +174,47 @@ describe-function-orig-buffer 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 valid command name" + "You didn't specify a function symbol"))) + (unless (or (fboundp fn) (get fn 'function-documentation)) + (user-error (if want-command + "No such 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' @@ -223,9 +244,14 @@ describe-function (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) diff --git a/lisp/help.el b/lisp/help.el index 084e941549..daeca2b406 100644 --- a/lisp/help.el +++ b/lisp/help.el @@ -106,6 +106,7 @@ help-map (define-key map "t" 'help-with-tutorial) (define-key map "w" 'where-is) (define-key map "v" 'describe-variable) + (define-key map "x" 'describe-command) (define-key map "q" 'help-quit) map) "Keymap for characters following the Help key.") @@ -192,7 +193,7 @@ 'help (defalias 'help-for-help 'help-for-help-internal) ;; It can't find this, but nobody will look. (make-help-screen help-for-help-internal - (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?") + (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvwx.] C-[cdefmnoptw] or ?") ;; Don't purecopy this one, because it's not evaluated (it's ;; directly used as a docstring in a function definition, so it'll ;; be moved to the DOC file anyway: no need for purecopying it). @@ -231,6 +232,7 @@ 'help-for-help 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). +x COMMAND Display documentation for the given command. . Display any available local help at point in the echo area. C-a Information about Emacs. diff --git a/lisp/menu-bar.el b/lisp/menu-bar.el index 133df65cbc..0e634cc4a0 100644 --- a/lisp/menu-bar.el +++ b/lisp/menu-bar.el @@ -1882,6 +1882,9 @@ menu-bar-describe-menu (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")) -- 2.30.0