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

   Version 0.2.2                     http://ickle.sourceforge.net/





 --------------------------------------------------------------------
 - 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. More info for developers
- 1. Contributing to ickle
- 2. Anonymous CVS
- 3. Alternative client developers (or using the libicq2000 library)

9. Comments, bug fixes, etc..

10. License




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

ickle supports:
- Message sending/receiving
- URL sending/receiving
- SMS sending/receiving, including delivery reports
- Status changes
- Fetching user info from server
- Fetching away messages

Features:
- Autoconnect, autoreconnect and retries
- GNOME applet

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 ideally, 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:
- libstdc++ library
- gtkmm version (1.2.5 or above)
- gtk+ library
- libsigc++ library

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

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:
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.

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 rightclicking 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"' - these 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

   This uses the little documented event substitution feature in
   ickle, certain %X symbols will be substituted for information about
   the message. Eg. %a = alias of contact sending message, %i = their
   IP address. There are many more - this feature will be documented
   better in a future release.


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

I've written a simple perl script in scripts/licq2ickle.pl that you
can run and will convert your licq contacts over to ickle. There is
also a similar script the micq. I might write something similar for
windows if I get any requests for it.



 --------------------------------------------------------------------
 - 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.

IMPORTANT NOTE: The CVS is provided primarily for developers and
developers alone. The fact anyone can check it out anonymously I just
view as a convenience for these developers. If you believe it to be
'elite' running a CVS version of a program or like running the
'cutting-edge' then I strongly discourage use of the CVS. Timely
releases are made of ickle when it is sufficiently stable for the
general public. If you decide to go against this advice then be sure
to know I will not support you in any problems you have compiling the
CVS and I will not answer stupid/repeat questions that have been
discussed on ickle-devel. I spend enough time supporting people who
should be using releases on releases let alone supporting people who
should be using releases on CVS.
DO NOT POST QUESTIONS ABOUT THE CVS VERSION TO THE SOURCEFORGE FORUMS.
I want discussion of CVS confined to ickle-devel. Don't let this
dissuade legitimate developers wanting to get into the project, we are
happy to welcome you in and help you get into the project. (End of rant).

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. I have an example
use of it like this as a simple command-line autoresponder in the
examples/ directory. There's no proper documentation for the library
yet, looking through the header files and source code is your best bet
at the moment. I will at some point split off the library into a
separate project and change the licensing to LGPL for that component.

Note: splitting the library off from ickle is complete now, you should
look at the libicq2000 project on sourceforge:
 http://libicq2000.sourceforge.net/
The next major release of ickle will be distributed with the library
separately.

 --------------------------------------------------------------------
 - 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 goodnight.