From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: "F. Jason Park" Date: Fri, 18 Jun 2021 04:25:44 -0700 Subject: [PATCH 27/35] Update ERC's Info doc with network-ID related changes * doc/misc/erc.texi: Update the `erc' and `erc-tls' entry-point sections with the new :id keyword parameter. Expand the auth-info related information in the passwords section. Remove all mention of the variable `erc-rename-buffers', whose "on" behavior has been made permanent. * etc/ERC-NEWS: Add new section for future 5.5 release. --- doc/misc/erc.texi | 192 ++++++++++++++++++++++++++++++++++++++-------- etc/ERC-NEWS | 86 +++++++++++++++++++++ 2 files changed, 244 insertions(+), 34 deletions(-) diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index b9297738ea..6daa54d956 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -545,20 +545,26 @@ Connecting @item @var{server} @item @var{port} @item @var{nick} +@item @var{user} @item @var{password} @item @var{full-name} +@item @var{id} @end itemize -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port} and @code{erc-compute-nick} will be invoked -for the values of the other parameters. +For example, calling the command like so -@example +@example lisp (erc :server "irc.libera.chat" :full-name "J. Random Hacker") @end example + +sets @var{server} and @var{full-name} directly while leaving the rest +up to functions like @code{erc-compute-port}. Note that some +arguments can't be specified interactively. @var{id}, in particular, +is rarely needed (@pxref{Network Identifier}). + @end defun +@noindent To connect securely over an encrypted TLS connection, use @kbd{M-x erc-tls}. @@ -570,21 +576,24 @@ Connecting @item @var{server} @item @var{port} @item @var{nick} +@item @var{user} @item @var{password} @item @var{full-name} +@item @var{id} @item @var{client-certificate} @end itemize -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port} and @code{erc-compute-nick} will be invoked -for the values of the other parameters, and @code{client-certificate} -will be @code{nil}. +That is, if called in the following manner -@example +@example lisp (erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker") @end example +the command will set @var{server} and @var{full-name} accordingly, +while helpers, like @code{erc-compute-nick}, will determine other +parameters, and some, like @code{client-certificate}, will just be +@code{nil}. + 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 @@ -719,29 +728,134 @@ Connecting You can manually set another nickname with the /NICK command. @end defopt +@subheading User +@defun erc-compute-user &optional user +Determine a suitable value to send for the first argument to the +opening @samp{USER} IRC command by consulting the following sources: + +@itemize +@item @var{user}, the argument passed to this function +@item The option @code{erc-email-userid}, assuming @code{erc-anonymous-login} +is non-@code{nil} +@item The result of calling the function @code{user-login-name} +@end itemize + +@end defun + +@defopt erc-email-userid +A permanent username value to send for all connections. It should be +a string abiding by the rules of the network. +@end defopt + @subheading Password @cindex password @defopt erc-prompt-for-password -If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password. +If non-@code{nil} (the default), @kbd{M-x erc} prompts for a server +password. This only affects interactive invocations of @code{erc} and +@code{erc-tls}. @end defopt +@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 -you use @file{~/.authinfo} as your auth-source backend, then put +the option @code{auth-sources} contains @file{~/.authinfo}, put something like the following in that file: @example -machine irc.example.net login "#fsf" password sEcReT +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, here @code{machine irc.example.net}, +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 work OOTB 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 messing with the more advanced options below. + +If ERC can't find a suitable server password, it'll 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 +sounds like you, you can also set the option +@code{erc-auth-source-server-function} to @code{nil} to skip +server-passwork lookup for all servers. Note that some networks and +IRCds may accept account-services authentication via server password +using the nonstandard ``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 +``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} 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 -ERC also consults @code{auth-source} to find any channel keys required -for the channels that you wish to autojoin, as specified by the -variable @code{erc-autojoin-channels-alist}. +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 and 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 just +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: -For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. +@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}. +@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 nil, if the search fails. + +The default value for all three options is the function +@code{erc-auth-source-search}. It tries to merge relevant contextual +params 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, and secrets are currently supported. +@end defopt @subheading Full name @@ -766,6 +880,31 @@ Connecting This can be either a string or a function to call. @end defopt + +@subheading ID +@anchor{Network Identifier} + +ERC uses an abstract designation called a @dfn{network context +identifier} for referring to a connection internally. While normally +derived from a combination of logical and physical connection +parameters, an ID can also be explicitly provided via an entry-point +command (like @code{erc-tls}). Use this in rare situations where ERC +would otherwise have trouble discerning between connections. + +One such situation might arise when using multiple connections to the +same network with the same nick but different (nonstandard) "device" +identifiers, which some bouncers may support. Another might be when +mimicking the experience offered by popular standalone clients, which +normally offer ``named'' persistent configurations with server buffers +reflecting those names. Yet another use case might involve +third-party code needing to identify a connection unequivocally but in +a human-friendly way suitable for UI components. + +When providing an ID as an entry-point argument, strings and symbols +make the most sense, but any reasonably printable object is +acceptable. + + @node Sample Configuration @section Sample Configuration @cindex configuration, sample @@ -827,12 +966,6 @@ Sample Configuration (setq erc-autojoin-channels-alist '(("Libera.Chat" "#emacs" "#erc"))) -;; Rename server buffers to reflect the current network name instead -;; of SERVER:PORT (e.g., "Libera.Chat" instead of -;; "irc.libera.chat:6667"). This is useful when using a bouncer like -;; ZNC where you have multiple connections to the same server. -(setq erc-rename-buffers t) - ;; Interpret mIRC-style color commands in IRC chats (setq erc-interpret-mirc-color t) @@ -891,15 +1024,6 @@ Options nickname is considered a lurker. @end defopt -@defopt erc-rename-buffers -If non, @code{nil}, this will rename server buffers to reflect the -current network name instead of IP:PORT - -@example -(setq erc-rename-buffers t) -@end example -@end defopt - @node Getting Help and Reporting Bugs @chapter Getting Help and Reporting Bugs @cindex help, getting @@ -924,7 +1048,7 @@ Getting Help and Reporting Bugs questions. @item -To report a bug in ERC, use @kbd{M-x report-emacs-bug}. +To report a bug in ERC, use @kbd{M-x erc-bug}. @end itemize diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS index bdcd943c37..0ac3df1ba1 100644 --- a/etc/ERC-NEWS +++ b/etc/ERC-NEWS @@ -11,6 +11,92 @@ This file is about changes in ERC, the powerful, modular, and extensible IRC (Internet Relay Chat) client distributed with GNU Emacs since Emacs version 22.1. + +* Changes in ERC 5.5 + +** Smarter buffer naming for withstanding collisions. +ERC buffers now remain tied to their logical network contexts, even +while offline. These associations can survive regional server changes +and the intercession of proxies. As has long been practiced in other +areas of Emacs, "uniquified" buffer renaming prevents collisions +between buffers of different contexts. Potential avenues for +confusion remain but will die out with the adoption of emerging +protocol extensions. + +** Option 'erc-rename-buffers' deprecated. +The promise of its old "on" state are now fully realized and enabled +permanently by default. Its old behavior when disabled has been +preserved and will remain available (with warnings) for years to come. + +** Option 'erc-reuse-buffers' deprecated. +This ancient option has been a constant source of confusion, as +exhibited most recently when its "disabled" meaning was partially +inverted. Introduced in ERC 5.4 (Emacs 28.1), this regression saw +existing channel buffers transparently reassociated instead of created +anew. The pre-5.4 "disabled" behavior has been restored and will +remain accessible for the foreseeable future, warts and all (e.g., +with its often superfluous "/DIALED-HOST" suffixing always present). + +** Convention adopted for auditioning edge functionality. +Objects bearing names like "erc--X-foo" or "erc-somemod--X-foo" will +be offered as trial balloons for potential export and as stopgaps for +overdue but immature fixes and features. (If you dare try them, +please give feedback!) This move comes out of desperation as we focus +on much needed internal remediation while trying to meet baseline +expectations in the face of mounting pressure from networks and users. + +** Tighter auth-source integration with bigger changes on the horizon. +The days of hit-and-miss auth-source queries are hopefully behind us. +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". If you require SASL immediately, +please participate in ERC development by volunteering to try (and give +feedback on) edge features, one of which is SASL. All known external +offerings, past and present, are makeshift efforts whose use is +discouraged. This includes the instructions on Libera.Chat's website. + +** Username argument for entry point commands. +Commands 'erc' and 'erc-tls' now accept a ':user' keyword argument, +which, when present, becomes the first argument passed to the "USER" +IRC command. The traditional way of setting this globally, via +'erc-email-userid', is still honored. + +** Additional display options for updated buffers. +Additional flexibility is now available for controlling the behavior +of newly created target buffers, especially during reconnection. + +** Miscellaneous behavioral changes impacting the user experience. +A bug has been fixed that saw prompts being mangled, doubled, or +erased in server buffers upon disconnection. Instead, prompts now +collapse into an alternate form designated by the option +'erc-prompt-hidden'. Behavior differs for query and channel buffers +but can be fine-tuned via the repurposed, formerly abandoned option +'erc-hide-prompt'. + +A bug has been fixed affecting users of the Soju bouncer: outgoing +messages during periods of heavy traffic no longer disappear. + +Although rare, server passwords containing white space are now handled +correctly. + +** Miscellaneous behavioral changes in the library API. +The function 'erc-network' always returns non-nil in server and target +buffers belonging to a successfully established IRC connection, even +after that connection is closed. In 5.4, support for network symbols +as keys was added for 'erc-autojoin-channels-alist'. This has been +extended to include explicit symbols passed to 'erc-tls' and 'erc' as +so-called network-context identifiers via a new ':id' keyword. The +latter carries wider significance beyond autojoin and can be used for +uniquely and unequivocally identifying a connection. The function +'erc-auto-query', unused internally, and basically inscrutable when +read, has been deprecated with no public replacement. Which raises +the issue: if you use ERC as a library and need something that's only +offered internally, please lobby for its exporting by writing to +emacs-erc@gnu.org. + * Changes in ERC 5.4.1 -- 2.36.1