ERC doc fixes for Emacs 29

From 6e1ab9b95aab7d7c34552df994dc5bc2a5cec79e Mon Sep 17 00:00:00 2001
From: "F. Jason Park" <[email protected]>
Date: Wed, 30 Nov 2022 23:10:58 -0800
Subject: [PATCH] Add dedicated auth-source section in ERC manual

* doc/misc/erc.texi: Move auth-source description from the Password
subsection of the Connecting chapter, to the new Integrations chapter
under the subheading Auth-source.
* etc/ERC-NEWS: Re-link auth-source mention.
* lisp/erc/erc-services.el (erc-auth-source-services-function):
Re-link auth-source info node in doc string.
* lisp/erc/erc.el (erc-password, erc-auth-source-server-function,
erc-auth-source-join-function): Re-link auth-source info node in doc
strings.
---
 doc/misc/erc.texi        | 233 ++++++++++++++++++++++-----------------
 etc/ERC-NEWS             |   4 +-
 lisp/erc/erc-services.el |   2 +-
 lisp/erc/erc.el          |   6 +-
 4 files changed, 136 insertions(+), 109 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index a8d1dd7823..808a6c1832 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -687,6 +687,8 @@ Connecting
 
 @xref{Help for users,,,auth, Emacs auth-source Library}, for more on the
 @file{.authinfo}/@file{.netrc} backend of @code{auth-source}.
+For other uses of auth-source throughout ERC, @xref{auth-source,
+ERC's auth-source integration}.
 @end defun
 
 @subheading Server
@@ -806,6 +808,24 @@ Connecting
 @subheading Password
 @cindex password
 
+This parameter was traditionally meant to specify a @dfn{server
+password} to be sent as an ``argument'' to the IRC @samp{PASS}
+command.  However, such passwords aren't really used these days, even
+for private IRC servers.  Instead, servers and networks typically
+consider a server password optional and expect them, when present, to
+convey other authentication information, such as account-services
+(a.k.a., ``NickServ'') credentials.  In the case of the latter, this
+typically involves a special syntax, such as @samp{myuser:mypass}.
+IRC bouncers often do something similar but include a pre-configured
+network-ID component, for example, @samp{bncuser/mynet:bncpass}.
+
+In general, if you have @emph{not} been asked by your network or
+bouncer to specify a repurposed server password, you should instead
+consider setting up @samp{erc-services} or, preferably, SASL.  In
+addition to providing user options that supplant it entirely, both
+offer a way of borrowing this parameter for their own respective mode
+of authentication.  @xref{SASL, SASL in ERC}.
+
 @defopt erc-prompt-for-password
 If non-@code{nil} (the default), @kbd{M-x erc} and @kbd{M-x erc-tls}
 prompt for a server password.  This only affects interactive
@@ -814,109 +834,8 @@ Connecting
 
 @noindent
 If you prefer, you can set this option to @code{nil} and use the
-@code{auth-source} mechanism to store your password.  For instance, if
-the option @code{auth-sources} contains @file{~/.authinfo}, put
-something like the following in that file:
-
-@example
-machine irc.example.net login mynick password sEcReT
-@end example
-
-@noindent
-For server passwords, that is, passwords sent for the IRC @samp{PASS}
-command, the @samp{host} field (@w{@code{machine irc.example.net}} in
-the above example)
-corresponds to the @var{server} parameter used by @code{erc} and
-@code{erc-tls}.  Unfortunately, specifying a network, like
-@samp{Libera.Chat}, or a specific network server, like
-@samp{platinum.libera.chat}, won't normally work for looking up a server
-password because such information isn't available during opening
-introductions.  (Actually, ERC @emph{can} find entries with arbitrary
-@samp{host} values for any context, including server passwords, but
-that requires customizing the more advanced options below.)
-
-If ERC can't find a suitable server password, it will just skip the IRC
-@samp{PASS} command altogether, something users may want when using
-CertFP or engaging NickServ via ERC's ``services'' module.  If that is
-what you'd like to do, you can also customize the option
-@code{erc-auth-source-server-function} to @code{nil} to skip
-server-password lookup for all servers.  Note that some networks and
-IRCds may accept account-services authentication via server password
-using the nonstandard @samp{mynick:sEcReT} convention.
-
-As just mentioned, you can also use @code{auth-source} to authenticate
-to account services the traditional way, through a bot called
-@samp{NickServ}.  To tell ERC to do that, set
-@code{erc-use-auth-source-for-nickserv-password} to @code{t}.  For
-these and most other queries, entries featuring custom identifiers and
-networks are matched first, followed by network-specific servers and
-dialed endpoints (typically, the @var{server} argument passed to
-@code{erc}). The following netrc-style entries appear in order of
-precedence:
-
-@example
-machine Libera/cellphone login MyNick password sEcReT
-machine Libera.Chat login MyNick password sEcReT
-machine zirconium.libera.chat login MyNick password sEcReT
-machine irc.libera.chat login MyNick password sEcReT
-@end example
-
-@noindent
-Remember that field labels vary per backend, so @samp{machine} (in
-netrc's case) maps to auth-source's generalized notion of a host,
-hence the @samp{:host} keyword property.  Also, be sure to mind the
-syntax of your chosen backend medium.  For example, always quote
-channel names in a netrc file.
-
-If this all seems overly nuanced or just plain doesn't appeal to you,
-see options @code{erc-auth-source-services-function} and friends, described
-below.  These let you query auth-source your way.  Most users can
-simply ignore the passed-in arguments and get by with something like
-the following:
-
-@lisp
-(defun my-fancy-auth-source-func (&rest _)
-  (let* ((host (read-string "host: " nil nil "default"))
-         (pass (auth-source-pick-first-password :host host)))
-    (if (and pass (string-search "libera" host))
-        (concat "MyNick:" pass)
-      pass)))
-@end lisp
-
-Lastly, ERC also consults @code{auth-source} to find ``keys'' that may
-be required by certain channels you join.  When modifying a
-traditional @code{auth-source} entry for this purpose, put the channel
-name in the @samp{user} field (for example, @samp{login "#fsf"}, in
-netrc's case).  The actual key goes in the @samp{password} (or
-@samp{secret}) field.
-
-@noindent
-For details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
-
-@anchor{ERC auth-source functions}
-@defopt erc-auth-source-server-function
-@end defopt
-@defopt erc-auth-source-services-function
-@end defopt
-@defopt erc-auth-source-join-function
-
-ERC calls these functions with keyword arguments recognized by
-@code{auth-source-search}, namely, those deemed most relevant to the
-current context, if any.  For example, with NickServ queries,
-@code{:user} is the ``desired'' nickname rather than the current one.
-Generalized names, like @code{:user} and @code{:host}, are always used
-over back-end specific ones, like @code{:login} or @code{:machine}.
-ERC expects a string to use as the secret or @code{nil}, if the search
-fails.
-
-@findex erc-auth-source-search
-The default value for all three options is the function
-@code{erc-auth-source-search}.  It tries to merge relevant contextual
-parameters with those provided or discovered from the logical connection
-or the underlying transport.  Some auth-source back ends may not be
-compatible; netrc, plstore, json, secrets, and pass are currently
-supported.
-@end defopt
+@code{auth-source} mechanism to store your password.
+@xref{auth-source, ERC's auth-source integration}, for more.
 
 @subheading Full name
 
@@ -1288,6 +1207,114 @@ Integrations
 @noindent
 Users on Emacs 28 and below may need to use @code{browse-url} instead.
 
+@subheading Auth-source
+@anchor{auth-source}
+@cindex auth-source
+
+ERC can be configured to use the built-in auth-source library for
+looking up passwords. @pxref{Top,,auth-source, auth, Emacs auth-source
+Library}, for general info on setting up various back ends.  To get
+started with the default, netrc back end, put something like the
+following in a file (such as @file{~/.authinfo}) known to the option
+@code{auth-sources}:
+
+@example
+machine irc.example.net login mynick password sEcReT
+@end example
+
+@noindent
+For server passwords, that is, passwords sent for the IRC @samp{PASS}
+command, the @samp{host} field (@w{@code{machine irc.example.net}} in
+the above example)
+corresponds to the @var{server} parameter used by @code{erc} and
+@code{erc-tls}.  Unfortunately, specifying a network, like
+@samp{Libera.Chat}, or a specific network server, like
+@samp{platinum.libera.chat}, won't normally work for looking up a server
+password because such information isn't available during opening
+introductions.  (Actually, ERC @emph{can} find entries with arbitrary
+@samp{host} values for any context, including server passwords, but
+that requires customizing the more advanced options below.)
+
+If ERC can't find a suitable server password, it will just skip the IRC
+@samp{PASS} command altogether, something users may want when using
+CertFP or engaging NickServ via ERC's ``services'' module.  If that is
+what you'd like to do, you can also customize the option
+@code{erc-auth-source-server-function} to @code{nil} to skip
+server-password lookup for all servers.  Note that some networks and
+IRCds may accept account-services authentication via server password
+using the nonstandard @samp{mynick:sEcReT} convention.
+
+As just mentioned, you can also use @code{auth-source} to authenticate
+to account services the traditional way, through a bot called
+@samp{NickServ}.  To tell ERC to do that, set
+@code{erc-use-auth-source-for-nickserv-password} to @code{t}.  For
+these and most other queries, entries featuring custom identifiers and
+networks are matched first, followed by network-specific servers and
+dialed endpoints (typically, the @var{server} argument passed to
+@code{erc}). The following netrc-style entries appear in order of
+precedence:
+
+@example
+machine Libera/cellphone login MyNick password sEcReT
+machine Libera.Chat login MyNick password sEcReT
+machine zirconium.libera.chat login MyNick password sEcReT
+machine irc.libera.chat login MyNick password sEcReT
+@end example
+
+@noindent
+Remember that field labels vary per backend, so @samp{machine} (in
+netrc's case) maps to auth-source's generalized notion of a host,
+hence the @samp{:host} keyword property.  Also, be sure to mind the
+syntax of your chosen backend medium.  For example, always quote
+channel names in a netrc file.
+
+If this all seems overly nuanced or just plain doesn't appeal to you,
+see options @code{erc-auth-source-services-function} and friends, described
+below.  These let you query auth-source your way.  Most users can
+simply ignore the passed-in arguments and get by with something like
+the following:
+
+@lisp
+(defun my-fancy-auth-source-func (&rest _)
+  (let* ((host (read-string "host: " nil nil "default"))
+         (pass (auth-source-pick-first-password :host host)))
+    (if (and pass (string-search "libera" host))
+        (concat "MyNick:" pass)
+      pass)))
+@end lisp
+
+Lastly, ERC also consults @code{auth-source} to find ``keys'' that may
+be required by certain channels you join.  When modifying a
+traditional @code{auth-source} entry for this purpose, put the channel
+name in the @samp{user} field (for example, @samp{login "#fsf"}, in
+netrc's case).  The actual key goes in the @samp{password} (or
+@samp{secret}) field.
+
+@anchor{ERC auth-source functions}
+@defopt erc-auth-source-server-function
+@end defopt
+@defopt erc-auth-source-services-function
+@end defopt
+@defopt erc-auth-source-join-function
+
+ERC calls these functions with keyword arguments recognized by
+@code{auth-source-search}, namely, those deemed most relevant to the
+current context, if any.  For example, with NickServ queries,
+@code{:user} is the ``desired'' nickname rather than the current one.
+Generalized names, like @code{:user} and @code{:host}, are always
+preferred over back-end specific ones, like @code{:login} or
+@code{:machine}.  In return, ERC expects a string if the search
+succeeds or @code{nil} if it fails.
+
+@findex erc-auth-source-search
+The default value for all three options is the function
+@code{erc-auth-source-search}.  It tries to merge relevant contextual
+parameters with those provided or discovered from the logical connection
+or the underlying transport.  Some auth-source back ends may not be
+compatible; netrc, plstore, json, secrets, and pass are currently
+supported.
+@end defopt
+
 @node Options
 @section Options
 @cindex options
diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS
index d0d84d0a98..1925cc1114 100644
--- a/etc/ERC-NEWS
+++ b/etc/ERC-NEWS
@@ -45,8 +45,8 @@ With the overhaul of the services module temporarily shelved and the
 transition to SASL-based authentication still underway, users may feel
 left in the lurch to endure yet another release cycle of backtick
 hell.  For some, auth-source may provide a workaround in the form of
-nonstandard server passwords.  See the "Connection" node in the manual
-under the subheading "Password".
+nonstandard server passwords.  See the section titled "Auth-source" in
+the Integrations chapter of ERC's manual.
 
 ** Rudimentary SASL support has arrived.
 A new module, 'erc-sasl', now ships with ERC 5.5.  See the SASL
diff --git a/lisp/erc/erc-services.el b/lisp/erc/erc-services.el
index 48953288d1..c2d91ca9d6 100644
--- a/lisp/erc/erc-services.el
+++ b/lisp/erc/erc-services.el
@@ -180,7 +180,7 @@ erc-auth-source-services-function
 `auth-source-search' and relevant to authenticating to nickname
 services.  In return, ERC expects a string to send as the
 password, or nil, to fall through to the next method, such as
-prompting.  See info node `(erc) Connecting' for details."
+prompting.  See info node `(erc) auth-source' for details."
   :package-version '(ERC . "5.4.1") ; FIXME update when publishing to ELPA
   :type '(choice (const erc-auth-source-search)
                  (const nil)
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 268d83dc44..32103aa029 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -219,7 +219,7 @@ erc-password
 This variable only exists for legacy reasons.  It's not customizable and
 is limited to a single server password.  Users looking for similar
 functionality should consider auth-source instead.  See info
-node `(auth) Top' and info node `(erc) Connecting'.")
+node `(auth) Top' and info node `(erc) auth-source'.")
 
 (make-obsolete-variable 'erc-password "use auth-source instead" "29.1")
 
@@ -3208,7 +3208,7 @@ erc-auth-source-server-function
 password, or nil, to skip the \"PASS\" command completely.  An
 explicit `:password' argument to entry-point commands `erc' and
 `erc-tls' also inhibits lookup, as does setting this option to
-nil.  See info node `(erc) Connecting' for details."
+nil.  See info node `(erc) auth-source' for details."
   :package-version '(ERC . "5.4.1") ; FIXME update when publishing to ELPA
   :group 'erc
   :type '(choice (const erc-auth-source-search)
@@ -3223,7 +3223,7 @@ erc-auth-source-join-function
 \"key\", or nil to just join the channel normally.  Setting the
 option itself to nil tells ERC to always forgo consulting
 auth-source for channel keys.  For more information, see info
-node `(erc) Connecting'."
+node `(erc) auth-source'."
   :package-version '(ERC . "5.4.1") ; FIXME update when publishing to ELPA
   :group 'erc
   :type '(choice (const erc-auth-source-search)
-- 
2.38.1

From a31664dc8f9f6515083d1e207407eba90344e7d0 Mon Sep 17 00:00:00 2001
From: "F. Jason Park" <[email protected]>
Date: Wed, 30 Nov 2022 23:10:58 -0800
Subject: [PATCH] ; * doc/misc/erc.texi: Fix SASL typo and example.

---
 doc/misc/erc.texi | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index a8d1dd7823..2ed3065ad9 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -1057,8 +1057,8 @@ SASL
 You can also set this to a nonemtpy string, and ERC will send that
 when needed, no questions asked.  Or, if you'd rather use auth-source,
 set @code{erc-sasl-auth-source-function} to a function, and ERC will
-perform an auth-source query instead.  As last resort in all cases,
-ERC will prompt you for input.
+perform an auth-source query instead.  In all cases, ERC will prompt
+you for input as a last resort.
 
 Lastly, if your mechanism is @code{ecdsa-nist256p-challenge}, this
 option should instead hold the file name of your key.
@@ -1137,7 +1137,7 @@ SASL
 
 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
+machine irc.example.net login aph-bot password sesame
 @end example
 
 @lisp
-- 
2.38.1