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!

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 @@ the buffer is merely buried instead.
 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 @@ the external @command{info} command, but uses Emacs's internal Info
 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 @@ Manual}.  Otherwise call the external @command{make} command.
 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 @@ is required.
 @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 @@ Source an Eshell file in a subshell environment.  This is not to be
 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 @@ Show the time elapsed during a command's execution.
 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 @@ modules.@footnote{ERC provides a similar module facility.}
 @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 @@ This section is not yet written.
 @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 @@ within the first command.
 @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 @@ Below is a list of some known problems with Eshell version 2.4.2,
 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))