3 @setfilename ../info/erc
9 * ERC: (erc). Powerful, modular, and extensible IRC client for Emacs.
15 This manual is for ERC version 5.1.4.
17 Copyright @copyright{} 2005, 2006 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.2 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, Front-Cover texts, or Back-Cover Texts.
29 @subtitle a full-featured IRC client
30 @subtitle for GNU Emacs and XEmacs
32 @c The following two commands
33 @c start the copyright page.
35 @vskip 0pt plus 1filll
39 @c So the toc is printed at the start
43 @node Top, Introduction, (dir), (dir)
44 @comment node-name, next, previous, up
51 * Introduction:: What is ERC?
52 * Obtaining ERC:: How to get ERC releases and development
54 * Installation:: Compiling and installing ERC.
55 * Getting Started:: Quick Start guide to using ERC.
56 * Keystroke Summary:: Keystrokes used in ERC buffers.
57 * Modules:: Available modules for ERC.
58 * Advanced Usage:: Cool ways of using ERC.
59 * Getting Help and Reporting Bugs::
60 * History:: The history of ERC.
61 * Concept Index:: Search for terms.
64 --- The Detailed Node Listing ---
68 * Releases:: Released versions of ERC.
69 * Development:: Latest unreleased development changes.
73 * Connecting:: Ways of connecting to an IRC server.
74 * Options:: Options that are available for ERC.
75 * Tips and Tricks:: Ways of enhancing your ERC experience.
76 * Sample Configuration:: An example configuration file.
81 @node Introduction, Obtaining ERC, Top, Top
82 @comment node-name, next, previous, up
85 ERC is a powerful, modular, and extensible IRC client for Emacs.
87 It comes with the following capabilities enabled by default.
92 @item Join channels automatically
93 @item Buttonize URLs, nicknames, and other text
95 @item Highlight or remove IRC control characters
96 @item Highlight pals, fools, and other keywords
97 @item Detect netsplits
98 @item Complete nicknames and commands in a programmable fashion
99 @item Make displayed lines read-only
101 @item Track channel activity in the mode-line
105 @node Obtaining ERC, Installation, Introduction, Top
106 @comment node-name, next, previous, up
107 @chapter Obtaining ERC
110 * Releases:: Released versions of ERC.
111 * Development:: Latest unreleased development changes.
114 These sections may be skipped if you are using the version of ERC that
117 @node Releases, Development, Obtaining ERC, Obtaining ERC
118 @comment node-name, next, previous, up
121 Choose to install a release if you want to minimize risk.
123 Errors are corrected in development first. User-visible changes will be
124 announced on the @email{erc-discuss@@gnu.org} mailing list.
125 @pxref{Getting Help and Reporting Bugs}.
127 @cindex releases, Debian package
128 @cindex Debian package for ERC
129 Debian users can get ERC via apt-get. The @file{erc} package is
130 available in the official Debian repository.
132 @cindex releases, from source
133 Alternatively, you can download the latest release from
134 @uref{http://ftp.gnu.org/gnu/erc}.
136 @node Development, , Releases, Obtaining ERC
137 @comment node-name, next, previous, up
141 Choose the development version if you want to live on the bleeding edge
142 of ERC development or try out new features before release.
146 ERC is developed using GNU Arch. Downloading ERC with Arch and staying
147 up-to-date involves the following steps.
150 @cindex GNU Arch, installing
154 @item Debian: @kbd{apt-get install tla}.
155 @item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}.
158 @cindex GNU Arch, downloading ERC
159 @item Register the archive.
161 tla register-archive -f http://arch.sv.gnu.org/archives/erc/erc
164 @item Download the ERC source code.
166 # Download ERC into the @file{erc} directory.
167 tla get erc@@sv.gnu.org/erc--main--0 erc
170 @item List upstream changes that are missing from your local copy.
171 Do this whenever you want to see whether new changes have been committed
175 # Change to the source directory you are interested in.
178 # Display the summary of changes
179 tla missing --summary
182 @cindex GNU Arch, updating ERC
183 @item Update to the latest version by replaying missing changes.
191 If you are new to Arch and want to learn more about developing with it,
192 you might find this tutorial helpful:
193 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
195 @subheading Development snapshots
197 @cindex development snapshot
198 Alternatively, the latest development snapshot may be downloaded in both
199 ``.tar.gz'' and ``.zip'' forms.
202 @item @uref{http://www.mwolson.org/static/dist/erc-latest.tar.gz}
203 @item @uref{http://www.mwolson.org/static/dist/erc-latest.zip}
207 @node Installation, Getting Started, Obtaining ERC, Top
208 @comment node-name, next, previous, up
209 @chapter Installation
211 ERC may be compiled and installed on your machine.
213 This section may be skipped if you are using the version of ERC that
216 @subsubheading Compilation
218 This is an optional step, since Emacs Lisp source code does not
219 necessarily have to be byte-compiled. It will yield a speed increase,
222 A working copy of Emacs or XEmacs is needed in order to compile ERC. By
223 default, the program that is installed with the name @command{emacs}
226 If you want to use the @command{xemacs} binary to perform the
227 compilation, you would need to edit @file{Makefile} in the top-level
228 directory as follows. You can put either a full path to an Emacs or
229 XEmacs binary or just the command name, as long as it is in the
234 SITEFLAG = -no-site-file
237 Running @code{make} should compile the ERC source files in the
238 @file{lisp} directory.
240 @subsubheading Installation
242 ERC may be installed into your file hierarchy by doing the following.
244 Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you
245 want the source and compiled ERC files to be installed and
246 @env{INFODIR} indicates where to put the ERC manual. Of course, you
247 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
248 Compilation section if you are using XEmacs.
250 If you are installing ERC on a Debian system, you might want to change
251 the value of @env{INSTALLINFO} as specified in @file{Makefile}.
253 Run @code{make} as a normal user.
255 Run @code{make install} as the root user if you have chosen installation
256 locations that require this.
259 @node Getting Started, Keystroke Summary, Installation, Top
260 @comment node-name, next, previous, up
261 @chapter Getting Started
264 @c PRE5_2: Mention .ercrc.el
266 To use ERC, add the directory containing its files to your
267 @code{load-path} variable, in your @file{.emacs} file. Then, load ERC
268 itself. An example follows.
274 Once ERC is loaded, the command @kbd{M-x erc-select} will start ERC and
275 prompt for the server to connect to.
277 @c PRE5_2: Sample session, including:
278 @c - connect to Freenode
280 @c - see messages flying past, point out topic lines, messages, channel
282 @c - identifying your nick with NickServ (most IRC servers have this)
283 @c - talking to the channel
284 @c - open a /query buffer to talk to someone (must identify first in
288 @node Keystroke Summary, Modules, Getting Started, Top
289 @comment node-name, next, previous, up
290 @chapter Keys Used in ERC
293 This is a summary of keystrokes available in every ERC buffer.
297 @item C-a or <home> (`erc-bol')
298 Go to beginning of line or end of prompt.
300 @item RET (`erc-send-current-line')
301 Send the current line
303 @item TAB (`erc-complete-word')
304 If at prompt, complete the current word.
305 Otherwise, move to the next link or button.
307 @item M-TAB (`ispell-complete-word')
308 Complete the given word, using ispell.
310 @item C-c C-a (`erc-bol')
311 Go to beginning of line or end of prompt.
313 @item C-c C-b (`erc-iswitchb')
314 Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to.
316 @item C-c C-c (`erc-toggle-interpret-controls')
317 Toggle interpretation of control sequences in messages.
319 @item C-c C-d (`erc-input-action')
320 Interactively input a user action and send it to IRC.
322 @item C-c C-e (`erc-toggle-ctcp-autoresponse')
323 Toggle automatic CTCP replies (like VERSION and PING).
325 @item C-c C-f (`erc-toggle-flood-control')
326 Toggle use of flood control on sent messages.
328 @item C-c TAB (`erc-invite-only-mode')
329 Turn on the invite only mode (+i) for the current channel.
331 @item C-c C-j (`erc-join-channel')
332 Join channel. If point is at the beginning of a channel name, use that
335 @item C-c C-k (`erc-go-to-log-matches-buffer')
336 Interactively open an erc-log-matches buffer
338 @item C-c C-l (`erc-save-buffer-in-logs')
339 Append buffer contents to the log file, if logging is enabled.
341 @item C-c C-n (`erc-channel-names')
342 Run "/names #channel" in the current channel.
344 @item C-c C-o (`erc-get-channel-mode-from-keypress')
345 Read a key sequence and call the corresponding channel mode function.
346 After doing @kbd{C-c C-o}, type in a channel mode letter.
348 @kbd{C-g} means quit.
349 @kbd{RET} lets you type more than one mode at a time.
350 If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called.
351 If @kbd{k} is pressed, @code{erc-set-channel-key} gets called.
352 Anything else will be sent to `erc-toggle-channel-mode'.
354 @item C-c C-p (`erc-part-from-channel')
355 Part from the current channel and prompt for a reason.
357 @item C-c C-q (`erc-quit-server')
358 Disconnect from current server after prompting for reason.
360 @item C-c C-r (`erc-remove-text-properties-region')
361 Clears the region (start,end) in object from all colors, etc.
363 @item C-c C-t (`erc-set-topic')
364 Prompt for a topic for the current channel.
366 @item C-c C-u (`erc-kill-input')
367 Kill current input line using `erc-bol' followed by `kill-line'.
372 @node Modules, Advanced Usage, Keystroke Summary, Top
373 @comment node-name, next, previous, up
377 One way to add functionality to ERC is to customize which of its many
380 There is a spiffy customize interface, which may be reached by typing
381 @kbd{M-x customize-option erc-modules RET}. Alternatively, set
382 @code{erc-modules} manually and then call @code{erc-update-modules}.
384 The following is a list of available modules.
388 @cindex modules, autoaway
390 Set away status automatically
392 @cindex modules, autojoin
394 Join channels automatically
396 @cindex modules, bbdb
398 Integrate with the Big Brother Database
400 @cindex modules, button
402 Buttonize URLs, nicknames, and other text
404 @cindex modules, completion
406 Complete nicknames and commands (programmable)
408 @cindex modules, fill
412 @cindex modules, hecomplete
414 Complete nicknames and commands (old). This is the old module---you
415 might prefer the ``completion'' module instead.
417 @cindex modules, identd
419 Launch an identd server on port 8113
421 @cindex modules, irccontrols
423 Highlight or remove IRC control characters
425 @cindex modules, list
427 List channels nicely in a separate buffer
433 @cindex modules, match
435 Highlight pals, fools, and other keywords
437 @cindex modules, netsplit
441 @cindex modules, noncommands
443 Don't display non-IRC commands after evaluation
445 @cindex modules, notify
447 Notify when the online status of certain users changes
449 @cindex modules, page
451 Process CTCP PAGE requests from IRC
453 @cindex modules, readonly
455 Make displayed lines read-only
457 @cindex modules, replace
459 Replace text in messages
461 @cindex modules, ring
463 Enable an input history
465 @cindex modules, scrolltobottom
467 Scroll to the bottom of the buffer
469 @cindex modules, services
471 Identify to Nickserv (IRC Services) automatically
473 @cindex modules, smiley
475 Convert smileys to pretty icons
477 @cindex modules, sound
479 Play sounds when you receive CTCP SOUND requests
481 @cindex modules, spelling
483 Check spelling of messages
485 @cindex modules, stamp
487 Add timestamps to messages
489 @cindex modules, track
491 Track channel activity in the mode-line
493 @cindex modules, truncate
495 Truncate buffers to a certain size
497 @cindex modules, unmorse
499 Translate morse code in messages
503 @c PRE5_2: Document every option of every module in its own subnode
506 @node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
507 @comment node-name, next, previous, up
508 @chapter Advanced Usage
509 @cindex advanced topics
512 * Connecting:: Ways of connecting to an IRC server.
513 * Options:: Options that are available for ERC.
514 * Tips and Tricks:: Ways of enhancing your ERC experience.
515 * Sample Configuration:: An example configuration file.
518 @node Connecting, Options, Advanced Usage, Advanced Usage
519 @comment node-name, next, previous, up
520 @section Connecting to an IRC Server
523 The easiest way to connect to an IRC server is to call
524 @kbd{M-x erc-select}. If you want to assign this function to a
525 keystroke, the following will help you figure out its parameters.
528 Select connection parameters and run ERC.
529 Non-interactively, it takes the following keyword arguments.
536 @item @var{full-name}
539 That is, if called with the following arguments, @var{server} and
540 @var{full-name} will be set to those values, whereas
541 @code{erc-compute-port}, @code{erc-compute-nick} and
542 @code{erc-compute-full-name} will be invoked for the values of the other
546 (erc-select :server "irc.freenode.net" :full-name "Harry S Truman")
552 @defun erc-compute-server &optional server
553 Return an IRC server name.
555 This tries a number of increasingly more default methods until a non-nil
559 @item @var{server} (the argument passed to this function)
560 @item The @code{erc-server} option
561 @item The value of the IRCSERVER environment variable
562 @item The @code{erc-default-server} variable
567 @defopt erc-server nil
568 IRC server to use if one is not provided.
573 @defun erc-compute-port &optional port
574 Return a port for an IRC server.
576 This tries a number of increasingly more default methods until a non-nil
580 @item @var{port} (the argument passed to this function)
581 @item The @code{erc-port} option
582 @item The @code{erc-default-port} variable
588 IRC port to use if not specified.
590 This can be either a string or a number.
595 @defun erc-compute-nick &optional nick
596 Return user's IRC nick.
598 This tries a number of increasingly more default methods until a
599 non-nil value is found.
602 @item @var{nick} (the argument passed to this function)
603 @item The @code{erc-nick} option
604 @item The value of the IRCNICK environment variable
605 @item The result from the @code{user-login-name} function
611 Nickname to use if one is not provided.
613 This can be either a string, or a list of strings.
614 In the latter case, if the first nick in the list is already in use,
615 other nicks are tried in the list order.
618 @defopt erc-nick-uniquifier
619 The string to append to the nick if it is already in use.
622 @defopt erc-try-new-nick-p
623 If the nickname you chose isn't available, and this option is non-nil,
624 ERC should automatically attempt to connect with another nickname.
626 You can manually set another nickname with the /NICK command.
629 @subheading Full name
631 @defun erc-compute-full-name &optional full-name
632 Return user's full name.
634 This tries a number of increasingly more default methods until a
635 non-nil value is found.
638 @item @var{full-name} (the argument passed to this function)
639 @item The @code{erc-user-full-name} option
640 @item The value of the IRCNAME environment variable
641 @item The result from the @code{user-full-name} function
646 @defopt erc-user-full-name
649 This can be either a string or a function to call.
652 @node Options, Tips and Tricks, Connecting, Advanced Usage
653 @comment node-name, next, previous, up
657 @c PRE5_2: (Node) Document every ERC option (module options go in
660 This section has not yet been written.
662 @node Tips and Tricks, Sample Configuration, Options, Advanced Usage
663 @comment node-name, next, previous, up
664 @section Tips and Tricks
665 @cindex tips and tricks
667 @c PRE5_2: (Node) Tips and tricks
669 This section has not yet been written.
671 @node Sample Configuration, , Tips and Tricks, Advanced Usage
672 @comment node-name, next, previous, up
673 @section Sample Configuration
674 @cindex configuration, sample
676 @c PRE5_2: (Node) Sample configs
678 This section has not yet been written.
681 @node Getting Help and Reporting Bugs, History, Advanced Usage, Top
682 @comment node-name, next, previous, up
683 @chapter Getting Help and Reporting Bugs
684 @cindex help, getting
685 @cindex bugs, reporting
687 After you have read this guide, if you still have questions about ERC,
688 or if you have bugs to report, there are several places you can go.
693 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsIRCClient} is the
694 emacswiki.org page for ERC. Anyone may add tips, hints, or bug
698 There are several mailing lists for ERC. To subscribe, visit
699 @uref{http://savannah.gnu.org/mail/?group=erc}.
701 The mailing lists are also available on Gmane.
702 (@url{http://gmane.org/}). Gmane provides additional methods for
703 accessing the mailing lists, adding content to them, and searching them.
706 @item gmane.emacs.erc.announce
709 @item gmane.emacs.erc.discuss
712 @item gmane.emacs.erc.cvs
713 Log messages for changes to the ERC source code
718 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
719 contributors are frequently around and willing to answer your
725 @node History, Concept Index, Getting Help and Reporting Bugs, Top
726 @comment node-name, next, previous, up
728 @cindex history, of ERC
730 ERC was originally written by Alexander L. Belikoff
731 @email{abel@@bfr.co.il} and Sergey Berezin
732 @email{sergey.berezin@@cs.cmu.edu}. They stopped development around
733 December 1999. Their last released version was ERC 2.0.
735 P.S.: If one of the original developers of ERC reads this, we'd like to
736 receive additional information for this file and hear comments in
742 In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder
743 @email{alex@@gnu.org} took over development and created a ERC Project at
744 @uref{http://sourceforge.net/projects/erc}.
746 In reaction to a mail about the new ERC development effort, Sergey
747 Berezin said, ``First of all, I'm glad that my version of ERC is being
748 used out there. The thing is, I do not have free time and enough
749 incentive anymore to work on ERC, so I would be happy if you guys take
750 over the project entirely.''
752 So we happily hacked away on ERC, and soon after (September 2001)
753 released the next "stable" version, 2.1.
755 Most of the development of the new ERC happened on #emacs on
756 irc.openprojects.net. Over time, many people contributed code, ideas,
757 bugfixes, and a lot of alpha/beta/gamma testing.
759 See the @file{CREDITS} file for a list of contributors.
763 ERC 3.0 was released.
767 ERC 4.0 was released.
771 ERC 5.0 was released. Michael Olson @email{mwolson@@gnu.org} became
772 the release manager and eventually the maintainer.
774 After some discussion between him and the Emacs developers, it was
775 decided to include ERC in Emacs.
779 ERC 5.1 was released. It was subsequently included in Emacs 22.
781 ERC became an official GNU project, and development moved to
782 @uref{http://sv.gnu.org/projects/erc}. We switched to using GNU Arch as
783 our revision control system. Our mailing list address changed as well.
787 @node Concept Index, , History, Top
788 @comment node-name, next, previous, up
796 arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e