From: Jim Porter <jporterbugs@gmail.com>
Date: Sat, 13 May 2023 03:11:01 +0000 (-0700)
Subject: Correct the Eshell documentation about how to write new modules
X-Git-Tag: emacs-29.1-rc1~47
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7c417b2ae555c8b07c4eb440a2c798826842c636;p=emacs.git

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.
---

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