From: Eli Zaretskii <eliz@gnu.org>
To: Stefan Kangas <stefan@marxist.se>
Cc: larsi@gnus.org, 46627@debbugs.gnu.org
Subject: bug#46627: [PATCH] Add new help command 'describe-command'
Date: Fri, 19 Feb 2021 22:05:58 +0200 [thread overview]
Message-ID: <83pn0v257d.fsf@gnu.org> (raw)
In-Reply-To: <CADwFkmndEihHnVSgTTDFFmc8y8bKLE0d077JuO+KfC2GURSYCw@mail.gmail.com> (message from Stefan Kangas on Fri, 19 Feb 2021 11:42:50 -0600)
> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 19 Feb 2021 11:42:50 -0600
> Cc: 46627@debbugs.gnu.org, Lars Ingebrigtsen <larsi@gnus.org>
>
> The way I add it in the documentation treats it as more basic than
> `C-h f'. That is, the proposed text first describes how to find
> documentation for commands, and only then describes how to find
> documentation for any Lisp function. It is the most reasonable way to
> do it here, I think; this is after all the "user" manual and not the
> "Elisp" manual.
Please remember this when we discuss use of functions in user-level
features, such as values for user options.
> +@item C-h x @var{command} @key{RET}
> +Display documentation on the command named @var{command}
It is better to avoid duplicating "command" here. Like this:
Display documentation on the named @var{command}.
It is advantageous to use this style whenever the thing in @var{..} is
a term that explains itself clearly enough, like here.
> + @kbd{C-h x @var{command} @key{RET}} (@code{describe-command})
> +displays the documentation of the command @var{command}, in a
^^^^^^^^^^^^^^^^^^^^^
Likewise.
> +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}). Since all
> +commands are Lisp functions, you can also find its documentation using
> +@code{describe-function}.
The last sentence is better moved to the description of describe-function.
> + @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
> +displays the documentation of Lisp function @var{function}. This
^^^^^^^^^^^^^^^^^^^^^^^
Duplication of "function" again. (Yes, I know it was that way in the
original text.)
> +@code{make-vector} properly, type @kbd{C-h f make-vector
> +@key{RET}}.
When a long text in |@kbd (or any other Texinfo markup) is near a
line's end, it is better to wrap it in @w{..}, so that it won't be
broken in half by the end of line.
> + (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))
These messages say "function" regardless of whether the user typed
"C-h x" or "C-h f". Is that optimal?
Thanks.
next prev parent reply other threads:[~2021-02-19 20:05 UTC|newest]
Thread overview: 86+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-02-19 1:06 bug#46627: [PATCH] Add new help command 'describe-command' Stefan Kangas
2021-02-19 8:42 ` Eli Zaretskii
2021-02-19 17:42 ` Stefan Kangas
2021-02-19 18:38 ` bug#46627: [External] : " Drew Adams
2021-02-20 3:25 ` Stefan Kangas
2021-02-20 4:25 ` Drew Adams
2021-02-20 8:20 ` Eli Zaretskii
2021-02-20 7:44 ` Eli Zaretskii
2021-02-19 20:05 ` Eli Zaretskii [this message]
2021-02-20 4:10 ` Stefan Kangas
2021-02-20 8:18 ` Eli Zaretskii
2021-02-20 17:10 ` Stefan Kangas
2021-02-21 13:08 ` Lars Ingebrigtsen
2021-02-22 15:58 ` Eli Zaretskii
2021-04-28 13:58 ` Stefan Kangas
2021-04-28 14:17 ` Stefan Kangas
2021-05-02 13:14 ` Stefan Kangas
2021-02-20 12:56 ` Lars Ingebrigtsen
2021-02-20 12:59 ` Eli Zaretskii
2021-02-20 16:16 ` Eli Zaretskii
2021-02-20 14:04 ` Stefan Kangas
2021-02-20 16:06 ` Richard Stallman
2021-02-20 16:09 ` Eli Zaretskii
2021-02-20 20:06 ` bug#46627: [External] : " Drew Adams
2021-02-20 20:17 ` Eli Zaretskii
2021-02-20 20:54 ` Drew Adams
2021-02-20 16:39 ` Stefan Kangas
2021-02-20 16:49 ` Eli Zaretskii
2021-02-20 20:35 ` bug#46627: [External] : " Drew Adams
2021-02-20 20:46 ` Eli Zaretskii
2021-02-20 21:16 ` Drew Adams
2021-02-21 15:07 ` Eli Zaretskii
2021-02-21 17:55 ` Drew Adams
2021-02-21 18:11 ` Eli Zaretskii
2021-02-21 18:30 ` Drew Adams
2021-02-26 21:34 ` Drew Adams
2021-02-27 8:04 ` Eli Zaretskii
2021-02-27 17:46 ` Drew Adams
2021-02-21 6:19 ` Richard Stallman
2021-02-21 7:18 ` Stefan Kangas
2021-02-21 15:27 ` Eli Zaretskii
2021-02-21 16:39 ` Howard Melman
2021-02-21 18:01 ` bug#46627: [External] : " Drew Adams
2021-02-21 17:01 ` Stefan Kangas
2021-02-21 17:36 ` Eli Zaretskii
2021-02-21 18:02 ` Stefan Kangas
2021-02-21 18:21 ` Eli Zaretskii
2021-02-21 19:57 ` Dmitry Gutov
2021-02-21 20:13 ` Eli Zaretskii
2021-02-21 23:46 ` Dmitry Gutov
2021-02-22 15:18 ` Eli Zaretskii
2021-02-27 20:38 ` Dmitry Gutov
2021-02-28 17:27 ` Eli Zaretskii
2021-02-28 21:40 ` Dmitry Gutov
2021-03-01 6:05 ` Eli Zaretskii
2021-03-02 1:40 ` Dmitry Gutov
2021-03-02 5:31 ` Eli Zaretskii
2021-03-02 12:55 ` Dmitry Gutov
2021-03-02 13:47 ` Eli Zaretskii
2021-02-21 17:57 ` bug#46627: [External] : " Drew Adams
2021-02-21 17:33 ` Drew Adams
2021-02-21 13:06 ` Lars Ingebrigtsen
2021-02-21 6:27 ` Richard Stallman
2021-02-21 6:10 ` Richard Stallman
2021-02-21 6:27 ` Richard Stallman
2021-02-19 13:12 ` Lars Ingebrigtsen
2021-02-19 18:27 ` bug#46627: [External] : " Drew Adams
2021-02-19 18:43 ` Eli Zaretskii
2021-02-21 6:18 ` Richard Stallman
2021-02-21 6:27 ` Richard Stallman
2021-02-20 6:56 ` Richard Stallman
2021-02-20 7:14 ` Stefan Kangas
2021-02-21 6:19 ` Richard Stallman
2021-02-21 6:27 ` Richard Stallman
2021-02-21 7:17 ` Stefan Kangas
2021-02-22 6:23 ` Richard Stallman
2021-02-24 3:28 ` Stefan Kangas
2021-02-27 18:58 ` Dmitry Gutov
2021-03-01 5:18 ` Richard Stallman
2021-03-01 16:13 ` bug#46627: [External] : " Drew Adams
2021-03-02 6:29 ` Richard Stallman
2021-03-02 6:50 ` Eli Zaretskii
2021-03-03 5:55 ` Richard Stallman
2021-03-03 15:26 ` Drew Adams
2021-03-03 16:14 ` Eli Zaretskii
2021-03-02 16:52 ` Drew Adams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83pn0v257d.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=46627@debbugs.gnu.org \
--cc=larsi@gnus.org \
--cc=stefan@marxist.se \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).