ERC
***

This manual is for ERC version 5.3.

Copyright © 2005-2011 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.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.  Buying copies from the FSF supports it in developing GNU and promoting software freedom.''

     All Emacs Lisp code contained in this document may be used, distributed, and modified without restriction.

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

Note that some ERC files are not included with Emacs due to copyright or dependency issues.  If desired, they may be found at the following locations, or from your local GNU mirror.

  * http://ftp.gnu.org/gnu/erc/erc-5.3-extras.tar.gz

  * http://ftp.gnu.org/gnu/erc/erc-5.3-extras.zip

The rest of this chapter 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-discuss@gnu.org 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://ftp.gnu.org/gnu/erc, or your local GNU mirror.

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

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

The git version control system allows you to keep up-to-date with the latest changes to the development version of ERC.  It also allows you to contribute changes (via commits, if you are have developer access to the repository, or via patches, otherwise).  If you would like to contribute to ERC development, it is highly recommended that you use git.

If you are new to git, you might find this tutorial helpful: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html.

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

 1. Install git.

       * Debian and Ubuntu: apt-get install git-core.

       * Windows: http://git.or.cz/gitwiki/WindowsInstall.

       * Other operating systems: download, compile, and install the source from http://www.kernel.org/pub/software/scm/git/, or find a git package for your operating system.

 2. Download the ERC development branch.

     If you have developer access to ERC, do:

          git clone ssh://loginname@git.sv.gnu.org/srv/git/erc.git

     otherwise, do:

          git clone git://git.sv.gnu.org/erc.git

     If you are behind a restrictive firewall, and do not have developer access, then do the following instead:

          git clone http://git.sv.gnu.org/r/erc.git

 3. 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.  If you wish, you may skip this step and proceed directly to the ``update'' step.

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

          # Fetch new changes from the repository, but don't apply them yet
          git fetch origin

          # Display log messages for the new changes
          git log HEAD..origin

     ``origin'' is git's name for the location where you originally got ERC from.  You can change this location at any time by editing the .git/config file in the directory where the ERC source was placed.

 4. Update to the latest version by pulling in any missing changes.

          cd erc
          git pull origin

     git will show how many files changed, and will provide a visual display for how many lines were changed in each file.

There are other ways to interact with the ERC repository.

  * Browse git repo: http://git.sv.gnu.org/gitweb/?p=erc.git

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

  * Latest development snapshot (zip file): http://mwolson.org/static/dist/erc-latest.zip

The latest development snapshot can lag behind the git repo by as much as 20 minutes, but never more than that.

For further information on committing changes to ERC and performing development, please consult http://emacswiki.org/cgi-bin/wiki/ErcDevelopment.

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.  An example follows.

     (require 'erc)

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

If you want to place ERC settings in their own file, you can place them in ~/.emacs.d/.ercrc.el, creating it if necessary.

If you would rather use the Customize interface to change how ERC works, do M-x customize-group RET erc RET.  In particular, ERC comes with lots of modules that may be enabled or disabled; to select which ones you want, do M-x customize-variable RET erc-modules RET.

Sample Session
==============

This is an example ERC session which shows how to connect to the #emacs channel on Freenode.  Another IRC channel on Freenode that may be of interest is #erc, which is a channel where ERC users and developers hang out.

  * Connect to Freenode

     Run M-x erc.  Use ``irc.freenode.net'' as the IRC server, ``6667'' as the port, and choose a nickname.

  * Get used to the interface

     Switch to the ``irc.freenode.net:6667'' buffer, if you're not already there.  You will see first some messages about checking for ident, and then a bunch of other messages that describe the current IRC server.

  * Join the #emacs channel

     In that buffer, type ``/join SPC #emacs'' and hit RET.  Depending on how you've set up ERC, either a new buffer for ``#emacs'' will be displayed, or a new buffer called ``#emacs'' will be created in the background.  If the latter, switch to the ``#emacs'' buffer.  You will see the channel topic and a list of the people who are currently on the channel.

  * Register your nickname with Freenode

     If you would like to be able to talk with people privately on the Freenode network, you will have to ``register'' your nickname.  To do so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg NickServ register <password>'', replacing ``<password>'' with your desired password.  It should tell you that the operation was successful.

  * Talk to people in the channel

     If you switch back to the ``#emacs'' buffer, you can type a message, and everyone on the channel will see it.

  * Open a query buffer to talk to someone

     If you want to talk with someone in private (this should usually not be done for technical help, only for personal questions), type ``/query <nick>'', replacing ``<nick>'' with the nickname of the person you would like to talk to.  Depending on how ERC is set up, you will either see a new buffer with the name of the person, or such a buffer will be created in the background and you will have to switch to it.  Begin typing messages, and you will be able to have a conversation.

     Note that if the other person is not registered, you will not be able to talk with them.

Special Features
================

ERC has some features that distinguish it from some IRC clients.

  * multiple channels and multiple servers

     Every channel is put in a separate buffer.  Several IRC servers may be connected to at the same time.

  * private message separation

     Private conversations are treated as channels, and are put into separate buffers in Emacs.  We call these ``query buffers''.

  * highlighting

     Some occurrences of words can be highlighted, which makes it easier to track different kinds of conversations.

  * notification

     ERC can notify you that certain users are online.

  * channel tracking

     Channels can be hidden and conversation continue in the background.  You are notified when something is said in such a channel that is not currently visible.  This makes it easy to get Real Work done while still maintaining an IRC presence.

  * nick completion

     ERC can complete words upon hitting TAB, which eases the writing of nicknames in messages.

  * history

     Past actions are kept in history rings for future use.  To navigate a history ring, hit M-p to go backwards and M-n to go forwards.

  * multiple languages

     Different channels and servers may have different language encodings.

     In addition, it is possible to translate the messages that ERC uses into multiple languages.  Please contact the developers of ERC at erc-discuss@gnu.org if you are interested in helping with the translation effort.

  * user scripting

     Users can load scripts (e.g. auto greeting scripts) when ERC starts up.

     It is also possible to make custom IRC commands, if you know a little Emacs Lisp.  Just make an Emacs Lisp function and call it erc-cmd-NEWCOMMAND, where NEWCOMMAND is the name of the new command in capital letters.

  * auto reconnect

     If the connection goes away at some point, ERC will try to reconnect automatically.  If it fails to reconnect, and you want to try to manually reestablish the connection at some later point, switch to an ERC  buffer and run the /RECONNECT command.

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 lets 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

capab-identify
     Mark unidentified users on freenode and other servers supporting CAPAB.

completion (aka pcomplete)
     Complete nicknames and commands (programmable)

fill
     Wrap long lines

hecomplete
     Complete nicknames and commands (old).  This is the old module---you might prefer the ``completion'' module instead.

identd
     Launch an identd server on port 8113

irccontrols
     Highlight or remove IRC control characters

log
     Save buffers in logs

match
     Highlight pals, fools, and other keywords

menu
     Display a menu in ERC buffers

netsplit
     Detect netsplits

noncommands
     Don't display non-IRC commands after evaluation

notify
     Notify when the online status of certain users changes

page
     Process CTCP PAGE requests from IRC

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

spelling
     Check spelling of messages

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

Connecting to an IRC Server
===========================

The easiest way to connect to an IRC server is to call M-x erc. If you want to assign this function to a keystroke, the following will help you figure out its parameters.

 -- Function: erc
     Select connection parameters and run ERC. Non-interactively, it takes the following keyword arguments.

       * SERVER

       * PORT

       * NICK

       * PASSWORD

       * FULL-NAME

     That is, if called with the following arguments, SERVER and FULL-NAME will be set to those values, whereas erc-compute-port, erc-compute-nick and erc-compute-full-name will be invoked for the values of the other parameters.

          (erc :server "irc.freenode.net" :full-name "Harry S Truman")

Server
------

 -- Function: erc-compute-server &optional server
     Return an IRC server name.

     This tries a number of increasingly more default methods until a non-nil value is found.

       * SERVER (the argument passed to this function)

       * The erc-server option

       * The value of the IRCSERVER environment variable

       * The erc-default-server variable

 -- User Option: erc-server nil
     IRC server to use if one is not provided.

Port
----

 -- Function: erc-compute-port &optional port
     Return a port for an IRC server.

     This tries a number of increasingly more default methods until a non-nil value is found.

       * PORT (the argument passed to this function)

       * The erc-port option

       * The erc-default-port variable

 -- User Option: erc-port
     IRC port to use if not specified.

     This can be either a string or a number.

Nick
----

 -- Function: erc-compute-nick &optional nick
     Return user's IRC nick.

     This tries a number of increasingly more default methods until a non-nil value is found.

       * NICK (the argument passed to this function)

       * The erc-nick option

       * The value of the IRCNICK environment variable

       * The result from the user-login-name function

 -- User Option: erc-nick
     Nickname to use if one is not provided.

     This can be either a string, or a list of strings. In the latter case, if the first nick in the list is already in use, other nicks are tried in the list order.

 -- User Option: erc-nick-uniquifier
     The string to append to the nick if it is already in use.

 -- User Option: erc-try-new-nick-p
     If the nickname you chose isn't available, and this option is non-nil, ERC should automatically attempt to connect with another nickname.

     You can manually set another nickname with the /NICK command.

Full name
---------

 -- Function: erc-compute-full-name &optional full-name
     Return user's full name.

     This tries a number of increasingly more default methods until a non-nil value is found.

       * FULL-NAME (the argument passed to this function)

       * The erc-user-full-name option

       * The value of the IRCNAME environment variable

       * The result from the user-full-name function

 -- User Option: erc-user-full-name
     User full name.

     This can be either a string or a function to call.

Sample Configuration
====================

Here is an example of configuration settings for ERC.  This can go into your Emacs configuration file.  Everything after the (require 'erc) command can optionally go into ~/.emacs.d/.ercrc.el.

     ;;; Sample ERC configuration

     ;; Add the ERC directory to load path -- you don't need this if you are
     ;; using the version of ERC that comes with Emacs
     (add-to-list 'load-path "~/elisp/erc")

     ;; Load ERC
     (require 'erc)

     ;; Load authentication info from an external source.  Put sensitive
     ;; passwords and the like in here.
     (load "~/.emacs.d/.erc-auth")

     ;; This is an example of how to make a new command.  Type "/uptime" to
     ;; use it.
     (defun erc-cmd-UPTIME (&rest ignore)
       "Display the uptime of the system, as well as some load-related
     stuff, to the current ERC buffer."
       (let ((uname-output
              (replace-regexp-in-string
               ", load average: " "] {Load average} ["
               ;; Collapse spaces, remove
               (replace-regexp-in-string
                " +" " "
                ;; Remove beginning and trailing whitespace
                (replace-regexp-in-string
                 "^ +\\|[ \n]+$" ""
                 (shell-command-to-string "uptime"))))))
         (erc-send-message
          (concat "{Uptime} [" uname-output "]"))))

     ;; This causes ERC to connect to the Freenode network upon hitting
     ;; C-c e f.  Replace MYNICK with your IRC nick.
     (global-set-key "\C-cef" (lambda () (interactive)
                                (erc :server "irc.freenode.net" :port "6667"
                                     :nick "MYNICK")))

     ;; This causes ERC to connect to the IRC server on your own machine (if
     ;; you have one) upon hitting C-c e b.  Replace MYNICK with your IRC
     ;; nick.  Often, people like to run bitlbee (http://bitlbee.org/) as an
     ;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with
     ;; people on those networks.
     (global-set-key "\C-ceb" (lambda () (interactive)
                                (erc :server "localhost" :port "6667"
                                     :nick "MYNICK")))

     ;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has
     ;; been commented out to avoid confusing new users.
     ;; (define-key erc-mode-map (kbd "RET") nil)
     ;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line)
     ;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line)

     ;;; Options

     ;; Join the #emacs and #erc channels whenever connecting to Freenode.
     (setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc")))

     ;; Interpret mIRC-style color commands in IRC chats
     (setq erc-interpret-mirc-color t)

     ;; The following are commented out by default, but users of other
     ;; non-Emacs IRC clients might find them useful.
     ;; Kill buffers for channels after /part
     ;; (setq erc-kill-buffer-on-part t)
     ;; Kill buffers for private queries after quitting the server
     ;; (setq erc-kill-queries-on-quit t)
     ;; Kill buffers for server messages after quitting the server
     ;; (setq erc-kill-server-buffer-on-quit t)

Options
=======

This section has not yet been written.  For now, the easiest way to check out the available options for ERC is to do M-x customize-group erc RET.

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/ERC is the emacswiki.org page for ERC.  Anyone may add tips, hints, or bug descriptions to it.

  * There are several mailing lists for ERC.  To subscribe, visit http://savannah.gnu.org/mail/?group=erc.

     The mailing lists are also available on Gmane. (http://gmane.org/).  Gmane provides additional methods for accessing the mailing lists, adding content to them, and searching them.

      1. gmane.emacs.erc.announce: Announcements

      2. gmane.emacs.erc.discuss: General discussion

      3. gmane.emacs.erc.cvs: Log messages for changes to the ERC source code

  * 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 http://sourceforge.net/projects/erc.

     In reaction to a mail about the new ERC development effort, 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 happened on #emacs on irc.openprojects.net.  Over time, many people contributed code, ideas, bugfixes, and a lot of alpha/beta/gamma testing.

     See the CREDITS file for a list of contributors.

  * 2003

     ERC 3.0 was released.

  * 2004

     ERC 4.0 was released.

  * 2005

     ERC 5.0 was released.  Michael Olson mwolson@gnu.org became the release manager and eventually the maintainer.

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

  * 2006

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

     ERC became an official GNU project, and development moved to http://sv.gnu.org/projects/erc.  We switched to using GNU Arch as our revision control system.  Our mailing list address changed as well.

  * 2007

     We switched to using git for our version control system.

     [file gpl.texi not included]

     [file doclicense.texi not included]