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.2.
  16
  17 Copyright @copyright{} 2005, 2006, 2007, 2008 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.  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.
  31
  32 All Emacs Lisp code contained in this document may be used, distributed,
  33 and modified without restriction.
  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.
  71 * GNU Free Documentation License:: The license for this documentation.
  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
  82 Getting Started
  83
  84 * Sample Session::              Example of connecting to the #emacs channel
  85 * Special Features::            Differences from standalone IRC clients
  86
  87 Advanced Usage
  88
  89 * Connecting::                  Ways of connecting to an IRC server.
  90 * Sample Configuration::        An example configuration file.
  91 * Options::                     Options that are available for ERC.
  92
  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
 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.
 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
 148 announced on the @email{erc-discuss@@gnu.org} mailing list.
 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
 158 @uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror.
 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
 168 @subheading GNU Arch
 169
 170 ERC is developed using GNU Arch.  Downloading ERC with Arch and staying
 171 up-to-date involves the following steps.
 172
 173 @enumerate
 174 @cindex GNU Arch, installing
 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
 182 @cindex GNU Arch, downloading ERC
 183 @item Register the archive.
 184 @example
 185 tla register-archive -f http://arch.sv.gnu.org/archives/erc/erc
 186 @end example
 187
 188 @item Download the ERC source code.
 189 @example
 190 # Download ERC into the @file{erc} directory.
 191 tla get erc@@sv.gnu.org/erc--main--0 erc
 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
 206 @cindex GNU Arch, updating ERC
 207 @item Update to the latest version by replaying missing changes.
 208 @example
 209 cd erc
 210 tla update
 211 @end example
 212
 213 @end enumerate
 214
 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.
 218
 219 @subheading Development snapshots
 220
 221 @cindex development snapshot
 222 Alternatively, the latest development snapshot may be downloaded in both
 223 ``.tar.gz'' and ``.zip'' forms.
 224
 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
 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
 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
 290 itself.  An example follows.
 291
 292 @lisp
 293 (require 'erc)
 294 @end lisp
 295
 296 Once ERC is loaded, the command @kbd{M-x erc} will start ERC and
 297 prompt for the server to connect to.
 298
 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
 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
 441 ERC  buffer and run the @code{/RECONNECT} command.
 442
 443 @end itemize
 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.
 504 After doing @kbd{C-c C-o}, type in a channel mode letter.
 505
 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.
 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
 548 Set away status automatically
 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
 562 @cindex modules, capab-identify
 563 @item capab-identify
 564 Mark unidentified users on freenode and other servers supporting CAPAB.
 565
 566 @cindex modules, completion
 567 @cindex modules, pcomplete
 568 @item completion (aka pcomplete)
 569 Complete nicknames and commands (programmable)
 570
 571 @cindex modules, fill
 572 @item fill
 573 Wrap long lines
 574
 575 @cindex modules, hecomplete
 576 @item hecomplete
 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
 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
 596 @cindex modules, menu
 597 @item menu
 598 Display a menu in ERC buffers
 599
 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
 612 @cindex modules, page
 613 @item page
 614 Process CTCP PAGE requests from IRC
 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
 644 @cindex modules, spelling
 645 @item spelling
 646 Check spelling of messages
 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
 666 @c PRE5_3: Document every option of every module in its own subnode
 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
 674 @menu
 675 * Connecting::                  Ways of connecting to an IRC server.
 676 * Sample Configuration::        An example configuration file.
 677 * Options::                     Options that are available for ERC.
 678 @end menu
 679
 680 @node Connecting, Sample Configuration, Advanced Usage, Advanced Usage
 681 @comment  node-name,  next,  previous,  up
 682 @section Connecting to an IRC Server
 683 @cindex connecting
 684
 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.
 688
 689 @defun erc
 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
 708 (erc :server "irc.freenode.net" :full-name "Harry S Truman")
 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
 792
 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
 814 @node Sample Configuration, Options, Connecting, Advanced Usage
 815 @comment  node-name,  next,  previous,  up
 816 @section Sample Configuration
 817 @cindex configuration, sample
 818
 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}.
 822
 823 @lisp
 824 ;;; Sample ERC configuration
 825
 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")
 829
 830 ;; Load ERC
 831 (require 'erc)
 832
 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
 893
 894 @node Options, , Sample Configuration, Advanced Usage
 895 @comment  node-name,  next,  previous,  up
 896 @section Options
 897 @cindex options
 898
 899 @c PRE5_3: (Node) Document every ERC option (module options go in
 900 @c previous chapter)
 901
 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}.
 905
 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
 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.
 930
 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
 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
 951 @node History, GNU Free Documentation License, Getting Help and Reporting Bugs, Top
 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
 959 December 1999.  Their last released version was ERC 2.0.
 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
 970 @uref{http://sourceforge.net/projects/erc}.
 971
 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.''
 977
 978 So we happily hacked away on ERC, and soon after (September 2001)
 979 released the next "stable" version, 2.1.
 980
 981 Most of the development of the new ERC happened on #emacs on
 982 irc.openprojects.net.  Over time, many people contributed code, ideas,
 983 bugfixes, and a lot of alpha/beta/gamma testing.
 984
 985 See the @file{CREDITS} file for a list of contributors.
 986
 987 @item 2003
 988
 989 ERC 3.0 was released.
 990
 991 @item 2004
 992
 993 ERC 4.0 was released.
 994
 995 @item 2005
 996
 997 ERC 5.0 was released.  Michael Olson @email{mwolson@@gnu.org} became
 998 the release manager and eventually the maintainer.
 999
1000 After some discussion between him and the Emacs developers, it was
1001 decided to include ERC in Emacs.
1002
1003 @item 2006
1004
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.
1010
1011 @end itemize
1012
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
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