emacs-29 9ac80e8a6e 1/7: Add dedicated auth-source section in ERC manual

[F. Jason Park]

branch: emacs-29
commit 9ac80e8a6e4969cfe88d5233dc4152bbfa46c848
Author: F. Jason Park <jp@neverwas.me>
Commit: F. Jason Park <jp@neverwas.me>

    Add dedicated auth-source section in ERC manual
    
    * doc/misc/erc.texi: Move auth-source description from the Password
    subheading of the Advanced chapter's Connecting section to the new
    Integrations section as a new node, Auth-Source, and give it a bit
    more structure.  Fix various misuses of xref vs. pxref.  Convert URL
    subheading to subsection and add anchor.  Prefer "backend" as a single
    word, based on usage in other manuals.  Also replace loud "warning" in
    SASL troubleshooting section.
    * etc/ERC-NEWS: Re-link auth-source mention.
    * lisp/erc/erc-sasl.el (erc-sasl-auth-source-function): Update info
    node in doc string.
    * 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        | 344 ++++++++++++++++++++++++++++++-----------------
 etc/ERC-NEWS             |   4 +-
 lisp/erc/erc-sasl.el     |   2 +-
 lisp/erc/erc-services.el |   2 +-
 lisp/erc/erc.el          |   6 +-
 5 files changed, 226 insertions(+), 132 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index 5ad739a77e..2ab2e90894 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -570,10 +570,20 @@ toggle never mutates @code{erc-modules}.
 
 @menu
 * Connecting::                  Ways of connecting to an IRC server.
-* SASL::                        Authenticating via SASL
+* SASL::                        Authenticating via SASL.
 * Sample Configuration::        An example configuration file.
 * Integrations::                Integrations available for ERC.
 * Options::                     Options that are available for ERC.
+
+@detailmenu
+--- Detailed Node Listing ---
+
+Integrations
+
+* URL::                         Opening IRC URLs in ERC.
+* auth-source::                 Retrieving auth-source entries with ERC.
+
+@end detailmenu
 @end menu
 
 @node Connecting
@@ -643,7 +653,7 @@ while helpers, like @code{erc-compute-nick}, will determine 
other
 parameters, and some, like @code{client-certificate}, will just be
 @code{nil}.
 
-@anchor{ERC client-certificate}
+@anchor{client-certificate}
 To use a certificate with @code{erc-tls}, specify the optional
 @var{client-certificate} keyword argument, whose value should be as
 described in the documentation of @code{open-network-stream}: if
@@ -687,6 +697,8 @@ machine irc.libera.chat key /home/bandali/my-cert.key cert 
/home/bandali/my-cert
 
 @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, @pxref{auth-source,
+ERC's auth-source integration}.
 @end defun
 
 @subheading Server
@@ -778,9 +790,9 @@ ERC should automatically attempt to connect with another 
nickname.
 You can manually set another nickname with the /NICK command.
 @end defopt
 
-@anchor{ERC username}
+@anchor{username parameter}
 @subheading User
-@cindex user
+@cindex username parameter
 
 @defun erc-compute-user &optional user
 Determine a suitable value to send as the first argument of the
@@ -803,8 +815,27 @@ A permanent username value to send for all connections.  
It should be
 a string abiding by the rules of the network.
 @end defopt
 
+@anchor{password parameter}
+@anchor{server password}
+@cindex password, server
 @subheading Password
-@cindex password
+
+This parameter was traditionally meant to specify a @dfn{server
+password} to be sent along with the IRC @samp{PASS} command.  However,
+such passwords aren't widely used.  Instead, networks typically expect
+them, when present, to convey other authentication information.  In
+the case of account-services (a.k.a., ``NickServ'') credentials, 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{services} or, preferably, @samp{sasl}, both
+ERC modules (@pxref{Modules}).  In addition to performing
+network-account authentication, these obviate the need for this
+parameter completely, although both can optionally borrow it for their
+own purposes.  (@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}
@@ -814,109 +845,9 @@ invocations of @code{erc} and @code{erc-tls}.
 
 @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
+auth-source facility to retrieve a server password, although hitting
+@kbd{RET} at the prompt may achieve the same effect.
+@xref{auth-source, ERC's auth-source integration}, for more.
 
 @subheading Full name
 
@@ -946,8 +877,8 @@ This can be either a string or a function to call.
 @end defopt
 
 
-@subheading ID
 @anchor{Network Identifier}
+@subheading ID
 
 ERC uses an abstract designation, called @dfn{network context
 identifier}, for referring to a connection internally.  While normally
@@ -1002,7 +933,7 @@ first is lowercase without delims (@samp{deadbeef}) and 
the second
 uppercase with colon seps (@samp{DE:AD:BE:EF}).  These days, there's
 usually a @samp{CERT ADD} command offered by NickServ that can
 register you automatically if you issue it while connected with a
-client cert.  (@pxref{ERC client-certificate}).
+client cert.  @xref{client-certificate}.
 
 Additional considerations:
 @enumerate
@@ -1038,30 +969,32 @@ ERC> /msg NickServ set property \
 This should be your network account username, typically the same one
 registered with nickname services.  Specify this when your NickServ
 login differs from the @code{:user} you're connecting with.
-(@pxref{ERC username})
+@xref{username parameter}.
 @end defopt
 
 @defopt erc-sasl-password
-As noted elsewhere, the @code{:password} parameter for @code{erc-tls}
-was originally intended for traditional ``server passwords,'' but these
-aren't really used any more.  As such, this option defaults to
-borrowing that parameter for its own uses, thus allowing you to call
-@code{erc-tls} with @code{:password} set to your NickServ password.
+As noted elsewhere, the entry-point @code{:password} param was
+originally intended for traditional ``server passwords,'' but these
+aren't really used any more (@pxref{password parameter}).  As such,
+this option defaults to borrowing that parameter for its own uses,
+thus allowing you to call @code{erc-tls} with @code{:password} set to
+your NickServ password.
 
 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.
 @end defopt
 
+@anchor{SASL auth-source function}
 @defopt erc-sasl-auth-source-function
 This is nearly identical to the other ERC @samp{auth-source} function
-options (@pxref{ERC auth-source functions}) except that the default
-value here is @code{nil}, meaning you have to set it to something like
+options (@pxref{auth-source functions}) except that the default value
+here is @code{nil}, meaning you have to set it to something like
 @code{erc-auth-source-search} for queries to be performed.  For
 convenience, this module provides the following as a possible value:
 
@@ -1163,9 +1096,9 @@ both networks.
 
 @subheading Troubleshooting
 
-@strong{Warning:} ERC's SASL offering is currently limited by a lack
-of support for proper IRCv3 capability negotiation.  In most cases,
-this shouldn't affect your ability to authenticate.
+First and foremost, please know that ERC's SASL offering is currently
+limited by a lack of support for proper IRCv3 capability negotiation.
+In most cases, this shouldn't affect your ability to authenticate.
 
 If you're struggling, remember that your SASL password is almost
 always your NickServ password.  When in doubt, try restoring all SASL
@@ -1260,12 +1193,19 @@ stuff, to the current ERC buffer."
 @section Integrations
 @cindex integrations
 
-@subheading URL
+@menu
+* auth-source::                 Retrieving auth-source entries with ERC.
+@end menu
+
+@anchor{URL}
+@subsection URL
+@cindex URL
+
 For anything to work, you'll want to set @code{url-irc-function} to
 @code{url-irc-erc}.  As a rule of thumb, libraries relying directly on
 @code{url-retrieve} should be fine out the box from Emacs 29.1 onward.
 On older versions of Emacs, you may need to @code{(require 'erc)}
-beforehand. @pxref{Retrieving URLs,,, url, URL}.
+beforehand.  @xref{Retrieving URLs,,, url, URL}.
 
 For other apps and libraries, such as those relying on the
 higher-level @code{browse-url}, you'll oftentimes be asked to specify
@@ -1282,6 +1222,160 @@ need a function as well:
 @noindent
 Users on Emacs 28 and below may need to use @code{browse-url} instead.
 
+@node auth-source
+@subsection auth-source
+@cindex auth-source
+
+You can configure ERC to use the built-in auth-source library for
+looking up passwords. @xref{Top,,auth-source, auth, Emacs auth-source
+Library}, for general info on setting up various backends, but keep in
+mind that some of these may not be compatible.  Those currently
+supported are netrc, plstore, json, secrets, and pass.  To get started
+with the default backend, netrc, put a line like the following in your
+@file{~/.authinfo.gpg} (or any file named in the option
+@code{auth-sources}):
+
+@example
+machine irc.example.net login mynick password sEcReT
+@end example
+
+@subsubheading Server Passwords
+When retrieving passwords to accompany the IRC @samp{PASS} command
+(@pxref{password parameter}), ERC asks auth-source to match the
+@var{server} parameter of @code{erc-tls} against each entry's
+@samp{host} field (@w{@code{machine irc.example.net}} in the above
+example).  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 that 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 @code{services} module.
+If that appeals to you, consider customizing 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.
+Also, some ERC modules may commandeer the @code{erc-tls}
+@var{password} parameter for their own ends, which likely don't
+involve a server password.
+
+@subsubheading The @samp{services} module
+You can use auth-source to authenticate to account services the
+traditional way through a bot called @samp{NickServ}.  To do so, add
+@code{services} to @code{erc-modules} and set the option
+@code{erc-use-auth-source-for-nickserv-password} to @code{t}.  After
+that, expect the @samp{user} parameter in relevant auth-source queries
+to be your current nickname.
+
+Most of the time, a query's precise contextual details (such as
+whether a nick was granted or forcibly assigned) shouldn't affect how
+you define entries in your backend.  However, if something isn't quite
+working, you may want to investigate the interplay between the option
+@code{erc-nickserv-identify-mode} and account services.  In
+particular, if you find yourself facing nicks suffixed with an
+@code{erc-nick-uniquifier} (the infamous @samp{`}), check that the
+network's entry in @code{erc-nickserv-alist} is up to date, and do let
+us know if something's off (@pxref{Getting Help and Reporting Bugs}).
+Of course, if you've had your fill of fiddling with this module,
+consider switching to SASL for what's likely a more consistent
+auth-source experience.  (@xref{SASL}.)
+
+@subsubheading Default query behavior
+When preparing entries for your backend, it may help to get a feel for
+how ERC and its modules conduct searches, especially when exploring a
+new context, such as channel keys.  (Hint: in such situations, try
+temporarily setting the variable @code{auth-source-debug} to @code{t}
+and checking @samp{*Messages*} periodically for insights into how
+auth-source is operating.)  Overall, though, ERC tries to be
+consistent in performing queries across various authentication
+contexts.  Here's what to expect with respect to the @samp{host}
+field, which, by default, most heavily influences the fate of a query:
+
+@enumerate
+@item
+entries featuring custom identifiers and networks are matched first
+(@pxref{Network Identifier})
+@item
+followed by network-specific servers
+@item
+and, finally, dialed endpoints (typically the @var{server} argument
+passed to @code{erc-tls})
+@end enumerate
+
+@noindent
+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 parameter to @code{auth-source-search}.
+Also, be sure to mind the syntax of your chosen backend medium.  For
+example, always quote channel names in a netrc file.
+
+Lastly, if this all seems overly nuanced or just plain doesn't appeal
+to you, please see options @code{erc-auth-source-services-function}
+and friends, described just below.
+
+@subsubheading Custom query functions
+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
+
+@anchor{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, when identifying to services,
+@code{:user} contains your current nickname.  Generalized parameter
+names, like @code{:user} and @code{:host}, are always preferred over
+backend 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.
+
+For using auth-source along with SASL, @pxref{SASL auth-source
+function}.
+@end defopt
+
+@subsubheading Channel keys
+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.
+
+
 @node Options
 @section Options
 @cindex options
diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS
index d0d84d0a98..76439f1d06 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-sasl.el b/lisp/erc/erc-sasl.el
index 5b2c93988a..280910111d 100644
--- a/lisp/erc/erc-sasl.el
+++ b/lisp/erc/erc-sasl.el
@@ -102,7 +102,7 @@ ERC binds all options defined in this library, such as
 `erc-sasl-password', to their values from entry-point invocation.
 In return, ERC expects a string to send as the SASL password, or
 nil, in which case, ERC will prompt the for input.  See info
-node `(erc) Connecting' for details on ERC's auth-source
+node `(erc) auth-source' for details on ERC's auth-source
 integration."
   :type '(choice (function-item erc-sasl-auth-source-password-as-host)
                  (function-item erc-auth-source-search)
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 @@ Called with a subset of keyword parameters known to
 `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 6bb2e013c3..3b0cde4155 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -219,7 +219,7 @@ parameters and authentication."
 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 @@ if any.  In return, ERC expects a string to send as the 
server
 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 @@ channel.  In return, ERC expects a string to use as the 
channel
 \"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)