scratch/emacs-29-eshell-docs d2be413c027 3/9: Correct the Eshell documentation about how to write new modules

[Jim Porter]

branch: scratch/emacs-29-eshell-docs
commit d2be413c0278f10059ff307d63f25dcf30fe6693
Author: Jim Porter <jporterbugs@gmail.com>
Commit: Jim Porter <jporterbugs@gmail.com>

    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.
    
    Do not merge to master.  This is a backport of 77f13edab0f.
---
 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 44eb438cfd9..cff7c594d96 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -2045,23 +2045,27 @@ 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:
+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