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}}.
@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 <password>'', replacing ``<password>'' 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{<password>} @samp{<email>} @key{RET}}, replacing
+@samp{<password>} and @samp{<email>} 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
-<nick>'', replacing ``<nick>'' 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{<nick>} @key{RET}}, replacing @samp{<nick>} 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{<nick>}. 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
@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 <RET> 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{<option>}
+@key{RET}}, replacing @samp{<option>} with:
+
+@itemize @bullet
+@item @code{erc-server-reconnect-function}, a function
+@item @code{erc-server-reconnect-timeout}, a number
+@end itemize
+
+@noindent
+(If it helps, hit @key{TAB} for completion.) As you may have noticed,
+when customizing options individually, each buffer displays but a
+single option's widget. When you get to the buffer for ``Erc Server
+Reconnect Function'', you'll see that @samp{[Toggle]} has been
+replaced with @samp{[Value Menu]} and that clicking it reveals three
+choices in a pop-up window. Enter @kbd{1} to select
+@code{erc-server-delayed-check-reconnect} before @key{TAB}'ing over to
+@samp{[State]} and hitting @key{RET}. Enter @kbd{1} again, this time
+to persists your changes.
+
+For the final option, @code{erc-server-reconnect-timeout}, you'll
+encounter a text field (instead of a button), which works like those
+in a typical web form. Enter @samp{30} and hit @kbd{C-x C-s} to save.
+Just for fun, click the group link for @samp{Erc Server} at the bottom
+of the buffer. You could just as well have set the last two options
+from this ``custom group'' buffer alone, which very much resembles the
+one for the @samp{Erc} group, which is actually the ``parent'' of this
+group (note the ``breadcrumb'' for group @samp{Erc} atop the buffer).
+Indeed, you can always get back here by running @kbd{M-x
+customize-group @key{RET} erc-server @key{RET}} from almost anywhere
+in Emacs.
+
+Now it's time to set some key bindings for @code{erc-mode-map}, a
+major-mode keymap active in all ERC buffers. In general, it's best to
+do this part either entirely or in conjunction with some lisp code in
+you init file. However, to keep things ``simple'', we'll do it all in
+customization buffers. To get started, hit @kbd{M-x customize-group
+@key{RET} erc-hooks @key{RET}} and search for ``Erc Mode Hook''. In
+the widget form, click @samp{[INS]}, and paste the following into the
+value field in place of the default text.
+
+@lisp
+(lambda ()
+ (keymap-set erc-mode-map "RET" nil)
+ (keymap-set erc-mode-map "C-c C-c" 'erc-send-current-line))
+@end lisp
+
+@noindent
+Don't worry about the line breaks. Emacs is smart enough to handle
+those. When you're ready, click @samp{[Apply and Save]}.
+
+Next, try tweaking the face ERC uses to stylize server messages that
+say things like ``SoAndSo has joined channel #chan''. Type @kbd{M-x
+customize-face @key{RET} erc-notice-face @key{RET}}. Click the
+``link''-looking button at the very bottom that says something like
+``Show All Attributes''. Untick @samp{Weight} and tick @samp{Slant}.
+Then, in the latter's @samp{[Value Menu]}, enter @samp{0} for
+@samp{italic}. Hit @kbd{C-x C-s} to save.
+
+Time for some more involved configuring. From now on, if something
+isn't applicable to your setup, just skip ahead. Also, note that if
+you've installed ERC from GNU ELPA, you may need to load libraries for
+groups and options you'd like to customize before Emacs can create a
+customization buffer. For example, to do this for the group
+@code{erc-sasl}, run @kbd{M-: (require 'erc-sasl) @key{RET}}.
+
+Speaking of @acronym{SASL}, those already authenticating with it may
+have noticed that connecting interactively requires running @kbd{C-u
+M-x erc-tls @key{RET}} in order to receive a ``User'' prompt for your
+account name. However, if your nickname happens to be the same as
+your account name, you can avoid the leading @kbd{C-u} by customizing
+the option @code{erc-sasl-user} to the keyword symbol @code{:nick}.
+At the time of writing, you'd hit @kbd{2} when prompted by the
+option's @samp{[Value menu]}. Hit @kbd{C-x C-s} to save your changes.
+
+One of ERC's most configured options lives in @file{erc-join}, and it
+determines the channels you join upon connecting. To make it work for
+you, customize the option @code{erc-autojoin-channels-alist}. In the
+customization widget, hit @samp{[INS]} to create a new entry. In the
+@samp{Network:} field, type @samp{Libera.Chat}. Under
+@samp{Channels:}, hit @samp{[INS]} again, this time to create a field
+to enter a channel name, and enter @samp{#emacs}. Now, find and click
+on the lowermost @samp{[INS]}, and this time enter @samp{#erc} in the
+@samp{Name:} field. Save your changes.
+
+If you're new to ERC, you may not be familiar with the various ways it
+can ``fill'' message text by inserting line breaks. The most modern
+fill style is called @code{fill-wrap}, and it's available by
+customizing @code{erc-fill-function} to @code{erc-fill-wrap}, which
+appears as @samp{Dynamic word-wrap} in the option's @samp{[Value
+Menu]}. After setting this, change the related option
+@code{erc-fill-static-center} to the integer @samp{18}. Save your
+changes. As a bonus exercise, try binding the key @kbd{C-c =} to the
+function @code{erc-fill-wrap-nudge} in the minor-mode keymap
+@code{erc-fill-wrap-mode-map} (hint: the minor mode's hook is called
+@code{erc-fill-wrap-mode-hook}, and it's not a member of any
+customization group).
+
+ERC users tend to be picky about the mode line. If you find that
+you'd rather not see changes when people join and leave channels,
+customize the option @code{erc-track-faces-priority-list}. When
+visiting its customization buffer, you'll notice it's quite busy.
+Ignore everything and type @kbd{C-s erc-notice-face @key{RET}}. Click
+the @samp{[DEL]} button at the beginning of the line you end up on,
+and save your changes. Next, customize the related option
+@code{erc-track-priority-faces-only} to the @samp{[Value Menu]} choice
+@samp{all}. Once again, save your changes.
+
+Let's say you'd like to enable a ``local module'' (ERC's version of a
+local minor mode) in a specific channel. One way to do that is by
+running some code to activate the module if the channel's name
+matches. Try that now by customizing the option @code{erc-join-hook}.
+Add the following in the value field before saving your changes:
@lisp
-;;; Sample ERC configuration
-
-;; Load authentication info from an external source. Put sensitive
-;; passwords and the like in here.
-(load "~/.emacs.d/.erc-auth")
-
-;; This is an example of how to make a new command. Type "/uptime" to
-;; use it.
-(defun erc-cmd-UPTIME (&rest ignore)
- "Display the uptime of the system, as well as some load-related
-stuff, to the current ERC buffer."
- (let ((uname-output
- (replace-regexp-in-string
- ", load average: " "] @{Load average@} ["
- ;; Collapse spaces, remove
- (replace-regexp-in-string
- " +" " "
- ;; Remove beginning and trailing whitespace
- (replace-regexp-in-string
- "^ +\\|[ \n]+$" ""
- (shell-command-to-string "uptime"))))))
- (erc-send-message
- (concat "@{Uptime@} [" uname-output "]"))))
-
-;; This causes ERC to connect to the Libera.Chat network upon hitting
-;; C-c e f. Replace MYNICK with your IRC nick.
-(global-set-key "\C-cef" (lambda () (interactive)
- (erc :server "irc.libera.chat" :port "6667"
- :nick "MYNICK")))
-
-;; This causes ERC to connect to the IRC server on your own machine (if
-;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC
-;; nick. Often, people like to run bitlbee (https://bitlbee.org/) as an
-;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with
-;; people on those networks.
-(global-set-key "\C-ceb" (lambda () (interactive)
- (erc :server "localhost" :port "6667"
- :nick "MYNICK")))
-
-;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has
-;; been commented out to avoid confusing new users.
-;; (define-key erc-mode-map (kbd "RET") nil)
-;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line)
-;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line)
-
-;;; Options
-
-;; Join the #emacs and #erc channels whenever connecting to
-;; Libera.Chat.
-(setq erc-autojoin-channels-alist
- '(("Libera.Chat" "#emacs" "#erc")))
-
-;; Interpret mIRC-style color commands in IRC chats
-(setq erc-interpret-mirc-color t)
-
-;; The following are commented out by default, but users of other
-;; non-Emacs IRC clients might find them useful.
-;; Kill buffers for channels after /part
-;; (setq erc-kill-buffer-on-part t)
-;; Kill buffers for private queries after quitting the server
-;; (setq erc-kill-queries-on-quit t)
-;; Kill buffers for server messages after quitting the server
-;; (setq erc-kill-server-buffer-on-quit t)
+(lambda ()
+ (require 'erc-goodies)
+ (when (equal (erc-default-target) "#emacs")
+ (erc-keep-place-indicator-mode +1)))
@end lisp
+Lastly, if you really want the two ``slash'' commands defined at the
+end of the previous section, you can put them in any file listed in
+@code{erc-startup-file-list}, such as @file{~/.emacs.d/.ercrc.el}.
+Make sure to put @code{(require 'erc-track)} near the top of the file.
+These will allow you to type @kbd{/TRACK @key{RET}} and @kbd{/UNTRACK
+@key{RET}} in channels and query buffers to tell ERC whether to show
+activity from these buffers in the mode line.
+
+
@node Integrations
@section Integrations
@cindex integrations
click @samp{Install}. Make sure to restart Emacs before reconnecting
to IRC, and don't forget that you can roll back to the previous
version by running @kbd{M-x package-delete @key{RET}}.
-@xref{Packages,,,emacs, the Emacs manual} for more information.
+@xref{Packages,,,emacs, The Emacs Editor}, for more information.
In the rare instance you need an emergency fix or have volunteered to
test an edge feature between ERC releases, you can try adding
@end itemize
+@anchor{Official IRC channels}
+@subheading Official IRC channels
+@cindex official IRC channels
+
+The official channels for GNU Emacs and ERC lived 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}.
+
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
projects / emacs.git / commitdiff