bug#49306: 28.0.50; Info of Eshell/Extension Modules/* is empty

bug#49306: 28.0.50; Info of Eshell/Extension Modules/* is empty

[Gabriel]

Emacs 28 from master branch (HEAD 8ebd8e1fea1d0d925850db97b64bf13a6a1f698b)

1. Open Info (C-h i)
2. Search for Eshell (C-s Eshell)
3. Navigate to 'Extension modules'
4. All child pages are empty:
   * Writing a module
   * Module testing
   * Directory handling
   * Key rebinding:
   * Smart scrolling
   * Terminal emulation

I checked the git history of file 'doc/misc/eshell.texi' and indeed
these sections are empty.

I suggest to either document these sections or remove these entries from
Info to avoid confusion.

bug#49306: 28.0.50; Info of Eshell/Extension Modules/* is empty

[Gabriel]

I just found out on Info 'Eshell/Bugs and Ideas' an entry about
'Documentation incomplete', but this page comes after 'Extension
modules'. Perhaps should we change the order of these pages or be more
explicit that the documentation is incomplete on the blank pages?

bug#49306: 28.0.50; Info of Eshell/Extension Modules/* is empty

[Stefan Kangas]

Gabriel <gabriel376@hotmail.com> writes:

> I just found out on Info 'Eshell/Bugs and Ideas' an entry about
> 'Documentation incomplete', but this page comes after 'Extension
> modules'. Perhaps should we change the order of these pages or be more
> explicit that the documentation is incomplete on the blank pages?

I have added an explicit note on these pages to say that they have not
yet been written.  This change will be in Emacs 28.1.

bug#49306: 28.0.50; Info of Eshell/Extension Modules/* is empty

[Jim Porter]

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

On 6/30/2021 5:20 PM, Gabriel wrote:
> I just found out on Info 'Eshell/Bugs and Ideas' an entry about
> 'Documentation incomplete', but this page comes after 'Extension
> modules'. Perhaps should we change the order of these pages or be more
> explicit that the documentation is incomplete on the blank pages?

Attached are some patches to finish the Eshell documentation, targeting 
Emacs 30 (they could probably be backported to 29 without much work, but 
I've made some other changes to the Eshell manual in 30 already...)

Here are the main notable parts in these patches:

* I moved the documentation for all disabled-by-default commands into 
the Optional Modules section. This way, it's more clearer (IMO) that 
these commands aren't available by default, since all the off-by-default 
features are together.

* I mostly copied the Key Rebinding and Smart Scrolling sections' 
documentation from their corresponding Elisp files. I don't know a ton 
about them (especially not Smart Scrolling), so it would be hard for me 
to write all-new documentation for them. Hopefully what I have here is 
still an improvement.

[-- Attachment #2: 0001-doc-misc-eshell.texi-Bugs-and-ideas-Remove-implement.patch --]
[-- Type: text/plain, Size: 817 bytes --]

From 6113f501361c5a16e6d0517b7a987eae82c7b587 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Sun, 29 Jan 2023 18:29:02 -0800
Subject: [PATCH 1/4] ; * doc/misc/eshell.texi (Bugs and ideas): Remove
 implemented feature.

---
 doc/misc/eshell.texi | 2 --
 1 file changed, 2 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 4e2bddf42af..456e5c7a1a9 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -2227,8 +2227,6 @@ Bugs and ideas
 
 @item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
 
-@item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
-
 @item @samp{mv @var{dir} @var{file}.tar} does not remove directories
 
 This is because the tar option --remove-files doesn't do so.  Should it
-- 
2.25.1


[-- Attachment #3: 0002-Restructure-Eshell-extension-modules-documentation.patch --]
[-- Type: text/plain, Size: 4316 bytes --]

From c93c64906d09c22e06f8a0a67f3af27a85e2592a Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Sun, 29 Jan 2023 19:59:56 -0800
Subject: [PATCH 2/4] Restructure Eshell extension modules documentation

This adds a section for documenting all the optional modules.

* doc/misc/eshell.texi (Extension modules): Move explanation about
writing modules to...
(Writing a module): ... here.
(Module testing): Remove.  Testing an Eshell module doesn't require
any special documentation.
(Key binding, Smart scrolling, Electric forward slash): Move under...
(Optional modules): ... here.
(Directory handling, Terminal emulation): Remove.  These modules are
enabled by default, and so are documented above.
(Tramp extensions, Extra built-in commands): New sections.
---
 doc/misc/eshell.texi | 86 ++++++++++++++++++++++----------------------
 1 file changed, 44 insertions(+), 42 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 456e5c7a1a9..001c96a0bea 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -2019,66 +2019,38 @@ Extension modules
 Eshell provides a facility for defining extension modules so that they
 can be disabled and enabled without having to unload and reload them,
 and to provide a common parent Customize group for the
-modules.@footnote{ERC provides a similar module facility.}  An Eshell
-module is defined the same as any other library but one requirement: the
-module must define a Customize@footnote{@xref{Customization, , ,
-elisp, The Emacs Lisp Reference Manual}.}
-group using @code{eshell-defgroup} (in place of @code{defgroup}) with
-@code{eshell-module} as the parent group.@footnote{If the module has
-no user-customizable options, then there is no need to define it as an
-Eshell module.}  You also need to load the following as shown:
-
-@example
-(eval-when-compile
-  (require 'cl-lib)
-  (require 'esh-mode)
-  (require 'eshell))
-
-(require 'esh-util)
-@end example
+modules.@footnote{ERC provides a similar module facility.}
 
 @menu
+* Optional modules::
 * Writing a module::
-* Module testing::
-* Directory handling::
-* Key rebinding::
-* Smart scrolling::
-* Terminal emulation::
-* Electric forward slash::
 @end menu
 
-@node Writing a module
-@section Writing a module
-
-This section is not yet written.
-
-@node Module testing
-@section Module testing
+@node Optional modules
+@section Optional modules
 
 This section is not yet written.
 
-@node Directory handling
-@section Directory handling
-
-This section is not yet written.
+@menu
+* Key rebinding::
+* Smart scrolling::
+* Electric forward slash::
+* Tramp extensions::
+* Extra built-in commands::
+@end menu
 
 @node Key rebinding
-@section Key rebinding
+@subsection Key rebinding
 
 This section is not yet written.
 
 @node Smart scrolling
-@section Smart scrolling
-
-This section is not yet written.
-
-@node Terminal emulation
-@section Terminal emulation
+@subsection Smart scrolling
 
 This section is not yet written.
 
 @node Electric forward slash
-@section Electric forward slash
+@subsection Electric forward slash
 
 To help with supplying absolute file name arguments to remote
 commands, you can add the @code{eshell-elecslash} module to
@@ -2132,6 +2104,36 @@ Electric forward slash
 @code{|} and @code{;}, the electric forward slash is active only
 within the first command.
 
+@node Tramp extensions
+@subsection Tramp extensions
+
+This section is not yet written.
+
+@node Extra built-in functions
+@subsection Extra built-in functions
+
+This section is not yet written.
+
+@node Writing a module
+@section Writing a module
+
+An Eshell module is defined the same as any other library but one requirement: the
+module must define a Customize@footnote{@xref{Customization, , ,
+elisp, The Emacs Lisp Reference Manual}.}
+group using @code{eshell-defgroup} (in place of @code{defgroup}) with
+@code{eshell-module} as the parent group.@footnote{If the module has
+no user-customizable options, then there is no need to define it as an
+Eshell module.}  You also need to load the following as shown:
+
+@example
+(eval-when-compile
+  (require 'cl-lib)
+  (require 'esh-mode)
+  (require 'eshell))
+
+(require 'esh-util)
+@end example
+
 @node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
-- 
2.25.1


[-- Attachment #4: 0003-Correct-the-Eshell-documentation-about-how-to-write-.patch --]
[-- Type: text/plain, Size: 2220 bytes --]

From 72a006ea394f383ce7440b2acd6c10726e4028e3 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Fri, 12 May 2023 20:11:01 -0700
Subject: [PATCH 3/4] Correct the Eshell documentation about how to write new
 modules

* doc/misc/eshell.texi (Writing a module): Fix the documentation.
'eshell-defgroup' doesn't exist anymore.
---
 doc/misc/eshell.texi | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 001c96a0bea..bb1ee99ffc0 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -2117,23 +2117,27 @@ Extra built-in functions
 @node Writing a module
 @section Writing a module
 
-An Eshell module is defined the same as any other library but one requirement: the
-module must define a Customize@footnote{@xref{Customization, , ,
-elisp, The Emacs Lisp Reference Manual}.}
-group using @code{eshell-defgroup} (in place of @code{defgroup}) with
-@code{eshell-module} as the parent group.@footnote{If the module has
-no user-customizable options, then there is no need to define it as an
-Eshell module.}  You also need to load the following as shown:
+An Eshell module is defined the same as any other library but with two
+additional requirements: first, the module's source file should be
+named @file{em-@var{name}.el}; second, the module must define an
+autoloaded Customize group (@pxref{Customization, , , elisp, The Emacs
+Lisp Reference Manual}) with @code{eshell-module} as the parent group.
+In order to properly autoload this group, you should wrap its
+definition with @code{progn} as follows:
 
 @example
-(eval-when-compile
-  (require 'cl-lib)
-  (require 'esh-mode)
-  (require 'eshell))
-
-(require 'esh-util)
+;;;###autoload
+(progn
+(defgroup eshell-my-module nil
+  "My module lets you do very cool things in Eshell."
+  :tag "My module"
+  :group 'eshell-module))
 @end example
 
+Even if you don't have any Customize options in your module, you
+should still define the group so that Eshell can include your module
+in the Customize interface for @code{eshell-modules-list}.
+
 @node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
-- 
2.25.1


[-- Attachment #5: 0004-Document-optional-Eshell-modules.patch --]
[-- Type: text/plain, Size: 11874 bytes --]

From 94e7f1da87af6a6fa9f42ac484ea77ba242a68e1 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Fri, 12 May 2023 20:03:48 -0700
Subject: [PATCH 4/4] Document optional Eshell modules

* lisp/eshell/em-rebind.el (eshell-rebind): Correct/reword docstring.

* doc/misc/eshell.texi (Built-ins): Move disabled-by-default commands
to...
(Tramp extensions, Extra built-in commands): ...here
(Optional modules, Key rebinding, Smart scrolling): Add documentation.
(Bug and ideas): Documentation is no longer incomplete!
---
 doc/misc/eshell.texi     | 211 ++++++++++++++++++++++++---------------
 lisp/eshell/em-rebind.el |  19 ++--
 2 files changed, 139 insertions(+), 91 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index bb1ee99ffc0..0e2f5e02973 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -586,14 +586,6 @@ Built-ins
 Set environment variables using input like Bash's @command{export}, as
 in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}.
 
-@item expr
-@cmindex expr
-An implementation of @command{expr} using the Calc package.
-@xref{Top,,, calc, The GNU Emacs Calculator}.
-
-This command can be loaded as part of the eshell-xtra module, which is
-disabled by default.
-
 @item grep
 @cmindex grep
 @itemx agrep
@@ -628,15 +620,6 @@ Built-ins
 reader.
 @xref{Misc Help, , , emacs, The GNU Emacs Manual}.
 
-@item intersection
-@cmindex intersection
-A wrapper around the function @code{cl-intersection} (@pxref{Lists as
-Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command
-can be used for comparing lists of strings.
-
-This command can be loaded as part of the eshell-xtra module, which is
-disabled by default.
-
 @item jobs
 @cmindex jobs
 List subprocesses of the Emacs process, if any, using the function
@@ -706,15 +689,6 @@ Built-ins
 Display Man pages using the Emacs @code{man} command.
 @xref{Man Page, , , emacs, The GNU Emacs Manual}.
 
-@item mismatch
-@cmindex mismatch
-A wrapper around the function @code{cl-mismatch} (@pxref{Searching
-Sequences,,, cl, GNU Emacs Common Lisp Emulation}).  This command can
-be used for comparing lists of strings.
-
-This command can be loaded as part of the eshell-xtra module, which is
-disabled by default.
-
 @item mkdir
 @cmindex mkdir
 Make new directories.
@@ -771,24 +745,6 @@ Built-ins
 @cmindex rmdir
 Removes directories if they are empty.
 
-@item set-difference
-@cmindex set-difference
-A wrapper around the function @code{cl-set-difference} (@pxref{Lists as
-Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command
-can be used for comparing lists of strings.
-
-This command can be loaded as part of the eshell-xtra module, which is
-disabled by default.
-
-@item set-exclusive-or
-@cmindex set-exclusive-or
-A wrapper around the function @code{cl-set-exclusive-or} (@pxref{Lists
-as Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command can be
-used for comparing lists of strings.
-
-This command can be loaded as part of the eshell-xtra module, which is
-disabled by default.
-
 @item set
 @cmindex set
 Set variable values, using the function @code{set} like a command
@@ -808,27 +764,6 @@ Built-ins
 confused with the command @command{.}, which sources a file in the
 current environment.
 
-@item su
-@cmindex su
-@itemx sudo
-@cmindex sudo
-@itemx doas
-@cmindex doas
-Uses TRAMP's @command{su}, @command{sudo}, or @command{doas} method
-@pxref{Inline methods, , , tramp} to run a command via @command{su},
-@command{sudo}, or @command{doas}.  These commands are in the
-eshell-tramp module, which is disabled by default.
-
-
-@item substitute
-@cmindex substitute
-A wrapper around the function @code{cl-substitute} (@pxref{Sequence
-Functions,,, cl, GNU Emacs Common Lisp Emulation}).  This command can
-be used for comparing lists of strings.
-
-This command can be loaded as part of the eshell-xtra module, which is
-disabled by default.
-
 @item time
 @cmindex time
 Show the time elapsed during a command's execution.
@@ -838,15 +773,6 @@ Built-ins
 Set or view the default file permissions for newly created files and
 directories.
 
-@item union
-@cmindex union
-A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,,
-cl, GNU Emacs Common Lisp Emulation}).  This command can be used for
-comparing lists of strings.
-
-This command can be loaded as part of the eshell-xtra module, which is
-disabled by default.
-
 @item unset
 @cmindex unset
 Unset one or more variables.  As with @command{set}, a variable name
@@ -2029,7 +1955,10 @@ Extension modules
 @node Optional modules
 @section Optional modules
 
-This section is not yet written.
+In addition to the various modules enabled by default (documented
+above), Eshell provides several other modules which are @emph{not}
+enabled by default.  If you want to enable these, you can add them to
+@code{eshell-modules-list}.
 
 @menu
 * Key rebinding::
@@ -2042,12 +1971,66 @@ Optional modules
 @node Key rebinding
 @subsection Key rebinding
 
-This section is not yet written.
+This module allows for special keybindings that only take effect
+while the point is in a region of input text.  The default keybindings
+mimic the bindings used in other shells when the user is editing new
+input text.  To enable this module, add @code{eshell-rebind} to
+@code{eshell-modules-list}.
+
+For example, it binds @kbd{C-u} to kill the current input text and
+@kbd{C-w} to @code{backward-kill-word}.  If the history module is
+enabled, it also binds @kbd{C-p} and @kbd{C-n} to move through the
+input history.
+
+If @code{eshell-confine-point-to-input} is non-@code{nil}, this module
+prevents certain commands from causing the point to leave the input
+area, such as @code{backward-word}, @code{previous-line}, etc.
 
 @node Smart scrolling
 @subsection Smart scrolling
 
-This section is not yet written.
+This module combines the facility of normal, modern shells with some
+of the edit/review concepts inherent in the design of Plan 9's 9term.
+To enable it, add @code{eshell-smart} to @code{eshell-modules-list}.
+
+@itemize @bullet
+@item
+When you invoke a command, it is assumed that you want to read the
+output of that command.
+
+@item
+If the output is not what you wanted, it is assumed that you will want
+to edit, and then resubmit a refined version of that command.
+
+@item
+If the output is valid, pressing any self-inserting character key will
+jump to end of the buffer and insert that character, in order to begin
+entry of a new command.
+
+@item
+If you show an intention to edit the previous command -- by moving
+around within it -- then the next self-inserting characters will
+insert *there*, instead of at the bottom of the buffer.
+
+@item
+If you show an intention to review old commands, such as @kbd{M-p} or
+@kbd{M-r}, point will jump to the bottom of the buffer before invoking
+that command.
+
+@item
+If none of the above has happened yet (i.e.@: your point is just
+sitting on the previous command), you can use @kbd{SPC} and
+@kbd{BACKSPACE} (or @kbd{Delete}) to page forward and backward
+@emph{through the output of the last command only}.  It will constrain
+the movement of the point and window so that the maximum amount of
+output is always displayed at all times.
+
+@item
+While output is being generated from a command, the window will be
+constantly reconfigured (until it would otherwise make no difference)
+in order to always show you the most output from the command possible.
+This happens if you change window sizes, scroll, etc.
+@end itemize
 
 @node Electric forward slash
 @subsection Electric forward slash
@@ -2107,12 +2090,76 @@ Electric forward slash
 @node Tramp extensions
 @subsection Tramp extensions
 
-This section is not yet written.
+This module adds built-in commands that use Tramp to handle running
+other commands as different users, replacing the corresponding
+external commands.  To enable it, add @code{eshell-tramp} to
+@code{eshell-modules-list}.
 
-@node Extra built-in functions
-@subsection Extra built-in functions
+@table @code
+
+@item su
+@cmindex su
+@itemx sudo
+@cmindex sudo
+@itemx doas
+@cmindex doas
+Uses TRAMP's @command{su}, @command{sudo}, or @command{doas} method
+(@pxref{Inline methods, , , tramp, The Tramp Manual}) to run a command
+via @command{su}, @command{sudo}, or @command{doas}.
 
-This section is not yet written.
+@end table
+
+@node Extra built-in commands
+@subsection Extra built-in commands
+
+This module provides several extra built-in commands documented below,
+primarily for working with lists of strings in Eshell.  To enable it,
+add @code{eshell-xtra} to @code{eshell-modules-list}.
+
+@table @code
+
+@item expr
+@cmindex expr
+An implementation of @command{expr} using the Calc package.
+@xref{Top,,, calc, The GNU Emacs Calculator}.
+
+@item intersection
+@cmindex intersection
+A wrapper around the function @code{cl-intersection} (@pxref{Lists as
+Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command
+can be used for comparing lists of strings.
+
+@item mismatch
+@cmindex mismatch
+A wrapper around the function @code{cl-mismatch} (@pxref{Searching
+Sequences,,, cl, GNU Emacs Common Lisp Emulation}).  This command can
+be used for comparing lists of strings.
+
+@item set-difference
+@cmindex set-difference
+A wrapper around the function @code{cl-set-difference} (@pxref{Lists
+as Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command can be
+used for comparing lists of strings.
+
+@item set-exclusive-or
+@cmindex set-exclusive-or
+A wrapper around the function @code{cl-set-exclusive-or} (@pxref{Lists
+as Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command can be
+used for comparing lists of strings.
+
+@item substitute
+@cmindex substitute
+A wrapper around the function @code{cl-substitute} (@pxref{Sequence
+Functions,,, cl, GNU Emacs Common Lisp Emulation}).  This command can
+be used for comparing lists of strings.
+
+@item union
+@cmindex union
+A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,,
+cl, GNU Emacs Common Lisp Emulation}).  This command can be used for
+comparing lists of strings.
+
+@end table
 
 @node Writing a module
 @section Writing a module
@@ -2164,8 +2211,6 @@ Bugs and ideas
 which is the version included with Emacs 22.
 
 @table @asis
-@item Documentation incomplete
-
 @item Differentiate between aliases and functions
 
 Allow for a Bash-compatible syntax, such as:
diff --git a/lisp/eshell/em-rebind.el b/lisp/eshell/em-rebind.el
index 75a2848a9d5..e4579497edc 100644
--- a/lisp/eshell/em-rebind.el
+++ b/lisp/eshell/em-rebind.el
@@ -29,14 +29,17 @@
 (progn
 (defgroup eshell-rebind nil
   "This module allows for special keybindings that only take effect
-while the point is in a region of input text.  By default, it binds
-C-a to move to the beginning of the input text (rather than just the
-beginning of the line), and C-p and C-n to move through the input
-history, C-u kills the current input text, etc.  It also, if
-`eshell-confine-point-to-input' is non-nil, does not allow certain
-commands to cause the point to leave the input area, such as
-`backward-word', `previous-line', etc.  This module intends to mimic
-the behavior of normal shells while the user editing new input text."
+while the point is in a region of input text.  The default
+keybindings mimic the bindings used in other shells when the user
+is editing new input text.
+
+For example, it binds C-u to kill the current input text and C-w
+to `backward-kill-word'.  If the history module is enabled, it
+also binds C-p and C-n to move through the input history, etc.
+
+If `eshell-confine-point-to-input' is non-nil, this module prevents
+certain commands from causing the point to leave the input area, such
+as `backward-word', `previous-line', etc."
   :tag "Rebind keys at input"
   :group 'eshell-module))
 
-- 
2.25.1

bug#49306: 28.0.50; Info of Eshell/Extension Modules/* is empty

[Jim Porter]

On 6/15/2023 10:12 AM, Jim Porter wrote:
> Attached are some patches to finish the Eshell documentation, targeting 
> Emacs 30 (they could probably be backported to 29 without much work, but 
> I've made some other changes to the Eshell manual in 30 already...)

I've now pushed these changes to master as 75278855f4a. Closing this 
bug. Of course, if there are any other areas we should add to the Eshell 
documentation, just let me know (probably in a new bug).