man/erc.texi

   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
   9 * ERC: (erc).  Powerful, modular, and extensible IRC client for Emacs.
  10 @end direntry
  11
  12 @syncodeindex fn cp
  13
  14 @copying
  15 This manual is for ERC version 5.1.
  16
  17 Copyright @copyright{} 2005, 2006 Free Software Foundation, Inc.
  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
  23 Invariant Sections, Front-Cover texts, or Back-Cover Texts.
  24 @end quotation
  25 @end copying
  26
  27 @titlepage
  28 @title ERC manual
  29 @subtitle a full-featured IRC client
  30 @subtitle for GNU Emacs and XEmacs
  31
  32 @c The following two commands
  33 @c start the copyright page.
  34 @page
  35 @vskip 0pt plus 1filll
  36 @insertcopying
  37 @end titlepage
  38
  39 @c So the toc is printed at the start
  40 @contents
  41
  42 @ifnottex
  43 @node Top, Introduction, (dir), (dir)
  44 @comment  node-name,  next,  previous,  up
  45 @top ERC
  46
  47 @insertcopying
  48 @end ifnottex
  49
  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.
  62
  63 @detailmenu
  64  --- The Detailed Node Listing ---
  65
  66 Obtaining ERC
  67
  68 * Releases::                    Released versions of ERC.
  69 * Development::                 Latest unreleased development changes.
  70
  71 @end detailmenu
  72 @end menu
  73
  74 @node Introduction, Obtaining ERC, Top, Top
  75 @comment  node-name,  next,  previous,  up
  76 @chapter Introduction
  77
  78 ERC is a powerful, modular, and extensible IRC client for Emacs.
  79
  80 It comes with the following capabilities enabled by default.
  81
  82 @itemize @bullet
  83 @item Flood control
  84 @item Timestamps
  85 @item Join channels automatically
  86 @item Buttonize URLs, nicknames, and other text
  87 @item Wrap long lines
  88 @item Highlight or remove IRC control characters
  89 @item Highlight pals, fools, and other keywords
  90 @item Detect netsplits
  91 @item Complete nicknames and commands in a programmable fashion
  92 @item Make displayed lines read-only
  93 @item Input history
  94 @item Track channel activity in the mode-line
  95
  96 @end itemize
  97
  98 @node Obtaining ERC, Installation, Introduction, Top
  99 @comment  node-name,  next,  previous,  up
 100 @chapter Obtaining ERC
 101
 102 @menu
 103 * Releases::                    Released versions of ERC.
 104 * Development::                 Latest unreleased development changes.
 105 @end menu
 106
 107 These sections may be skipped if you are using the version of ERC that
 108 comes with Emacs.
 109
 110 @node Releases, Development, Obtaining ERC, Obtaining ERC
 111 @comment  node-name,  next,  previous,  up
 112 @section Releases
 113
 114 Choose to install a release if you want to minimize risk.
 115
 116 Errors are corrected in development first.  User-visible changes will be
 117 announced on the @email{erc-help@@lists.sourceforge.net} mailing list.
 118 @pxref{Getting Help and Reporting Bugs}.
 119
 120 @cindex releases, Debian package
 121 @cindex Debian package for ERC
 122 Debian users can get ERC via apt-get.  The @file{erc} package is
 123 available in the official Debian repository.
 124
 125 @cindex releases, from source
 126 Alternatively, you can download the latest release from
 127 @uref{http://sourceforge.net/project/showfiles.php?group_id=30118}.
 128
 129 @node Development,  , Releases, Obtaining ERC
 130 @comment  node-name,  next,  previous,  up
 131 @section Development
 132 @cindex development
 133
 134 Choose the development version if you want to live on the bleeding edge
 135 of ERC development or try out new features before release.
 136
 137 @subsection Using CVS
 138 @cindex CVS, using
 139
 140 ERC is primarily developed using a CVS repository on sourceforge.net.
 141 To check out a copy of the latest changes, do the following.
 142
 143 @example
 144 cvs -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/erc login
 145 cvs -z3 -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/erc co -P erc
 146 @end example
 147
 148 @cindex CVS snapshot
 149 Alternatively, the latest CVS snapshot may be downloaded in the
 150 following forms.
 151
 152 @itemize @bullet
 153 @item http://mwolson.org/static/dist/erc-latest.tar.gz
 154 @item http://mwolson.org/static/dist/erc-latest.zip
 155 @end itemize
 156
 157 @subsection Using the GNU Arch Revision Control System
 158 @cindex arch revision control system, using
 159 The Arch revision control system allows you to retrieve previous
 160 versions and select specific features and bug fixes.
 161
 162 Michael Olson maintains an official Arch branch for ERC which stays
 163 current with the CVS repository for ERC.  If you would like to
 164 contribute to ERC development, and would prefer to use a modern Revision
 165 Control System, feel free to make your own branch.
 166
 167 If you are new to Arch, you might find this tutorial helpful:
 168 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
 169
 170 Downloading ERC with Arch and staying up-to-date involves the following
 171 steps.
 172
 173 @enumerate
 174 @item Install arch
 175
 176 @itemize @bullet
 177 @item Debian: @kbd{apt-get install tla}.
 178 @item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}.
 179 @end itemize
 180
 181 @item Register the archive.
 182 @example
 183 tla register-archive -f http://www.mwolson.org/archives/2006
 184 @end example
 185
 186 @item Download the ERC source code.
 187 @example
 188 # Download ERC into the @file{erc} directory.
 189 tla get mwolson@@gnu.org--2006/erc--cvs--0 erc
 190 @end example
 191
 192 @item List upstream changes that are missing from your local copy.
 193 Do this whenever you want to see whether new changes have been committed
 194 to ERC.
 195
 196 @example
 197 # Change to the source directory you are interested in.
 198 cd erc/
 199
 200 # Display the summary of changes
 201 tla missing --summary
 202 @end example
 203
 204 @cindex updating ERC with Arch
 205 @item Update to the latest version by replaying missing changes.
 206 @example
 207 cd erc
 208 tla replay
 209 @end example
 210
 211 @end enumerate
 212
 213 There are other ways to interact with the ERC archive.
 214
 215 @itemize
 216 @item Browse arch repository: @uref{http://www.mwolson.org/archives/}
 217 @item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/erc-latest.tar.gz}
 218 @end itemize
 219
 220 The latest development snapshot will be kept up-to-date since it is
 221 updated at the same time as the Arch repository.
 222
 223
 224 @node Installation, Getting Started, Obtaining ERC, Top
 225 @comment  node-name,  next,  previous,  up
 226 @chapter Installation
 227
 228 ERC may be compiled and installed on your machine.
 229
 230 This section may be skipped if you are using the version of ERC that
 231 comes with Emacs.
 232
 233 @subsubheading Compilation
 234
 235 This is an optional step, since Emacs Lisp source code does not
 236 necessarily have to be byte-compiled.  It will yield a speed increase,
 237 though.
 238
 239 A working copy of Emacs or XEmacs is needed in order to compile ERC.  By
 240 default, the program that is installed with the name @command{emacs}
 241 will be used.
 242
 243 If you want to use the @command{xemacs} binary to perform the
 244 compilation, you would need to edit @file{Makefile} in the top-level
 245 directory as follows.  You can put either a full path to an Emacs or
 246 XEmacs binary or just the command name, as long as it is in the
 247 @env{PATH}.
 248
 249 @example
 250 EMACS    = xemacs
 251 SITEFLAG = -no-site-file
 252 @end example
 253
 254 Running @code{make} should compile the ERC source files in the
 255 @file{lisp} directory.
 256
 257 @subsubheading Installation
 258
 259 ERC may be installed into your file hierarchy by doing the following.
 260
 261 Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you
 262 want the source and compiled ERC files to be installed and
 263 @env{INFODIR} indicates where to put the ERC manual.  Of course, you
 264 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
 265 Compilation section if you are using XEmacs.
 266
 267 If you are installing ERC on a Debian system, you might want to change
 268 the value of @env{INSTALLINFO} as specified in @file{Makefile}.
 269
 270 Run @code{make} as a normal user.
 271
 272 Run @code{make install} as the root user if you have chosen installation
 273 locations that require this.
 274
 275
 276 @node Getting Started, Keystroke Summary, Installation, Top
 277 @comment  node-name,  next,  previous,  up
 278 @chapter Getting Started
 279 @cindex settings
 280
 281 @c PRE5_2: Mention .ercrc.el
 282
 283 To use ERC, add the directory containing its files to your
 284 @code{load-path} variable, in your @file{.emacs} file.  Then, load ERC
 285 itself along with any extra modules you desire.  An example follows.
 286
 287 @lisp
 288 (require 'erc)
 289
 290 (require 'erc-spelling)
 291 @end lisp
 292
 293 Once this is loaded, the command @kbd{M-x erc-select} will start ERC and
 294 prompt for the server to connect to.
 295
 296 @c PRE5_2: Sample session, including:
 297 @c - connect to Freenode
 298 @c - /join #emacs
 299 @c - see messages flying past, point out topic lines, messages, channel
 300 @c   members
 301 @c - identifying your nick with NickServ (most IRC servers have this)
 302 @c - talking to the channel
 303 @c - open a /query buffer to talk to someone (must identify first in
 304 @c   FreeNode)
 305
 306
 307 @node Keystroke Summary, Modules, Getting Started, Top
 308 @comment  node-name,  next,  previous,  up
 309 @chapter Keys Used in ERC
 310 @cindex keystrokes
 311
 312 This is a summary of keystrokes available in every ERC buffer.
 313
 314 @table @kbd
 315
 316 @item C-a or <home> (`erc-bol')
 317 Go to beginning of line or end of prompt.
 318
 319 @item RET (`erc-send-current-line')
 320 Send the current line
 321
 322 @item TAB (`erc-complete-word')
 323 If at prompt, complete the current word.
 324 Otherwise, move to the next link or button.
 325
 326 @item M-TAB (`ispell-complete-word')
 327 Complete the given word, using ispell.
 328
 329 @item C-c C-a (`erc-bol')
 330 Go to beginning of line or end of prompt.
 331
 332 @item C-c C-b (`erc-iswitchb')
 333 Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to.
 334
 335 @item C-c C-c (`erc-toggle-interpret-controls')
 336 Toggle interpretation of control sequences in messages.
 337
 338 @item C-c C-d (`erc-input-action')
 339 Interactively input a user action and send it to IRC.
 340
 341 @item C-c C-e (`erc-toggle-ctcp-autoresponse')
 342 Toggle automatic CTCP replies (like VERSION and PING).
 343
 344 @item C-c C-f (`erc-toggle-flood-control')
 345 Toggle use of flood control on sent messages.
 346
 347 @item C-c TAB (`erc-invite-only-mode')
 348 Turn on the invite only mode (+i) for the current channel.
 349
 350 @item C-c C-j (`erc-join-channel')
 351 Join channel.  If point is at the beginning of a channel name, use that
 352 as default.
 353
 354 @item C-c C-k (`erc-go-to-log-matches-buffer')
 355 Interactively open an erc-log-matches buffer
 356
 357 @item C-c C-l (`erc-save-buffer-in-logs')
 358 Append buffer contents to the log file, if logging is enabled.
 359
 360 @item C-c C-n (`erc-channel-names')
 361 Run "/names #channel" in the current channel.
 362
 363 @item C-c C-o (`erc-get-channel-mode-from-keypress')
 364 Read a key sequence and call the corresponding channel mode function.
 365 After doing C-c C-o type in a channel mode letter.
 366
 367 C-g means quit.
 368 RET let's you type more than one mode at a time.
 369 If "l" is pressed, `erc-set-channel-limit' gets called.
 370 If "k" is pressed, `erc-set-channel-key' gets called.
 371 Anything else will be sent to `erc-toggle-channel-mode'.
 372
 373 @item C-c C-p (`erc-part-from-channel')
 374 Part from the current channel and prompt for a reason.
 375
 376 @item C-c C-q (`erc-quit-server')
 377 Disconnect from current server after prompting for reason.
 378
 379 @item C-c C-r (`erc-remove-text-properties-region')
 380 Clears the region (start,end) in object from all colors, etc.
 381
 382 @item C-c C-t (`erc-set-topic')
 383 Prompt for a topic for the current channel.
 384
 385 @item C-c C-u (`erc-kill-input')
 386 Kill current input line using `erc-bol' followed by `kill-line'.
 387
 388 @end table
 389
 390
 391 @node Modules, Advanced Usage, Keystroke Summary, Top
 392 @comment  node-name,  next,  previous,  up
 393 @chapter Modules
 394 @cindex modules
 395
 396 One way to add functionality to ERC is to customize which of its many
 397 modules are loaded.
 398
 399 There is a spiffy customize interface, which may be reached by typing
 400 @kbd{M-x customize-option erc-modules RET}.  Alternatively, set
 401 @code{erc-modules} manually and then call @code{erc-update-modules}.
 402
 403 The following is a list of available modules.
 404
 405 @table @code
 406
 407 @cindex modules, autoaway
 408 @item autoaway
 409 Set away status automatically.
 410
 411 @cindex modules, autojoin
 412 @item autojoin
 413 Join channels automatically
 414
 415 @cindex modules, bbdb
 416 @item bbdb
 417 Integrate with the Big Brother Database
 418
 419 @cindex modules, button
 420 @item button
 421 Buttonize URLs, nicknames, and other text
 422
 423 @cindex modules, fill
 424 @item fill
 425 Wrap long lines
 426
 427 @cindex modules, irccontrols
 428 @item irccontrols
 429 Highlight or remove IRC control characters
 430
 431 @cindex modules, log
 432 @item log
 433 Save buffers in logs
 434
 435 @cindex modules, match
 436 @item match
 437 Highlight pals, fools, and other keywords
 438
 439 @cindex modules, netsplit
 440 @item netsplit
 441 Detect netsplits
 442
 443 @cindex modules, noncommands
 444 @item noncommands
 445 Don't display non-IRC commands after evaluation
 446
 447 @cindex modules, notify
 448 @item notify
 449 Notify when the online status of certain users changes
 450
 451 @cindex modules, pcomplete
 452 @item pcomplete
 453 Complete nicknames and commands (programmable)
 454
 455 @cindex modules, readonly
 456 @item readonly
 457 Make displayed lines read-only
 458
 459 @cindex modules, replace
 460 @item replace
 461 Replace text in messages
 462
 463 @cindex modules, ring
 464 @item ring
 465 Enable an input history
 466
 467 @cindex modules, scrolltobottom
 468 @item scrolltobottom
 469 Scroll to the bottom of the buffer
 470
 471 @cindex modules, services
 472 @item services
 473 Identify to Nickserv (IRC Services) automatically
 474
 475 @cindex modules, smiley
 476 @item smiley
 477 Convert smileys to pretty icons
 478
 479 @cindex modules, sound
 480 @item sound
 481 Play sounds when you receive CTCP SOUND requests
 482
 483 @cindex modules, spell
 484 @item spell
 485 Check spelling
 486
 487 @cindex modules, stamp
 488 @item stamp
 489 Add timestamps to messages
 490
 491 @cindex modules, track
 492 @item track
 493 Track channel activity in the mode-line
 494
 495 @cindex modules, truncate
 496 @item truncate
 497 Truncate buffers to a certain size
 498
 499 @cindex modules, unmorse
 500 @item unmorse
 501 Translate morse code in messages
 502
 503 @end table
 504
 505 @c PRE5_2: Document every option of every module in its own subnode
 506
 507
 508 @node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
 509 @comment  node-name,  next,  previous,  up
 510 @chapter Advanced Usage
 511 @cindex advanced topics
 512
 513 Write me.
 514
 515 @c PRE5_2: (Node) Document every ERC option
 516
 517 @c PRE5_2: (Node) Tips and tricks
 518
 519 @c PRE5_2: (Node) Sample configs
 520
 521
 522 @node Getting Help and Reporting Bugs, History, Advanced Usage, Top
 523 @comment  node-name,  next,  previous,  up
 524 @chapter Getting Help and Reporting Bugs
 525 @cindex help, getting
 526 @cindex bugs, reporting
 527
 528 After you have read this guide, if you still have questions about ERC,
 529 or if you have bugs to report, there are several places you can go.
 530
 531 @itemize @bullet
 532
 533 @item
 534 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsIRCClient} is the
 535 emacswiki.org page for ERC.  Anyone may add tips, hints, or bug
 536 descriptions to it.
 537
 538 @item
 539 You can join the mailing list at @email{erc-help@@lists.sourceforge.net}
 540 using the subscription form at
 541 @uref{http://lists.sourceforge.net/lists/listinfo/erc-help}.
 542
 543 This mailing list is also available via Gmane
 544 (@url{http://gmane.org/}). The group is called
 545 @samp{gmane.emacs.erc.general}.  This provides additional methods for
 546 accessing the mailing list, adding content to it, and searching it.
 547
 548 @item
 549 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
 550 contributors are frequently around and willing to answer your
 551 questions.
 552
 553 @end itemize
 554
 555
 556 @node History, Concept Index, Getting Help and Reporting Bugs, Top
 557 @comment  node-name,  next,  previous,  up
 558 @chapter History
 559 @cindex history, of ERC
 560
 561 ERC was originally written by Alexander L. Belikoff
 562 @email{abel@@bfr.co.il} and Sergey Berezin
 563 @email{sergey.berezin@@cs.cmu.edu}.  They stopped development around
 564 december 1999. Their last released version was ERC 2.0.
 565
 566 P.S.: If one of the original developers of ERC reads this, we'd like to
 567 receive additional information for this file and hear comments in
 568 general.
 569
 570 @itemize
 571 @item 2001
 572
 573 In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder
 574 @email{alex@@gnu.org} took over development and created a ERC Project at
 575 sourceforge.net.
 576
 577 In reaction to a mail about the new erc development, Sergey Berezin
 578 said, "First of all, I'm glad that my version of ERC is being used out
 579 there. The thing is, I do not have free time and enough incentive
 580 anymore to work on ERC, so I would be happy if you guys take over the
 581 project entirely."
 582
 583 So we happily hacked away on ERC, and soon after (september 2001)
 584 released the next "stable" version, 2.1.
 585
 586 Most of the development of the new ERC happend on #emacs on
 587 irc.openprojects.net. Over time, many people contributed code, ideas,
 588 bugfixes. And not to forget alot of alpha/beta/gamma testing.
 589
 590 See the @file{CREDITS} file for a list of contributors.
 591
 592 @item 2003
 593
 594 ERC 3.0 is released.
 595
 596 @item 2004
 597
 598 ERC 4.0 is released.
 599
 600 @item 2005
 601
 602 ERC 5.0 is released.  Michael Olson @email{mwolson@@gnu.org} becomes
 603 the release manager and eventually the maintainer.
 604
 605 After some discussion between him and the Emacs developers, it is
 606 decided to include ERC in Emacs.
 607
 608 @item 2006
 609
 610 ERC 5.1 is released.
 611
 612 @end itemize
 613
 614 @node Concept Index,  , History, Top
 615 @comment  node-name,  next,  previous,  up
 616 @unnumbered Index
 617
 618 @printindex cp
 619
 620 @bye
 621
 622 @ignore
 623    arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e
 624 @end ignore