Some new packets, fixing "Unknown SNAC" errors.

[emchat] / README

-*- outline -*-

* Introduction

http://www.emchat.org/INSTALL

This file is best viewed under (S)XEmacs. Press C-c C-o now to
see the outline of topics. You can use (S)XEmacs menu to
navigate and hide/show different topics. (C-c means Control
and c; M-x means Meta and x.)

I publish this package in the hope of making more people
appreciate (S)XEmacs and Lisp.

You can contact me for anything at <steve@emchat.org>

* Feature list

- EMchat is written entirely in elisp
- EMchat uses the latest version of the ICQ protocol. (OSCAR)
- Send/receive messages
- Send/receive URL type messagse
- Send/Receive authorisation request messages
- Approve/Decline incoming auth requests
- Query ICQ users' meta info
- Search for ICQ users
- Dynamically add new users to your contact list (recent protocol
  changes broke this)
- Play sounds for different events.
- Auto online after a auto away/na.
- Auto response away/na/dnd/occ messages.
- Different auto response messages if EMchat has idled away/na
- Auto reconnect if you are kicked off ICQ.
- Gnus style smileys
- Gnus style text emphasis (underline, bold, italic, etc)
- "Clickable" hyperlinks for URL's, email addresses, and Unix manual page titles
- climm (mICQ) style per contact history logs
- ERC/Riece style modeline activity indicator
- Works in both a GUI environment and on a console/TTY (even both at the same time)
- A dockable frame that tracks the number of unread messages.
- Interactive customisation through (S)XEmacs Custom widgets.
- Key binding, "scripting" in elisp.
- Allow other users/contacts to psycho-analyse themselves
- Display X-Face/Colour Face header images in buddy buffer.
- An "oops" function
- Customisable semi-automation


EMchat cannot yet transfer files, chat, or anything that requires a
peer-to-peer direct TCP connection.  This is not a limitation of
EMchat, but rather of XEmacs.  As yet, XEmacs can not "listen" for an
incoming TCP connection.

P2P _IS_ coming!  SXEmacs now has server sockets, we just have to use
em in EMchat.

* Installation
See the file 'INSTALL' in this directory.

There are a few mailing lists. See <http://www.emchat.org/#maillist>

Have fun!

* Submitting Patches

If you've got a patch for a bug fix or some wiz-bang new feature mail
them to <emchat-devel@emchat.org>.  The EMchat developers will review your
contribution and either accept it and add it to the EMchat code, or
reject it.  Whether accepted or rejected, you'll hear back from us.

Please be aware though that because of spam levels the EMchat mailing
list is a members-only posting.  If you are not subscribed you'll have
to wait for the moderator to process your post.  Please be patient,
he's a rilly busy guy. :-)

* Faq and tips

** password

How to save password?

M-x customize-variable RET emchat-user-password
Or simply, (setq emchat-user-password "mypassword") in your
`user-init-file'. 

** "M" vs "m" (send-message)

Commands in capital letters prompt you for aliases/uin while
those in small letters search for aliases/uin around the
cursor in emchat buffers, and perform actions on them. For
example, "m" inside an incoming message acts like a reply.

** alias vs uin

"JackaLX" is my alias while "34307457" is my uin. In all prompts
of entering an icq person, you can enter either an alias or
an uin, although only alias completing read is provided. 
(Press TAB when entering an alias!)

** message/alias history

Use M-p/M-n or UP/DOWN to navigate history in prompts of
entering alias or messages.
Use M-r/M-s to search history.

** log file size

Watch out for monster emchat-log buffer size! Use M-x
emchat-log-new-file occasionally.

As of version 0.2.16 Eicq will automatically save the log file when
you disconnect from ICQ.  You can change this behaviour with
'M-x emchat-customize' in the 'emchat-log' group.

** hooks

If you want to customize anything fancy:

emchat-buddy-mode-hook
emchat-log-mode-hook
emchat-new-message-hook
emchat-read-message-hook
emchat-status-update-hook
emchat-system-message-hook

** Using EMchatWharf

EMchatWharf is a tiny frame that shows the number of unread messages you
have.  It is suitable for docking into the GNOME panel (YMMV).  I use
it with Sawfish WM (in a "sawlet" dockapp thingy).  And I've also used
EMchatWharf in FVWM by simply setting the geometry and making it
sticky from my FVWM rc file.

To get the EMchatWharf frame put into your (S)XEmacs init file:

(require 'emchat-wharf)
(setq emchat-wharf-frame-use-p t)
(add-hook 'emchat-new-message-hook #'emchat-wharf-inc-messages)
(add-hook 'emchat-system-message-hook #'emchat-wharf-inc-system)
(add-hook 'emchat-read-message-hook #'emchat-wharf-dec-messages)

*** Add Riece integration to EMchatWharf

Riece is a VERY good emacs IRC client (I highly recommend it).  If
you'd like to know when there is activity in your Riece frame, you can
have EMchatWharf tell you.  All you have to do is add this to the
above EMchatWharf settings...

(setq emchat-wharf-notice-riece-flag t)
(add-hook 'riece-biff-activity-hook #'emchat-wharf-riece-active)
(add-hook 'riece-biff-clear-hook #'emchat-wharf-riece-inactive)

And then turn on riece-biff in your Riece settings

** EMchat in its own frame

You can optionally start EMchat in its own frame with:

(setq emchat-start-in-new-frame t)

** Using EMchat-Track

EMchat-Track is a modeline indicator that tells you when you have new
messages.  To turn it on, just put in your (S)XEmacs init file:

(setq emchat-track-enable t)

** Using EMchat-History

EMchat-History are per contact history files.  Basically individual logs
for each contact.  Turn it on with:

(setq emchat-history-enabled-flag t)

** Displaying X-Face or colour Face Images in buddy buffer

You can display X-Face images (or colour face images) in the buddy
buffer, but it does require a little setting up, both in EMchat and in
BBDB.

*** EMchat Setup

This is the easy part, all you need to do is:

  (setq emchat-buddy-show-xface t)

*** BBDB Setup

First of all, you need a new field called "icqnick" for each EMchat
contact that is in your BBDB.  This field's value is the alias name
from EMchat (the name displayed in the buddy buffer).

  M-x bbdb-insert-new-field RET icqnick RET

  answer `yes' to the prompt about `icqnick' isn't a known field,
  define it?

  Then just give it the desired value (contact name)

You'll also have to set up BBDB to collect X-Face and colour face
headers from your mail.  For some docs on how to do that, see:

  <http://www.emacswiki.org/cgi-bin/wiki/BbdbFaces>

** newline

How to enter new lines in minibuffer? 

        Type 'Hello C-q 12 World'

To get:

        Hello
        world

** (S)XEmacs Init File tips

(resize-minibuffer-mode 1)