summaryrefslogtreecommitdiff
path: root/man/erc.texi
blob: b1bea8141683cbd35fe414d47fa9770d1d1a9f0a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
\input texinfo
@c %**start of header
@setfilename ../info/erc
@settitle ERC Manual
@c %**end of header

@dircategory Emacs
@direntry
* ERC: (erc).           Powerful, modular, and extensible IRC client for Emacs.
@end direntry

@syncodeindex fn cp

@copying
This manual is for ERC version 5.1.2.

Copyright @copyright{} 2005, 2006 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, Front-Cover texts, or Back-Cover Texts.
@end quotation
@end copying

@titlepage
@title ERC manual
@subtitle a full-featured IRC client
@subtitle for GNU Emacs and XEmacs

@c The following two commands
@c start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c So the toc is printed at the start
@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top ERC

@insertcopying
@end ifnottex

@menu
* Introduction::                What is ERC?
* Obtaining ERC::               How to get ERC releases and development
                                  versions.
* Installation::                Compiling and installing ERC.
* Getting Started::             Quick Start guide to using ERC.
* Keystroke Summary::           Keystrokes used in ERC buffers.
* Modules::                     Available modules for ERC.
* Advanced Usage::              Cool ways of using ERC.
* Getting Help and Reporting Bugs::  
* History::                     The history of ERC.
* Concept Index::               Search for terms.

@detailmenu
 --- The Detailed Node Listing ---

Obtaining ERC

* Releases::                    Released versions of ERC.
* Development::                 Latest unreleased development changes.

@end detailmenu
@end menu

@node Introduction, Obtaining ERC, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

ERC is a powerful, modular, and extensible IRC client for Emacs.

It comes with the following capabilities enabled by default.

@itemize @bullet
@item Flood control
@item Timestamps
@item Join channels automatically
@item Buttonize URLs, nicknames, and other text
@item Wrap long lines
@item Highlight or remove IRC control characters
@item Highlight pals, fools, and other keywords
@item Detect netsplits
@item Complete nicknames and commands in a programmable fashion
@item Make displayed lines read-only
@item Input history
@item Track channel activity in the mode-line

@end itemize

@node Obtaining ERC, Installation, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Obtaining ERC

@menu
* Releases::                    Released versions of ERC.
* Development::                 Latest unreleased development changes.
@end menu

These sections may be skipped if you are using the version of ERC that
comes with Emacs.

@node Releases, Development, Obtaining ERC, Obtaining ERC
@comment  node-name,  next,  previous,  up
@section Releases

Choose to install a release if you want to minimize risk.

Errors are corrected in development first.  User-visible changes will be
announced on the @email{erc-help@@lists.sourceforge.net} mailing list.
@pxref{Getting Help and Reporting Bugs}.

@cindex releases, Debian package
@cindex Debian package for ERC
Debian users can get ERC via apt-get.  The @file{erc} package is
available in the official Debian repository.

@cindex releases, from source
Alternatively, you can download the latest release from
@uref{http://sourceforge.net/project/showfiles.php?group_id=30118}.

@node Development,  , Releases, Obtaining ERC
@comment  node-name,  next,  previous,  up
@section Development
@cindex development

Choose the development version if you want to live on the bleeding edge
of ERC development or try out new features before release.

@subsection Using CVS
@cindex CVS, using

ERC is primarily developed using a CVS repository on sourceforge.net.
To check out a copy of the latest changes, do the following.

@example
cvs -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/erc login
cvs -z3 -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/erc co -P erc
@end example

@cindex CVS snapshot
Alternatively, the latest CVS snapshot may be downloaded in the
following forms.

@itemize @bullet
@item http://mwolson.org/static/dist/erc-latest.tar.gz
@item http://mwolson.org/static/dist/erc-latest.zip
@end itemize

@subsection Using the GNU Arch Revision Control System
@cindex arch revision control system, using
The Arch revision control system allows you to retrieve previous
versions and select specific features and bug fixes.

Michael Olson maintains an official Arch branch for ERC which stays
current with the CVS repository for ERC.  If you would like to
contribute to ERC development, and would prefer to use a modern Revision
Control System, feel free to make your own branch.

If you are new to Arch, you might find this tutorial helpful:
@uref{http://www.mwolson.org/projects/ArchTutorial.html}.

Downloading ERC with Arch and staying up-to-date involves the following
steps.

@enumerate
@item Install arch

@itemize @bullet
@item Debian: @kbd{apt-get install tla}.
@item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}.
@end itemize

@item Register the archive.
@example
tla register-archive -f http://www.mwolson.org/archives/2006
@end example

@item Download the ERC source code.
@example
# Download ERC into the @file{erc} directory.
tla get mwolson@@gnu.org--2006/erc--cvs--0 erc
@end example

@item List upstream changes that are missing from your local copy.
Do this whenever you want to see whether new changes have been committed
to ERC.

@example
# Change to the source directory you are interested in.
cd erc/

# Display the summary of changes
tla missing --summary
@end example

@cindex updating ERC with Arch
@item Update to the latest version by replaying missing changes.
@example
cd erc
tla replay
@end example

@end enumerate

There are other ways to interact with the ERC archive.

@itemize
@item Browse arch repository: @uref{http://www.mwolson.org/archives/}
@item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/erc-latest.tar.gz}
@end itemize

The latest development snapshot will be kept up-to-date since it is
updated at the same time as the Arch repository.


@node Installation, Getting Started, Obtaining ERC, Top
@comment  node-name,  next,  previous,  up
@chapter Installation

ERC may be compiled and installed on your machine.

This section may be skipped if you are using the version of ERC that
comes with Emacs.

@subsubheading Compilation

This is an optional step, since Emacs Lisp source code does not
necessarily have to be byte-compiled.  It will yield a speed increase,
though.

A working copy of Emacs or XEmacs is needed in order to compile ERC.  By
default, the program that is installed with the name @command{emacs}
will be used.

If you want to use the @command{xemacs} binary to perform the
compilation, you would need to edit @file{Makefile} in the top-level
directory as follows.  You can put either a full path to an Emacs or
XEmacs binary or just the command name, as long as it is in the
@env{PATH}.

@example
EMACS    = xemacs
SITEFLAG = -no-site-file
@end example

Running @code{make} should compile the ERC source files in the
@file{lisp} directory.

@subsubheading Installation

ERC may be installed into your file hierarchy by doing the following.

Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you
want the source and compiled ERC files to be installed and
@env{INFODIR} indicates where to put the ERC manual.  Of course, you
will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
Compilation section if you are using XEmacs.

If you are installing ERC on a Debian system, you might want to change
the value of @env{INSTALLINFO} as specified in @file{Makefile}.

Run @code{make} as a normal user.

Run @code{make install} as the root user if you have chosen installation
locations that require this.


@node Getting Started, Keystroke Summary, Installation, Top
@comment  node-name,  next,  previous,  up
@chapter Getting Started
@cindex settings

@c PRE5_2: Mention .ercrc.el

To use ERC, add the directory containing its files to your
@code{load-path} variable, in your @file{.emacs} file.  Then, load ERC
itself along with any extra modules you desire.  An example follows.

@lisp
(require 'erc)

(require 'erc-spelling)
@end lisp

Once this is loaded, the command @kbd{M-x erc-select} will start ERC and
prompt for the server to connect to.

@c PRE5_2: Sample session, including:
@c - connect to Freenode
@c - /join #emacs
@c - see messages flying past, point out topic lines, messages, channel
@c   members
@c - identifying your nick with NickServ (most IRC servers have this)
@c - talking to the channel
@c - open a /query buffer to talk to someone (must identify first in
@c   FreeNode)


@node Keystroke Summary, Modules, Getting Started, Top
@comment  node-name,  next,  previous,  up
@chapter Keys Used in ERC
@cindex keystrokes

This is a summary of keystrokes available in every ERC buffer.

@table @kbd

@item C-a or <home> (`erc-bol')
Go to beginning of line or end of prompt.

@item RET (`erc-send-current-line')
Send the current line

@item TAB (`erc-complete-word')
If at prompt, complete the current word.
Otherwise, move to the next link or button.

@item M-TAB (`ispell-complete-word')
Complete the given word, using ispell.

@item C-c C-a (`erc-bol')
Go to beginning of line or end of prompt.

@item C-c C-b (`erc-iswitchb')
Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to.

@item C-c C-c (`erc-toggle-interpret-controls')
Toggle interpretation of control sequences in messages.

@item C-c C-d (`erc-input-action')
Interactively input a user action and send it to IRC.

@item C-c C-e (`erc-toggle-ctcp-autoresponse')
Toggle automatic CTCP replies (like VERSION and PING).

@item C-c C-f (`erc-toggle-flood-control')
Toggle use of flood control on sent messages.

@item C-c TAB (`erc-invite-only-mode')
Turn on the invite only mode (+i) for the current channel.

@item C-c C-j (`erc-join-channel')
Join channel.  If point is at the beginning of a channel name, use that
as default.

@item C-c C-k (`erc-go-to-log-matches-buffer')
Interactively open an erc-log-matches buffer

@item C-c C-l (`erc-save-buffer-in-logs')
Append buffer contents to the log file, if logging is enabled.

@item C-c C-n (`erc-channel-names')
Run "/names #channel" in the current channel.

@item C-c C-o (`erc-get-channel-mode-from-keypress')
Read a key sequence and call the corresponding channel mode function.
After doing C-c C-o type in a channel mode letter.

C-g means quit.
RET let's you type more than one mode at a time.
If "l" is pressed, `erc-set-channel-limit' gets called.
If "k" is pressed, `erc-set-channel-key' gets called.
Anything else will be sent to `erc-toggle-channel-mode'.

@item C-c C-p (`erc-part-from-channel')
Part from the current channel and prompt for a reason.

@item C-c C-q (`erc-quit-server')
Disconnect from current server after prompting for reason.

@item C-c C-r (`erc-remove-text-properties-region')
Clears the region (start,end) in object from all colors, etc.

@item C-c C-t (`erc-set-topic')
Prompt for a topic for the current channel.

@item C-c C-u (`erc-kill-input')
Kill current input line using `erc-bol' followed by `kill-line'.

@end table


@node Modules, Advanced Usage, Keystroke Summary, Top
@comment  node-name,  next,  previous,  up
@chapter Modules
@cindex modules

One way to add functionality to ERC is to customize which of its many
modules are loaded.

There is a spiffy customize interface, which may be reached by typing
@kbd{M-x customize-option erc-modules RET}.  Alternatively, set
@code{erc-modules} manually and then call @code{erc-update-modules}.

The following is a list of available modules.

@table @code

@cindex modules, autoaway
@item autoaway
Set away status automatically.

@cindex modules, autojoin
@item autojoin
Join channels automatically

@cindex modules, bbdb
@item bbdb
Integrate with the Big Brother Database

@cindex modules, button
@item button
Buttonize URLs, nicknames, and other text

@cindex modules, fill
@item fill
Wrap long lines

@cindex modules, irccontrols
@item irccontrols
Highlight or remove IRC control characters

@cindex modules, log
@item log
Save buffers in logs

@cindex modules, match
@item match
Highlight pals, fools, and other keywords

@cindex modules, netsplit
@item netsplit
Detect netsplits

@cindex modules, noncommands
@item noncommands
Don't display non-IRC commands after evaluation

@cindex modules, notify
@item notify
Notify when the online status of certain users changes

@cindex modules, pcomplete
@item pcomplete
Complete nicknames and commands (programmable)

@cindex modules, readonly
@item readonly
Make displayed lines read-only

@cindex modules, replace
@item replace
Replace text in messages

@cindex modules, ring
@item ring
Enable an input history

@cindex modules, scrolltobottom
@item scrolltobottom
Scroll to the bottom of the buffer

@cindex modules, services
@item services
Identify to Nickserv (IRC Services) automatically

@cindex modules, smiley
@item smiley
Convert smileys to pretty icons

@cindex modules, sound
@item sound
Play sounds when you receive CTCP SOUND requests

@cindex modules, spell
@item spell
Check spelling

@cindex modules, stamp
@item stamp
Add timestamps to messages

@cindex modules, track
@item track
Track channel activity in the mode-line

@cindex modules, truncate
@item truncate
Truncate buffers to a certain size

@cindex modules, unmorse
@item unmorse
Translate morse code in messages

@end table

@c PRE5_2: Document every option of every module in its own subnode


@node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
@comment  node-name,  next,  previous,  up
@chapter Advanced Usage
@cindex advanced topics

Write me.

@c PRE5_2: (Node) Document every ERC option

@c PRE5_2: (Node) Tips and tricks

@c PRE5_2: (Node) Sample configs


@node Getting Help and Reporting Bugs, History, Advanced Usage, Top
@comment  node-name,  next,  previous,  up
@chapter Getting Help and Reporting Bugs
@cindex help, getting
@cindex bugs, reporting

After you have read this guide, if you still have questions about ERC,
or if you have bugs to report, there are several places you can go.

@itemize @bullet

@item
@uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsIRCClient} is the
emacswiki.org page for ERC.  Anyone may add tips, hints, or bug
descriptions to it.

@item
You can join the mailing list at @email{erc-help@@lists.sourceforge.net}
using the subscription form at
@uref{http://lists.sourceforge.net/lists/listinfo/erc-help}.

This mailing list is also available via Gmane
(@url{http://gmane.org/}). The group is called
@samp{gmane.emacs.erc.general}.  This provides additional methods for
accessing the mailing list, adding content to it, and searching it.

@item
You can visit the IRC Freenode channel @samp{#emacs}. Many of the
contributors are frequently around and willing to answer your
questions.

@end itemize


@node History, Concept Index, Getting Help and Reporting Bugs, Top
@comment  node-name,  next,  previous,  up
@chapter History
@cindex history, of ERC

ERC was originally written by Alexander L. Belikoff
@email{abel@@bfr.co.il} and Sergey Berezin
@email{sergey.berezin@@cs.cmu.edu}.  They stopped development around
december 1999. Their last released version was ERC 2.0.

P.S.: If one of the original developers of ERC reads this, we'd like to
receive additional information for this file and hear comments in
general.

@itemize
@item 2001

In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder
@email{alex@@gnu.org} took over development and created a ERC Project at
sourceforge.net.

In reaction to a mail about the new erc development, Sergey Berezin
said, "First of all, I'm glad that my version of ERC is being used out
there. The thing is, I do not have free time and enough incentive
anymore to work on ERC, so I would be happy if you guys take over the
project entirely."

So we happily hacked away on ERC, and soon after (september 2001)
released the next "stable" version, 2.1.

Most of the development of the new ERC happend on #emacs on
irc.openprojects.net. Over time, many people contributed code, ideas,
bugfixes. And not to forget alot of alpha/beta/gamma testing.

See the @file{CREDITS} file for a list of contributors.

@item 2003

ERC 3.0 is released.

@item 2004

ERC 4.0 is released.

@item 2005

ERC 5.0 is released.  Michael Olson @email{mwolson@@gnu.org} becomes
the release manager and eventually the maintainer.

After some discussion between him and the Emacs developers, it is
decided to include ERC in Emacs.

@item 2006

ERC 5.1 is released.  It is subsequently included in Emacs 22.

@end itemize

@node Concept Index,  , History, Top
@comment  node-name,  next,  previous,  up
@unnumbered Index

@printindex cp

@bye

@ignore
   arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e
@end ignore