; Improve erc-services and upgrade documentation

* doc/misc/erc.texi (Getting Help and Reporting Bugs): Describe
alternate method for upgrading from GNU ELPA.  This is a partial
workaround for bug#68660 discovered by ERC contributor Alcor.
* lisp/erc/erc-backend.el (erc-call-hooks): Add comment.
* lisp/erc/erc-services.el (erc-nickserv-alist): Doc.
* test/lisp/erc/erc-scenarios-base-renick.el
(erc-scenarios-base-renick-queries-bouncer): Adjust timeout.

doc/misc/erc.texi

@@ -2123,11 +2123,20 @@ to IRC, and don't forget that you can roll back to the previous
 version by running @kbd{M-x package-delete @key{RET}}.
 @xref{Packages,,,emacs, The Emacs Editor}, for more information.
 
+Note that a bug affecting Emacs' packaging machinery may prevent the
+above method from working on Emacs versions 29 and below.  Users on 29
+can try running @kbd{C-u M-x package-install @key{RET}} instead.
+Users on 28 and below can click on the @emph{installed} @samp{erc}
+line item in the @file{*Packages*} buffer instead of the newest one,
+and then, in the resulting @code{help-mode} buffer, find and activate
+the button for the newest version, which should appear in the summary
+item @samp{Other versions}.
+
 In the rare instance you need an emergency fix or have volunteered to
 test an edge feature between ERC releases, you can try adding
 @samp{("devel" . "https://elpa.gnu.org/devel/")} to
 @code{package-archives} prior to performing the steps above.  For
-this, you'll want to instead select a ``snapshot'' version from the
+this, you'll want to instead select a @dfn{snapshot} version from the
 menu.  Please be aware that when going this route, the latest changes
 may not yet be available and you run the risk of incurring other bugs
 and encountering unstable features.

lisp/erc/erc-backend.el

@@ -1536,6 +1536,8 @@ Finds hooks by looking in the `erc-server-responses' hash table."
   (let ((hook (or (erc-get-hook (erc-response.command message))
                   'erc-default-server-functions)))
     (run-hook-with-args-until-success hook process message)
+    ;; Some handlers, like `erc-cmd-JOIN', open new targets without
+    ;; saving excursion, and `erc-open' sets the current buffer.
     (erc-with-server-buffer
       (run-hook-with-args 'erc-timer-hook (erc-current-time)))))
 

lisp/erc/erc-services.el

@@ -22,6 +22,13 @@
 
 ;;; Commentary:
 
+;; As of ERC 5.6, this library's main module, `services', mainly
+;; concerns itself with authenticating to legacy IRC servers.  If your
+;; server supports SASL or CERTFP, please use one of those instead.
+;; See (info "(erc) client-certificate") and (info "(erc) SASL") for
+;; details.  Note that this library also contains the local module
+;; `services-regain' as well as standalone utility functions.
+
 ;; There are two ways to go about identifying yourself automatically to
 ;; NickServ with this module.  The more secure way is to listen for identify
 ;; requests from the user NickServ.  Another way is to identify yourself to
@@ -37,10 +44,7 @@
 
 ;; Usage:
 ;;
-;; Put into your .emacs:
-;;
-;; (require 'erc-services)
-;; (erc-services-mode 1)
+;; Customize the option `erc-modules' to include `services'.
 ;;
 ;; Add your nickname and NickServ password to `erc-nickserv-passwords'.
 ;; Using the Libera.Chat network as an example:
@@ -50,10 +54,7 @@
 ;;
 ;; The default automatic identification mode is autodetection of NickServ
 ;; identify requests.  Set the variable `erc-nickserv-identify-mode' if
-;; you'd like to change this behavior.  You can also change the way
-;; automatic identification is handled by using:
-;;
-;; M-x erc-nickserv-identify-mode
+;; you'd like to change this behavior.
 ;;
 ;; If you'd rather not identify yourself automatically but would like access
 ;; to the functions contained in this file, just load this file without
@@ -309,21 +310,26 @@ Example of use:
      "/msg\\s-NickServ\\s-IDENTIFY\\s-\^_password"
      "NickServ@services.slashnet.org"
      "IDENTIFY" nil nil nil))
-   "Alist of NickServer details, sorted by network.
+  "Alist of NickServer details, sorted by network.
 Every element in the list has the form
-  (SYMBOL NICKSERV REGEXP NICK KEYWORD USE-CURRENT ANSWER SUCCESS-REGEXP)
+  (NETWORK SENDER INSTRUCT-RX NICK SUBCMD YOUR-NICK-P ANSWER SUCCESS-RX)
 
-SYMBOL is a network identifier, a symbol, as used in `erc-networks-alist'.
-NICKSERV is the description of the nickserv in the form nick!user@host.
-REGEXP is a regular expression matching the message from nickserv.
-NICK is nickserv's nickname.  Use nick@server where necessary/possible.
-KEYWORD is the keyword to use in the reply message to identify yourself.
-USE-CURRENT indicates whether the current nickname must be used when
-  identifying.
-ANSWER is the command to use for the answer.  The default is `privmsg'.
-SUCCESS-REGEXP is a regular expression matching the message nickserv
-  sends when you've successfully identified.
-The last two elements are optional."
+NETWORK is a network identifier, a symbol, as used in `erc-networks-alist'.
+SENDER is the exact nick!user@host \"source\" for \"NOTICE\" messages
+indicating success or requesting that the user identify.
+INSTRUCT-RX is a regular expression matching a \"NOTICE\" from the
+  services bot instructing the user to identify.  It must be non-null
+  when the option `erc-nickserv-identify-mode' is set to `autodetect'.
+  When it's `both', and this field is non-null, ERC will forgo
+  identifying on nick changes and after connecting.
+NICK is the nickname of the services bot to use when issuing commands.
+SUBCMD is the bot command for identifying, typically \"IDENTIFY\".
+YOUR-NICK-P indicates whether to send the user's current nickname before
+  their password when identifying.
+ANSWER is the command to use for the answer.  The default is \"PRIVMSG\".
+SUCCESS-RX is a regular expression matching the message NickServ sends
+  when you've successfully identified.
+The last two elements are optional, as are others, where implied."
    :type '(repeat
 	   (list :tag "Nickserv data"
 		 (symbol :tag "Network name")

test/lisp/erc/erc-scenarios-base-renick.el

@@ -253,7 +253,7 @@
     (ert-info ("Joined by bouncer to #chan@barnet, pal persent")
       (with-current-buffer (erc-d-t-wait-for 10 (get-buffer "#chan@barnet"))
         (funcall expect 1 "rando")
-        (funcall expect 2 "come, sir, I am")))
+        (funcall expect 5 "come, sir, I am")))
 
     (ert-info ("Query buffer exists for rando@foonet")
       (with-current-buffer (erc-d-t-wait-for 10 (get-buffer "rando@foonet"))