From: Howard Melman <hmelman@gmail.com>
To: emacs-devel@gnu.org
Subject: Re: Proposal for an improved `help-for-help'
Date: Wed, 07 Apr 2021 19:15:58 -0400 [thread overview]
Message-ID: <lyft018z4h.fsf@Lumet2.home> (raw)
In-Reply-To: CADwFkmnYY2XoEMNP5e45=jWFeKoWTn2U4bvUmLZ0pKSikmvDFA@mail.gmail.com
Stefan Kangas <stefankangas@gmail.com> writes:
>>> Getting Help
>>>
>>> m Help for current minor and major modes and their commands
>>
>> Why not "Show help for" like the others?
>
> Basically to keep it short, and I feel it reads better. I'm not sure
> the consistency is overly important here.
>
> Perhaps we should even remove all instances of "Show", as it is fairly
> obvious that help commands will show something.
Long ago a technical writer told me of the importance of
consistency in technical writing as opposed to other prose
writing where redundancy is more of an issue. I agree it's
not critically important here and that there are other
considerations, but I did want to point the inconsistencies
when I saw them.
>>> a Search for commands (see also M-x apropos)
>>> d Search documentation of functions, variables, and other items
>>
>> In other places you use the word "help" instead of
>> "documentation". I agree "Search documentation" reads
>> better than "Search help" but by using a different word it
>> suggests to me that it searches differen text than what is
>> shown by other help commands. Maybe "Seach help text" would
>> be better?
>
> I see what you're saying, but OTOH "documentation" is the mnemonic for
> "d". So I'm not sure what's best here.
The mnemonic is a good point. I might go with "help
documentation" or "help docstrings". If you don't like
either of those, then I'd just leave it as you have it.
>>> R Show given manual
>>
>> For w above you say "a given command" maybe these two
>> should match?
>
> Eli suggested "Show specified command", which I think is okay. I'm not
> sure they should match as they are far apart, and IMHO they read a bit
> better this way.
I prefer the word "specified" too. I don't think their
distance makes any difference. I'd used specified in both places.
>>> S Find symbol in Info manual for current programming language
>>
>> With the construction used above for F and K this would
>> read: "Show current programming language manual section for
>> symbol" If that's too long, perhaps those commands should
>> use this construction with "Find..."
>
> Hmm. I'm not sure we need the consistency, as the "Show" implies that
> exactly what you're looking for will always be there: The Emacs Manual
> won't go anywhere.
It won't, but what you're looking for may not be in it.
> Whereas "Find" implies that we must first see if there even exists any
> documentation for this particular symbol/identifier/name.
I may be wrong, but I think these commands behave the same
way, the difference is in which manuals are checked.
>>> Misc Help
>>>
>>> p Search for packages matching topic
>>> P Describe Emacs Lisp package
>>> e Show recent messages
>>
>> I'd like to see word the "echo" in here as the mnemonic. Perhaps
>> "Show recent messages from the echo area" or "Show recently
>> echoed messages"
>
> It basically becomes a decision of where to strike the balance between
> brevity and mnemonics.
>
> We have below:
>
>>> l Show last 300 input keystrokes (lossage)
>
> So I'd suggest: "Show recent messages (from echo area)"
>
> It reads better (and faster), I think.
I agree.
>>> Help Files
>>>
>>> C-a About Emacs
>>> C-c Emacs copying permission (GNU General Public License)
>>> C-d Debugging GNU Emacs
>>
>> The "GNU" seems unnecessary here, particularly compared to
>> the other lines.
>
> The problem is that the license is the "GNU GPL", while the "General
> Public License" could refer to anything... I think? Could we just use
> "GNU GPL"? Perhaps Richard has something to add?
I was just referring to it use in "Debugging GNU Emacs". I
think that should be "Debugging Emacs". The "GNU" should stay
in "(GNU General Public License)" and also in the warranty
description.
> Thanks a lot for these detailed comments.
Thanks for your work on this.
> This is all very subjective, so please bare with me as I'm trying to
> take into account all the comments and work out a coherent whole.
Yes and please take my comments as just one person's opinion.
--
Howard
next prev parent reply other threads:[~2021-04-07 23:15 UTC|newest]
Thread overview: 188+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-02-21 12:06 Proposal for an improved `help-for-help' Stefan Kangas
2021-02-21 16:46 ` [External] : " Drew Adams
2021-02-21 17:31 ` Stefan Kangas
2021-02-21 18:17 ` Drew Adams
2021-02-21 17:42 ` Lars Ingebrigtsen
2021-02-21 18:18 ` [External] : " Drew Adams
2021-02-21 19:49 ` Stefan Kangas
2021-02-24 1:40 ` Consistent face for keys in *Help* and `substitute-command-keys' Stefan Kangas
2021-02-24 2:24 ` [External] : " Drew Adams
2021-02-24 4:44 ` Stefan Kangas
2021-02-24 22:01 ` Drew Adams
2021-02-25 1:25 ` Stefan Kangas
2021-02-25 6:43 ` Drew Adams
2021-02-25 15:06 ` Eli Zaretskii
2021-02-25 16:22 ` Stefan Kangas
2021-02-24 14:00 ` Basil L. Contovounesios
2021-02-24 16:35 ` Stefan Kangas
2021-02-24 19:09 ` Basil L. Contovounesios
2021-02-25 2:11 ` Stefan Kangas
2021-02-24 14:29 ` Lars Ingebrigtsen
2021-02-24 16:46 ` Eli Zaretskii
2021-02-25 2:26 ` Stefan Kangas
2021-02-25 14:28 ` Eli Zaretskii
2021-02-25 16:45 ` Stefan Kangas
2021-02-25 18:25 ` Eli Zaretskii
2021-02-25 18:48 ` Stefan Kangas
2021-02-25 19:11 ` Eli Zaretskii
2021-02-25 19:47 ` Stefan Kangas
2021-02-25 20:32 ` Eli Zaretskii
2021-03-04 6:24 ` Stefan Kangas
2021-03-04 14:00 ` Eli Zaretskii
2021-03-05 16:18 ` Stefan Kangas
2021-03-05 17:07 ` [External] : " Drew Adams
2021-03-05 17:58 ` Stefan Kangas
2021-03-06 16:44 ` Drew Adams
2021-03-06 17:04 ` Stefan Kangas
2021-03-06 17:39 ` Drew Adams
2021-03-05 18:58 ` Eli Zaretskii
2021-03-05 19:28 ` Stefan Kangas
2021-03-05 20:15 ` Eli Zaretskii
2021-03-05 20:39 ` Stefan Kangas
2021-03-05 20:52 ` Eli Zaretskii
2021-03-05 21:43 ` Stefan Kangas
2021-03-06 7:33 ` Eli Zaretskii
2021-03-06 16:25 ` Stefan Kangas
2021-03-06 17:32 ` Stefan Kangas
2021-03-06 18:28 ` Eli Zaretskii
2021-03-07 3:03 ` Stefan Kangas
2021-03-07 6:45 ` Eli Zaretskii
2021-03-07 7:26 ` Stefan Kangas
2021-03-07 7:42 ` Eli Zaretskii
2021-03-08 9:17 ` Juri Linkov
2021-03-08 11:10 ` Stefan Kangas
2021-03-08 17:43 ` Juri Linkov
2021-03-10 1:38 ` Stefan Kangas
2021-03-10 17:16 ` Juri Linkov
2021-03-10 19:35 ` Stefan Kangas
2021-03-10 19:50 ` Juri Linkov
2021-03-10 19:59 ` Eli Zaretskii
2021-03-11 0:46 ` Stefan Kangas
2021-03-11 3:09 ` Stefan Monnier
2021-03-11 6:25 ` Eli Zaretskii
2021-03-11 13:25 ` Stefan Monnier
2021-03-11 13:59 ` Eli Zaretskii
2021-03-13 14:11 ` Stefan Kangas
2021-03-11 6:05 ` Eli Zaretskii
2021-03-13 14:27 ` Stefan Kangas
2021-03-13 15:16 ` Eli Zaretskii
2021-03-13 15:59 ` Stefan Kangas
2021-03-11 0:45 ` Stefan Kangas
2021-03-15 9:19 ` Juri Linkov
2021-03-16 2:37 ` Stefan Kangas
2021-03-16 23:20 ` Dmitry Gutov
2021-03-08 15:39 ` [External] : " Drew Adams
2021-03-08 16:40 ` Stefan Kangas
2021-03-08 17:43 ` Juri Linkov
2021-03-09 7:38 ` Stefan Kangas
2021-03-09 9:05 ` Juri Linkov
2021-02-25 19:14 ` Drew Adams
2021-02-25 19:44 ` martin rudalics
2021-02-24 16:51 ` Eli Zaretskii
2021-02-25 1:56 ` Stefan Kangas
2021-02-25 14:24 ` Eli Zaretskii
2021-02-21 17:45 ` Proposal for an improved `help-for-help' Eli Zaretskii
2021-02-21 18:20 ` [External] : " Drew Adams
2021-02-21 18:48 ` Stefan Kangas
2021-02-21 19:19 ` Eli Zaretskii
2021-02-21 20:04 ` Stefan Kangas
2021-02-21 20:16 ` Eli Zaretskii
2021-02-21 23:27 ` Stefan Kangas
2021-02-22 16:12 ` Eli Zaretskii
2021-03-13 16:26 ` Stefan Kangas
2021-03-14 2:37 ` [External] : " Drew Adams
2021-03-14 23:05 ` Drew Adams
2021-03-14 23:53 ` Stefan Kangas
2021-03-15 1:54 ` Drew Adams
2021-04-07 15:18 ` Stefan Kangas
2021-04-07 16:10 ` Eli Zaretskii
2021-04-07 22:54 ` Howard Melman
2021-04-08 7:15 ` Eli Zaretskii
2021-04-08 12:57 ` Stefan Kangas
2021-04-08 13:35 ` Stefan Kangas
2021-04-08 13:50 ` Eli Zaretskii
2021-04-08 15:27 ` Stefan Kangas
2021-04-08 15:34 ` Eli Zaretskii
2021-04-08 17:16 ` Howard Melman
2021-04-08 22:52 ` Stefan Kangas
2021-04-09 6:23 ` Eli Zaretskii
2021-04-08 14:08 ` Alan Mackenzie
2021-04-08 14:50 ` Dmitry Gutov
2021-04-08 15:02 ` Alan Mackenzie
2021-04-08 15:15 ` Eli Zaretskii
2021-04-08 15:45 ` Alan Mackenzie
2021-04-08 15:51 ` Eli Zaretskii
2021-04-08 17:55 ` Howard Melman
2021-04-09 15:42 ` Stefan Kangas
2021-04-08 18:48 ` Gregory Heytings
2021-04-08 23:23 ` Stefan Kangas
2021-04-08 23:35 ` Gregory Heytings
2021-04-08 23:41 ` Howard Melman
2021-04-07 16:42 ` [External] : " Drew Adams
2021-04-07 18:33 ` Gregory Heytings
2021-04-07 19:50 ` Gregory Heytings
2021-04-07 22:56 ` Stefan Kangas
2021-04-07 23:26 ` Gregory Heytings
2021-04-08 12:42 ` Stefan Kangas
2021-04-07 19:55 ` Juri Linkov
2021-04-24 13:21 ` Stefan Kangas
2021-04-24 13:27 ` Eli Zaretskii
2021-04-24 16:44 ` Dmitry Gutov
2021-04-24 23:48 ` Stefan Kangas
2021-04-25 7:26 ` Eli Zaretskii
2021-04-25 9:30 ` Stefan Kangas
2021-04-25 10:25 ` Eli Zaretskii
2021-04-25 11:49 ` Stefan Kangas
2021-04-25 12:14 ` Eli Zaretskii
2021-04-25 16:26 ` [External] : " Drew Adams
2021-04-25 10:20 ` Dmitry Gutov
2021-04-25 10:38 ` Eli Zaretskii
2021-04-25 10:46 ` Eli Zaretskii
2021-04-25 11:23 ` Dmitry Gutov
2021-04-25 15:18 ` Stefan Kangas
2021-04-25 15:28 ` Dmitry Gutov
2021-04-30 17:39 ` Stefan Kangas
2021-04-30 20:02 ` Dmitry Gutov
2021-04-30 20:36 ` Stefan Monnier
2021-04-30 22:09 ` Dmitry Gutov
2021-05-02 10:23 ` Stefan Kangas
2021-05-02 18:57 ` Dmitry Gutov
2021-04-30 17:34 ` Stefan Kangas
2021-04-25 12:47 ` Gregory Heytings
2021-04-25 13:05 ` Eli Zaretskii
2021-04-25 13:09 ` Eli Zaretskii
2021-04-25 16:22 ` [External] : " Drew Adams
2021-04-25 16:30 ` Eli Zaretskii
2021-04-25 13:16 ` Gregory Heytings
2021-04-25 13:24 ` Eli Zaretskii
2021-04-25 13:32 ` Gregory Heytings
2021-04-25 13:44 ` Eli Zaretskii
2021-04-25 13:58 ` Dmitry Gutov
2021-04-25 11:12 ` Dmitry Gutov
2021-04-25 15:47 ` DEL vs Backspace (was: Proposal for an improved `help-for-help') Stefan Monnier
2021-04-25 16:49 ` DEL vs Backspace Lars Ingebrigtsen
2021-04-25 17:25 ` Stefan Monnier
2021-04-25 17:50 ` Dmitry Gutov
2021-04-26 0:45 ` Stefan Kangas
2021-04-26 11:45 ` Eli Zaretskii
2021-04-26 11:48 ` Dmitry Gutov
2021-04-26 4:41 ` Richard Stallman
2021-04-27 20:56 ` Proposal for an improved `help-for-help' Stefan Kangas
2021-04-27 23:15 ` Dmitry Gutov
2021-04-24 17:18 ` Gregory Heytings
2021-04-24 20:32 ` Juri Linkov
2021-04-25 10:00 ` Stefan Kangas
2021-04-07 17:56 ` Howard Melman
2021-04-07 18:21 ` John Yates
2021-04-07 22:56 ` Stefan Kangas
2021-04-07 22:41 ` Stefan Kangas
2021-04-07 23:15 ` Howard Melman [this message]
2021-04-08 12:57 ` Stefan Kangas
2021-02-21 19:27 ` Howard Melman
2021-02-22 15:25 ` Stefan Kangas
2021-02-22 10:01 ` Yuri Khan
2021-02-22 15:25 ` Stefan Kangas
2021-04-25 15:11 ` Stefan Kangas
2021-04-25 15:34 ` Dmitry Gutov
2021-04-25 18:43 ` Stefan Kangas
2021-04-25 14:06 ` Dmitry Gutov
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=lyft018z4h.fsf@Lumet2.home \
--to=hmelman@gmail.com \
--cc=emacs-devel@gnu.org \
/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).