Re: [ELPA] New package: transient

[Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>]

[-- Attachment #1: Type: text/plain, Size: 1825 bytes --]



> On May 4, 2020, at 23:22, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Mon, 4 May 2020 10:13:56 +0900
>> Cc: Dmitry Gutov <dgutov@yandex.ru>,
>> tomas@tuxteam.de,
>> Emacs developers <emacs-devel@gnu.org>,
>> Stefan Monnier <monnier@iro.umontreal.ca>,
>> rms@gnu.org
>> 
>>> I'd rather expect that people would listen to better tools being
>>> presented to them, and would consider using them to enrich their
>>> experience and make their everyday's life better.
>> 
>> Would you consider that a tutorial on the information search system provided by emacs would help in that matter ?
> 
> Maybe.  I don't think I understand well enough what would such a
> tutorial include.  You didn't say.

What a tutorial usually includes is step-by-step help with practical examples. I'll be putting that on my todo list.

> We already have some of that ion the Emacs tutorial

Very little in fact:

C-h t
C-h i
C-h f
C-h v
M-. → "requires running etags to record all the manuals nodes"
C-h p in a quote from the Emacs manual
M-x apropos
C-h a → the example Chassell gives produces 211 results

> and then we have the "Help" chapter in the Emacs manual.

The Help chapter provides a "summary of help commands for accessing the built-in documentation." That summary does not group the information by topic but merely lists the commands in the alphabetical order of the keys.

Let me attach a patch that groups the commands by topic (tables) in that summary. I am not sure adding a @subsection is the best way to label such groups (tables) but I could not find a better solution.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune



[-- Attachment #2: help.texi.200505.diff --]
[-- Type: application/octet-stream, Size: 6705 bytes --]

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 49c53c5cbc..ee7435fc13 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -86,94 +86,139 @@ Help Summary
 documentation.  Most of these are described in more detail in the
 following sections.
 
+@subsection Commands, functions, variables, symbols
+
 @table @kbd
 @item C-h a @var{topics} @key{RET}
 Display a list of commands whose names match @var{topics}
 (@code{apropos-command}).
-@item C-h b
-Display all active key bindings; minor mode bindings first, then those
-of the major mode, then global bindings (@code{describe-bindings}).
-@item C-h c @var{key}
-Show the name of the command that the key sequence @var{key} is bound
-to (@code{describe-key-briefly}).  Here @kbd{c} stands for
-``character''.  For more extensive information on @var{key}, use
-@kbd{C-h k}.
+
 @item C-h d @var{topics} @key{RET}
 Display the commands and variables whose documentation matches
 @var{topics} (@code{apropos-documentation}).
-@item C-h e
-Display the @file{*Messages*} buffer
-(@code{view-echo-area-messages}).
+
+@item C-h F @var{command} @key{RET}
+Enter Info and go to the node that documents the Emacs command
+@var{command} (@code{Info-goto-emacs-command-node}).
+
 @item C-h f @var{function} @key{RET}
 Display documentation on the Lisp function named @var{function}
 (@code{describe-function}).  Since commands are Lisp functions,
 this works for commands too.
-@item C-h h
-Display the @file{HELLO} file, which shows examples of various character
-sets.
-@item C-h i
-Run Info, the GNU documentation browser (@code{info}).  The Emacs
-manual is available in Info.
-@item C-h k @var{key}
-Display the name and documentation of the command that @var{key} runs
-(@code{describe-key}).
-@item C-h l
-Display a description of your last 300 keystrokes
-(@code{view-lossage}).
-@item C-h m
-Display documentation of the current major mode and minor modes
-(@code{describe-mode}).
-@item C-h n
-Display news of recent Emacs changes (@code{view-emacs-news}).
+
+@item C-h v @var{var} @key{RET}
+Display the documentation of the Lisp variable @var{var}
+(@code{describe-variable}).
+
 @item C-h o @var{symbol}
 Display documentation of the Lisp symbol named @var{symbol}
 (@code{describe-symbol}).  This will show the documentation of all
 kinds of symbols: functions, variables, and faces.
+
+@item C-h S @var{symbol} @key{RET}
+Display the Info documentation on symbol @var{symbol} according to the
+programming language you are editing (@code{info-lookup-symbol}).
+@end table
+
+@subsection Keys
+
+@table @kbd
+@item C-h b
+Display all active key bindings; minor mode bindings first, then those
+of the major mode, then global bindings (@code{describe-bindings}).
+
+@item C-h c @var{key}
+Show the name of the command that the key sequence @var{key} is bound
+to (@code{describe-key-briefly}).  Here @kbd{c} stands for
+``character''.  For more extensive information on @var{key}, use
+@kbd{C-h k}.
+
+@item C-h k @var{key}
+Display the name and documentation of the command that @var{key} runs
+(@code{describe-key}).
+
+@item C-h K @var{key}
+Enter Info and go to the node that documents the key sequence
+@var{key} (@code{Info-goto-emacs-key-command-node}).
+
+@item C-h w @var{command} @key{RET}
+Show which keys run the command named @var{command} (@code{where-is}).
+@end table
+
+@subsection Modes, packages
+
+@table @kbd
 @item C-h p
 Find packages by topic keyword (@code{finder-by-keyword}).  This lists
 packages using a package menu buffer.  @xref{Packages}.
+
 @item C-h P @var{package} @key{RET}
 Display documentation about the specified package
 (@code{describe-package}).
-@item C-h r
-Display the Emacs manual in Info (@code{info-emacs-manual}).
-@item C-h s
-Display the contents of the current @dfn{syntax table}
-(@code{describe-syntax}).  The syntax table says which characters are
-opening delimiters, which are parts of words, and so on.  @xref{Syntax
-Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for
-details.
-@item C-h t
-Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
-@item C-h v @var{var} @key{RET}
-Display the documentation of the Lisp variable @var{var}
-(@code{describe-variable}).
-@item C-h w @var{command} @key{RET}
-Show which keys run the command named @var{command} (@code{where-is}).
+
+@item C-h m
+Display documentation of the current major mode and minor modes
+(@code{describe-mode}).
+@end table
+
+@subsection Input method, coding systems, languages
+
+@table @kbd
 @item C-h C @var{coding} @key{RET}
 Describe the coding system @var{coding}
 (@code{describe-coding-system}).
+
 @item C-h C @key{RET}
 Describe the coding systems currently in use.
-@item C-h F @var{command} @key{RET}
-Enter Info and go to the node that documents the Emacs command
-@var{command} (@code{Info-goto-emacs-command-node}).
+
 @item C-h I @var{method} @key{RET}
 Describe the input method @var{method} (@code{describe-input-method}).
-@item C-h K @var{key}
-Enter Info and go to the node that documents the key sequence
-@var{key} (@code{Info-goto-emacs-key-command-node}).
+
 @item C-h L @var{language-env} @key{RET}
 Display information on the character sets, coding systems, and input
 methods used in language environment @var{language-env}
 (@code{describe-language-environment}).
-@item C-h S @var{symbol} @key{RET}
-Display the Info documentation on symbol @var{symbol} according to the
-programming language you are editing (@code{info-lookup-symbol}).
+
+@item C-h h
+Display the @file{HELLO} file, which shows examples of various character
+sets.
+@end table
+
+@subsection Various information buffers
+
+@table @kbd
+@item C-h l
+Display a description of your last 300 keystrokes
+(@code{view-lossage}).
+
+@item C-h r
+Display the Emacs manual in Info (@code{info-emacs-manual}).
+
+@item C-h t
+Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
+
+@item C-h i
+Run Info, the GNU documentation browser (@code{info}) where all the
+installed info manuals can be found.
+
+@item C-h e
+Display the @file{*Messages*} buffer
+(@code{view-echo-area-messages}).
+
+@item C-h n
+Display news of recent Emacs changes (@code{view-emacs-news}).
+
 @item C-h .
 Display the help message for a special text area, if point is in one
 (@code{display-local-help}).  (These include, for example, links in
 @file{*Help*} buffers.)
+
+@item C-h s
+Display the contents of the current @dfn{syntax table}
+(@code{describe-syntax}).  The syntax table says which characters are
+opening delimiters, which are parts of words, and so on.  @xref{Syntax
+Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for
+details.
 @end table
 
 @node Key Help