From 80e5e9ddc8d76993fa44a659307174b778aa60b7 Mon Sep 17 00:00:00 2001 From: "F. Jason Park" Date: Thu, 29 Jun 2023 07:12:46 -0700 Subject: [PATCH] Improve walkthrough and sample config in ERC manual * doc/misc/erc.texi: Improve "Sample Session" and "Sample Configuration" sections. Move introductory paragraph detailing the history of official GNU IRC channels to the "History" chapter (from "Sample Sessoin"), and leave a link in its place. Silence strange warning in "Getting Help and Reporting Bugs" about lack of punctuation after xref. --- doc/misc/erc.texi | 467 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 352 insertions(+), 115 deletions(-) diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index d59c6d8a6c6..63ea94d9b2e 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -144,11 +144,11 @@ the @samp{#emacs} channels where you can chat with other Emacs users, and if you're having trouble with ERC, you can join the @samp{#erc} channel and ask for help there. -If you want to place ERC settings in their own file, you can place them -in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. - -If you would rather use the Customize interface to change how ERC -works, do @kbd{M-x customize-group @key{RET} erc @key{RET}}. In +At some point in your ERC journey, you'll inevitably want to change +how the client looks and behaves. As with other Emacs applications, +the typical place to store your settings is your @file{init.el}. If +you would rather use the Customize interface, a good place to start is +by running @kbd{M-x customize-group @key{RET} erc @key{RET}}. In particular, ERC comes with lots of modules that may be enabled or disabled; to select which ones you want, do @kbd{M-x customize-variable @key{RET} erc-modules @key{RET}}. @@ -161,69 +161,90 @@ customize-variable @key{RET} erc-modules @key{RET}}. @node Sample Session @section Sample Session -This is an example ERC session which shows how to connect to the -@samp{#emacs} channel on Libera.Chat. Another IRC channel on -Libera.Chat that may be of interest is @samp{#erc}, which is a channel -where ERC users and developers hang out. These channels used to live -on the Freenode IRC network until June 2021, when they---along with -the official IRC channels of the GNU Project, the Free Software -Foundation, and many other free software communities---relocated to -the Libera.Chat network in the aftermath of changes in governance and -policies of Freenode in May and June 2021. GNU and FSF's -announcements about this are at -@uref{https://lists.gnu.org/archive/html/info-gnu/2021-06/msg00005.html}, -@uref{https://lists.gnu.org/archive/html/info-gnu/2021-06/msg00007.html}, -and -@uref{https://lists.gnu.org/archive/html/info-gnu-emacs/2021-06/msg00000.html}. +This example ERC session describes how to connect to the @samp{#emacs} +channel on Libera.Chat. Also worth checking out is Libera's own +introductory guide to IRC, @uref{https://libera.chat/guides/basics}, +which presents a more comprehensive overview without instructions +specific to ERC. @itemize @bullet @item Connect to Libera.Chat -Run @kbd{M-x erc}. Use ``irc.libera.chat'' as the IRC server, ``6667'' -as the port, and choose a nickname. +Run @kbd{M-x erc @key{RET}}. Use @samp{irc.libera.chat} for the +server and @samp{6667} for the port. Choose a nickname, and hit +@key{y} when asked if you'd prefer to connect over @acronym{TLS}. @item Get used to the interface -Switch to the ``irc.libera.chat:6667'' buffer, if you're not already -there. You will see first some messages about checking for ident, and -then a bunch of other messages that describe the current IRC server. +Switch to the @file{Libera.Chat} buffer if you're not already there. +ERC calls this a @dfn{server buffer}, and it must exist for the +duration of the session. You will likely see some messages about +``ident'', authentication, and the like, followed by information +describing the current server and the network. @item Join the #emacs channel -In that buffer, type ``/join @key{SPC} #emacs'' and hit @kbd{RET}. Depending -on how you've set up ERC, either a new buffer for ``#emacs'' will be -displayed, or a new buffer called ``#emacs'' will be created in the -background. If the latter, switch to the ``#emacs'' buffer. You will -see the channel topic and a list of the people who are currently on the -channel. +In the server buffer, type @kbd{/join #emacs @key{RET}} at the prompt. +ERC will create a new buffer called @file{#emacs}. If you've already +configured ERC, you may need to switch to it manually. Once there, +you will see the channel's ``topic'' in the buffer's header line +(@pxref{Header Lines,,,elisp,}) and a list of people currently in the +channel. If you can't see the full topic, mouse over it or type +@kbd{/topic @key{RET}} at the prompt. @item Register your nickname with Libera.Chat -If you would like to be able to talk with people privately on the -Libera.Chat network, you will have to ``register'' your nickname. -To do so, switch to the ``irc.libera.chat:6667'' buffer and type -``/msg NickServ register '', replacing ``'' with -your desired password. It should tell you that the operation was -successful. +In order to access essential network features, like speaking in +certain channels and participating in private conversations, you'll +likely have to ``register'' your nickname. To do so, switch to the +@file{Libera.Chat} buffer and type @kbd{/msg NickServ register +@samp{} @samp{} @key{RET}}, replacing +@samp{} and @samp{} with your desired account +password and contact email (both sans quotes). The server should tell +you that the operation was successful. See the official Libera.Chat +docs if you encounter problems. + +In addition to creating an account, this process also +``authenticates'' you to the network's ``account services'' system for +the duration of the session. In other words, you're now logged in. +However, when you connect in the future, you'll need to authenticate +again by providing the same credentials somehow. When you're finished +with this walk through, see ``Next Steps'', below, to learn some ways +to do that. @item Talk to people in the channel -If you switch back to the ``#emacs'' buffer, you can type a message, and -everyone on the channel will see it. +Switch back to the @file{#emacs} buffer and type a message at the +prompt, hitting @kbd{RET} once satisfied. Everyone in the channel +will now see your message. @item Open a query buffer to talk to someone -If you want to talk with someone in private (this should usually not be -done for technical help, only for personal questions), type ``/query -'', replacing ``'' with the nickname of the person you would -like to talk to. Depending on how ERC is set up, you will either see a -new buffer with the name of the person, or such a buffer will be created -in the background and you will have to switch to it. Begin typing -messages, and you will be able to have a conversation. - -Note that if the other person is not registered, you will not be able to -talk with them. +If you want to talk with someone in private, type @kbd{/query +@samp{} @key{RET}}, replacing @samp{} with the their +nickname. As before, with the server buffer, if this new @dfn{query +buffer} doesn't appear in the current window, you may have to switch +to it. Regardless, its name should match @samp{}. Once there, +type something at the prompt and hit @kbd{RET}, and the other party +will see it. + +Keep in mind that if either party isn't authenticated, you may not be +able to converse at all. Also, depending on the network, certain +social conventions may apply to the practice of direct messaging. As +a general rule, queries should usually be reserved for personal +matters rather than technical help, which can often benefit (and +benefit @emph{from}) a larger audience. + +@item Next steps + +Try joining another channel, such as @samp{#erc}, where ERC users and +developers hang out (@pxref{Official IRC channels} for more on the +history of @samp{#emacs}). For ideas on various options to customize, +@pxref{Sample Configuration}. To learn how ERC can authenticate you +to the network automatically whenever you connect, @pxref{SASL}. As +always, if you encounter problems, @pxref{Getting Help and Reporting +Bugs}. @end itemize @@ -1192,76 +1213,277 @@ case, you'll probably want to temporarily disable @section Sample Configuration @cindex configuration, sample -Here is an example of configuration settings for ERC@. This can go into -your Emacs configuration file. Everything after the @code{(require -'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}. +Here is an example configuration for ERC@. @strong{Don't panic} if +you aren't familiar with @samp{use-package} or have no interest in +learning it. For our purposes, it's just a means of presenting +configuration details in a tidy, standardized format. If it helps, +just pretend it's some make-believe, pseudo configuration language. +Although the syntax below is easy enough to intuit and adapt to your +setup, you may wish to keep the following in mind (or @pxref{Top,,, +use-package,}): + +@itemize @bullet +@item +Each @code{use-package} ``declaration'' focuses on a library +``feature'', which is just a symbol you'd normally @code{require} in +your config @pxref{Named Features,,, elisp,}). + +@item +Emacs loads anything in a @code{:config} section @emph{after} loading +whatever library @code{provide}s the declaration's feature. + +@item +Everything in a @code{:custom} or @code{:custom-face} section is +basically something you'd find in your @code{custom-file}. +@end itemize + +@noindent +The following would typically go in your init file. Experienced users +may opt to keep any non-settings, like commands and functions, in a +dedicated @file{~/.emacs.d/.ercrc.el}. Whatever the case, please keep +in mind that you can replace nearly all of the following with Custom +settings (@pxref{Sample configuration via Customize}). + +@lisp +;;; My ERC configuration -*- lexical-binding: t -*- + +(use-package erc + :config + ;; Prefer SASL to NickServ, colorize nicknames, interpret mIRC colors, + ;; and list buffers and channel members in separate side panels. + (setopt erc-modules + (seq-union '(sasl nicks irccontrols bufbar nickbar scrolltobottom) + erc-modules)) + + :custom + ;; Protect me from accidentally sending excess lines. + (erc-inhibit-multiline-input t) + (erc-send-whitespace-lines t) + (erc-ask-about-multiline-input t) + + ;; Reconnect automatically using a fancy strategy. + (erc-server-reconnect-function #'erc-server-delayed-check-reconnect) + (erc-server-reconnect-timeout 30) + + ;; Insert a newline when I hit at the prompt, and prefer + ;; something more deliberate for actually sending messages. + :bind (:map erc-mode-map + ("RET" . nil) + ("C-c C-c" . #'erc-send-current-line)) + + ;; Emphasize buttonized text in notices. + :custom-face (erc-notice-face ((t (:slant italic :weight unspecified))))) + +(use-package erc-sasl + ;; Since my account name is the same as my nick, free me from having + ;; to hit C-u before M-x erc to trigger a username prompt. + :custom (erc-sasl-user :nick)) + +(use-package erc-join + ;; Join #emacs and #erc whenever I connect to Libera.Chat. + :custom (erc-autojoin-channels-alist '((Libera.Chat "#emacs" "#erc")))) + +(use-package erc-fill + :custom + ;; Prefer one message per line without continuation indicators. + (erc-fill-function #'erc-fill-wrap) + (erc-fill-static-center 18) + + :bind (:map erc-fill-wrap-mode-map ("C-c =" . #'erc-fill-wrap-nudge))) + +(use-package erc-track + ;; Prevent JOINs and PARTs from lighting up the mode-line. + :config (setopt erc-track-faces-priority-list + (remq 'erc-notice-face erc-track-faces-priority-list)) + + :custom (erc-track-priority-faces-only 'all)) + +(use-package erc-goodies + ;; Turn on read indicators when joining channels. + :hook (erc-join . my-erc-enable-read-indicator-on-join)) + +(defvar my-erc-read-indicator-channels '("#emacs") + "Channels in which to show a `keep-place-indicator'.") + +(defun my-erc-enable-read-indicator-on-join () + "Enable read indicators for certain queries or channels." + (when (member (erc-default-target) my-erc-read-indicator-channels) + (erc-keep-place-indicator-mode +1))) + +;; Handy commands from the Emacs Wiki. +(defun erc-cmd-TRACK (&optional target) + "Start tracking TARGET or that of current buffer." + (setq erc-track-exclude (delete (or target (erc-default-target)) + erc-track-exclude))) + +(defun erc-cmd-UNTRACK (&optional target) + "Stop tracking TARGET or that of current buffer." + (setq erc-track-exclude (cl-pushnew (or target (erc-default-target)) + erc-track-exclude + :test #'equal))) + +@end lisp + +@noindent +Those familiar with @code{use-package} may have noticed the lack of +@code{:defer} keyword args. This was done to conserve space, but you +can just pretend that this user has enabled +@code{use-package-always-defer} elsewhere. + +@anchor{Sample configuration via Customize} +@subheading Via Customize +@cindex configuration, via customize + +As mentioned, Customize users can accomplish nearly all of the above +via the Customize interface. Start by running @kbd{M-x +customize-group @key{RET} erc @key{RET}}, and search for ``Modules'' +with @kbd{C-s modules @key{RET}}. Toggle open the flyout menu to +reveal the full ``widget'' panel, a web-form-like interface for ``Erc +Modules''. Tick the boxes for @samp{bufbar}, @samp{irccontrols}, +@samp{nickbar}, @samp{nicks}, @samp{sasl}, and @samp{scrolltobottom}. + +Next, search for the phrases ``Erc Ask About Multiline Input'', ``Erc +Inhibit Mulitline Input'', and ``Erc Send Whitespace Lines''. These +are the print names of three Boolean options that control how ERC +treats prompt input containing line breaks. When visiting each +option's section, twirl open its triangle icon to reveal its widget +UI, and click its @samp{[Toggle]} button to set its value to @code{t}. +While going about this, you may find it helpful to glance at the +descriptions just in case you want to disable them later. When +finished, hit @kbd{C-x C-s} or click @samp{[Apply and Save]} atop the +buffer. + +Now do the same for another couple options, this time having to do +with automatic reconnection. But instead of searching for their print +names, try running @kbd{M-x customize-option @key{RET} @samp{