emacs-jabber/jabber.texi

\input texinfo          @c -*-texinfo-*-
@c $Id: jabber.texi,v 1.3 2004/01/30 21:25:13 legoscia Exp $
@c %**start of header
@setfilename jabber.info
@settitle jabber.el manual 0.4
@c %**end of header
@syncodeindex fn cp

@dircategory Emacs
@direntry
* jabber.el: (jabber).             Emacs Jabber client
@end direntry

@copying
This manual is for jabber.el, version 0.4.

Copyright @copyright{} 2004 Magnus Henoch, Tom Berger.

@quotation
Permission is granted to make and distribute verbatim copies or
modified versions of this manual, provided the copyright notice and
this permission notice are preserved on all copies.
@end quotation
@end copying

@titlepage
@sp 10
@titlefont{jabber.el}

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top jabber.el manual

@insertcopying

@end ifnottex

@menu
* Introduction::                
* Basic operation::             
* Groupchat::                   
* Services::                    
* Customization::               
* Hacking and extending::       
* Index::                       
@end menu


@node Introduction, Basic operation, Top, Top
@chapter Introduction

jabber.el is a Jabber client running under Emacs.  For more
information on the open-protocol instant messaging network Jabber,
please visit @uref{http://www.jabber.org}.

As a Jabber client, jabber.el is mostly just a face in the crowd,
except that it uses buffers where GUI clients have windows.  There is
a roster buffer, and to chat with someone you open a chat buffer, and
there are browse buffers (increasingly inexactly named) for
interaction with servers and services.  Then again, jabber.el delivers
excellent console performance and customizable hooks (if you have
speech synthesizer software, hook it up to your presence alerts).

Main unfeatures of jabber.el are SASL, SSL and TLS.  Beyond that,
there is nearly no support for advanced MUC features required for
moderation and other things.

@menu
* Contact::                     
@end menu

@node Contact,  , Introduction, Introduction
@section Contact

jabber.el is developed by Tom Berger (e-mail
@email{object@@intellectronica.net}, JID @code{object@@jabber.org.uk}) and
Magnus Henoch (e-mail @email{mange@@freemail.hu}, JID
@code{legoscia@@charente.de}).  There is a web page at
@uref{http://intellectronica.net/emacs-jabber/}, and a Sourceforge
project page at @uref{http://sourceforge.net/projects/emacs-jabber}.

@node Basic operation, Groupchat, Introduction, Top
@chapter Basic operation

This chapter is intended as an introduction to basic usage of
jabber.el.  If you have used Jabber before and are familiar with the
terminology, you might find it a bit too basic --- in that case, just
skim it, making sure to pick up the commands mentioned.

@menu
* Connecting::                  
* Chatting::                    
* Presence::                    
* Presence subscription::       
* Roster buffer::               
@end menu

@node Connecting, Chatting, Basic operation, Basic operation
@section Connecting

@findex jabber-connect
@findex jabber-disconnect
@cindex Connecting
@cindex Registering with server

I'll assume that you have already successfully installed jabber.el; if
not, consult the @file{README} file.  Also, make sure you have
@code{(require 'jabber.el)} in your @file{.emacs}.

Now, type @kbd{M-x jabber-customize}.  This brings up a customize
buffer for jabber.el.  The most important variables to customize are
@code{jabber-username} and @code{jabber-server}.  If for some reason
the JID of your server is not the same as its network name, change
@code{jabber-network-server} also.  Save your changes, and type
@kbd{M-x jabber-connect} to connect.

If you do not yet have a Jabber account, you can register one.  Enter
your desired username for @code{jabber-username} and the server you
wish to use for @code{jabber-server}, save, and type @kbd{C-u M-x
jabber-connect}.  If the server supports in-band registration, you
will be presented with a registration form to fill out and send.
There you will have to enter your username again.  Enter the same
username in both places, otherwise jabber.el will be confused.

If you successfully connect, jabber.el will download your roster and
display it in a buffer called @code{*-jabber-*}.

Now that you are connected, you can send @dfn{initial presence}.  This
means sending a notification of you being online to everyone on your
roster.  You don't have to do that, and if you don't noone can see
that you are online.  This is usually not what you want, but it is
occasionally useful.  To send presence, type @kbd{M-x
jabber-send-presence}.  You will be asked three questions; the
defaults will do for now.  @xref{Presence}, for more information.

To disconnect, type @kbd{M-x jabber-disconnect}.

@node Chatting, Presence, Connecting, Basic operation
@section Chatting

@cindex Chatting

In the roster display, you can access several menus through keystrokes
or mouse clicks.  You can bring one big menu up by pressing the second
mouse button, or you can bring up the ``chat menu'' by typing @kbd{C-c
C-c}.  If you do the latter while point is on a roster entry, that
entry will be the default value when you are asked for whom to chat
with.

Now, try opening a chat with someone.  In the default configuration,
you will hear a beep and see ``Message from @var{person}'' in the echo
area.  This is exactly the same message you receive if the other
person sends a message to you.  In any case, go to the buffer
@code{*-jabber-chat-:-@var{person}-*} and start chatting.  Most
normal keystrokes open the minibuffer where you can type a message.

@node Presence, Presence subscription, Chatting, Basic operation
@section Presence

@cindex Presence
@cindex Sending presence
@findex jabber-send-presence

``Presence'' is the Jabber term for letting other people know that you
are online, and additionally how ``available'' you are.  There are
three elements to presence: availability status (called ``show''),
status message, and priority.

Your show status may either be empty (meaning simply ``online''), or
one of @code{away}, @code{xa}, @code{dnd} and @code{chat}, meaning
``away'', ``extended away'' (i.e. away for an extended period), ``do
not disturb'', and ``free for chat'', respectively.  This information
is available to everyone subscribing to your presence, but technically
it does not restrict anyone's actions.  You can chat with people even
if you claim to be away.

The status message is a short text complementing your show status,
such as ``at home'', ``working'', ``phone'', ``playing games'' or
whatever you want.  It is sent to everyone subscribing to your
presence, but not all clients prominently display it to the user.

The priority is only interesting if you are running more than one
Jabber client at a time accessing the same account.  In that case,
messages sent to you without an indication of which client to send to
are sent to the client with the highest priority.

To set your presence, use the function @code{jabber-send-presence}.
It can be called both interactively and in Lisp code.  For the latter
case, use something like @code{(jabber-send-presence "away" "idle for
10 minutes" 10)}.

@node Presence subscription, Roster buffer, Presence, Basic operation
@section Presence subscription

@cindex Presence subscription
@findex jabber-send-subscription-request

Having permission to view the presence status of a person is called
@dfn{subscribing to his presence}.  Presence subscription between two
persons can be asymmetric.

When jabber.el receives a presence subscription request, it will
present it to you in an alert requiring immediate response, and offer
you to send a subscription request back to that person.

To request subscription to someone, type @kbd{M-x
jabber-send-subscription-request}.  You will be prompted for the JID
to send it to.  This command can also be accessed through the Roster
menu, by typing @kbd{C-c C-r} in the roster buffer.

@node Roster buffer,  , Presence subscription, Basic operation
@section The roster buffer

@cindex Roster buffer
@cindex Menus
@cindex Key bindings
@findex jabber-display-roster

The roster buffer is called @code{*-jabber-*}.  It simply contains a
list of the contacts on your roster.

In the roster buffer, any command which requires a JID will default to
the JID under point when called.  These commands can be called through
either keyboard menus or mouse menus.  To open a menu with the mouse,
simply press the second mouse button over the JID in question.  This
will bring up a menu with all available actions.  The keyboard menus
are split into categories: Chat, Roster, Information, MUC (Multi-User
Chat, or groupchat) and Services, opened by @kbd{C-c C-c}, @kbd{C-c
C-r}, @kbd{C-c C-i}, @kbd{C-c C-m} and @kbd{C-c C-s}, respectively.

You can call @code{jabber-display-roster} to redisplay your roster
according to changed preferences (@pxref{Customizing the roster
buffer}).  This will not refetch your roster from the server.
Refetching the roster is usually not needed, since updates are pushed
to clients automatically.

You can choose not to have the roster updated automatically on
presence changes (@pxref{Presence alerts}).  In that case, you need to
call @code{jabber-display-roster} manually.

@node Groupchat, Services, Basic operation, Top
@chapter Groupchat

@cindex Groupchat
@cindex MUC
@findex jabber-groupchat-join

The groupchat menu can be accessed by typing @kbd{C-c C-m} in the
roster buffer.  You can also type the commands directly, as will be
shown here.

To join a groupchat, type @kbd{M-x jabber-groupchat-join}.  You will
be prompted for the groupchat to join, and your nickname in the
groupchat.  This nickname doesn't need to have any correlation to your
JID; in fact, groupchats are usually (but not always) configured such
that only moderators can see your JID.

Groupchat messages will be displayed in a buffer called
@code{*-jabber-groupchat-:-@var{groupchat}-*}.  It works much like the
chat buffer.

To leave a groupchat, type @kbd{M-x jabber-groupchat-leave}.

If you are the owner of a groupchat, you can change its configuration
by typing @kbd{M-x jabber-groupchat-get-config}.  A configuration form
will be rendered in new buffer.

@node Services, Customization, Groupchat, Top
@chapter Services

Not every Jabber entity is a physical person.  There are many
automatic entities, called servers, services, components, agents,
transports and other names.  The use of these is described here.

The functions described in this chapter use @dfn{browse buffers}.
Browse buffers are named @code{*-jabber-browse-:-@var{service}-*},
sometimes with a numerical suffix.  They have the same keybindings as
the roster buffer, and if you call a function operating on a JID while
point is over a JID, that JID will be the default value, so you don't
have to type it or copy it yourself.

@menu
* Service discovery and browsing::  
* Registering::                 
* Searching::                   
@end menu

@node Service discovery and browsing, Registering, Services, Services
@section Service discovery and browsing

@cindex Service discovery
@cindex Browsing
@findex jabber-get-browse
@findex jabber-get-disco-items
@findex jabber-get-disco-info

To find services you want to use, you need to discover them first.
This can be done with either service discovery or browsing.  Service
discovery is the newer and preferred protocol, while browsing is still
used by much software.  The use of both is very similar.

The most common use of service discovery is to browse your home
server, to see what services are provided locally.  Note, however,
that this is no restriction; you can use services from all over the
network.

To start browsing, type @kbd{M-x jabber-get-browse} and enter the JID
you want to browse.  For service discovery there are two commands,
@code{jabber-get-disco-items} and @code{jabber-get-disco-info},
depending on whether you want information about that specific JID or
about services related to it, respectively.

These commands can be accessed from the Info menu, which is opened by
typing @kbd{C-c C-i}.

@node Registering, Searching, Service discovery and browsing, Services
@section Registering

@cindex Registration
@cindex Cancelling registration
@cindex Changing password
@cindex Gateway registration
@cindex Password change
@findex jabber-get-register

Some services, in particular user directories and gateways to legacy
IM systems, require registration.  To register with such a service,
either type @kbd{M-x jabber-get-register} or select it from the
Service menu, which is opened by typing @kbd{C-c C-s}.  You have to
know the service's JID, possibly from service discovery.
(@pxref{Service discovery and browsing})

This is also the way to change your registration details, e.g. your
password --- just ask to register with that service again.  To change
the password of your Jabber account, ask to register with your Jabber
service.

Please note that any passwords sent in this way will be sent in
cleartext to your Jabber server, as jabber.el doesn't support
encryption yet, and possibly sent in cleartext from your server to the
server hosting the service.

jabber.el will then request a registration form from that service.  If
for some reason the service does not answer (maybe network problems,
or some services neither support registration nor report errors about
that) that will be the last thing you saw about it.  jabber.el will
not report timeout errors, but rather simply wait until you shut it
down.

Once the response arrives, the form will be rendered in a browse
buffer.  Just fill out the fields, and hit Submit.  You will receive
confirmation of your registration in the echo area.

To cancel an existing registration (and also for cancelling your
Jabber account, if you sent a registration request to your server),
hit Cancel.  The unregistration will be confirmed in the echo area.

@node Searching,  , Registering, Services
@section Searching

@cindex Searching
@findex jabber-get-search

Some services, notably user directories and gateways to legacy IM
systems, allow searching.  Searching in Jabber generally means
searching for someone's JID, but the protocol is general enough to
support most databases.

To search a service, either type @kbd{M-x jabber-get-search} or select
it from the Service menu, which is opened by typing @kbd{C-c C-s}.

Just like with registration, this command sends a request for a search
form, and displays it if and when the response arrives.  Enter your
search and submit it.  Search results will be displayed in a different
browse buffer.

@node Customization, Hacking and extending, Services, Top
@chapter Customization

jabber.el is intended to be customizable for many tastes.  After all,
this is Emacs.  To open a customization buffer for jabber.el, type
@kbd{M-x jabber-customize}.

@menu
* Connection settings::         
* Customizing the roster buffer::  
* Customizing alerts::          
@end menu

@node Connection settings, Customizing the roster buffer, Customization, Customization
@section Connection settings

@code{jabber-username} is the username part of your JID.

@code{jabber-server} is the JID of your server, i.e. the hostname part
of your JID.  This is usually, but not necessarily, the same as the
hostname of the server.

@code{jabber-network-server} is the hostname or IP address of your
server.  If it is set to @code{nil}, jabber.el will use the name in
@code{jabber-server}.

@code{jabber-port} is the TCP port of the server to connect to.  This
is 5222 in almost all cases.

@code{jabber-password} is your password.  You have the option to set
it here, in which case it will be stored in cleartext in your
@file{.emacs} file.  If this is set to @code{nil}, you will be prompted for
your password every time you connect.

@code{jabber-resource} is the resource you want to log in under.  This
only matters if you are connected to the same account from different
clients or different computers, since each connection must have a
unique resource.  You might want to set this to your hostname.

@code{jabber-default-priority} is the default priority sent with your
presence.  Regardless of what you have here, you can change your
priority during a session with @code{jabber-send-presence}.
@xref{Presence}, for more information on priority.

@code{jabber-nickname} is your default nickname for groupchats.

@node Customizing the roster buffer, Customizing alerts, Connection settings, Customization
@section Customizing the roster buffer

@code{jabber-debug} toggles extended debug output.  Currently, this
means two things.  In the roster buffer, you can see the properties of
each contact.  All XML stanzas sent and received are logged in the
buffer @code{*-jabber-xml-log-*} in list format.  @xref{XML
representation}.

@code{jabber-sort-order} controls how roster items are sorted by
presence.  It is a list containing strings corresponding to show
status (@pxref{Presence}) or @code{nil}, which represents offline.

@code{jabber-show-resources} controls when your contacts' resources
are shown in the roster buffer.  The default is to show resources when
a contact has more than one connected resource.

@node Customizing alerts,  , Customizing the roster buffer, Customization
@section Customizing alerts

When an event happens (currently including presence changes, incoming
messages, and completed queries) you will usually want to be
notified.  Since tastes in this area vary wildly, these alerts are
implemented as hooks, so you can choose which ones you want, or write
your own if none fit.

Actually, if you don't want to write your own, stop reading this
section and just read @ref{Provided alerts}.

Many kinds of alerts consist in displaying a text message through a
certain mechanism.  This text message is provided by a function which
you can rewrite or replace.  If this function returns @code{nil}, no
message is displayed, and non-textual alerts refrain from action.

The hooks take different arguments depending on category.  However,
they all have in common that the last argument is the result of the
message function.  The message function for each category takes the
same arguments as the corresponding hooks, except for that last
argument.

Was that confusing enough?  The preceding paragraph will be expressed
in code in the following subsections.

@menu
* Provided alerts::             
* Presence alerts::             
* Message alerts::              
* Info alerts::                 
@end menu

@node Standard alerts, Presence alerts, Customizing alerts, Customizing alerts
@subsection Standard alerts

Six alerts are already written for all three alert categories.  These
all obey the result from the corresponding message function.

The @code{beep} alerts simply sound the terminal bell by calling
@code{ding}.  They are enabled by default.

The @code{echo} alerts display a message in the echo area by calling
@code{message}.  They are enabled by default.

The @code{switch} alerts switch to the buffer where the event occurred
(chat buffer for incoming messages, roster buffer for presence
changes, browse buffer for completed queries).  They are disabled by
default.  Take care when using them, as they may interrupt your
editing.

The @code{wave} alerts play a sound file by calling
@code{play-sound-file}.  No sound files are provided.  To use this,
enter the names of the sound files in
@code{jabber-alert-message-wave}, @code{jabber-alert-presence-wave}
and @code{jabber-alert-info-wave}, respectively.

The @code{screen} alerts send a message through the Screen terminal
manager (see @uref{http://www.gnu.org/software/screen/}).  They do no
harm if called when you don't use Screen.

The @code{ratpoison} alerts send a message through the Ratpoison
window manager (see @uref{http://ratpoison.sourceforge.net/}).  They
do no harm if used when you're not running X, but if you are running X
with another window manager, the calls to ratpoison will stall
indefinitely.  Avoid that.

All these functions are near the end of the @file{jabber.el} file.
You can use them as templates or inspiration for your own alerts.

@node Presence alerts, Message alerts, Provided alerts, Customizing alerts
@subsection Presence alerts

Set @code{jabber-alerts-presence-message-function} to your desired
function.  This function should take four arguments, @var{who},
@var{oldstatus}, @var{newstatus} and @var{statustext}.  @var{who} is
the JID symbol (@pxref{Roster structure}), @var{oldstatus} and
@var{newstatus} are the previous and current stati, respectively, and
@var{statustext} is the status message if provided, otherwise nil.

@var{newstatus} can also be one of @code{"subscribe"},
@code{"subscribed"}, @code{"unsubscribe"} and @code{"unsubscribed"}.

The default function, @code{jabber-presence-default-message}, returns
@code{nil} if @var{oldstatus} and @var{newstatus} are the same, and in
other cases constructs a message from the given data.

All presence alert hooks take the same arguments plus the additional
@var{proposed-alert}, which is the result of the specified message
function.  This last argument is usually the only one they use.

@node Message alerts, Info alerts, Presence alerts, Customizing alerts
@subsection Message alerts

@node Info alerts,  , Message alerts, Customizing alerts
@subsection Info alerts

@node Hacking and extending, Index, Customization, Top
@chapter Hacking and extending

@menu
* XML representation::          
* Roster structure::            
* Listening for new requests::  
* Sending new requests::        
@end menu

@node XML representation, Roster structure, Hacking and extending, Hacking and extending
@section XML representation

@node Roster structure, Listening for new requests, XML representation, Hacking and extending
@section Roster structure

@node Listening for new requests, Sending new requests, Roster structure, Hacking and extending
@section Listening for new requests

@node Sending new requests,  , Listening for new requests, Hacking and extending
@section Sending new requests

@node Index,  , Hacking and extending, Top
@unnumbered Index

@printindex cp

@bye