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

[Howard Melman]

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