Commit 6c1c3204 authored by Stefan Kangas's avatar Stefan Kangas
Browse files

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.  (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'.
parent c842399e
Pipeline #10598 failed with stages
in 9 minutes and 57 seconds
......@@ -107,8 +107,8 @@ Display the @file{*Messages*} buffer
(@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 @@ Display the documentation of the Lisp variable @var{var}
@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,31 +236,31 @@ the button.
@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,
......@@ -265,7 +268,7 @@ 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
......
......@@ -1007,6 +1007,11 @@ GTK toolkit, this is only true if 'x-gtk-use-system-tooltips' is t.
---
*** '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.
......
......@@ -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 <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.
......
......@@ -174,26 +174,47 @@ with the current prefix. The files are chosen according to
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'
......@@ -223,9 +244,14 @@ When called from lisp, FUNCTION may also be a function object."
(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)
......
......@@ -106,6 +106,7 @@
(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.")
......@@ -252,6 +253,7 @@ Do not call this in the scope of `with-help-window'."
"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"))
......
......@@ -1882,6 +1882,9 @@ they ran"))
(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"))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment