unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
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.





  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).