From f2981a1681d34b145753296e506f4c3ca7cba359 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Sun, 29 Jan 2023 19:59:56 -0800
Subject: [PATCH] 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 @@ at the end of the command are excluded.  This allows input like this:
 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 @@ when chaining commands with the operators @code{&&}, @code{||},
 @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.39.2