>From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: "F. Jason Park" Date: Fri, 18 Jun 2021 04:25:44 -0700 Subject: [PATCH 23/28] Update ERC's Info doc with session-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. --- doc/misc/erc.texi | 86 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 66 insertions(+), 20 deletions(-) diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 3b8e231d3a..1eaf7f6c33 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -521,6 +521,7 @@ Connecting @item @var{nick} @item @var{password} @item @var{full-name} +@item @var{id} @end itemize That is, if called with the following arguments, @var{server} and @@ -531,8 +532,24 @@ Connecting @example (erc :server "irc.libera.chat" :full-name "J. Random Hacker") @end example + +The optional @var{id} param can be used to explicitly declare a +``session identifier'', which ERC will use to refer to the connection +when relating buffers to each other. This is meant for rare +situations in which ERC would otherwise have trouble discerning +between connections. One example would be to allow multiple +connections to the same network with the same nick but different +(non-standard) "device" identifiers, which some bouncers may support. +Another might be to mimic the experience of popular standalone +clients, which normally offer ``named'' persistent configurations with +server buffers reflecting those names. Yet another use case might +involve writing code that needs to identify a connection unequivocally +but in a human-friendly way that isn't dependent on meaningless +suffixes. + @end defun +@noindent To connect securely over an encrypted TLS connection, use @kbd{M-x erc-tls}. @@ -547,13 +564,14 @@ Connecting @item @var{password} @item @var{full-name} @item @var{client-certificate} +@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, and @code{client-certificate} -will be @code{nil}. +will be @code{nil}. See @code{erc} for the meaning of @var{id}. @example (erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker") @@ -697,22 +715,65 @@ Connecting @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 +Here, @code{irc.example.net} corresponds to the @var{server} param +passed to @code{erc} or @code{erc-tls} or provideed at the ``IRC +server:'' prompt. Unfortunately, specifying a network, like +``Libera.Chat'', or a specific network server, like +@code{zirconium.libera.chat}, won't work for this introductory +exchange because IRC servers don't provide such information up front. + +If ERC can't find a suitable server password, it'll just skip the IRC +@code{PASS} command altogether, which users may want when using CertFP +or engaging NickServ via ERC's ``services'' module. If that sounds +like you, set the option @code{erc-connect-auth-source-host} to +@code{nil}. You can also set it to @code{t} to tell ERC to favor a +``session identifier'' (corresponding to the @var{id} parameter of +@code{erc-tls}) as the ``machine'' field and to fall back on +@var{server} when an @var{id} hasn't been provided. Note that some +networks and IRCds may support NickServ authentication via server +password when specified using the non-standard ``mynick:sEcReT'' +convention. + +Another entry in an @code{auth-source} file can be used to +authenticate to a nickname service (bot), often called ``NickServ''. +To tell ERC to do that, set the option +@code{erc-use-auth-source-for-nickserv-password} to @code{t}. For +these queries, entries featuring session IDs and networks are matched +first, followed by network-specific servers and dialed TCP endpoints +(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}. +variable @code{erc-autojoin-channels-alist}. When modifying a +netrc-style @code{auth-source} file for such use, ensure an entry +exists with the channel name, for example ``#erc'', in the value of +the ``login'' field (also known as the ``user'' field). The actual key +goes in the ``password'' field. For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. @@ -801,12 +862,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) @@ -865,15 +920,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 -- 2.31.1