ERC
***

This manual is for ERC version 5.1.

Copyright © 2005, 2006 Free Software Foundation, Inc.

     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.

Introduction
************

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

It comes with the following capabilities enabled by default.

  * Flood control

  * Timestamps

  * Join channels automatically

  * Buttonize URLs, nicknames, and other text

  * Wrap long lines

  * Highlight or remove IRC control characters

  * Highlight pals, fools, and other keywords

  * Detect netsplits

  * Complete nicknames and commands in a programmable fashion

  * Make displayed lines read-only

  * Input history

  * Track channel activity in the mode-line

Obtaining ERC
*************

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

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 erc-help@lists.sourceforge.net mailing list. see Getting Help and Reporting Bugs.

Debian users can get ERC via apt-get.  The erc package is available in the official Debian repository.

Alternatively, you can download the latest release from http://sourceforge.net/project/showfiles.php?group_id=30118.

Development
===========

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

Using CVS
---------

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

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

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

  * http://mwolson.org/static/dist/erc-latest.tar.gz

  * http://mwolson.org/static/dist/erc-latest.zip

Using the GNU Arch Revision Control System
------------------------------------------

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: http://www.mwolson.org/projects/ArchTutorial.html.

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

 1. Install arch

       * Debian: apt-get install tla.

       * Other distributions: see ftp://ftp.gnu.org/gnu/gnu-arch/.

 2. Register the archive.

          tla register-archive -f http://www.mwolson.org/archives/2006

 3. Download the ERC source code.

          # Download ERC into the erc directory.
          tla get mwolson@gnu.org--2006/erc--cvs--0 erc

 4. 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.

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

          # Display the summary of changes
          tla missing --summary

 5. Update to the latest version by replaying missing changes.

          cd erc
          tla replay

There are other ways to interact with the ERC archive.

  * Browse arch repository: http://www.mwolson.org/archives/

  * Latest development snapshot: http://www.mwolson.org/static/dist/erc-latest.tar.gz

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

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.

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 emacs will be used.

If you want to use the xemacs binary to perform the compilation, you would need to edit 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 PATH.

     EMACS    = xemacs
     SITEFLAG = -no-site-file

Running make should compile the ERC source files in the lisp directory.

Installation
............

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

Edit the Makefile file so that ELISPDIR points to where you want the source and compiled ERC files to be installed and INFODIR indicates where to put the ERC manual.  Of course, you will want to edit EMACS and 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 INSTALLINFO as specified in Makefile.

Run make as a normal user.

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

Getting Started
***************

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

     (require 'erc)

     (require 'erc-spelling)

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

Keys Used in ERC
****************

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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'.

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

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

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

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

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

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 M-x customize-option erc-modules RET.  Alternatively, set erc-modules manually and then call erc-update-modules.

The following is a list of available modules.

autoaway
     Set away status automatically.

autojoin
     Join channels automatically

bbdb
     Integrate with the Big Brother Database

button
     Buttonize URLs, nicknames, and other text

fill
     Wrap long lines

irccontrols
     Highlight or remove IRC control characters

log
     Save buffers in logs

match
     Highlight pals, fools, and other keywords

netsplit
     Detect netsplits

noncommands
     Don't display non-IRC commands after evaluation

notify
     Notify when the online status of certain users changes

pcomplete
     Complete nicknames and commands (programmable)

readonly
     Make displayed lines read-only

replace
     Replace text in messages

ring
     Enable an input history

scrolltobottom
     Scroll to the bottom of the buffer

services
     Identify to Nickserv (IRC Services) automatically

smiley
     Convert smileys to pretty icons

sound
     Play sounds when you receive CTCP SOUND requests

spell
     Check spelling

stamp
     Add timestamps to messages

track
     Track channel activity in the mode-line

truncate
     Truncate buffers to a certain size

unmorse
     Translate morse code in messages

Advanced Usage
**************

Write me.

Getting Help and Reporting Bugs
*******************************

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.

  * 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.

  * You can join the mailing list at erc-help@lists.sourceforge.net using the subscription form at http://lists.sourceforge.net/lists/listinfo/erc-help.

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

  * You can visit the IRC Freenode channel #emacs. Many of the contributors are frequently around and willing to answer your questions.

History
*******

ERC was originally written by Alexander L. Belikoff abel@bfr.co.il and Sergey Berezin 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.

  * 2001

     In June 2001, Mario Lang mlang@delysid.org and Alex Schroeder 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 CREDITS file for a list of contributors.

  * 2003

     ERC 3.0 is released.

  * 2004

     ERC 4.0 is released.

  * 2005

     ERC 5.0 is released.  Michael Olson 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.

  * 2006

     ERC 5.1 is released.