Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Howard Melman <hmelman@gmail.com> writes:

> I had missed this and it looks great.  I have a few small comments.

Thanks!

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

> Also I'd say "major and minor" since it shows the major mode first.

Fixed.

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

>>    f         Show help for function
>>    o Show help for function or variable
>
> I would move this one either above f or below v.  It seem
> odd to me be to placed between them.

Agreed, changed.

>> Info Manuals
>>
>>    r Show Emacs manual
>>    F Show Emacs manual section for command
>>    K Show Emacs manual section for command bound to key
>>    i         Show all included manuals
>
> I feel like the word info should be here, as that's the
> mnemonic (not "included").

I'm fine with that.  (Eli has also pointed out it should say "installed"
rather than "included".)

>>    R Show given manual
>
> Is this a new function in Emacs 28?  I don't see it in Emacs
> 27.  For w above you say "a given command" maybe these two
> should match?

I think it's new, yes.

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.

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

Whereas "Find" implies that we must first see if there even exists any
documentation for this particular symbol/identifier/name.

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

>>    t         Start the Emacs tutorial
>
> I understand that the tuturial is probably the least used
> command here, but I'll make the case that for a new user,
> the ones most likely to use C-h C-h, it's perhaps the most
> important one.  I'd put it first in this section.

Sure, why not?  My initial concern was that this gives a less prominent
place to Emacs packages, but having tested it I think it is perfectly
okay this way.

>> 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?

Thanks a lot for these detailed comments.

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.