Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-22 21:07:36 +00:00
Code Issues Projects Releases Packages Wiki Activity

Improve walkthrough and sample config in ERC manual

Browse source 
* 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.
This commit is contained in:
F. Jason Park 2023-06-29 07:12:46 -07:00
parent 08515350fa
commit 80e5e9ddc8
1 changed files with 342 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

447
doc/misc/erc.texi
View file

@ -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 <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.
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.
Note that if the other person is not registered, you will not be able to
talk with them.
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
;;; Sample ERC configuration
;;; My ERC configuration -*- lexical-binding: t -*-
;; Load authentication info from an external source. Put sensitive
;; passwords and the like in here.
(load "~/.emacs.d/.erc-auth")
(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))
;; 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 "]"))))
:custom
;; Protect me from accidentally sending excess lines.
(erc-inhibit-multiline-input t)
(erc-send-whitespace-lines t)
(erc-ask-about-multiline-input t)
;; 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")))
;; Reconnect automatically using a fancy strategy.
(erc-server-reconnect-function #'erc-server-delayed-check-reconnect)
(erc-server-reconnect-timeout 30)
;; 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")))
;; 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))
;; 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)
;; Emphasize buttonized text in notices.
:custom-face (erc-notice-face ((t (:slant italic :weight unspecified)))))
;;; Options
(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))
;; Join the #emacs and #erc channels whenever connecting to
;; Libera.Chat.
(setq erc-autojoin-channels-alist
'(("Libera.Chat" "#emacs" "#erc")))
(use-package erc-join
;; Join #emacs and #erc whenever I connect to Libera.Chat.
:custom (erc-autojoin-channels-alist '((Libera.Chat "#emacs" "#erc"))))
;; Interpret mIRC-style color commands in IRC chats
(setq erc-interpret-mirc-color t)
(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)))
;; 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)
@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
(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
@ -1777,7 +1999,7 @@ In the resulting @code{help-mode} buffer, confirm the version and
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
@ -1866,6 +2088,21 @@ is maintained as part of Emacs.
@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