(syms_of_keyboard): Doc fix.
[emacs.git] / man / erc.texi
blob60c682b892f033596d22f7a010bb31993efaf7d9
1 \input texinfo
2 @c %**start of header
3 @setfilename ../info/erc
4 @settitle ERC Manual
5 @c %**end of header
7 @dircategory Emacs
8 @direntry
9 * ERC: (erc).           Powerful, modular, and extensible IRC client for Emacs.
10 @end direntry
12 @syncodeindex fn cp
14 @copying
15 This manual is for ERC version 5.2 stable pre-release.
17 Copyright @copyright{} 2005, 2006, 2007 Free Software Foundation, Inc.
19 @quotation
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.
24 @end quotation
25 @end copying
27 @titlepage
28 @title ERC manual
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.
34 @page
35 @vskip 0pt plus 1filll
36 @insertcopying
37 @end titlepage
39 @c So the toc is printed at the start
40 @contents
42 @ifnottex
43 @node Top, Introduction, (dir), (dir)
44 @comment  node-name,  next,  previous,  up
45 @top ERC
47 @insertcopying
48 @end ifnottex
50 @menu
51 * Introduction::                What is ERC?
52 * Obtaining ERC::               How to get ERC releases and development
53                                   versions.
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.
63 @detailmenu
64  --- The Detailed Node Listing ---
66 Obtaining ERC
68 * Releases::                    Released versions of ERC.
69 * Development::                 Latest unreleased development changes.
71 Advanced Usage
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.
78 @end detailmenu
79 @end menu
81 @node Introduction, Obtaining ERC, Top, Top
82 @comment  node-name,  next,  previous,  up
83 @chapter Introduction
85 ERC is a powerful, modular, and extensible IRC client for Emacs.
87 It comes with the following capabilities enabled by default.
89 @itemize @bullet
90 @item Flood control
91 @item Timestamps
92 @item Join channels automatically
93 @item Buttonize URLs, nicknames, and other text
94 @item Wrap long lines
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
100 @item Input history
101 @item Track channel activity in the mode-line
103 @end itemize
105 @node Obtaining ERC, Installation, Introduction, Top
106 @comment  node-name,  next,  previous,  up
107 @chapter Obtaining ERC
109 @menu
110 * Releases::                    Released versions of ERC.
111 * Development::                 Latest unreleased development changes.
112 @end menu
114 These sections may be skipped if you are using the version of ERC that
115 comes with Emacs.
117 @node Releases, Development, Obtaining ERC, Obtaining ERC
118 @comment  node-name,  next,  previous,  up
119 @section Releases
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
138 @section Development
139 @cindex development
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.
144 @subheading GNU Arch
146 ERC is developed using GNU Arch.  Downloading ERC with Arch and staying
147 up-to-date involves the following steps.
149 @enumerate
150 @cindex GNU Arch, installing
151 @item Install arch
153 @itemize @bullet
154 @item Debian: @kbd{apt-get install tla}.
155 @item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}.
156 @end itemize
158 @cindex GNU Arch, downloading ERC
159 @item Register the archive.
160 @example
161 tla register-archive -f http://arch.sv.gnu.org/archives/erc/erc
162 @end example
164 @item Download the ERC source code.
165 @example
166 # Download ERC into the @file{erc} directory.
167 tla get erc@@sv.gnu.org/erc--main--0 erc
168 @end example
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
172 to ERC.
174 @example
175 # Change to the source directory you are interested in.
176 cd erc/
178 # Display the summary of changes
179 tla missing --summary
180 @end example
182 @cindex GNU Arch, updating ERC
183 @item Update to the latest version by replaying missing changes.
184 @example
185 cd erc
186 tla update
187 @end example
189 @end enumerate
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.
201 @itemize @bullet
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}
204 @end itemize
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
214 comes with Emacs.
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,
220 though.
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}
224 will be used.
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
230 @env{PATH}.
232 @example
233 EMACS    = xemacs
234 SITEFLAG = -no-site-file
235 @end example
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
262 @cindex settings
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.
270 @lisp
271 (require 'erc)
272 @end lisp
274 Once ERC is loaded, the command @kbd{M-x erc} will start ERC and
275 prompt for the server to connect to.
277 If the connection goes away at some point, ERC will try to reconnect
278 automatically.  If it fails to reconnect, and you want to try to
279 manually reestablish the connection at some later point, switch to an
280 ERC buffer and run the /RECONNECT command.
282 @c PRE5_2: Sample session, including:
283 @c - connect to Freenode
284 @c - /join #emacs
285 @c - see messages flying past, point out topic lines, messages, channel
286 @c   members
287 @c - identifying your nick with NickServ (most IRC servers have this)
288 @c - talking to the channel
289 @c - open a /query buffer to talk to someone (must identify first in
290 @c   FreeNode)
293 @node Keystroke Summary, Modules, Getting Started, Top
294 @comment  node-name,  next,  previous,  up
295 @chapter Keys Used in ERC
296 @cindex keystrokes
298 This is a summary of keystrokes available in every ERC buffer.
300 @table @kbd
302 @item C-a or <home> (`erc-bol')
303 Go to beginning of line or end of prompt.
305 @item RET (`erc-send-current-line')
306 Send the current line
308 @item TAB (`erc-complete-word')
309 If at prompt, complete the current word.
310 Otherwise, move to the next link or button.
312 @item M-TAB (`ispell-complete-word')
313 Complete the given word, using ispell.
315 @item C-c C-a (`erc-bol')
316 Go to beginning of line or end of prompt.
318 @item C-c C-b (`erc-iswitchb')
319 Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to.
321 @item C-c C-c (`erc-toggle-interpret-controls')
322 Toggle interpretation of control sequences in messages.
324 @item C-c C-d (`erc-input-action')
325 Interactively input a user action and send it to IRC.
327 @item C-c C-e (`erc-toggle-ctcp-autoresponse')
328 Toggle automatic CTCP replies (like VERSION and PING).
330 @item C-c C-f (`erc-toggle-flood-control')
331 Toggle use of flood control on sent messages.
333 @item C-c TAB (`erc-invite-only-mode')
334 Turn on the invite only mode (+i) for the current channel.
336 @item C-c C-j (`erc-join-channel')
337 Join channel.  If point is at the beginning of a channel name, use that
338 as default.
340 @item C-c C-k (`erc-go-to-log-matches-buffer')
341 Interactively open an erc-log-matches buffer
343 @item C-c C-l (`erc-save-buffer-in-logs')
344 Append buffer contents to the log file, if logging is enabled.
346 @item C-c C-n (`erc-channel-names')
347 Run "/names #channel" in the current channel.
349 @item C-c C-o (`erc-get-channel-mode-from-keypress')
350 Read a key sequence and call the corresponding channel mode function.
351 After doing @kbd{C-c C-o}, type in a channel mode letter.
353 @kbd{C-g} means quit.
354 @kbd{RET} lets you type more than one mode at a time.
355 If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called.
356 If @kbd{k} is pressed, @code{erc-set-channel-key} gets called.
357 Anything else will be sent to `erc-toggle-channel-mode'.
359 @item C-c C-p (`erc-part-from-channel')
360 Part from the current channel and prompt for a reason.
362 @item C-c C-q (`erc-quit-server')
363 Disconnect from current server after prompting for reason.
365 @item C-c C-r (`erc-remove-text-properties-region')
366 Clears the region (start,end) in object from all colors, etc.
368 @item C-c C-t (`erc-set-topic')
369 Prompt for a topic for the current channel.
371 @item C-c C-u (`erc-kill-input')
372 Kill current input line using `erc-bol' followed by `kill-line'.
374 @end table
377 @node Modules, Advanced Usage, Keystroke Summary, Top
378 @comment  node-name,  next,  previous,  up
379 @chapter Modules
380 @cindex modules
382 One way to add functionality to ERC is to customize which of its many
383 modules are loaded.
385 There is a spiffy customize interface, which may be reached by typing
386 @kbd{M-x customize-option erc-modules RET}.  Alternatively, set
387 @code{erc-modules} manually and then call @code{erc-update-modules}.
389 The following is a list of available modules.
391 @table @code
393 @cindex modules, autoaway
394 @item autoaway
395 Set away status automatically
397 @cindex modules, autojoin
398 @item autojoin
399 Join channels automatically
401 @cindex modules, bbdb
402 @item bbdb
403 Integrate with the Big Brother Database
405 @cindex modules, button
406 @item button
407 Buttonize URLs, nicknames, and other text
409 @cindex modules, capab-identify
410 @item capab-identify
411 Mark unidentified users on freenode and other servers supporting CAPAB.
413 @cindex modules, completion
414 @item pcomplete
415 Complete nicknames and commands (programmable)
417 @cindex modules, fill
418 @item fill
419 Wrap long lines
421 @cindex modules, hecomplete
422 @item completion
423 Complete nicknames and commands (old).  This is the old module---you
424 might prefer the ``completion'' module instead.
426 @cindex modules, identd
427 @item identd
428 Launch an identd server on port 8113
430 @cindex modules, irccontrols
431 @item irccontrols
432 Highlight or remove IRC control characters
434 @cindex modules, log
435 @item log
436 Save buffers in logs
438 @cindex modules, match
439 @item match
440 Highlight pals, fools, and other keywords
442 @cindex modules, netsplit
443 @item netsplit
444 Detect netsplits
446 @cindex modules, noncommands
447 @item noncommands
448 Don't display non-IRC commands after evaluation
450 @cindex modules, notify
451 @item notify
452 Notify when the online status of certain users changes
454 @cindex modules, page
455 @item page
456 Process CTCP PAGE requests from IRC
458 @cindex modules, readonly
459 @item readonly
460 Make displayed lines read-only
462 @cindex modules, replace
463 @item replace
464 Replace text in messages
466 @cindex modules, ring
467 @item ring
468 Enable an input history
470 @cindex modules, scrolltobottom
471 @item scrolltobottom
472 Scroll to the bottom of the buffer
474 @cindex modules, services
475 @item services
476 Identify to Nickserv (IRC Services) automatically
478 @cindex modules, smiley
479 @item smiley
480 Convert smileys to pretty icons
482 @cindex modules, sound
483 @item sound
484 Play sounds when you receive CTCP SOUND requests
486 @cindex modules, spelling
487 @item spelling
488 Check spelling of messages
490 @cindex modules, stamp
491 @item stamp
492 Add timestamps to messages
494 @cindex modules, track
495 @item track
496 Track channel activity in the mode-line
498 @cindex modules, truncate
499 @item truncate
500 Truncate buffers to a certain size
502 @cindex modules, unmorse
503 @item unmorse
504 Translate morse code in messages
506 @end table
508 @c PRE5_2: Document every option of every module in its own subnode
511 @node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
512 @comment  node-name,  next,  previous,  up
513 @chapter Advanced Usage
514 @cindex advanced topics
516 @menu
517 * Connecting::                  Ways of connecting to an IRC server.
518 * Options::                     Options that are available for ERC.
519 * Tips and Tricks::             Ways of enhancing your ERC experience.
520 * Sample Configuration::        An example configuration file.
521 @end menu
523 @node Connecting, Options, Advanced Usage, Advanced Usage
524 @comment  node-name,  next,  previous,  up
525 @section Connecting to an IRC Server
526 @cindex connecting
528 The easiest way to connect to an IRC server is to call @kbd{M-x erc}.
529 If you want to assign this function to a keystroke, the following will
530 help you figure out its parameters.
532 @defun erc
533 Select connection parameters and run ERC.
534 Non-interactively, it takes the following keyword arguments.
536 @itemize @bullet
537 @item @var{server}
538 @item @var{port}
539 @item @var{nick}
540 @item @var{password}
541 @item @var{full-name}
542 @end itemize
544 That is, if called with the following arguments, @var{server} and
545 @var{full-name} will be set to those values, whereas
546 @code{erc-compute-port}, @code{erc-compute-nick} and
547 @code{erc-compute-full-name} will be invoked for the values of the other
548 parameters.
550 @example
551 (erc :server "irc.freenode.net" :full-name "Harry S Truman")
552 @end example
553 @end defun
555 @subheading Server
557 @defun erc-compute-server &optional server
558 Return an IRC server name.
560 This tries a number of increasingly more default methods until a non-nil
561 value is found.
563 @itemize @bullet
564 @item @var{server} (the argument passed to this function)
565 @item The @code{erc-server} option
566 @item The value of the IRCSERVER environment variable
567 @item The @code{erc-default-server} variable
568 @end itemize
570 @end defun
572 @defopt erc-server nil
573 IRC server to use if one is not provided.
574 @end defopt
576 @subheading Port
578 @defun erc-compute-port &optional port
579 Return a port for an IRC server.
581 This tries a number of increasingly more default methods until a non-nil
582 value is found.
584 @itemize @bullet
585 @item @var{port} (the argument passed to this function)
586 @item The @code{erc-port} option
587 @item The @code{erc-default-port} variable
588 @end itemize
590 @end defun
592 @defopt erc-port
593 IRC port to use if not specified.
595 This can be either a string or a number.
596 @end defopt
598 @subheading Nick
600 @defun erc-compute-nick &optional nick
601 Return user's IRC nick.
603 This tries a number of increasingly more default methods until a
604 non-nil value is found.
606 @itemize
607 @item @var{nick} (the argument passed to this function)
608 @item The @code{erc-nick} option
609 @item The value of the IRCNICK environment variable
610 @item The result from the @code{user-login-name} function
611 @end itemize
613 @end defun
615 @defopt erc-nick
616 Nickname to use if one is not provided.
618 This can be either a string, or a list of strings.
619 In the latter case, if the first nick in the list is already in use,
620 other nicks are tried in the list order.
621 @end defopt
623 @defopt erc-nick-uniquifier
624 The string to append to the nick if it is already in use.
625 @end defopt
627 @defopt erc-try-new-nick-p
628 If the nickname you chose isn't available, and this option is non-nil,
629 ERC should automatically attempt to connect with another nickname.
631 You can manually set another nickname with the /NICK command.
632 @end defopt
634 @subheading Full name
636 @defun erc-compute-full-name &optional full-name
637 Return user's full name.
639 This tries a number of increasingly more default methods until a
640 non-nil value is found.
642 @itemize @bullet
643 @item @var{full-name} (the argument passed to this function)
644 @item The @code{erc-user-full-name} option
645 @item The value of the IRCNAME environment variable
646 @item The result from the @code{user-full-name} function
647 @end itemize
649 @end defun
651 @defopt erc-user-full-name
652 User full name.
654 This can be either a string or a function to call.
655 @end defopt
657 @node Options, Tips and Tricks, Connecting, Advanced Usage
658 @comment  node-name,  next,  previous,  up
659 @section Options
660 @cindex options
662 @c PRE5_2: (Node) Document every ERC option (module options go in
663 @c previous chapter)
665 This section has not yet been written.
667 @node Tips and Tricks, Sample Configuration, Options, Advanced Usage
668 @comment  node-name,  next,  previous,  up
669 @section Tips and Tricks
670 @cindex tips and tricks
672 @c PRE5_2: (Node) Tips and tricks
674 This section has not yet been written.
676 @node Sample Configuration, , Tips and Tricks, Advanced Usage
677 @comment  node-name,  next,  previous,  up
678 @section Sample Configuration
679 @cindex configuration, sample
681 @c PRE5_2: (Node) Sample configs
683 This section has not yet been written.
686 @node Getting Help and Reporting Bugs, History, Advanced Usage, Top
687 @comment  node-name,  next,  previous,  up
688 @chapter Getting Help and Reporting Bugs
689 @cindex help, getting
690 @cindex bugs, reporting
692 After you have read this guide, if you still have questions about ERC,
693 or if you have bugs to report, there are several places you can go.
695 @itemize @bullet
697 @item
698 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsIRCClient} is the
699 emacswiki.org page for ERC.  Anyone may add tips, hints, or bug
700 descriptions to it.
702 @item
703 There are several mailing lists for ERC.  To subscribe, visit
704 @uref{http://savannah.gnu.org/mail/?group=erc}.
706 The mailing lists are also available on Gmane.
707 (@url{http://gmane.org/}).  Gmane provides additional methods for
708 accessing the mailing lists, adding content to them, and searching them.
710 @enumerate
711 @item gmane.emacs.erc.announce
712 Announcements
714 @item gmane.emacs.erc.discuss
715 General discussion
717 @item gmane.emacs.erc.cvs
718 Log messages for changes to the ERC source code
720 @end enumerate
722 @item
723 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
724 contributors are frequently around and willing to answer your
725 questions.
727 @end itemize
730 @node History, Concept Index, Getting Help and Reporting Bugs, Top
731 @comment  node-name,  next,  previous,  up
732 @chapter History
733 @cindex history, of ERC
735 ERC was originally written by Alexander L. Belikoff
736 @email{abel@@bfr.co.il} and Sergey Berezin
737 @email{sergey.berezin@@cs.cmu.edu}.  They stopped development around
738 December 1999.  Their last released version was ERC 2.0.
740 P.S.: If one of the original developers of ERC reads this, we'd like to
741 receive additional information for this file and hear comments in
742 general.
744 @itemize
745 @item 2001
747 In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder
748 @email{alex@@gnu.org} took over development and created a ERC Project at
749 @uref{http://sourceforge.net/projects/erc}.
751 In reaction to a mail about the new ERC development effort, Sergey
752 Berezin said, ``First of all, I'm glad that my version of ERC is being
753 used out there.  The thing is, I do not have free time and enough
754 incentive anymore to work on ERC, so I would be happy if you guys take
755 over the project entirely.''
757 So we happily hacked away on ERC, and soon after (September 2001)
758 released the next "stable" version, 2.1.
760 Most of the development of the new ERC happened on #emacs on
761 irc.openprojects.net.  Over time, many people contributed code, ideas,
762 bugfixes, and a lot of alpha/beta/gamma testing.
764 See the @file{CREDITS} file for a list of contributors.
766 @item 2003
768 ERC 3.0 was released.
770 @item 2004
772 ERC 4.0 was released.
774 @item 2005
776 ERC 5.0 was released.  Michael Olson @email{mwolson@@gnu.org} became
777 the release manager and eventually the maintainer.
779 After some discussion between him and the Emacs developers, it was
780 decided to include ERC in Emacs.
782 @item 2006
784 ERC 5.1 was released.  It was subsequently included in Emacs 22.
786 ERC became an official GNU project, and development moved to
787 @uref{http://sv.gnu.org/projects/erc}.  We switched to using GNU Arch as
788 our revision control system.  Our mailing list address changed as well.
790 @end itemize
792 @node Concept Index,  , History, Top
793 @comment  node-name,  next,  previous,  up
794 @unnumbered Index
796 @printindex cp
798 @bye
800 @ignore
801    arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e
802 @end ignore