mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-01 11:14:55 +00:00
Code Issues Releases Activity

Update ERC's Info doc with network-ID related changes

Browse Source 
* 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.
This commit is contained in:
F. Jason Park 2021-06-18 04:25:44 -07:00
parent 10237840d0
commit 85c2f3bc3e
2 changed files with 248 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
doc/misc/erc.texi
View File

@ -545,20 +545,26 @@ Non-interactively, it takes the following keyword arguments.
@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 @@ Non-interactively, it takes the following keyword arguments.
@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 @@ ERC should automatically attempt to connect with another nickname.
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
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}.
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.
For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
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
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:
@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 @@ User full name.
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 @@ stuff, to the current ERC buffer."
(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 @@ lurkers. The function @code{erc-lurker-p} determines whether a given
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 @@ contributors are frequently around and willing to answer your
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

90
etc/ERC-NEWS
View File

@ -11,6 +11,96 @@ 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. ERC's approach prioritizes
predictability over economy, favoring fully qualified suffixes without
elided or omitted components. Potential avenues for confusion remain
but will die out with the adoption of emerging protocol extensions.
** Option 'erc-rename-buffers' deprecated.
The promises made by 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).
** 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
valiant efforts whose use is nevertheless discouraged.
** 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.
** Improved handling of multiline prompt input.
This means better detection and handling of intervening and trailing
blanks when 'erc-send-whitespace-lines' is active. New options have
also been added for warning when input spans multiple lines. Although
off by default, new users are encouraged to enable them.
** 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, input 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 has been 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
unequivocally identifying a connection in a human-readable way.
The function 'erc-auto-query', unused internally, and basically
inscrutable when read, has been deprecated with no public replacement.
This raises a related issue: if you use ERC as a library and need
something only offered internally, please lobby to have it exported by
writing to emacs-erc@gnu.org.
* Changes in ERC 5.4.1