,--------------------------------------------------------------------,
|                                                                    |
|                  ickle - A Gtk-- ICQ2000 Client                    |
|                                                                    |
`--------------------------------------------------------------------'

   Version 0.3.2                     http://ickle.sourceforge.net/
  (Codename: moo)




 --------------------------------------------------------------------
 - Contents                                                         -
 --------------------------------------------------------------------

1. Features

2. Installation
- 1. Prerequisites
- 2. Compiling
- 3. Installation

3. Keyboard shortcuts

4. Translation (of character sets)

5. Icons

6. Sounds + Noises on events

7. Importing contacts

8. Custom away messages

9. More info for developers
- 1. Contributing to ickle
- 2. Anonymous CVS
- 3. Alternative client developers (or using the libicq2000 library)

10. Comments, bug fixes, etc..

11. License




 --------------------------------------------------------------------
 - Features                                                         -
 --------------------------------------------------------------------

ickle supports:
- Message sending/receiving
- URL sending/receiving
- SMS sending/receiving, including delivery reports
- Status changes
- Fetching user info from server
- Fetching/setting away messages
- Custom away messages
- Authorisation Requests
- "User Added You" messages

Features:
- Autoconnect, autoreconnect and retries
- Easy history browsing
- GNOME applet
- Command-line control
  (through ickle_control)
- Autoaway on timer
- Executing shell-commands on events

See the TODO for information about planned features in
progress. Please don't duplicate requests for features already
mentioned in the TODO. Send legitimate feature requests to the
ickle-users mailing list on sourceforge, the address is
<ickle-users@lists.sourceforge.net> and you don't need to subscribe to
post.

ickle is in no way affiliated with 'ICQ' or 'Mirabilis'.



 --------------------------------------------------------------------
 - Installation                                                     -
 --------------------------------------------------------------------

   ------------------------------------------------------------------
   - Prerequisites                                                  -
   ------------------------------------------------------------------

You will need:
- libicq2000 (0.3.2 or greater)
- libstdc++ library
- gtkmm version (1.2.5 or above)
- gtk+ library
- libsigc++ library
   (1.0.0 or above - not the unstable 1.1 though)

The last two should be installed if you have gtkmm working and
installed. Read more below for the prerequisites for the GNOME applet.

Distribution   Packages required
------------   -----------------
Redhat 7.1     gtk+-1.2.9-4.i386.rpm, gtk+-devel-1.2.9-4.i386.rpm,
               libstdc++-2.96-81.i386.rpm, libstdc++-devel-2.96-81.i386.rpm
               There are no rpms provided by Redhat for gtk-- or sigc,
               so you'll have to compile from sources, or get the rpms
               supplied by Ximian. See links below.

Other          I'd appreciate any input from people on success/failures.
Redhats

SuSE 7.0       The rpms for gtkmm are very out of date on SuSE 7.0, you'll
	       either have to compile gtk, gtk-- and sigc++ from sources
               or try fudging it with newer rpms for 7.2 I'm afraid.

SuSE 7.1       sigc++.rpm, gtk.rpm, gtk-devel.rpm, gtkmm.rpm,
               gtkmm-devel.rpm

SuSE 7.2       libsigc++.rpm, libsigc++-devel.rpm, gtk.rpm,
               gtk-devel.rpm, gtkmm.rpm, gtkmm-devel.rpm, gpp.rpm,
               gppshare.rpm, libgpp.rpm

Mandrake 8.1   You will need these rpms and their dependancies:
               libstdc++2.10-devel-2.96-0.62mdk.i586.rpm
               libgtkmm1.2-devel-1.2.7-2mdk.i586.rpm   
               libgtk+1.2-devel-1.2.10-14mdk.i586.rpm
               libsigc++1.0-devel-1.0.3-2mdk.i586.rpm
               (thanks Meindert Niemeijer for contributing this)

Other          At a guess similar to Mandrake 8.1, some more info is needed
Mandrakes      here.


For RPM distributions (Redhat, SuSE, etc..) - make sure you install
the 'development' RPMs for all these libraries as well. Usually these
are called library-devel.rpm or similar. I'm trying to build up a list
of the names of the rpms that are required, so send me info about what
you needed for your distribution if it's not already here.

Debian         libstdc++2.10 and libstdc++2.10-dev
(+ Progeny,    libgtkmm1.2 and libgtkmm-dev
 etc..)        libsigc++0 and libsigc++-dev

Sources for these libraries can be found at the following addresses:
libicq2000: http://libicq2000.sourceforge.net/
libstdc++:  http://www.gnu.org/software/gcc/libstdc++/ 
            (should have come with your version of gcc)
gtk:        http://www.gtk.org/
gtkmm:      http://gtkmm.sourceforge.net/
libsigc++:  http://libsigc.sourceforge.net/

GNOME applet:

Additionally, if you want to build the GNOME applet you will also need
the required GNOME libraries.

For Debian based distributions it should suffice to have the following
packages installed (and their dependencies as well).

libgnome32
libgnome-dev
libpanel-applet-dev
libpanel-applet0

And for RPM based distributions the corresponding packages should suffice
(again, along with their dependencies). The names may not be exactly the
same but there should be a package named libpanel_applet-dev or
libpanel_applet0-dev, having that installed along with it's dependencies 
should probably suffice.

Redhat users note: due to a missing dependancy in one of the Ximian rpms
for gnome ickle may pass configure but fail at compile time due to
missing orbit headers. You need to ensure you have the orbit development
rpm installed.

If you encounter packages that you had to install besides the ones
mentioned here, please help out by sending a list over the packages you
had to install along with some info about your platform (distribution/os,
version, etc).

Sources for the GNOME libraries can be found at:

http://www.gnome.org

   ------------------------------------------------------------------
   - Compiling                                                      -
   ------------------------------------------------------------------

Generic configure instructions can be found in INSTALL. These are the
brief instructions for ickle:

1. Type './configure'

 If you have the gnome dependencies installed ickle will by default
 compile the gnome applet. A message after configure will confirm
 whether this is going to happen. The option --without-gnome will
 always prevent the gnome applet from being compiled.

2. Type 'make' to compile the package

On some systems that don't have gmake as the default make you might
have to install and explicitly use that (usually named as gmake in
that case).

   ------------------------------------------------------------------
   - Installation                                                   -
   ------------------------------------------------------------------

1. Type 'make install' as root to install ickle.

Easy as that.

To run ickle you should be able to type simply 'ickle', assuming you
have the directory into which you installed ickle in your
path. (usually /usr/local/bin)

If you built it as a GNOME applet the executable will instead be named
'ickle_applet'. You should then run ickle by right-clicking the panel
and choosing Applets->Network->Ickle ICQ.



 --------------------------------------------------------------------
 - Keyboard shortcuts                                               -
 --------------------------------------------------------------------

Key           Action
---           ------
Ctrl-Enter    Send Message from Message window
or Alt-S

Alt-C         Close Message window
or ESC



 --------------------------------------------------------------------
 - Translation (of character sets)                                  -
 --------------------------------------------------------------------

I've now added support for translating between different character
sets. This can be reached by going to Settings. For example, many
Russian users will want to use the Russian character map file to
translate between windows-cp1251 and KOI8-R.



 --------------------------------------------------------------------
 - Icons                                                            -
 --------------------------------------------------------------------

The default set of icons distributed with ickle are designed by
me. They're not amazing but they do the job. I've also included some
more familiar ones. To change between icon sets, go to Settings and
then choose from the list. You are welcome to design you own set (or
improve on mine) and contribute them.



 --------------------------------------------------------------------
 - Sounds + Noises on events                                        -
 --------------------------------------------------------------------

You can run any arbitrary shell command on an event - go into Settings
and then Events to set this up. This is the system by which you can
make noises on a message. Following the unix philosophy the sound
support is left to your choice of tools which best fit the job of
playing sound. Here are some suggestions of shell commands to make
some noise:

1. use 'echo -e "\a"' - this usually produces a beep on the bell, but
   doesn't work reliably across different platforms.

2. use 'play wavfile.wav' - the play utility is a standard utility to
   play wav files to your sound device. Part of the sox package on
   most systems.

3. get the beep program from:
    http://johnath.com/beep/
   I use the command-line:
    beep -f 523 -l 100 -D 20 -n -l 100 -f 440
   to play a little tune

4. get a speech synthesis program and then have it announce the person
   who is sending you the incoming message. *Very cool* :-) I tried
   out the program 'festival' since that was the easiest to get access
   to for me (there's a debian package). I'm sure there are lots of
   other alternative text-to-speech software. For festival use the
   command-line:
    echo "Message from %a" | festival --tts


 --------------------------------------------------------------------
 - Importing contacts                                               -
 --------------------------------------------------------------------

There are three simple perl scripts in the scripts directory to
convert from gnomeicu, licq and micq contact lists across to ickle. I
might write something similar for windows if I get any requests for
it.



 --------------------------------------------------------------------
 - Custom away messages                                             -
 --------------------------------------------------------------------

Auto responses and event commands make the following substitutions
based on the contact who sent the event and the time it was sent:
  %i  contact's external IP
  %p  contact's external port
  %e  email
  %n  first and last name, separated by a space
  %f  first name
  %l  last name
  %a  ICQ alias
  %u  ICQ UIN
  %c  SMS mobile number
  %s  contact's status string (e.g. "Online")
  %t  event time, like "Dec 24 02:09:41 AM"
  %T  event time, like "Dec 24 02:09 EST"
  %m  number of messages pending from contact
  %%  literal '%' sign

Any lines beginning with "|" will be passed to a shell for execution,
with all %-substitutions enclosed in double quotes and metacharacters
(hopefully) escaped. The standard output of the shell command will be
inserted into the response. So you can have an N/A message like this:

    Hi, %a!
    |/usr/games/fortune -o
    |echo `date +%%s` %i %a >> $HOME/.log

which should attempt to send an offensive fortune, then run the
equivalent of 'echo `date +%s` "ipaddr" "alias" >> $HOME/.log'.



 --------------------------------------------------------------------
 - More info for developers                                         -
 --------------------------------------------------------------------

   ------------------------------------------------------------------
   - Contributing to ickle                                          -
   ------------------------------------------------------------------

In the spirit of opensource ickle is a community effort with
contributions welcomely accepted. If it's just a small patch for a bug
fix, or you are wishing to help out more big time in the development
of ickle or libicq2000 please feel free to contribute.

Now that ickle has become something bigger than my own little baby
project I'd prefer patches and development related questions to go to
the sourceforge ickle-devel mailing list - so they can be seen by all
the developers rather than just me. I'd suggest subscribing, although
you can post even if you aren't subscribed.
  <ickle-devel@users.sourceforge.net>

For submitting patches, please:

a) Make sure you are working on a recent checked out copy of the
   anonymous CVS, often the problem has been fixed already.

b) Follow code conventions in the layout of the code as it is at the
   moment.

c) Produce the diff by running 'cvs diff -uN > my-patch.diff'

d) Email the diff to <ickle-devel@lists.sourceforge.net>

   ------------------------------------------------------------------
   - Anonymous CVS                                                  -
   ------------------------------------------------------------------

If you want to get the bleeding edge latest version of ickle it is
available on anonymous CVS, see the following url:
http://sourceforge.net/cvs/?group_id=36654

The modulename is ickle. Once you have checked out the sources, you
must run the autogen.sh file to generate configure. You need autoconf
> 2.5, automake > 1.5  and libtool 1.4.2.

Beware though - the CVS is often unstable inbetween releases. Please
subscribe to the ickle-devel mailing list on sourceforge to stay up to
date on what is going on in CVS. You will also probably want to
subscribe to ickle-commits, so you can see what work is being done on
the source. If you find a problem in CVS please check back in the
archives for ickle-devel to check it hasn't already been
acknowledged/solved.



   ------------------------------------------------------------------
   - Alternative client developers                                  -
   ------------------------------------------------------------------

ickle is actually split into two parts, the ickle GUI and the
libicq2000 library. If you are interested in developing your own
client you can use just the libicq2000 on it's own.

You should see the libicq2000 project homepage:
 http://libicq2000.sourceforge.net/



 --------------------------------------------------------------------
 - Comments, bug reports, etc..                                     -
 --------------------------------------------------------------------

User related feature requests should be sent to:
  <ickle-users@lists.sourceforge.net>

Bug reports and development related comments should be sent to:
  <ickle-devel@lists.sourceforge.net>

For bug reports ensure you include these details:
- Version of ickle
- Source (tarball, CVS)
- Distribution
- gcc version (type: gcc -v)
- libstdc++ version (type: ls /usr/lib/libstdc++*)
- gtkmm version (type: gtkmm-config --version)
- sigc version (type: sigc-config --version)
- gtk+ version (type: gtk-config --version)
- Any other quirks of your system..

Thanks.

(You don't need to be subscribed to post to either list)

You can send me mail to:
  <barnaby@beedesign.co.uk>
Although ickle is more than a one-man/developer band now, so I'd
  prefer the above lists be used where relevant.

Send me a message (ICQ# 12137587 Alias bee) if you like ickle.

 --------------------------------------------------------------------
 - License                                                          -
 --------------------------------------------------------------------

ickle is released under the GNU GPL license, see COPYING for copying
conditions.


Thank you, and good mornin'.