master bb894845ed6 1/3: Teach customize-option about erc-modules

[F. Jason Park]

branch: master
commit bb894845ed6a06e8b301251d62f8b4a73a09d5ea
Author: F. Jason Park <jp@neverwas.me>
Commit: F. Jason Park <jp@neverwas.me>

    Teach customize-option about erc-modules
    
    * lisp/erc/erc-goodies.el (erc-scrolltobottom-mode)
    (erc-scrolltobottom-enable): Use `setq' instead of `setopt' because
    the latter isn't defined in Emacs 27 and 28.  This fix is unrelated to
    the main thrust of this commit.
    * lisp/erc/erc.el (erc-modules): Make good on decades old language in
    info node "(erc) Modules" by ensuring `customize-option' can find this
    option before its containing library is loaded.  Like
    `gnus-select-method', this option serves as an entry point for
    configuring the application and is presented that way in tutorials and
    library front matter.  Moreover, it can't be reasonably autoloaded in
    the traditional way because of its many dependencies and large textual
    footprint.
    (erc-display-message): Revise doc string.
---
 lisp/erc/erc-goodies.el |  2 +-
 lisp/erc/erc.el         | 37 ++++++++++++++++++++-----------------
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/lisp/erc/erc-goodies.el b/lisp/erc/erc-goodies.el
index 8293994c5d4..7e30b1060fd 100644
--- a/lisp/erc/erc-goodies.el
+++ b/lisp/erc/erc-goodies.el
@@ -83,7 +83,7 @@ be experimental.  It currently only works with Emacs 28+."
    (when (and erc-scrolltobottom-all (< emacs-major-version 28))
      (erc-button--display-error-notice-with-keys
       "Option `erc-scrolltobottom-all' requires Emacs 28+. Disabling.")
-     (setopt erc-scrolltobottom-all nil))
+     (setq erc-scrolltobottom-all nil))
    (unless erc--updating-modules-p (erc-buffer-do #'erc--scrolltobottom-setup))
    (if erc-scrolltobottom-all
        (progn
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index edac1060c3e..67c31d961e3 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -2183,13 +2183,17 @@ buffer rather than a server buffer.")
       (cl-pushnew mod (if (get mod 'erc--module) built-in third-party)))
     `(,@(sort built-in #'string-lessp) ,@(nreverse third-party))))
 
+;;;###autoload(custom-autoload 'erc-modules "erc")
+
 (defcustom erc-modules '( autojoin button completion fill imenu irccontrols
                           list match menu move-to-prompt netsplit
                           networks readonly ring stamp track)
-  "A list of modules which ERC should enable.
-If you set the value of this without using `customize' remember to call
-\(erc-update-modules) after you change it.  When using `customize', modules
-removed from the list will be disabled."
+  "Modules to enable while connecting.
+When modifying this option in lisp code, use a Custom-friendly
+facilitator, like `setopt', or call `erc-update-modules'
+afterward.  This ensures a consistent ordering and disables
+removed modules.  It also gives packages access to the hook
+`erc-before-connect'."
   :get (lambda (sym)
          ;; replace outdated names with their newer equivalents
          (erc-migrate-modules (symbol-value sym)))
@@ -3828,14 +3832,14 @@ TYPE, when non-nil, to be a symbol handled by
 string MSG).  Expect BUFFER to be among the sort accepted by the
 function `erc-display-line'.
 
-Expect BUFFER to be a live `erc-mode' buffer, a list of such
-buffers, or the symbols `all' or `active'.  If `all', insert
-STRING in all buffers for the current session.  If `active',
-defer to the function `erc-active-buffer', which may return the
-session's server buffer if the previously active buffer has been
-killed.  If BUFFER is nil or a network process, pretend it's set
-to the appropriate server buffer.  Otherwise, use the current
-buffer.
+When non-nil, expect BUFFER to be a live `erc-mode' buffer, a
+list of such buffers, or the symbols `all' or `active'.  If
+`all', insert STRING in all buffers for the current session.  If
+`active', defer to the function `erc-active-buffer', which may
+return the session's server buffer if the previously active
+buffer has been killed.  If BUFFER is nil or a network process,
+pretend it's set to the appropriate server buffer.  Otherwise,
+use the current buffer.
 
 When TYPE is a list of symbols, call handlers from left to right
 without influencing how they behave when encountering existing
@@ -3848,11 +3852,10 @@ being (erc-error-face erc-notice-face) throughout MSG 
when
 `erc-notice-highlight-type' is left at its default, `all'.
 
 As of ERC 5.6, assume third-party code will use this function
-instead of lower-level ones, like `erc-insert-line', when needing
-ERC to process arbitrary informative messages as if they'd been
-sent from a server.  That is, guarantee \"local\" messages, for
-which PARSED is typically nil, will be subject to buttonizing,
-filling, and other effects."
+instead of lower-level ones, like `erc-insert-line', to insert
+arbitrary informative messages as if sent by the server.  That
+is, tell modules to treat a \"local\" message for which PARSED is
+nil like any other server-sent message."
   (let* ((erc--msg-props
           (or erc--msg-props
               (let ((table (make-hash-table))