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.

Copyright © 2006--2015 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.''

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 servers relay messages from one to the next.

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 customary 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 using the defaults. See Configuration, if you want to change the defaults.

Use C-u M-x irc if you don't want to use the defaults, e.g., if you want to connect to a different network, or connect to the same network using a different nick.  This will prompt you 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 organizations 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`.

IRC 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 channel about all things Emacs, or join #rcirc, the channel about rcirc.

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

Once you are connected to multiple channels, or once you've turned you attention to other buffers in Emacs, you probably want to be notified of any activity in channels not currently visible.  All you need to do is switch channel tracking on using M-x rcirc-track-minor-mode. To make this permanent, add the following to your init file:

     (rcirc-track-minor-mode 1)

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 valid 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....)

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 the Internet Relay Chat (IRC) help archive (http://www.irchelp.org/).

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

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

rcirc-server-alist
     This variable contains an alist of servers to connect to by default and the keywords parameters to use.  The keyword parameters are optional.  If you don't provide any, the defaults as documented below will be used.

     The most important parameter is the :channels parameter.  It controls which channels you will join by default as soon as you are connected to the server.

     Here's an example of how to set it:

          (add-to-list 'rcirc-server-alist
                       '("otherworlders.org"
                         :channels ("#FUDGE" "#game-design")))

     By default you will be connected to the rcirc support channel: #rcirc on irc.freenode.net.

     :nick
          This overrides rcirc-default-nick.

     :port
          This overrides rcirc-default-port.

     :user-name
          This overrides rcirc-default-user-name.

     :full-name
          This overrides rcirc-default-full-name.

     :channels
          This describes which channels to join when connecting to the server. If absent, no channels will be connected to automatically.

rcirc-default-nick
     This variable is used for the default nick.  It defaults to the login name returned by user-login-name.

          (setq rcirc-default-nick "kensanata")

rcirc-default-port
     This variable contains the default port to connect to.  It is 6667 by default and rarely needs changing.

rcirc-default-user-name
     This variable contains the default user name to report to the server. It defaults to the login name returned by user-login-name, just like rcirc-default-nick.

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

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

rcirc-authinfo
     This variable is an alist used to automatically identify yourself on networks.  Each sublist starts with a regular expression that is compared to the server address you're connecting to.  The second element in the list is a symbol representing the method to use, followed by the arguments this method requires.

     Here is an example to illustrate how you would set it:

          (setq rcirc-authinfo
                '(("freenode" nickserv "bob" "p455w0rd")
                  ("freenode" chanserv "bob" "#bobland" "passwd99")
                  ("bitlbee" bitlbee "robert" "sekrit")))

     And here are the valid method symbols and the arguments they require:

     nickserv
          Use this symbol if you need to identify yourself as follows when connecting to a network: /msg nickserv identify secret.  The necessary arguments are the nickname you want to use this for, and the password to use.

          Before you can use this method, you will have to register your nick and pick a password for it.  Contact nickserv and check out the details.  (Using /msg nickserv help, for example.)

     chanserv
          Use this symbol if you need to identify yourself as follows if you want to join a particular channel: /msg chanserv identify #underground secret.  The necessary arguments are the nickname and channel you want to use this for, and the password to use.

          Before you can use this method, a channel contact must tell you about the password to use.  Contact chanserv and check out the details. (Using /msg chanserv help, for example.)

     bitlbee
          Use this symbol if you need to identify yourself in the Bitlbee channel as follows: identify secret.  The necessary arguments are the nickname you want to use this for, and the password to use.

          Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of other instant messaging services.  You can either install Bitlbee locally or use a public Bitlbee server.  There, you need to create an account with a password.  This is the nick and password you need to provide for the bitlbee authentication method.

          Later, you will tell Bitlbee about your accounts and passwords on all the other instant messaging services, and Bitlbee will log you in.  All rcirc needs to know, is the login to your Bitlbee account.  Don't confuse the Bitlbee account with all the other accounts.

Fighting Information Overload
*****************************

This is the section of the manual that caters to the busy person online.  There are support channels with several hundred people in them.  Trying to follow a conversation in these channels can be a daunting task.  This chapters tells you how rcirc can help.

Channels
========

Most people want a notification when something is said on a channel they have joined, particularly if they have been addressed directly.  There is a global minor mode that will do this kind of tracking for you.  All you need to do is switch it on using M-x rcirc-track-minor-mode. To make this permanent, add the following to your init file:

     (rcirc-track-minor-mode 1)

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

If you prefer not to load rcirc immediately, you can delay the activation of this mode:

     (add-hook 'rcirc-mode-hook
               (lambda ()
                 (rcirc-track-minor-mode 1)))

If you've joined a very active support channel, tracking activity is no longer useful.  The channel will be always active.  Switching to active channels using C-c C-SPC no longer works as expected.

The solution is to mark this channel as a low priority channel. Use C-c C-l to make the current channel a low-priority channel. Low priority channels have the modeline indicator ``LowPri''. C-c C-SPC will not switch to low priority channels unless you use the C-u prefix.

If you prefer a channel to never show up in the modeline, then you have to ignore it.  Use C-c TAB to ignore the current channel.

People
======

The most important command available to the discerning IRC user is /ignore.  It's the big equalizer online: If people aggravate you, just ignore them.

This is of course a crude all-or-nothing solution.  Fear not, rcirc offers alternatives: You can ``brighten'' your buddies and ``dim'' certain other nicks that you don't want to ignore altogether.

/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 rudybot.

/bright
     This command toggles the bright status of a nick, if you provide one. If you don't provide a nick, the command lists all the ``brightened'' nicks.  All messages by brightened nicks are---you guessed it---brightened.  Use this for your friends.  Example: /bright rcy.

/dim
     This command toggles the dim status of a nick, if you provide one.  If you don't provide a nick, the command lists all the ``dimmed'' nicks. All messages by dimmed nicks are---you guessed it---dimmed.  Use this for boring people and bots.  If you are tracking channel activity, messages by dimmed nicks will not register as activity.  Example: /dim fsbot.

Keywords
========

On a busy channel, you might want to ignore all activity (using C-c TAB) and just watch for certain keywords.  The following command allows you to highlight certain keywords:

/keyword
     This command toggles the highlighting of a keyword, if you provide one.  If you don't provide a keyword, the current keywords are listed.  Example: /keyword manual.

Notices
=======

In busy channels you might not be interested in all the joining, parting, quitting, and renaming that goes on.  You can omit those notices using C-c C-o.

You can control which notices get omitted via the rcirc-omit-responses variable.  Here's an example of how to omit away messages:

     (setq rcirc-omit-responses '("JOIN" "PART" "QUIT" "NICK" "AWAY"))

Notice that these messages will not be omitted if the nick in question has recently been active.  After all, you don't want to continue a conversation with somebody who just left.  That's why rcirc checks recent lines in the buffer to figure out if a nick has been active and only omits a message if the nick has not been active.  The window rcirc considers is controlled by the rcirc-omit-threshold variable.

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 realize 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 (rcirc-nick process))
                 channels query-buffers)
            (dolist (buf (buffer-list))
              (with-current-buffer buf
                (when (eq process (rcirc-buffer-process))
                  (remove-hook 'change-major-mode-hook
                               'rcirc-change-major-mode-hook)
                  (if (rcirc-channel-p rcirc-target)
                      (setq channels (cons rcirc-target channels))
                    (setq query-buffers (cons buf query-buffers))))))
            (delete-process process)
            (rcirc-connect server port nick
                           rcirc-default-user-name
                           rcirc-default-full-name
                           channels))))

GNU Free Documentation License
******************************

     [file doclicense.texi not included]