Commit | Line | Data |
---|---|---|
597993cf MB |
1 | \input texinfo |
2 | @c %**start of header | |
3 | @setfilename ../info/erc | |
4 | @settitle ERC Manual | |
5 | @c %**end of header | |
6 | ||
7 | @dircategory Emacs | |
8 | @direntry | |
b223e22d | 9 | * ERC: (erc). Powerful, modular, and extensible IRC client for Emacs. |
597993cf MB |
10 | @end direntry |
11 | ||
12 | @syncodeindex fn cp | |
13 | ||
14 | @copying | |
ff59d266 | 15 | This manual is for ERC version 5.2. |
597993cf | 16 | |
4e6835db | 17 | Copyright @copyright{} 2005, 2006, 2007 Free Software Foundation, Inc. |
597993cf MB |
18 | |
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 | |
32aad466 CY |
23 | Invariant Sections, Front-Cover texts, or Back-Cover Texts. A copy of |
24 | the license is included in the section entitled ``GNU Free | |
25 | Documentation License'' in the Emacs manual. | |
26 | ||
27 | This document is part of a collection distributed under the GNU Free | |
28 | Documentation License. If you want to distribute this document | |
29 | separately from the collection, you can do so by adding a copy of the | |
30 | license to the document, as described in section 6 of the license. | |
ff59d266 MB |
31 | |
32 | All Emacs Lisp code contained in this document may be used, distributed, | |
33 | and modified without restriction. | |
597993cf MB |
34 | @end quotation |
35 | @end copying | |
36 | ||
37 | @titlepage | |
38 | @title ERC manual | |
39 | @subtitle a full-featured IRC client | |
40 | @subtitle for GNU Emacs and XEmacs | |
41 | ||
42 | @c The following two commands | |
43 | @c start the copyright page. | |
44 | @page | |
45 | @vskip 0pt plus 1filll | |
46 | @insertcopying | |
47 | @end titlepage | |
48 | ||
49 | @c So the toc is printed at the start | |
50 | @contents | |
51 | ||
52 | @ifnottex | |
53 | @node Top, Introduction, (dir), (dir) | |
54 | @comment node-name, next, previous, up | |
55 | @top ERC | |
56 | ||
57 | @insertcopying | |
58 | @end ifnottex | |
59 | ||
60 | @menu | |
61 | * Introduction:: What is ERC? | |
62 | * Obtaining ERC:: How to get ERC releases and development | |
63 | versions. | |
64 | * Installation:: Compiling and installing ERC. | |
65 | * Getting Started:: Quick Start guide to using ERC. | |
66 | * Keystroke Summary:: Keystrokes used in ERC buffers. | |
67 | * Modules:: Available modules for ERC. | |
68 | * Advanced Usage:: Cool ways of using ERC. | |
69 | * Getting Help and Reporting Bugs:: | |
70 | * History:: The history of ERC. | |
84247bb5 | 71 | * GNU Free Documentation License:: The license for this documentation. |
597993cf MB |
72 | * Concept Index:: Search for terms. |
73 | ||
74 | @detailmenu | |
75 | --- The Detailed Node Listing --- | |
76 | ||
77 | Obtaining ERC | |
78 | ||
79 | * Releases:: Released versions of ERC. | |
80 | * Development:: Latest unreleased development changes. | |
81 | ||
ff59d266 MB |
82 | Getting Started |
83 | ||
84 | * Sample Session:: Example of connecting to the #emacs channel | |
85 | * Special Features:: Differences from standalone IRC clients | |
86 | ||
0b6bb130 MB |
87 | Advanced Usage |
88 | ||
89 | * Connecting:: Ways of connecting to an IRC server. | |
0b6bb130 | 90 | * Sample Configuration:: An example configuration file. |
ff59d266 | 91 | * Options:: Options that are available for ERC. |
0b6bb130 | 92 | |
597993cf MB |
93 | @end detailmenu |
94 | @end menu | |
95 | ||
96 | @node Introduction, Obtaining ERC, Top, Top | |
97 | @comment node-name, next, previous, up | |
98 | @chapter Introduction | |
99 | ||
100 | ERC is a powerful, modular, and extensible IRC client for Emacs. | |
101 | ||
102 | It comes with the following capabilities enabled by default. | |
103 | ||
104 | @itemize @bullet | |
105 | @item Flood control | |
106 | @item Timestamps | |
107 | @item Join channels automatically | |
108 | @item Buttonize URLs, nicknames, and other text | |
109 | @item Wrap long lines | |
110 | @item Highlight or remove IRC control characters | |
111 | @item Highlight pals, fools, and other keywords | |
112 | @item Detect netsplits | |
113 | @item Complete nicknames and commands in a programmable fashion | |
114 | @item Make displayed lines read-only | |
115 | @item Input history | |
116 | @item Track channel activity in the mode-line | |
117 | ||
118 | @end itemize | |
119 | ||
120 | @node Obtaining ERC, Installation, Introduction, Top | |
121 | @comment node-name, next, previous, up | |
122 | @chapter Obtaining ERC | |
123 | ||
124 | @menu | |
125 | * Releases:: Released versions of ERC. | |
126 | * Development:: Latest unreleased development changes. | |
127 | @end menu | |
128 | ||
ff59d266 MB |
129 | Note that some ERC files are not included with Emacs due to copyright or |
130 | dependency issues. If desired, they may be found at the following | |
131 | locations, or from your local GNU mirror. | |
132 | ||
133 | @itemize @bullet | |
134 | @item @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.tar.gz} | |
135 | @item @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.zip} | |
136 | @end itemize | |
137 | ||
138 | The rest of this chapter may be skipped if you are using the version of | |
139 | ERC that comes with Emacs. | |
597993cf MB |
140 | |
141 | @node Releases, Development, Obtaining ERC, Obtaining ERC | |
142 | @comment node-name, next, previous, up | |
143 | @section Releases | |
144 | ||
145 | Choose to install a release if you want to minimize risk. | |
146 | ||
147 | Errors are corrected in development first. User-visible changes will be | |
0b6bb130 | 148 | announced on the @email{erc-discuss@@gnu.org} mailing list. |
597993cf MB |
149 | @pxref{Getting Help and Reporting Bugs}. |
150 | ||
151 | @cindex releases, Debian package | |
152 | @cindex Debian package for ERC | |
153 | Debian users can get ERC via apt-get. The @file{erc} package is | |
154 | available in the official Debian repository. | |
155 | ||
156 | @cindex releases, from source | |
157 | Alternatively, you can download the latest release from | |
ff59d266 | 158 | @uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror. |
597993cf MB |
159 | |
160 | @node Development, , Releases, Obtaining ERC | |
161 | @comment node-name, next, previous, up | |
162 | @section Development | |
163 | @cindex development | |
164 | ||
165 | Choose the development version if you want to live on the bleeding edge | |
166 | of ERC development or try out new features before release. | |
167 | ||
0b6bb130 | 168 | @subheading GNU Arch |
597993cf | 169 | |
0b6bb130 MB |
170 | ERC is developed using GNU Arch. Downloading ERC with Arch and staying |
171 | up-to-date involves the following steps. | |
597993cf MB |
172 | |
173 | @enumerate | |
0b6bb130 | 174 | @cindex GNU Arch, installing |
597993cf MB |
175 | @item Install arch |
176 | ||
177 | @itemize @bullet | |
178 | @item Debian: @kbd{apt-get install tla}. | |
179 | @item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}. | |
180 | @end itemize | |
181 | ||
0b6bb130 | 182 | @cindex GNU Arch, downloading ERC |
597993cf MB |
183 | @item Register the archive. |
184 | @example | |
0b6bb130 | 185 | tla register-archive -f http://arch.sv.gnu.org/archives/erc/erc |
597993cf MB |
186 | @end example |
187 | ||
188 | @item Download the ERC source code. | |
189 | @example | |
190 | # Download ERC into the @file{erc} directory. | |
0b6bb130 | 191 | tla get erc@@sv.gnu.org/erc--main--0 erc |
597993cf MB |
192 | @end example |
193 | ||
194 | @item List upstream changes that are missing from your local copy. | |
195 | Do this whenever you want to see whether new changes have been committed | |
196 | to ERC. | |
197 | ||
198 | @example | |
199 | # Change to the source directory you are interested in. | |
200 | cd erc/ | |
201 | ||
202 | # Display the summary of changes | |
203 | tla missing --summary | |
204 | @end example | |
205 | ||
0b6bb130 | 206 | @cindex GNU Arch, updating ERC |
597993cf MB |
207 | @item Update to the latest version by replaying missing changes. |
208 | @example | |
209 | cd erc | |
0b6bb130 | 210 | tla update |
597993cf MB |
211 | @end example |
212 | ||
213 | @end enumerate | |
214 | ||
ff59d266 MB |
215 | If you are new to Arch and want to learn more about developing ERC with |
216 | it, visit @uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment} for | |
217 | full instructions. | |
0b6bb130 MB |
218 | |
219 | @subheading Development snapshots | |
597993cf | 220 | |
0b6bb130 MB |
221 | @cindex development snapshot |
222 | Alternatively, the latest development snapshot may be downloaded in both | |
223 | ``.tar.gz'' and ``.zip'' forms. | |
597993cf | 224 | |
0b6bb130 MB |
225 | @itemize @bullet |
226 | @item @uref{http://www.mwolson.org/static/dist/erc-latest.tar.gz} | |
227 | @item @uref{http://www.mwolson.org/static/dist/erc-latest.zip} | |
228 | @end itemize | |
597993cf MB |
229 | |
230 | ||
231 | @node Installation, Getting Started, Obtaining ERC, Top | |
232 | @comment node-name, next, previous, up | |
233 | @chapter Installation | |
234 | ||
235 | ERC may be compiled and installed on your machine. | |
236 | ||
237 | This section may be skipped if you are using the version of ERC that | |
238 | comes with Emacs. | |
239 | ||
240 | @subsubheading Compilation | |
241 | ||
242 | This is an optional step, since Emacs Lisp source code does not | |
243 | necessarily have to be byte-compiled. It will yield a speed increase, | |
244 | though. | |
245 | ||
246 | A working copy of Emacs or XEmacs is needed in order to compile ERC. By | |
247 | default, the program that is installed with the name @command{emacs} | |
248 | will be used. | |
249 | ||
250 | If you want to use the @command{xemacs} binary to perform the | |
251 | compilation, you would need to edit @file{Makefile} in the top-level | |
252 | directory as follows. You can put either a full path to an Emacs or | |
253 | XEmacs binary or just the command name, as long as it is in the | |
254 | @env{PATH}. | |
255 | ||
256 | @example | |
257 | EMACS = xemacs | |
258 | SITEFLAG = -no-site-file | |
259 | @end example | |
260 | ||
261 | Running @code{make} should compile the ERC source files in the | |
262 | @file{lisp} directory. | |
263 | ||
264 | @subsubheading Installation | |
265 | ||
266 | ERC may be installed into your file hierarchy by doing the following. | |
267 | ||
268 | Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you | |
269 | want the source and compiled ERC files to be installed and | |
270 | @env{INFODIR} indicates where to put the ERC manual. Of course, you | |
271 | will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the | |
272 | Compilation section if you are using XEmacs. | |
273 | ||
274 | If you are installing ERC on a Debian system, you might want to change | |
275 | the value of @env{INSTALLINFO} as specified in @file{Makefile}. | |
276 | ||
277 | Run @code{make} as a normal user. | |
278 | ||
279 | Run @code{make install} as the root user if you have chosen installation | |
280 | locations that require this. | |
281 | ||
282 | ||
283 | @node Getting Started, Keystroke Summary, Installation, Top | |
284 | @comment node-name, next, previous, up | |
285 | @chapter Getting Started | |
286 | @cindex settings | |
287 | ||
597993cf MB |
288 | To use ERC, add the directory containing its files to your |
289 | @code{load-path} variable, in your @file{.emacs} file. Then, load ERC | |
0b6bb130 | 290 | itself. An example follows. |
597993cf MB |
291 | |
292 | @lisp | |
293 | (require 'erc) | |
597993cf MB |
294 | @end lisp |
295 | ||
83dc6995 | 296 | Once ERC is loaded, the command @kbd{M-x erc} will start ERC and |
597993cf MB |
297 | prompt for the server to connect to. |
298 | ||
ff59d266 MB |
299 | If you want to place ERC settings in their own file, you can place them |
300 | in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. | |
301 | ||
302 | If you would rather use the Customize interface to change how ERC works, | |
303 | do @kbd{M-x customize-group RET erc RET}. In particular, ERC comes with | |
304 | lots of modules that may be enabled or disabled; to select which ones | |
305 | you want, do @kbd{M-x customize-variable RET erc-modules RET}. | |
306 | ||
307 | @menu | |
308 | * Sample Session:: Example of connecting to the #emacs channel | |
309 | * Special Features:: Differences from standalone IRC clients | |
310 | @end menu | |
311 | ||
312 | @node Sample Session, Special Features, Getting Started, Getting Started | |
313 | @comment node-name, next, previous, up | |
314 | @section Sample Session | |
315 | ||
316 | This is an example ERC session which shows how to connect to the #emacs | |
317 | channel on Freenode. Another IRC channel on Freenode that may be of | |
318 | interest is #erc, which is a channel where ERC users and developers hang | |
319 | out. | |
320 | ||
321 | @itemize @bullet | |
322 | ||
323 | @item Connect to Freenode | |
324 | ||
325 | Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667'' | |
326 | as the port, and choose a nickname. | |
327 | ||
328 | @item Get used to the interface | |
329 | ||
330 | Switch to the ``irc.freenode.net:6667'' buffer, if you're not already | |
331 | there. You will see first some messages about checking for ident, and | |
332 | then a bunch of other messages that describe the current IRC server. | |
333 | ||
334 | @item Join the #emacs channel | |
335 | ||
336 | In that buffer, type ``/join SPC #emacs'' and hit @kbd{RET}. Depending | |
337 | on how you've set up ERC, either a new buffer for ``#emacs'' will be | |
338 | displayed, or a new buffer called ``#emacs'' will be created in the | |
339 | background. If the latter, switch to the ``#emacs'' buffer. You will | |
340 | see the channel topic and a list of the people who are currently on the | |
341 | channel. | |
342 | ||
343 | @item Register your nickname with Freenode | |
344 | ||
345 | If you would like to be able to talk with people privately on the | |
346 | Freenode network, you will have to ``register'' your nickname. To do | |
347 | so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg | |
348 | NickServ register <password>'', replacing ``<password>'' with your | |
349 | desired password. It should tell you that the operation was successful. | |
350 | ||
351 | @item Talk to people in the channel | |
352 | ||
353 | If you switch back to the ``#emacs'' buffer, you can type a message, and | |
354 | everyone on the channel will see it. | |
355 | ||
356 | @item Open a query buffer to talk to someone | |
357 | ||
358 | If you want to talk with someone in private (this should usually not be | |
359 | done for technical help, only for personal questions), type ``/query | |
360 | <nick>'', replacing ``<nick>'' with the nickname of the person you would | |
361 | like to talk to. Depending on how ERC is set up, you will either see a | |
362 | new buffer with the name of the person, or such a buffer will be created | |
363 | in the background and you will have to switch to it. Begin typing | |
364 | messages, and you will be able to have a conversation. | |
365 | ||
366 | Note that if the other person is not registered, you will not be able to | |
367 | talk with them. | |
368 | ||
369 | @end itemize | |
370 | ||
371 | @node Special Features, , Sample Session, Getting Started | |
372 | @comment node-name, next, previous, up | |
373 | @section Special Features | |
374 | ||
375 | ERC has some features that distinguish it from some IRC clients. | |
376 | ||
377 | @itemize @bullet | |
378 | ||
379 | @item multiple channels and multiple servers | |
380 | ||
381 | Every channel is put in a separate buffer. Several IRC servers may be | |
382 | connected to at the same time. | |
383 | ||
384 | @cindex query buffers | |
385 | @item private message separation | |
386 | ||
387 | Private conversations are treated as channels, and are put into separate | |
388 | buffers in Emacs. We call these ``query buffers''. | |
389 | ||
390 | @item highlighting | |
391 | ||
392 | Some occurences of words can be highlighted, which makes it easier to | |
393 | track different kinds of conversations. | |
394 | ||
395 | @item notification | |
396 | ||
397 | ERC can notify you that certain users are online. | |
398 | ||
399 | @item channel tracking | |
400 | ||
401 | Channels can be hidden and conversation continue in the background. You | |
402 | are notified when something is said in such a channel that is not | |
403 | currently visible. This makes it easy to get Real Work done while still | |
404 | maintaining an IRC presence. | |
405 | ||
406 | @item nick completion | |
407 | ||
408 | ERC can complete words upon hitting @kbd{TAB}, which eases the writing | |
409 | of nicknames in messages. | |
410 | ||
411 | @cindex history ring | |
412 | @item history | |
413 | ||
414 | Past actions are kept in history rings for future use. To navigate a | |
415 | history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go | |
416 | forwards. | |
417 | ||
418 | @item multiple languages | |
419 | ||
420 | Different channels and servers may have different language encodings. | |
421 | ||
422 | In addition, it is possible to translate the messages that ERC uses into | |
423 | multiple languages. Please contact the developers of ERC at | |
424 | @email{erc-discuss@@gnu.org} if you are interested in helping with the | |
425 | translation effort. | |
426 | ||
427 | @item user scripting | |
428 | ||
429 | Users can load scripts (e.g. auto greeting scripts) when ERC starts up. | |
430 | ||
431 | It is also possible to make custom IRC commands, if you know a little | |
432 | Emacs Lisp. Just make an Emacs Lisp function and call it | |
433 | @code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the | |
434 | new command in capital letters. | |
435 | ||
436 | @item auto reconnect | |
437 | ||
10dc9f9e MB |
438 | If the connection goes away at some point, ERC will try to reconnect |
439 | automatically. If it fails to reconnect, and you want to try to | |
440 | manually reestablish the connection at some later point, switch to an | |
ff59d266 | 441 | ERC buffer and run the @code{/RECONNECT} command. |
10dc9f9e | 442 | |
ff59d266 | 443 | @end itemize |
597993cf MB |
444 | |
445 | ||
446 | @node Keystroke Summary, Modules, Getting Started, Top | |
447 | @comment node-name, next, previous, up | |
448 | @chapter Keys Used in ERC | |
449 | @cindex keystrokes | |
450 | ||
451 | This is a summary of keystrokes available in every ERC buffer. | |
452 | ||
453 | @table @kbd | |
454 | ||
455 | @item C-a or <home> (`erc-bol') | |
456 | Go to beginning of line or end of prompt. | |
457 | ||
458 | @item RET (`erc-send-current-line') | |
459 | Send the current line | |
460 | ||
461 | @item TAB (`erc-complete-word') | |
462 | If at prompt, complete the current word. | |
463 | Otherwise, move to the next link or button. | |
464 | ||
465 | @item M-TAB (`ispell-complete-word') | |
466 | Complete the given word, using ispell. | |
467 | ||
468 | @item C-c C-a (`erc-bol') | |
469 | Go to beginning of line or end of prompt. | |
470 | ||
471 | @item C-c C-b (`erc-iswitchb') | |
472 | Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to. | |
473 | ||
474 | @item C-c C-c (`erc-toggle-interpret-controls') | |
475 | Toggle interpretation of control sequences in messages. | |
476 | ||
477 | @item C-c C-d (`erc-input-action') | |
478 | Interactively input a user action and send it to IRC. | |
479 | ||
480 | @item C-c C-e (`erc-toggle-ctcp-autoresponse') | |
481 | Toggle automatic CTCP replies (like VERSION and PING). | |
482 | ||
483 | @item C-c C-f (`erc-toggle-flood-control') | |
484 | Toggle use of flood control on sent messages. | |
485 | ||
486 | @item C-c TAB (`erc-invite-only-mode') | |
487 | Turn on the invite only mode (+i) for the current channel. | |
488 | ||
489 | @item C-c C-j (`erc-join-channel') | |
490 | Join channel. If point is at the beginning of a channel name, use that | |
491 | as default. | |
492 | ||
493 | @item C-c C-k (`erc-go-to-log-matches-buffer') | |
494 | Interactively open an erc-log-matches buffer | |
495 | ||
496 | @item C-c C-l (`erc-save-buffer-in-logs') | |
497 | Append buffer contents to the log file, if logging is enabled. | |
498 | ||
499 | @item C-c C-n (`erc-channel-names') | |
500 | Run "/names #channel" in the current channel. | |
501 | ||
502 | @item C-c C-o (`erc-get-channel-mode-from-keypress') | |
503 | Read a key sequence and call the corresponding channel mode function. | |
0b6bb130 | 504 | After doing @kbd{C-c C-o}, type in a channel mode letter. |
597993cf | 505 | |
0b6bb130 MB |
506 | @kbd{C-g} means quit. |
507 | @kbd{RET} lets you type more than one mode at a time. | |
508 | If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called. | |
509 | If @kbd{k} is pressed, @code{erc-set-channel-key} gets called. | |
597993cf MB |
510 | Anything else will be sent to `erc-toggle-channel-mode'. |
511 | ||
512 | @item C-c C-p (`erc-part-from-channel') | |
513 | Part from the current channel and prompt for a reason. | |
514 | ||
515 | @item C-c C-q (`erc-quit-server') | |
516 | Disconnect from current server after prompting for reason. | |
517 | ||
518 | @item C-c C-r (`erc-remove-text-properties-region') | |
519 | Clears the region (start,end) in object from all colors, etc. | |
520 | ||
521 | @item C-c C-t (`erc-set-topic') | |
522 | Prompt for a topic for the current channel. | |
523 | ||
524 | @item C-c C-u (`erc-kill-input') | |
525 | Kill current input line using `erc-bol' followed by `kill-line'. | |
526 | ||
527 | @end table | |
528 | ||
529 | ||
530 | @node Modules, Advanced Usage, Keystroke Summary, Top | |
531 | @comment node-name, next, previous, up | |
532 | @chapter Modules | |
533 | @cindex modules | |
534 | ||
535 | One way to add functionality to ERC is to customize which of its many | |
536 | modules are loaded. | |
537 | ||
538 | There is a spiffy customize interface, which may be reached by typing | |
539 | @kbd{M-x customize-option erc-modules RET}. Alternatively, set | |
540 | @code{erc-modules} manually and then call @code{erc-update-modules}. | |
541 | ||
542 | The following is a list of available modules. | |
543 | ||
544 | @table @code | |
545 | ||
546 | @cindex modules, autoaway | |
547 | @item autoaway | |
0b6bb130 | 548 | Set away status automatically |
597993cf MB |
549 | |
550 | @cindex modules, autojoin | |
551 | @item autojoin | |
552 | Join channels automatically | |
553 | ||
554 | @cindex modules, bbdb | |
555 | @item bbdb | |
556 | Integrate with the Big Brother Database | |
557 | ||
558 | @cindex modules, button | |
559 | @item button | |
560 | Buttonize URLs, nicknames, and other text | |
561 | ||
6904f7fe MB |
562 | @cindex modules, capab-identify |
563 | @item capab-identify | |
564 | Mark unidentified users on freenode and other servers supporting CAPAB. | |
565 | ||
0b6bb130 | 566 | @cindex modules, completion |
057fc147 GM |
567 | @cindex modules, pcomplete |
568 | @item completion (aka pcomplete) | |
0b6bb130 MB |
569 | Complete nicknames and commands (programmable) |
570 | ||
597993cf MB |
571 | @cindex modules, fill |
572 | @item fill | |
573 | Wrap long lines | |
574 | ||
0b6bb130 | 575 | @cindex modules, hecomplete |
057fc147 | 576 | @item hecomplete |
0b6bb130 MB |
577 | Complete nicknames and commands (old). This is the old module---you |
578 | might prefer the ``completion'' module instead. | |
579 | ||
580 | @cindex modules, identd | |
581 | @item identd | |
582 | Launch an identd server on port 8113 | |
583 | ||
597993cf MB |
584 | @cindex modules, irccontrols |
585 | @item irccontrols | |
586 | Highlight or remove IRC control characters | |
587 | ||
588 | @cindex modules, log | |
589 | @item log | |
590 | Save buffers in logs | |
591 | ||
592 | @cindex modules, match | |
593 | @item match | |
594 | Highlight pals, fools, and other keywords | |
595 | ||
ff59d266 MB |
596 | @cindex modules, menu |
597 | @item menu | |
598 | Display a menu in ERC buffers | |
599 | ||
597993cf MB |
600 | @cindex modules, netsplit |
601 | @item netsplit | |
602 | Detect netsplits | |
603 | ||
604 | @cindex modules, noncommands | |
605 | @item noncommands | |
606 | Don't display non-IRC commands after evaluation | |
607 | ||
608 | @cindex modules, notify | |
609 | @item notify | |
610 | Notify when the online status of certain users changes | |
611 | ||
0b6bb130 MB |
612 | @cindex modules, page |
613 | @item page | |
614 | Process CTCP PAGE requests from IRC | |
597993cf MB |
615 | |
616 | @cindex modules, readonly | |
617 | @item readonly | |
618 | Make displayed lines read-only | |
619 | ||
620 | @cindex modules, replace | |
621 | @item replace | |
622 | Replace text in messages | |
623 | ||
624 | @cindex modules, ring | |
625 | @item ring | |
626 | Enable an input history | |
627 | ||
628 | @cindex modules, scrolltobottom | |
629 | @item scrolltobottom | |
630 | Scroll to the bottom of the buffer | |
631 | ||
632 | @cindex modules, services | |
633 | @item services | |
634 | Identify to Nickserv (IRC Services) automatically | |
635 | ||
636 | @cindex modules, smiley | |
637 | @item smiley | |
638 | Convert smileys to pretty icons | |
639 | ||
640 | @cindex modules, sound | |
641 | @item sound | |
642 | Play sounds when you receive CTCP SOUND requests | |
643 | ||
0b6bb130 MB |
644 | @cindex modules, spelling |
645 | @item spelling | |
646 | Check spelling of messages | |
597993cf MB |
647 | |
648 | @cindex modules, stamp | |
649 | @item stamp | |
650 | Add timestamps to messages | |
651 | ||
652 | @cindex modules, track | |
653 | @item track | |
654 | Track channel activity in the mode-line | |
655 | ||
656 | @cindex modules, truncate | |
657 | @item truncate | |
658 | Truncate buffers to a certain size | |
659 | ||
660 | @cindex modules, unmorse | |
661 | @item unmorse | |
662 | Translate morse code in messages | |
663 | ||
664 | @end table | |
665 | ||
ff59d266 | 666 | @c PRE5_3: Document every option of every module in its own subnode |
597993cf MB |
667 | |
668 | ||
669 | @node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top | |
670 | @comment node-name, next, previous, up | |
671 | @chapter Advanced Usage | |
672 | @cindex advanced topics | |
673 | ||
0b6bb130 MB |
674 | @menu |
675 | * Connecting:: Ways of connecting to an IRC server. | |
0b6bb130 | 676 | * Sample Configuration:: An example configuration file. |
ff59d266 | 677 | * Options:: Options that are available for ERC. |
0b6bb130 MB |
678 | @end menu |
679 | ||
ff59d266 | 680 | @node Connecting, Sample Configuration, Advanced Usage, Advanced Usage |
0b6bb130 MB |
681 | @comment node-name, next, previous, up |
682 | @section Connecting to an IRC Server | |
683 | @cindex connecting | |
684 | ||
83dc6995 MB |
685 | The easiest way to connect to an IRC server is to call @kbd{M-x erc}. |
686 | If you want to assign this function to a keystroke, the following will | |
687 | help you figure out its parameters. | |
0b6bb130 | 688 | |
83dc6995 | 689 | @defun erc |
0b6bb130 MB |
690 | Select connection parameters and run ERC. |
691 | Non-interactively, it takes the following keyword arguments. | |
692 | ||
693 | @itemize @bullet | |
694 | @item @var{server} | |
695 | @item @var{port} | |
696 | @item @var{nick} | |
697 | @item @var{password} | |
698 | @item @var{full-name} | |
699 | @end itemize | |
700 | ||
701 | That is, if called with the following arguments, @var{server} and | |
702 | @var{full-name} will be set to those values, whereas | |
703 | @code{erc-compute-port}, @code{erc-compute-nick} and | |
704 | @code{erc-compute-full-name} will be invoked for the values of the other | |
705 | parameters. | |
706 | ||
707 | @example | |
83dc6995 | 708 | (erc :server "irc.freenode.net" :full-name "Harry S Truman") |
0b6bb130 MB |
709 | @end example |
710 | @end defun | |
711 | ||
712 | @subheading Server | |
713 | ||
714 | @defun erc-compute-server &optional server | |
715 | Return an IRC server name. | |
716 | ||
717 | This tries a number of increasingly more default methods until a non-nil | |
718 | value is found. | |
719 | ||
720 | @itemize @bullet | |
721 | @item @var{server} (the argument passed to this function) | |
722 | @item The @code{erc-server} option | |
723 | @item The value of the IRCSERVER environment variable | |
724 | @item The @code{erc-default-server} variable | |
725 | @end itemize | |
726 | ||
727 | @end defun | |
728 | ||
729 | @defopt erc-server nil | |
730 | IRC server to use if one is not provided. | |
731 | @end defopt | |
732 | ||
733 | @subheading Port | |
734 | ||
735 | @defun erc-compute-port &optional port | |
736 | Return a port for an IRC server. | |
737 | ||
738 | This tries a number of increasingly more default methods until a non-nil | |
739 | value is found. | |
740 | ||
741 | @itemize @bullet | |
742 | @item @var{port} (the argument passed to this function) | |
743 | @item The @code{erc-port} option | |
744 | @item The @code{erc-default-port} variable | |
745 | @end itemize | |
746 | ||
747 | @end defun | |
748 | ||
749 | @defopt erc-port | |
750 | IRC port to use if not specified. | |
751 | ||
752 | This can be either a string or a number. | |
753 | @end defopt | |
754 | ||
755 | @subheading Nick | |
756 | ||
757 | @defun erc-compute-nick &optional nick | |
758 | Return user's IRC nick. | |
759 | ||
760 | This tries a number of increasingly more default methods until a | |
761 | non-nil value is found. | |
762 | ||
763 | @itemize | |
764 | @item @var{nick} (the argument passed to this function) | |
765 | @item The @code{erc-nick} option | |
766 | @item The value of the IRCNICK environment variable | |
767 | @item The result from the @code{user-login-name} function | |
768 | @end itemize | |
769 | ||
770 | @end defun | |
771 | ||
772 | @defopt erc-nick | |
773 | Nickname to use if one is not provided. | |
774 | ||
775 | This can be either a string, or a list of strings. | |
776 | In the latter case, if the first nick in the list is already in use, | |
777 | other nicks are tried in the list order. | |
778 | @end defopt | |
779 | ||
780 | @defopt erc-nick-uniquifier | |
781 | The string to append to the nick if it is already in use. | |
782 | @end defopt | |
783 | ||
784 | @defopt erc-try-new-nick-p | |
785 | If the nickname you chose isn't available, and this option is non-nil, | |
786 | ERC should automatically attempt to connect with another nickname. | |
787 | ||
788 | You can manually set another nickname with the /NICK command. | |
789 | @end defopt | |
790 | ||
791 | @subheading Full name | |
597993cf | 792 | |
0b6bb130 MB |
793 | @defun erc-compute-full-name &optional full-name |
794 | Return user's full name. | |
795 | ||
796 | This tries a number of increasingly more default methods until a | |
797 | non-nil value is found. | |
798 | ||
799 | @itemize @bullet | |
800 | @item @var{full-name} (the argument passed to this function) | |
801 | @item The @code{erc-user-full-name} option | |
802 | @item The value of the IRCNAME environment variable | |
803 | @item The result from the @code{user-full-name} function | |
804 | @end itemize | |
805 | ||
806 | @end defun | |
807 | ||
808 | @defopt erc-user-full-name | |
809 | User full name. | |
810 | ||
811 | This can be either a string or a function to call. | |
812 | @end defopt | |
813 | ||
ff59d266 | 814 | @node Sample Configuration, Options, Connecting, Advanced Usage |
0b6bb130 | 815 | @comment node-name, next, previous, up |
ff59d266 MB |
816 | @section Sample Configuration |
817 | @cindex configuration, sample | |
0b6bb130 | 818 | |
ff59d266 MB |
819 | Here is an example of configuration settings for ERC. This can go into |
820 | your Emacs configuration file. Everything after the @code{(require | |
821 | 'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}. | |
0b6bb130 | 822 | |
ff59d266 MB |
823 | @lisp |
824 | ;;; Sample ERC configuration | |
0b6bb130 | 825 | |
ff59d266 MB |
826 | ;; Add the ERC directory to load path -- you don't need this if you are |
827 | ;; using the version of ERC that comes with Emacs | |
828 | (add-to-list 'load-path "~/elisp/erc") | |
597993cf | 829 | |
ff59d266 MB |
830 | ;; Load ERC |
831 | (require 'erc) | |
597993cf | 832 | |
ff59d266 MB |
833 | ;; Load authentication info from an external source. Put sensitive |
834 | ;; passwords and the like in here. | |
835 | (load "~/.emacs.d/.erc-auth") | |
836 | ||
837 | ;; This is an example of how to make a new command. Type "/uptime" to | |
838 | ;; use it. | |
839 | (defun erc-cmd-UPTIME (&rest ignore) | |
840 | "Display the uptime of the system, as well as some load-related | |
841 | stuff, to the current ERC buffer." | |
842 | (let ((uname-output | |
843 | (replace-regexp-in-string | |
844 | ", load average: " "] @{Load average@} [" | |
845 | ;; Collapse spaces, remove | |
846 | (replace-regexp-in-string | |
847 | " +" " " | |
848 | ;; Remove beginning and trailing whitespace | |
849 | (replace-regexp-in-string | |
850 | "^ +\\|[ \n]+$" "" | |
851 | (shell-command-to-string "uptime")))))) | |
852 | (erc-send-message | |
853 | (concat "@{Uptime@} [" uname-output "]")))) | |
854 | ||
855 | ;; This causes ERC to connect to the Freenode network upon hitting | |
856 | ;; C-c e f. Replace MYNICK with your IRC nick. | |
857 | (global-set-key "\C-cef" (lambda () (interactive) | |
858 | (erc :server "irc.freenode.net" :port "6667" | |
859 | :nick "MYNICK"))) | |
860 | ||
861 | ;; This causes ERC to connect to the IRC server on your own machine (if | |
862 | ;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC | |
863 | ;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an | |
864 | ;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with | |
865 | ;; people on those networks. | |
866 | (global-set-key "\C-ceb" (lambda () (interactive) | |
867 | (erc :server "localhost" :port "6667" | |
868 | :nick "MYNICK"))) | |
869 | ||
870 | ;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has | |
871 | ;; been commented out to avoid confusing new users. | |
872 | ;; (define-key erc-mode-map (kbd "RET") nil) | |
873 | ;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line) | |
874 | ;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line) | |
875 | ||
876 | ;;; Options | |
877 | ||
878 | ;; Join the #emacs and #erc channels whenever connecting to Freenode. | |
879 | (setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc"))) | |
880 | ||
881 | ;; Interpret mIRC-style color commands in IRC chats | |
882 | (setq erc-interpret-mirc-color t) | |
883 | ||
884 | ;; The following are commented out by default, but users of other | |
885 | ;; non-Emacs IRC clients might find them useful. | |
886 | ;; Kill buffers for channels after /part | |
887 | ;; (setq erc-kill-buffer-on-part t) | |
888 | ;; Kill buffers for private queries after quitting the server | |
889 | ;; (setq erc-kill-queries-on-quit t) | |
890 | ;; Kill buffers for server messages after quitting the server | |
891 | ;; (setq erc-kill-server-buffer-on-quit t) | |
892 | @end lisp | |
0b6bb130 | 893 | |
ff59d266 | 894 | @node Options, , Sample Configuration, Advanced Usage |
0b6bb130 | 895 | @comment node-name, next, previous, up |
ff59d266 MB |
896 | @section Options |
897 | @cindex options | |
0b6bb130 | 898 | |
ff59d266 MB |
899 | @c PRE5_3: (Node) Document every ERC option (module options go in |
900 | @c previous chapter) | |
597993cf | 901 | |
ff59d266 MB |
902 | This section has not yet been written. For now, the easiest way to |
903 | check out the available option for ERC is to do | |
904 | @kbd{M-x customize-group erc RET}. | |
0b6bb130 | 905 | |
597993cf MB |
906 | |
907 | @node Getting Help and Reporting Bugs, History, Advanced Usage, Top | |
908 | @comment node-name, next, previous, up | |
909 | @chapter Getting Help and Reporting Bugs | |
910 | @cindex help, getting | |
911 | @cindex bugs, reporting | |
912 | ||
913 | After you have read this guide, if you still have questions about ERC, | |
914 | or if you have bugs to report, there are several places you can go. | |
915 | ||
916 | @itemize @bullet | |
917 | ||
918 | @item | |
919 | @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsIRCClient} is the | |
920 | emacswiki.org page for ERC. Anyone may add tips, hints, or bug | |
921 | descriptions to it. | |
922 | ||
923 | @item | |
0b6bb130 MB |
924 | There are several mailing lists for ERC. To subscribe, visit |
925 | @uref{http://savannah.gnu.org/mail/?group=erc}. | |
926 | ||
927 | The mailing lists are also available on Gmane. | |
928 | (@url{http://gmane.org/}). Gmane provides additional methods for | |
929 | accessing the mailing lists, adding content to them, and searching them. | |
597993cf | 930 | |
0b6bb130 MB |
931 | @enumerate |
932 | @item gmane.emacs.erc.announce | |
933 | Announcements | |
934 | ||
935 | @item gmane.emacs.erc.discuss | |
936 | General discussion | |
937 | ||
938 | @item gmane.emacs.erc.cvs | |
939 | Log messages for changes to the ERC source code | |
940 | ||
941 | @end enumerate | |
597993cf MB |
942 | |
943 | @item | |
944 | You can visit the IRC Freenode channel @samp{#emacs}. Many of the | |
945 | contributors are frequently around and willing to answer your | |
946 | questions. | |
947 | ||
948 | @end itemize | |
949 | ||
950 | ||
84247bb5 | 951 | @node History, GNU Free Documentation License, Getting Help and Reporting Bugs, Top |
597993cf MB |
952 | @comment node-name, next, previous, up |
953 | @chapter History | |
954 | @cindex history, of ERC | |
955 | ||
956 | ERC was originally written by Alexander L. Belikoff | |
957 | @email{abel@@bfr.co.il} and Sergey Berezin | |
958 | @email{sergey.berezin@@cs.cmu.edu}. They stopped development around | |
0b6bb130 | 959 | December 1999. Their last released version was ERC 2.0. |
597993cf MB |
960 | |
961 | P.S.: If one of the original developers of ERC reads this, we'd like to | |
962 | receive additional information for this file and hear comments in | |
963 | general. | |
964 | ||
965 | @itemize | |
966 | @item 2001 | |
967 | ||
968 | In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder | |
969 | @email{alex@@gnu.org} took over development and created a ERC Project at | |
0b6bb130 | 970 | @uref{http://sourceforge.net/projects/erc}. |
597993cf | 971 | |
0b6bb130 MB |
972 | In reaction to a mail about the new ERC development effort, Sergey |
973 | Berezin said, ``First of all, I'm glad that my version of ERC is being | |
974 | used out there. The thing is, I do not have free time and enough | |
975 | incentive anymore to work on ERC, so I would be happy if you guys take | |
976 | over the project entirely.'' | |
597993cf | 977 | |
4dc5fe62 | 978 | So we happily hacked away on ERC, and soon after (September 2001) |
597993cf MB |
979 | released the next "stable" version, 2.1. |
980 | ||
4dc5fe62 | 981 | Most of the development of the new ERC happened on #emacs on |
0b6bb130 MB |
982 | irc.openprojects.net. Over time, many people contributed code, ideas, |
983 | bugfixes, and a lot of alpha/beta/gamma testing. | |
597993cf MB |
984 | |
985 | See the @file{CREDITS} file for a list of contributors. | |
986 | ||
987 | @item 2003 | |
988 | ||
0b6bb130 | 989 | ERC 3.0 was released. |
597993cf MB |
990 | |
991 | @item 2004 | |
992 | ||
0b6bb130 | 993 | ERC 4.0 was released. |
597993cf MB |
994 | |
995 | @item 2005 | |
996 | ||
0b6bb130 | 997 | ERC 5.0 was released. Michael Olson @email{mwolson@@gnu.org} became |
597993cf MB |
998 | the release manager and eventually the maintainer. |
999 | ||
0b6bb130 | 1000 | After some discussion between him and the Emacs developers, it was |
597993cf MB |
1001 | decided to include ERC in Emacs. |
1002 | ||
1003 | @item 2006 | |
1004 | ||
0b6bb130 MB |
1005 | ERC 5.1 was released. It was subsequently included in Emacs 22. |
1006 | ||
1007 | ERC became an official GNU project, and development moved to | |
1008 | @uref{http://sv.gnu.org/projects/erc}. We switched to using GNU Arch as | |
1009 | our revision control system. Our mailing list address changed as well. | |
597993cf MB |
1010 | |
1011 | @end itemize | |
1012 | ||
84247bb5 CY |
1013 | @node GNU Free Documentation License, Concept Index, History, Top |
1014 | @appendix GNU Free Documentation License | |
1015 | @include doclicense.texi | |
1016 | ||
1017 | @node Concept Index, , GNU Free Documentation License, Top | |
597993cf MB |
1018 | @comment node-name, next, previous, up |
1019 | @unnumbered Index | |
1020 | ||
1021 | @printindex cp | |
1022 | ||
1023 | @bye | |
1024 | ||
1025 | @ignore | |
1026 | arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e | |
1027 | @end ignore |