\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename irchat
@settitle irchat.el, an IRC interface for GNU Emacs
@setchapternewpage odd
@comment %**end of header

@ifinfo
This file documents use of irchat.el, a GNU Emacs interface for Internet
Relay Chat.

Copyright @copyright{} 1990 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled "Distribution" and "General Public License" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled "Distribution" and "General Public
License" may be included in a translation approved by the author instead
of in the original English.

@end ifinfo

@titlepage
@sp 10
@center @titlefont {irchat.el}
@sp 2
@center IRC interface for GNU Emacs
@sp 2
@center Tor Lillqvist (author, original version 1989)
@sp 2
@center Kim Nyberg (fixes/improvement 1989-1990)
@center Jukka Partanen (fixes/improvement 1989-1990)
@sp 2
@center Markku J@{rvinen (fixes/improvement 1989-1991)
@center Kai Kein@{nen (fixes/improvement 1989-1991)
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled "Distribution" and "General Public License" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled "Distribution" and "General Public
License" may be included in a translation approved by the author instead
of in the original English.

@end titlepage

@node Top, Introduction, (dir), (dir)    
@comment  node-name,  next,  previous,  up

Welcome to the documentation of irchat.el, the GNU Emacs interface to
Internet Relay Chat. irchat.el provides all the necessary IRC features,
combined with the easy extensibility of GNU Emacs.

@menu
* Introduction::What is irchat.el?
* Etiquette::	How to behave in IRC.
* Overview::	Why use IRC in GNU Emacs?
* Installing::	How to get irchat.el up and running?
* Using:: 	Using irchat.el
* Commands::	IRC Commands in irchat.el
* Customizing::	Customizing irchat.el
* Authors::	Reporting bugs etc.
@end menu

@node Introduction, Etiquette, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

What is irchat.el?

Irchat.el is a GNU Emacs client for the Internet Relay Chat protocol.
Study the documentation accompanying the server. Make sure to read the
etiquette file. Irchat.el is designed to be easily modifiable if you know
emacs-lisp and understand the meaning of hooks.@*
Files that are needed to run irchat are: irchat.el, irchat-commands.el
and irchat-handle.el. @*
This document describes version 2.1 of irchat. It runs with servers
up to and including ircd2.6.1.

@node Etiquette, Overview, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Etiquette

/************************************************************************
 *   IRC - Internet Relay Chat, doc/etiquette
 *   Copyright (C) 1990, Lea Viljanen and Ari Husa
 *
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation; either version 1, or (at your option)
 *   any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

HOW TO BEHAVE ON IRC

Authors:      Lea Viljanen (LadyBug)  viljanen@@kreeta.helsinki.fi
              Ari Husa     (luru)     so-luru@@tolsun.oulu.fi 


1) Language

   The most widely understood and spoken language on IRC is English. 
However! As IRC is used in many different countries, English is by
no means the only language. If you want to speak some other language
than English (for example with your friends), go to a separate channel
and set the topic (with /topic) to indicate that. For example
   /topic Finnish only!
would mean that this channel would be reserved for Finnish discussion.
On the other hand, you should check the topic (with /list command) 
before you move to a channel to see if there are any restrictions about 
language.
   On a channel not restricted by /topic, please speak a language
everybody can understand. If you want to do otherwise, change channels
and set the topic accordingly.


2) Hello/Goodbye

   It's not necessary to greet everybody on a channel personally.
Usually one "Hello" or equivalent is enough. And don't expect everybody
to greet you back. On a channel with 20 people that would mean one
screenful of hellos. It's sensible not to greet, in order not to be rude
to the rest of the channel. If you must say hello, do it with a private /msg.
The same applies to goodbyes.


3) Discussion

   When you come to a new channel it's advised you to listen
for a while to get an impression of what's discussed. Please feel free
to join in, but do not try to force your topic into the discussion
if that doesn't come naturally.


4) {}|[]\

   IRC has quite a lot of people from Scandinavian countries,
the above characters are letters in their alphabet. This 
has been explained on IRC about a thousand and one times, so
read the following, do not ask it on IRC:

   {     is an A with 2 dots over it
   }     is an A with a small circle above it
   |     is either an O with 2 dots over it or an O with a dash (/) through it
   [, ], and \ are the preceding three letters in upper case.

   There are a lot of people from Japan as well, who use Kanji characters
which may look quite exotic as well. As I don't know Kanji I don't
even try to explain any of the characters.

5) ATTENTION!

   Remember, people on IRC form their opinions about you only by 
your actions, writings and comments on IRC. So think before you type.
Do not "dump" to a channel or user (send large amounts of unwanted
information). This is likely to get you /kicked off the channel or
/killed off from irc. Dumping causes network 'burbs', connections going
down because servers cannot handle the large amount of traffic any more.

@node Overview, Installing, Etiquette, Top
@comment  node-name,  next,  previous,  up
@chapter Overview

Why IRC in Emacs?

@enumerate
@item
You can have other Emacs buffers visible and have irchat either in a
small buffer or not visible at all. For example, you can read USENET
news with GNUS without leaving irc, and be noticed if someone is trying
to reach you. Nowadays when computing power is cheap you can have
multiple emacses running so this view has lost some of its importance.

@item
You get all the GNU Emacs features such as a calculator, all usable
while in IRC. And you can run your favourite shell commands and
get their output directly to IRC or to your input (*IRC Commands*)
buffer for you to send to IRC channel.

@item
You can edit other files while talking about their contents on IRC.

@item
The commands for editing your text are those familiar from GNU Emacs and
if you have customized them, the customized editing keys are
automatically available. Irchat uses it's own keymap bound to C-c,
so if you have used that key in your own keybindings you have to do 
some reordering in order to use your own commands.

@item
You may easily add features if you find something missing (assuming you
know elisp, of course, but this is a good reason to learn. ;))
Actually we are now (01-07.1991) working on a easily modifiable
hooks to irchat (something like /ON on @code{ircII} - one of the most popular
irc clients).

@item
GNU Emacs has been ported on many different UNIX machines, so you will
not have to do the porting yourself, which might be the case with the
traditional clients.

@item
If you use IRC on several machines, you don't need to compile an IRC
client for all of them. You can just take the small elisp code with you
and use it.

@item
GNU Emacs tries to handle most terminals, which might not be the case
with the traditional clients.

@end enumerate

@node Installing, Using, Overview, Top
@comment  node-name,  next,  previous,  up
@chapter Installing irchat.el

Try to convince your local emacs administrator to put irchat.el to a
globally accessible elisp directory and to add this info to the info
tree. No modifications are needed in irchat.el itself, as long as the
irc port is 6667 as it usually is and the server is local. If your server
uses different irc port or you use non local irc server then you have to
set them by setting environment variables IRCPORT and/or IRCSERVER.

You need add line containing following to your @code{.emacs}, that way
can start irchat by issuing command M-x irchat.
@example
(autoload 'irchat "irchat" "GNUemacs IRC client." t)

@end example

If you are not happy with the way irchat.el is when shipped, you need to
have a small piece of code for yourself for setting some variables that
control irchat the way you want them to be. You may place them in your
@code{.emacs} or in an other file to be loaded before starting irchat itself.
See the section called "Customizing irchat.el" for info on the
customization possibilities.

@node Using, Commands, Installing, Top    
@comment  node-name,  next,  previous,  up
@chapter Using irchat.el

In irc-mode you will have two buffers, the command buffer and the
dialogue buffer. You will be typing in the command buffer, and the
dialogue will appear in the dialogue buffer. The command buffer roughly
corresponds to the one-line area in the bottom in the traditional
clients.

In the command buffer, the lines you type will be sent to the channel you
are on when you press the return or the linefeed key. You may freely edit
them or do any regular editing tricks that you may want to do. If the line
exceeds the right margin, it will be wrapped around, so you can finish the
line and send it when you're ready.

The cursor keys move you around in the buffer. If you want to say
something again, just find it in the command buffer, move the cursor on
it, and press the return key.

You can use the regular GNU Emacs commands in the command buffer for
inserting text from elsewhere, like insert-file (C-x i) for adding other
files, C-u M-! for inserting output of shell commands and so forth.
Notice that these will NOT be sent to the channel before you go on each
line and press return. You can send output of shell command to IRC by 
executing irchat-Command-exec (C-c !).

The commands for controlling IRC are available in the command buffer.
See section "IRC Commands" for info.

The other buffer is the dialogue buffer. The conversation you have had in
IRC will be stored there. Notice that this buffer is not saved anywhere
unless you explicitly tell emacs to do so. This feature lets you see what
has been spoken about on the channel while you have been away, for
example. There is a number of commands for the dialogue buffer. There are
also a couple of commands for controlling the dialogue buffer from the
command buffer, namely C-c C-f, C-c DEL and C-c C-l. C-c C-f (or C-c F)
will freeze the dialogue buffer so that you can read the text there and
scroll the buffer. C-c DEL will scroll dialogue buffer one windowful
back and C-c C-l will refresh the irchat buffers. To scroll dialogue
forward one screenful you can use C-SPC or if you have only two buffers
visible you can use the default emacs scroll-other-window M-C-v.

Notice that there will be a capital F on the modeline of the dialogue
buffer if the dialogue buffer is frozen. Press C-c C-f again to unfreeze
it. A capital A signifies that you've marked yourself as being AWAY.

In the dialogue buffer there is a special keymap, which doesn't allow
for typing.@*
The commands there are:
@itemize @bullet
@item 
t for tagging the line
@item
o for switching buffers
@item
f for freeze
@item
DEL for scrolling up (backward)
@item
space for scrolling down (forward)
@item
$ for end of buffer
@item
> for end of buffer
@item
< for beginning of buffer
@item
m for sending message to your selected channel
@item
C-m for sending private message to user
@end itemize

There is also a mode for debugging irchat, which you can use if you want
to familiarize yourself with the server-client traffic or think that
irchat is handling something wrong. You invoke it with C-c C-d and end
with another C-c C-d.

CTCP (Client-To-Client-Protocol) is bound on prefix C-c C-c, it has
7 (seven) different commands:@*
@itemize @bullet
@item
v for version
@item
u for userinfo
@item
h for help
@item
c for clientinfo
@item
g for generic (ask any CTCP info, not nessessary on all clients)
@item
U for setting userinfo, asks it from minibuffer
@item
C-u for setting userinfo to contain current line from command-buffer
@end itemize

@node Commands, Customizing, Using, Top
@comment  node-name,  next,  previous,  up
@chapter IRC Commands

There are two kinds of commands in IRC, namely client commands and 
server commands. For using irchat.el it is useful to understand 
the difference.  For example, the client command /CLEAR for clearing 
the screen is used in the traditional clients. This command has no 
effect outside your screen, and the other IRC-users need not be notified. 
On the other hand, the server command /NICK changes your nickname. 
This command affects everyone and is sent to everyone on the same channel
with you (and to all servers in the network, so don't change nick
without need).

In irchat.el, all the server commands are directly available. If you have set
irchat-want-traditional simply by typing a slash (/) at the beginning of a 
line and then typing the server command with the parameters or by typing
the server command in *IRC Commands* buffer and then typing C-c c. 
This line will be sent directly to the server (no /QUOTE needed or allowed).
Notice, however, that you need to type the commands in full.
So you cannot use abbreviations like /N for /NAMES.
Also notice that the /M (message to user) command is really called /PRIVMSG.

For most commands, however, there is a better way. We have written emacs
commands for sending the line and bound them to keys. For example, for
/LIST you just say C-c l, C-c n for /NICK, C-c C-n for /NAMES and so on.

Some of there commands require parameters and they'll prompt you for
them. For example, the C-c n command will ask you for the new nickname
you with to use. If you at this point decide that you didn't really want
to change your nickname, press C-g (control-g) to cancel.

For some commands you may give an argument but you don't have to. For
example, to see the users on channel 42, you type C-u 42 C-c w when just
C-c w would show you all users. You may omit the channel number if you
mean the current channel, that is C-u C-c w for users on the same channel
with you. To ask users on named channels like @code{+glbf} or @code{#war}
you can use C-u - C-c w, which asks the channel name in minibuffer.
C-c n works in a similar fashion.

There exists a special /QUERY-like mode, in which every line you type
will be sent to one person via a private message. You begin it with C-c
2 and specifying the person to chat with, and end with another
C-c 2 with blank spaces as the name of the person.

There are two other ways for sending private messages, C-c p and C-c m.
With C-c m you'll be asked for the name of the person and then for the
text. You'll be typing the text in the minibuffer. The other way is to
type the text in the command buffer, and to press C-c p to send it.
irchat.el prompts you for the name of the person to send it to, the
default being the name of the person you sent your last private message
to. You can easily chat privately with two persons at a time by being in
a C-c 2 with one and C-c p:ing with the other.

When you join a channel, completion is also
available. C-c j +mTAB takes you to the channel
+My_very_long_channel_name, if there happens to be such a channel. 
You can also join a channel where some person you know is, just
use C-c j mta and you would be on channel where user mta is.

Notice that for C-c m, C-c p, C-c 2, C-c f (/WHOIS), and C-c k
(/IGNORE) nickname completion is available. What this means is that you
only need to type a few first letters of the nick, and you can use TAB
or SPC to fill in the rest. This feature is also available in the
command buffer, bound to C-i (TAB), where it completes the word
you typed last assuming it is a nickname. This is handy for typing long
nicks so that you get the CaSe correctly. For example, to say
"BigCheese: ..." you just need to say "biTAB:", assuming nobody
else (on IRC at the time) has nick that starts with bi.

@node Customizing, Authors, Using, Top    
@comment  node-name,  next,  previous,  up
@chapter Customizing irchat.el

The simplest way to customize is through the defvars, that is, variables.
You can place these either in your @code{.emacs} or in a special file. The most
important defvars for getting irchat work the way you want it to are
irchat-beep-on-bells and irchat-command-window-on-top, but there are many
others.

The most used irchat variables follow, setting other variables requires 
deeper understanding of irchat and is not recommended.

@itemize @bullet
@item
irchat-want-traditional: nil@*
Currently only used on determing whether the commands-window
is placed on bottom and to force regognition of old irc commands
that start with /.
@item
irchat-server: from environment variable IRCSERVER@*
Tells what irc server irchat tries to connect.
@item
irchat-service: from environment variable IRCPORT or 6667@*
Tells in what port the server resides.
@item
irchat-nickname: from environment variable IRCNICK or your loginname@*
What is your nickname in IRC.
@item
irchat-startup-channel: nil@*
Channel you try to join when starting irchat.
@item
irchat-format-string: ">%s<"@*
Format used when displaying your private messages to some person, 
person's name is inserted in place of %s.
@item
irchat-format-string1 "=%s="@*
Format used when displaying private messages to you from some person, 
person's name is inserted in place of %s.
@item
irchat-format-string2 "<%s>"@*
Format used when displaying messages to your primary channel,
senders name is inserted in place of %s, sender is on this primary channel.
@item
irchat-format-string3 "<%s:%s>"@*
Format used when displaying messages to some of your secondary channel,
senders name is inserted in place of first %s, channel the message has
arrived in place of second %s, sender is on this secondary channel.
@item
irchat-format-string4 "(%s)"@*
Format used when displaying messages to your primary channel,
senders name is inserted in place of %s, sender is NOT on this primary channel.
@item
irchat-format-string5 "(%s:%s)"@*
Format used when displaying messages to some of your secondary channel,
senders name is inserted in place of first %s, channel the message has
arrived in place of second %s, sender is NOT on this secondary channel.
@item
irchat-nam-suffix: ""@*
What suffix is to be added to every line you send. 
Not recommended to set, can be very annoying.
@item
irchat-beep-on-bells: nil@*
What to do with arriving bells, if nil don't ring bell (or flash).
If value is 'always always ring a bell when it arrives, other values
mean that only bell us when bell arrives in private message to us.
@end itemize

Variables for controlling CTCP (Client-To-Client-Protocol) and
irchat's own file transmission protocol.
@itemize @bullet
@item
irchat-client-userinfo: "No userinfo given."@*
What is given as userinfo for people requesting it from you.
@item
irchat-file-accept: nil@*
Do we want to accept file transmissions from users.
@item
irchat-file-confirm-save: t@*
Do we want irchat to ask us before it writes the file in our directory.
@end itemize

If you're not happy with the way the keys are set up, you may wish to
modify the key bindings. This is most conveniently done by defining them
in your irchat-Command-mode-hook.

There are lots of other hooks, one for each server reply and so forth.
For every servers message the irchat first tries to run function named 
irchat-handle- 'message' -hook, if that returns true it won't run 
internal handler for that message. The definition of these functions
is somewhat tricky, you have to define it via @code{defun} and then
use @code{setq} to set its variable-value as this function, see provided
example for details.
With these, an auto-greeter, for example, would be trivial to write.
Here is two examples of using hooks. First we set up
irchat-Command-mode-hook to read our abbreviations and require
our own hook-code if it is not yet loaded and then
we set up autogreeter.
BTW, auto-greeters are annoying most of the time.

@example
(setq irchat-Command-mode-hook
      '(lambda ()
         (make-variable-buffer-local 'blink-matching-paren)
         (setq blink-matching-paren nil)
         (setq local-abbrev-table irchat-mode-abbrev-table)
         (abbrev-mode 1)
         (require 'irchat-hooks)
         ))

(setq irchat-join-hook
      '(lambda (prefix rest)
	 (cond
;;; do not greet people coming to channel #report
	  ((and (not (string= prefix irchat-nickname))
		(string= "#report" rest))
	   t)
	  ((and (string= "INSERT_YOUR_FAVOURITE_PERSON_HERE" prefix)
		(string= irchat-current-channel rest))
;;; send the greeting as private message
	   (irchat-Command-message prefix (format "Greetings %s" prefix)))
	  (t nil))))

@end example

@node Authors,,Customizing, Top
@comment  node-name,  next,  previous,  up
@chapter irchat.history, reporting bugs etc.

The original irchat.el was written by Tor Lillqvist <tml@@hemuli.tik.vtt.fi>,
but the irchat.el from those days is much different from what it is now,
irchat.el is highly ... eh ...  dynamic right now. 

Thanks for developing are to nam <kny@@niksula.hut.fi>, 
cletus <jtp@@niksula.hut.fi> for listening luru's <luru@@tolsun.oulu.fi> 
and Kaizzu's ideas and implementing them. Then after that
Kaizzu <kmk@@cc.tut.fi> and mta <mta@@cc.tut.fi> are responsible
for developing irchat to what it is now.

There is, undoubtedly, lots of bugs and unintended features left in both
the code and the documentation. We welcome any suggestions and really
appreciate nice hacks and bug fixes.

The bugs and comments should be send to irchat <irchat@@cc.tut.fi>
which is mailing list for people interested in irchat. To join
that list send request to <irchat-request@@cc.tut.fi>.

This documentation was Kaizzu's first attempt ever to write emacs-info
-like text, and I probably failed miserably. Sorry.

P.S. I (mta) am responsible for the last revision of this text, so you
can as well accuse me.

@bye
