Copyright © 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, 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'' in the Emacs manual.

     (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software.  Copies published by the Free Software Foundation raise funds for GNU development.''

     This document is part of a collection distributed under the GNU Free Documentation License.  If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

rcirc Manual
************

rcirc is an Emacs IRC client.

IRC (Internet Relay Chat) is a multi-user chat protocol.  Users communicate with each other in real-time.  Communication occurs both in topic channels which are collections of many users, or privately, with just one other user.

Basics
******

This chapter contains a brief introduction to IRC (Internet Relay Chat), and a quick tutorial on rcirc.

Internet Relay Chat
===================

Internet Relay Chat (IRC) is a form of instant communication over the Internet.  It is mainly designed for group (many-to-many) communication in discussion forums called channels, but also allows one-to-one communication.

Contrary to most Instant Messenger (IM) systems, users usually don't connect to a central server.  Instead, users connect to a random server in a network, and the servers share information between them.

Here's a typical example:

When you connect to the Freenode network (http://freenode.net/), you point your IRC client at the server irc.freenode.net.  That server will redirect your client to a random server on the network, such as zelazny.freenode.net.

Once you're connected, you can send messages to all other users connected to the same network, and you can join all channels on the same network.  You might join the #emacs and the #rcirc channels, for example.  (Typically, channel names begin with a hash character.)

Once you have joined a channel, anything you type will be broadcast to all the other users on the same channel.

If you want to address someone specifically, for example as an answer to a question, it is custom to prefix the message with the nick followed by a colon, like this:

     deego: fsbot rules!

Since this is so common, you can use TAB to do nick completion.

Getting started with rcirc
==========================

Use the command M-x irc to connect to a server.  You will be asked for four things:

IRC server
     What server do you want to connect to? All the servers in a particular network are equivalent.  Some networks use a round-robin system where a single server redirects new connections to a random server in the network.  irc.freenode.net is such a server for the Freenode network.  Freenode provides the network ``for the Free and Open Source Software communities, for not-for-profit organisations and for related communities and organizations.''

IRC port
     All network connections require a port.  Just as web servers and clients use port 80 per default, IRC uses port 6667 per default.  You rarely have to use a different port.

IRC nick
     Every users needs a handle on-line.  You will automatically be assigned a slightly different nick if your chosen nick is already in use.  If your user-login-name is "alex", and this nick is already in use, you might for example get assigned the nick alex`.

Channels
     A space separated list of channels you want to join when connecting. You don't need to join any channels, if you just want to have one-to-one conversations with friends on the same network.  If you're new to the Freenode network, join #emacs, the about all things Emacs.

When you have answered these questions, rcirc will create a server buffer, which will be named something like *irc.freenode.net*, and a channel buffer for each of the channels you wanted to join.

To talk in a channel, just type in what you want to say in a channel buffer, and press RET.

If you want to paste multiple lines, such as source code, you can use C-c C-c to edit your message in a separate buffer.  Use C-c C-c to finish editing.  You still need to press RET to send it, though.  Generally, IRC users don't like people pasting more than around four lines of code, so use with care.

You will note that when other people say things in buffers that are currently buried (no window is showing them), the mode line will show you the abbreviated channel or nick name.  Use C-c C-SPC to switch to these buffers.

Reference
*********

This is the reference section of the manual.  It is not complete.  For complete listings of rcirc features, use Emacs built-in documentation.

rcirc commands
==============

This is a list of commands that you may use in rcirc.  It is not complete.  For a complete listing, press C-h m in an rcirc buffer.

In addition to using regular Emacs key bindings, you can call them by typing them into an rcirc buffer.

For instance, instead of using the command C-c C-j to join a new channel, you may type this in an rcirc buffer, and press RET:

     /join #emacs

This is why you cannot start a message with a slash.  You will have to precede the command with a space, or rewrite your message in order to send it to a channel.

Many commands take parameters.  IRC commands usually ignore string delimiters.  Neither quote nor double-quote have special meanings in IRC.

     /nick "alex schroeder"

This will try to change your nick to "alex.  Usually this will fail because the double quote character is not a legal character for nicks.

These commands are case insensitive.

If a command isn't known by rcirc, it will simply be sent along to the server.  There is a list of some useful commands like that in the next section.

C-c C-j
     This joins a channel such as #rcirc or #emacs.  On most networks, anybody can create new channels.  If you want to talk with some friends, for example, all you have to do is agree on a valid channel name and join that channel.  (Also /join #emacs.)

C-c C-p
     This leaves the current channel.  You can optionally provide a reason for parting.  When you kill a channel buffer, you automatically part the corresponding channel.  (Also /part you are too weird!.)

C-c C-r
     This changes your nick to some other name.  Your nick must be unique across the network.  Most networks don't allow too many nick changes in quick succession, and have restrictions on the valid characters in nick names.  (Also /nick alex-test)

C-c C-w
     Gives you some basic information about a nick.  This often includes what other channels people are on.  (Also /whois fsbot.)

C-c C-q
     Starts a one-to-one conversation with another person on the same network.  A new buffer will be created for this conversation.  It works like a channel with only two members.  (Also /query fsbot.)

C-c RET
     This sends a single message to a nick.  Like with C-c C-q, a new buffer is created, where the response from the other party will show up.  (Also /msg nickserv identify secret.)

C-c C-x
     This disconnects from the server and parts all channels.  You can optionally provide a reason for quitting.  When you kill the server buffer, you automatically quit the server and part all channels.  (Also /quit ZZZzzz....)

Some commands may not have a key binding, but only be available as typed commands, such as:

/ignore
     This command toggles the ignore status of a nick, if you provide one. If you don't provide a nick, the command lists all the nicks you are ignoring.  All messages by ignored nicks are---you guessed it---ignored. Since only ``operators'' can kick people from channels, the ignore command is often the only way to deal with some of the more obnoxious fellows online.  Example: /ignore xah.

Useful IRC commands
===================

As mentioned, if a command isn't known by rcirc, it will simply be sent along to the server.  Some such commands are available on nearly all IRC servers, such as:

/away
     This sets your status as ``being away'' if you provide a reason, or sets your status as ``being back'' if you do not.  People can use the C-c C-w command to check your status.  Example: /away food.

Typical IRC servers implement many more commands.  You can read more about the fantastic world of IRC online at http://www.irchelp.org/, the Internet Relay Chat (IRC) help archive.

Configuration
=============

These are some variables you can change to configure rcirc to your liking.

rcirc-server
     the default server to connect to.

rcirc-port
     the default port to connect to.

rcirc-nick
     the default nick to use.

     (setq rcirc-server "irc.mozilla.org"
           rcirc-port 6666
           rcirc-nick "alx")

rcirc-user-full-name is used to set your ``real name'' on IRC. It defaults to user-full-name.  If you want to hide your full name, you might want to set it to some pseudonym.

     (setq rcirc-user-full-name "Curious Minds Want To Know")

rcirc-startup-channels-alist is the alist of channels to join when connecting to a particular network.  An alist is a list of lists. Each sublist starts with a regular expression that is compared to the server address you're connecting to.  The remaining sublist items are the channels to join.

     (setq rcirc-startup-channels-alist
           '(("\\.freenode\\.net$" "#emacs" "#rcirc" "#wiki")))

Note the subtle problem, here --- IRC clients connect to servers, and there is no way of knowing which servers belong to a particular network. In the example above we're exploiting a naming convention used by within the Freenode network --- all servers within the network have a host in the freenode.net domain.

Hacking and Tweaking
********************

Here are some examples of stuff you can do to configure rcirc.

Skipping /away messages using handlers
======================================

The IRC protocol specifies how certain events are signaled from server to client.  These events have numbers and are dealt with using so-called handlers.  You can override existing handlers by exploiting the naming convention adopted for rcirc.

Here's how to stop rcirc from printing /away messages. Since rcirc doesn't define a 301 handler, you don't need to require rcirc before defining the handler:

     (defun rcirc-handler-301 (process cmd sender args)
       "/away message handler.")

Using fly spell mode
====================

The following code activates Fly Spell Mode for rcirc buffers:

     (add-hook 'rcirc-mode-hook (lambda ()
                                  (flyspell-mode 1)))

See Flyspell mode (The GNU Emacs Manual), for details.

Scrolling conservatively
========================

IRC buffers are constantly growing.  If you want to see as much as possible at all times, you would want the prompt at the bottom of the window when possible.  The following snippet uses a local value for scroll-conservatively to achieve this:

     (add-hook 'rcirc-mode-hook
               (lambda ()
                 (set (make-local-variable 'scroll-conservatively)
                      8192)))

See Scrolling conservatively (The GNU Emacs Manual), for details.

Changing the time stamp format
==============================

rcirc-time-format is the format used for the time stamp.  Here's how to include the date in the time stamp:

     (setq rcirc-time-format "%Y-%m-%d %H:%M ")

Defining a new command
======================

Here's a simple new command, /sv.  With it, you can boast about your IRC client.  It shows how you can use defun-rcirc-command to define new commands.

We're waiting for the definition of this command until rcirc is loaded because defun-rcirc-command is not yet available, and without rcirc loaded, the command wouldn't do us much good anyway.

     (eval-after-load 'rcirc
       '(defun-rcirc-command sv (arg)
          "Boast about rcirc."
          (interactive "i")
          (rcirc-send-message process target
                              (concat "I use " rcirc-id-string))))

Reconnecting after you have lost the connection
===============================================

If you're chatting from a laptop, then you might be familiar with this problem: When your laptop falls asleep and wakes up later, your IRC client doesn't realise that it has been disconnected.  It takes several minutes until the client decides that the connection has in fact been lost.  The simple solution is to use M-x rcirc.  The problem is that this opens an additional connection, so you'll have two copies of every channel buffer --- one dead and one live.

The real answer, therefore, is a /reconnect command:

     (eval-after-load 'rcirc
       '(defun-rcirc-command reconnect (arg)
          "Reconnect the server process."
          (interactive "i")
          (unless process
            (error "There's no process for this target"))
          (let* ((server (car (process-contact process)))
                 (port (process-contact process :service))
                 (nick (with-rcirc-process-buffer process rcirc-nick))
                 channels query-buffers)
            (dolist (buf (buffer-list))
              (with-current-buffer buf
                (when (eq process rcirc-process)
                  (if (rcirc-channel-p rcirc-target)
                      (setq channels (cons rcirc-target channels))
                    (setq query-buffers (cons buf query-buffers))))))
            (delete-process process)
            (let ((new-process (rcirc-connect server port nick
                                              rcirc-user-name user-full-name
                                              channels)))
              (dolist (buf query-buffers)
                (with-current-buffer buf
                  (setq rcirc-process new-process)))))))