master 56706254a8e 1/2: ; Don't mention erc-branded Compat macros in ERC-NEWS

[F. Jason Park]

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

    ; Don't mention erc-branded Compat macros in ERC-NEWS
    
    * doc/misc/erc.texi: Change fancy SASL example to also demonstrate
    `let'-binding a local module.
    * etc/ERC-NEWS: Don't mention `erc-compat-call' and
    `erc-compat-function' because Emacs now ships with a compat.el stub
    library.
    * lisp/erc/erc-backend.el (erc-decode-parsed-server-response): Add
    comments.
    * lisp/erc/erc.el (erc): Mention return value.
---
 doc/misc/erc.texi       | 33 +++++++++++++++++++--------------
 etc/ERC-NEWS            |  2 --
 lisp/erc/erc-backend.el |  2 ++
 lisp/erc/erc.el         |  5 +++--
 4 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index f877fb681fe..c7ab7e7bf21 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -1230,25 +1230,30 @@ machine Example.Net login aph-bot password sesame
 
 (defun my-erc-up (network)
   (interactive "Snetwork: ")
-
-  (pcase network
-    ('libera
-     (let ((erc-sasl-mechanism 'external))
-       (erc-tls :server "irc.libera.chat" :port 6697
-                :client-certificate t)))
-    ('example
-     (let ((erc-sasl-auth-source-function
-            #'erc-sasl-auth-source-password-as-host))
-       (erc-tls :server "irc.example.net" :port 6697
-                :user "alyssa"
-                :password "Example.Net")))))
+  (require 'erc-sasl)
+  (or (let ((erc-modules (cons 'sasl erc-modules)))
+        (pcase network
+          ('libera
+           (let ((erc-sasl-mechanism 'external))
+             (erc-tls :server "irc.libera.chat"
+                      :client-certificate t)))
+          ('example
+           (let ((erc-sasl-auth-source-function
+                  #'erc-sasl-auth-source-password-as-host))
+             (erc-tls :server "irc.example.net"
+                      :user "alyssa"
+                      :password "Example.Net")))))
+      ;; Non-SASL
+      (call-interactively #'erc-tls)))
 @end lisp
 
 You've started storing your credentials with auth-source and have
 decided to try SASL on another network as well.  But there's a catch:
 this network doesn't support @samp{EXTERNAL}.  You use
-@code{let}-binding to get around this and successfully authenticate to
-both networks.
+@code{let}-binding to work around this and successfully authenticate
+to both networks.  (Note that this example assumes you've removed
+@code{sasl} from @code{erc-modules} globally and have instead opted to
+add it locally when connecting to preconfigured networks.)
 
 @end itemize
 
diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS
index b2aceaa9f39..e8082582de3 100644
--- a/etc/ERC-NEWS
+++ b/etc/ERC-NEWS
@@ -694,8 +694,6 @@ by toggling a provided compatibility switch.  See source 
code around
 the function 'erc-send-action' for details.
 
 *** Miscellaneous changes
-Two helper macros from GNU ELPA's Compat library are now available to
-third-party modules as 'erc-compat-call' and 'erc-compat-function'.
 In 'erc-button-alist', 'Info-goto-node' has been supplanted by plain
 old 'info', and the "<URL:...>" entry has been removed because it was
 more or less redundant.  In all ERC buffers, the "<TAB>" key is now
diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el
index 7b782d0ef44..9fc8a4d29f4 100644
--- a/lisp/erc/erc-backend.el
+++ b/lisp/erc/erc-backend.el
@@ -1479,10 +1479,12 @@ for decoding."
   (let ((args (erc-response.command-args parsed-response))
         (decode-target nil)
         (decoded-args ()))
+    ;; FIXME this should stop after the first match.
     (dolist (arg args nil)
       (when (string-match "^[#&].*" arg)
         (setq decode-target arg)))
     (when (stringp decode-target)
+      ;; FIXME `decode-target' should be passed as TARGET.
       (setq decode-target (erc-decode-string-from-target decode-target nil)))
     (setf (erc-response.unparsed parsed-response)
           (erc-decode-string-from-target
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index f250584e47a..5c8b3785bc6 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -2772,8 +2772,9 @@ PORT, NICK, and PASSWORD, along with USER and FULL-NAME 
when
 given a prefix argument.  Non-interactively, expect the rarely
 needed ID parameter, when non-nil, to be a symbol or a string for
 naming the server buffer and identifying the connection
-unequivocally.  (See Info node `(erc) Connecting' for details
-about all mentioned parameters.)
+unequivocally.  Once connected, return the server buffer.  (See
+Info node `(erc) Connecting' for details about all mentioned
+parameters.)
 
 Together with `erc-tls', this command serves as the main entry
 point for ERC, the powerful, modular, and extensible IRC client.