-
Notifications
You must be signed in to change notification settings - Fork 51
Manual
Circe is distributed as a tar ball containing a few files. To install her, you need to unpack it, tell Emacs where it can find the files, and load the package.
Let's say you unpacked the Circe distribution files into the directory
~/.elisp/circe/. The following lines belong into your
~/.emacs. The first line tells Emacs where to find the Circe
files, and the second tells it to load Circe. She does not connect yet,
though.
(add-to-list 'load-path "~/.elisp/circe/lisp")
(require 'circe)Once Circe is loaded, it is easy to connect to an IRC server. The
command is M-x circe. She will ask you for the server and port to
connect to. Good servers to try at the beginning are
irc.freenode.net, port 6667---you can join the channel #emacs
there. To join the channel, just type /JOIN #emacs in the initial
Circe buffer (the server buffer).
The following documents a sample Circe configuration for your
~/.emacs. The comments try to elaborate what is done here.
;;; Tell Emacs how to load Circe when needed
(require 'circe-auto)
;;; The following file contains our nickserv password for Freenode, very
;;; probably by doing something like:
;;; (setq freenode-passwd "t!n3be") ; There Is No Editor But Emacs
(load-file "~/.private.el")
(setq ;;; On Freenode, automatically join the channel #emacs
circe-server-auto-join-channels '(("^freenode$" "#emacs"))
;;; Also use our Nickserv password on Freenode
circe-nickserv-auth-info `(("freenode" "freenode" "FreenodeNick" ,freenode-passwd))
;;; Truncate long buffers to conserve memory.
lui-max-buffer-size 30000
;;; Also, do spell checking. This only works when you have ispell
;;; installed.
lui-flyspell-p t
;;; When we kill the server buffer, ask, and if we insist, kill
;;; all other buffers belonging to that server as well
circe-server-killed-confirmation 'ask-and-kill-all)
;;; Now define a M-x irc command to connect to IRC.
(defun irc ()
"Connect to IRC"
(interactive)
(circe "irc.freenode.net" 6667 "freenode"))Now when you re-load your ~/.emacs, or restart Emacs, you can
just do M-x irc to connect to Freenode and join the channel
#emacs.
An IRC network consists of servers which are connected to each other in a tree structure (some disagree and argue that an IRC network is not an IRC network unless the server are disconnected to each other). There are many IRC networks out there, for example Freenode, IRCnet and EFnet. Those networks are never connected to each other, and provide different features.
Ever user on an IRC network has a unique nickname. This nickname,
or nick for short, is used for most IRC commands to identify a
person.
Once connected to a server, and, transitively, to a network, you can
join a channel. A channel is the main way to communicate with
others on IRC. Different people can join a channel and talk on it.
Everything said on the channel is visible to all participants. Channels
exist on various topics, though it is not uncommon for the people on a
channel to diverge widely from the actual topic implied by the name of
the channel. An example channel is #emacs on Freenode, which
exists to provide help with Emacs, but has seen discussions ranging from
the issues of Free Software, to WikiWikiWeb design, to detailed analyses
of Marx and Kropotkin.
To talk on a channel, just write what you want to say. 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:
Glaucos: Have you seen Scylla recently?
When Circe connects to an IRC server, she creates a server buffer
which is dedicated only to this server. Rarely any output is sent via
this buffer, but it is initially the only indication of an IRC
connection. Most commands, especially JOIN, do work in the server
buffer as well, though.
As soon as you join a channel, Circe creates a channel buffer for
you, which will contain all data received from or sent to this channel.
For private messages, Circe creates a query buffer, which is
dedicated to the conversation with a single other individual. Circe
tries to keep track of the nick of that individual.
The channel in channel buffers and the other nick in query buffers is
usually called the target of this buffer.
Any text typed at the input line of any Circe buffer is sent as a message to the target. In a channel, this means you send this as a message to the channel; in a query, this is sent as a private message to the corresponding nick. But when the line starts with a slash, it is considered to be a command. See the next section for more information.
Circe uses the Linewise User Interface for all output. This means that all the configuration options of Lui apply to Circe as well.
A line starting with a slash (/) is a command to Circe, and not
sent as a message to the server. The word immediately following the
slash is called the command word, or command for short. Following is a
description of all the commands Circe knows so far.
Say text to the current target. This is useful to prevent a
misinterpretation of a slash at the beginning of a line.
Tell the current channel that you are doing action. This is
usually displayed to others as follows (where padawan is your
nick):
/me smiles at the people in the channel.
- padawan smiles at the people in the channel.
This command can be confusing, as correct sentences using it require thinking of yourself in the third person. It is not uncommon among IRCers to talk about themselves as "me", either.
A different kind of command, this is called using M-x circe-reconnect. It reconnects the current IRC session, for example
when your network connection died.
Channel commands are primarily useful in channels, or to get onto channels.
Join channel, optionally supplying a key. Some channels have a
keyword set so that only those in the know can join it. This is rare,
though.
Leave the current channel. You can give a reason, too.
Get a list of people on the current channel, or possibly on channel.
This can also be invoked with C-c C-n.
This command retrieves or sets the topic of the current channel. The topic is a (more or less) long line of text, usually announcing important URLs or events. It's often a good idea to read it. Many channels disallow changing the topic unless you have special privileges.
Replace the current input line with a command to set the topic as it
is at the moment. This is useful if you want to change the topic
slightly. It is bound to C-c C-t by default.
As has been said before, the IRC server are connected as a tree. This
means that when two IRC servers lose the connection, there remain two
disconnected parts of the tree. This is called a netsplit. When the
servers connect again, it's called a netmerge. So far, so bad, but
the typical netsplit will cause about half the channel to apparently
quit IRC (they will see you, and all that stay on your ``side'' of the
split, quit as well). Shortly thereafter, the net merges, and all the
people who just quitted will rejoin the channel automatically. This
causes an annoying amount of text which disturbs channel talks.
When Circe detects a netsplit, she does not report every person
leaving, but instead records that they split away. When the net merges
again, she notes that as well. All you will see about this is a notice
that the net is splitting or merging. The command WL, for Who Left,
will tell you which users left the channel due to the split, and are
still missing.
Query commands are primarily useful to open a query, that is, a private discussion with someone else.
Send nick a message containing text. This is equivalent to opening
(or switching to) a query buffer for this person, and typing text at
the prompt.
Open a query buffer for user nick.
Server commands change your status at the server, and have no immediate effects on other users.
This command sets you away, which means you're not available for
talking at the moment. The reason is told to everyone who sends
messages to you, or checks your whois information.
The GAWAY variant does the same, but on all servers you are
connected to.
This command removes any away status. It is equivalent to AWAY
without any arguments.
A completely useless command which makes you leave IRC. Since this is
such a completely incomprehensible thing to do, it is very useful to
give a reason why you did that.
GQUIT does the same, but on all servers you are on.
General commands don't fit anywhere else.
Idiots exist everywhere. IRC is everywhere. Consequently, idiots exist on IRC. When someone annoys you too much, the best thing to do is to ignore them. This can be done mentally, but Circe can help you a bit. When a user matches the pattern you pass to this command, messages from that user are never displayed. Nor are messages displayed which start out with a word matching such a pattern followed by a colon, comma or space.
Without the pattern, this command lists your current ignore list. You
can store permanent regular expressions in it by modifying the
circe-ignore-list variable in your ~/.emacs.
When you're in the mood to be annoyed again, you can remove a pattern from your ignore list again.
The net being what it is, it is possible that sometimes a connection is very slow. How fast someone is receiving your messages can be tested with this message.
The WHOIS returns some information about another user. Just try
it. WHOWAS is very similar, but works on nicks that are not on
IRC anymore, though it returns less information.
When you don't see your own nick in messages you send, it is sometimes
quite nice to be remembered who you are again. This command does a
WHOIS on yourself.
CTCP is the Client-To-Client Protocol used on IRC. If you want to test
it, try to send yourself a CTCP message. Possible commands are
VERSION and TIME, both of which don't take any arguments.
Sometimes it is desirable for some people to send IRC commands
themselves. The QUOTE command just takes its argument and passes
it unmodified to the IRC server.
This command tells the current target the version of Circe and Emacs you are using. Besides being useful in bragging contests, this also helps in debugging problems.
Circe is quite configurable. Please see the customize group circe
for a complete list of options: M-x customize-group RET circe RET.
Please refer to the chapter about extension modules, and of course the
source, for information more suited for developers.
To extend Circe for other purposes than those features in the core you have to write an extension module.
There are only few requirements for extension modules. A hypothetical
grovel module should be provided in a circe-grovel.el
file. This file needs to provide the circe-grovel feature, and
two commands, named enable-circe-grovel and
disable-circe-grovel. What those commands do is up to you.
It is also advisable that the enable function be annotated with an autoloads line.
Currently there are two extension modules.
The highlight all nicks module provided by the file
circe-highlight-all-nicks.el is a good example of how you can
extend circe with modules. It highlights all nicknames of a channel when
they appear in conversations.
You activate the module by typing M-x enable-circe-highlight-all-nicks. If you want nick-highlighting as
default behavior add this line to your .emacs.
(enable-circe-highlight-all-nicks)The logging module provides a history of chat conversations. Whenever a logging enabled chat buffer is closed its contents will be saved in a log file. When you enter the same chat again the log will be inserted.
To enable logging add
(enable-circe-log)into your .emacs or enable it manually with M-x enable-circe-log.
Which chats will be logged can be configured with the two variables:
Only buffers matching this regexp and not matching `circe-log-exlude-buffer-regexp' will be logged.
Only buffers not matching this regexp and matching `circe-log-buffer-regexp' will be logged. By default query buffers for ChanServ and NickServ will be ignored.
The directory in which circe's log files should reside.
The basic design decision behind Circe is the separation of the frontend or user interface from the backend. The frontend is now called Lui, the Linewise User Interface, which provides all user interface related functions behind a clean abstraction layer. The next step is to separate an IRC library from the rest of Circe, so that Circe only needs to provide the communication layer between the two.
Circe does not try to find old server or channel buffers when a new
connection attempt is done. Instead, new buffers are created all the
time. If you need to reconnect to a server, use the M-x circe-reconnect command. In the future, it might be possible to find a
suitable old server buffer which is currently not connected, and use it
to connect to IRC.
The extension modules should not use minor modes. When a number of modules are loaded, any major mode help buffer is croweded with those useless minor modes which add no information. The enable/disable convention of Circe does not clutter the minor mode list.