diff options
Diffstat (limited to 'doc/misc/erc.texi')
| -rw-r--r-- | doc/misc/erc.texi | 59 |
1 files changed, 39 insertions, 20 deletions
diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 7fbe6f9766e..c7ab7e7bf21 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -678,6 +678,14 @@ signals an error. Users defining personal modules in an init file should @code{(provide 'erc-my-module)} somewhere to placate ERC. Dynamically generating modules on the fly is not supported. +Some older built-in modules have a second name along with a second +minor-mode toggle, which is just a function alias for its primary +counterpart. For practical reasons, ERC does not define a +corresponding variable alias because contending with indirect +variables complicates bookkeeping tasks, such as persisting module +state across IRC sessions. New modules should definitely avoid +defining aliases without a good reason. + Some packages have been known to autoload a module's definition instead of its minor-mode command, which severs the link between the library and the module. This means that enabling the mode by invoking @@ -1048,13 +1056,19 @@ acceptable. @section Authenticating via SASL @cindex SASL -Regardless of the mechanism or the network, you'll likely have to be -registered before first use. Please refer to the network's own +If you've used @acronym{SASL} elsewhere, you can probably skip to the +examples below. Otherwise, if you haven't already registered with +your network, please do so now, referring to the network's own instructions for details. If you're new to IRC and using a bouncer, -know that you probably won't be needing SASL for the client-to-bouncer -connection. To get started, just add @code{sasl} to -@code{erc-modules} like any other module. But before that, please -explore all custom options pertaining to your chosen mechanism. +know that you probably won't be needing this for the client-to-bouncer +connection. + +When you're ready to get started, add @code{sasl} to +@code{erc-modules}, like you would any other module. If unsure which +@dfn{mechanism} to choose, stick with the default of @samp{PLAIN}. +Then try @kbd{C-u M-x erc-tls @key{RET}}, and give your account name +for the @samp{user} parameter and your account password for the +@samp{server password}. @defopt erc-sasl-mechanism The name of an SASL subprotocol type as a @emph{lowercase} symbol. @@ -1216,25 +1230,30 @@ machine Example.Net login aph-bot password sesame (defun my-erc-up (network) (interactive "Snetwork: ") - - (pcase network - ('libera - (let ((erc-sasl-mechanism 'external)) - (erc-tls :server "irc.libera.chat" :port 6697 - :client-certificate t))) - ('example - (let ((erc-sasl-auth-source-function - #'erc-sasl-auth-source-password-as-host)) - (erc-tls :server "irc.example.net" :port 6697 - :user "alyssa" - :password "Example.Net"))))) + (require 'erc-sasl) + (or (let ((erc-modules (cons 'sasl erc-modules))) + (pcase network + ('libera + (let ((erc-sasl-mechanism 'external)) + (erc-tls :server "irc.libera.chat" + :client-certificate t))) + ('example + (let ((erc-sasl-auth-source-function + #'erc-sasl-auth-source-password-as-host)) + (erc-tls :server "irc.example.net" + :user "alyssa" + :password "Example.Net"))))) + ;; Non-SASL + (call-interactively #'erc-tls))) @end lisp You've started storing your credentials with auth-source and have decided to try SASL on another network as well. But there's a catch: this network doesn't support @samp{EXTERNAL}. You use -@code{let}-binding to get around this and successfully authenticate to -both networks. +@code{let}-binding to work around this and successfully authenticate +to both networks. (Note that this example assumes you've removed +@code{sasl} from @code{erc-modules} globally and have instead opted to +add it locally when connecting to preconfigured networks.) @end itemize |