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

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

> If the general direction here is okay, I will provide a full proposal,
> including thinking through the order.

Please find attached an updated proposal.

My overarching goal here has been to design this as an _overview_ of
_important_ and _non-obvious_ information.

This is a summary of the changes:

- Added sections.

- Drastically shortened descriptions of the command.

- Changed ordering to be roughly based on: order of importance, logical
  grouping of related items, and the Emacs manual.

- Removed the indication about which commands will show a prompt.
  [Rationale: I find that information overly pedantic, messy and fully
  redundant; it will either be obvious from context or, at the very
  least, when invoking a given help command.]

I'm not sure what is considered a large attachment these days, so I
posted a screenshot at some image host:

    https://i.imgur.com/Cv67yUN.png

To facilitate the discussion, I have also pasted below the plain text of
the help buffer.  The patch is attached below.


(Type SPC or DEL to scroll, or q to exit.)

Getting Help

   m    Help for current minor and major modes and their commands
   b    Show all key bindings
   k    Show help for key
   c    Show help for key briefly
   w    Show which key runs a given command

   a    Search for commands (see also M-x apropos)
   d    Search documentation of functions, variables, and other items
   f    Show help for function
   o    Show help for function or variable
   v    Show help for variable

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
   R    Show given manual
   S    Find symbol in Info manual for current programming language

Misc Help

   p    Search for packages matching topic
   P    Describe Emacs Lisp package
   e    Show recent messages
   g    Show information about the GNU project
   l    Show last 300 input keystrokes (lossage)
   s    Show current syntax table
   .    Show local help at point
   t    Start the Emacs tutorial

Help Files

   C-a  About Emacs
   C-c  Emacs copying permission (GNU General Public License)
   C-d  Debugging GNU Emacs
   C-e  External packages
   C-f  Emacs FAQ
   C-m  Order printed Emacs manuals
   C-n  News of recent Emacs changes
   C-o  Emacs ordering and distribution information
   C-p  Known Emacs problems
   C-t  Emacs TODO
   C-w  Information on absence of warranty for GNU Emacs

Language Help

   C    Describe coding system
   I    Describe input method
   L    Describe language environment
   h    Display the HELLO file illustrating various scripts

0001-Improved-help-for-help.patch
Description: Text Data