emacs-29 83b9496a19 2/3: * doc/misc/erc.texi: Revise SASL and modules chapters.

[Amin Bandali]

branch: emacs-29
commit 83b9496a193c41ed7e41b36838727e234c81a2d1
Author: F. Jason Park <jp@neverwas.me>
Commit: Amin Bandali <bandali@gnu.org>

    * doc/misc/erc.texi: Revise SASL and modules chapters.
---
 doc/misc/erc.texi | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 79 insertions(+), 4 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index e165adbb49..2835baa3d6 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -392,10 +392,14 @@ modules are loaded.
 There is a spiffy customize interface, which may be reached by typing
 @kbd{M-x customize-option @key{RET} erc-modules @key{RET}}.
 When removing a module outside of the Custom ecosystem, you may wish
-to ensure it's disabled by invoking its associated minor-mode toggle,
-such as @kbd{M-x erc-spelling-mode @key{RET}}.  Note that, these days,
-calling @code{erc-update-modules} in an init file is typically
-unnecessary.
+to ensure it's disabled by invoking its associated minor-mode toggle
+with a nonpositive prefix argument, for example, @kbd{C-u - M-x
+erc-spelling-mode @key{RET}}.  Additionally, if you plan on loading
+third-party modules that perform atypical setup on activation, you may
+need to arrange for calling @code{erc-update-modules} in your init
+file.  Examples of such setup might include registering an
+@code{erc-before-connect} hook, advising @code{erc-open}, and
+modifying @code{erc-modules} itself.
 
 The following is a list of available modules.
 
@@ -1082,6 +1086,77 @@ such a thing, please contact your network operator.  
Otherwise, just
 leave this set to @code{nil}.
 @end defopt
 
+@subheading Examples
+
+@itemize @bullet
+@item
+Defaults
+
+@lisp
+(erc-tls :server "irc.libera.chat" :port 6697
+         :nick "aph"
+         :user "APHacker"
+         :password "changeme")
+@end lisp
+
+Here, after adding @code{sasl} to @code{erc-modules} via the Customize
+interface, you authenticate to Libera.Chat using the @samp{PLAIN}
+mechanism and your NickServ credentials, @samp{APHacker} and
+@samp{changeme}.
+
+@item
+External
+
+@lisp
+(setopt erc-sasl-mechanism 'external)
+
+(erc-tls :server "irc.libera.chat" :port 6697 :nick "aph"
+         :client-certificate
+         '("/home/aph/my.key" "/home/aph/my.crt"))
+@end lisp
+
+You decide to switch things up and try out the @samp{EXTERNAL}
+mechanism.  You follow your network's instructions for telling
+NickServ about your client-certificate's fingerprint, and you
+authenticate successfully.
+
+@item
+Multiple networks
+
+@example
+# ~/.authinfo.gpg
+
+machine irc.libera.chat key /home/aph/my.key cert /home/aph/my.crt
+machine Example.Net login alyssa password sEcReT
+machine Example.Net login aph-bot password sesame
+@end example
+
+@lisp
+;; init.el
+
+(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-auth-source-search)
+           (erc-sasl-password 'Example.Net))
+       (erc-tls :server "irc.example.net" :port 6697
+                :user "alyssa")))))
+@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.
+
+@end itemize
+
 @subheading Troubleshooting
 
 @strong{Warning:} ERC's SASL offering is currently limited by a lack