annotate doc/FAQ @ 3116:0cb4b01c5733

[gaim-migrate @ 3131] "God I'm stoned." -- "Kermit the Frog" "God I'm drunk." -- Eric Warmenhoven committer: Tailor Script <[e-mail]>

Gaim: The Pimpin' Penguin IM Clone Thats Good For The Soul

1  The Basics
	1.1  What does 'gaim' stand for?
	1.2  Where are my log files stored?
	1.3  What are GtkHTML and GtkIMHtml, and why not just use GNOME's
	     GtkHTML?
	1.4  How do I load plugins/perl scripts?
	1.5  I'm not a native English speaker and I would like a translated
	     version of gaim.
	1.6  Why can I import my buddylist but not export it?

2  Multiple Connections
	2.1  What do you mean by "multiple connections"?
	2.2  How do I sign on more than one account?
	2.3  How do buddy lists work for multiple connections?
	2.4  What's a PRPL?
	2.5  How do I use a different protocol?

3  About the Protocols (what they support, and how to do things with them)
	3.0  Introduction
	3.1  TOC
	3.2  Oscar
	3.3  Yahoo!
	3.4  IRC
	3.5  ICQ
	3.6  MSN
	3.7  Jabber
	3.8  Napster

4  Problems
	4.1  Sound doesn't work
	4.2  Clicking on URLs doesn't open Netscape
	4.3  I don't use Netscape
	4.4  I have a bug not described here

5  Programming
	5.1  I have a patch for gaim!
	5.2  I have a plugin/perl script for gaim!
	5.3  Can you teach me how to program GTK?

6  Miscellaneous
	6.1  Can I talk to you on IM?
	6.2  I want to write an IM client. Will you help me?
	6.3  I have money. I need software written. Can you help?
	6.4  I have hardware here that's not being used. Can you use it?
	6.5  I would like to send you beer.
	6.6  Are you going to port this to Windows?
	6.7  Why no AOL logo?
	6.8  Why the GPL?
	6.9  What is a wagii?
	6.10 What window manager/distribution/other crap do you use?
	6.11 Is XX a good hard drive, YY a good monitor and ZZ a good CPU?
	6.12 I want to contribute to the effort. Where can I send beer to?

---

1  The Basics

1.1  What does 'gaim' stand for?

It's basically the letter 'g' tacked on to the beginning of 'AIM' (which is
fairly obvious). G stands for all sorts of good things. Girls, Godzilla, GTK,
graham crackers, whatever.

1.2  Where are my log files stored?

Your logs are stored in $HOME/.gaim/logs/. They had previously been stored in
$HOME/.gaim/YourScreenName/ (e.g. $HOME/.gaim/EWarmenhoven).

1.3  What are GtkHTML and GtkIMHtml, and why not just use GNOME's GtkHTML?

The widget Gaim had previously used to display HTML was called GtkHTML, and
was written by Mark and Jim specifically for Gaim. Over time, Rob and Eric
hacked at it (read: broke it) and it's gotten to be very fragile and fairly
buggy.

One day Eric got pissed off at GtkHTML and decided to rewrite it, and called
it GtkIMHtml (IM to indicate that it should be used in IM clients). He made
it its own separate project, so that other IM clients (like Jabber clients)
could use it. He based it somewhat off of the old GtkHTML and GNOME's GtkHTML.

GNOME's GtkHTML is a very powerful HTML viewer. Because of this, it isn't
well-suited for Gaim. It wouldn't be very good if we let you have IFrames in
your conversation, for example. Also, GNOME's GtkHTML depends on a lot of
GNOME libraries that we don't want to force people to use in Gaim. (There is
a strip-down version, CSCHTML, which doesn't use the GNOME libraries; but the
first objection (that it supports too many tags) still applies.)

1.4  How do I load plugins/perl scripts?

Plugins you had loaded when you quit gaim are loaded again when you start
gaim. To load a new plugin, either click 'Plugins' on the login screen, or
select 'Plugins' from the 'Tools' menu in the buddy list. From there, you
can load and unload plugins, and configure certain ones. If you click on
the 'Load Plugin' button, it will present you with a file dialog, asking
which file you want to load; it will default to looking for a .so file in
the directory plugins get installed to, though you don't have to load a .so
file, and you don't have to load it from that directory.

When you start gaim, all the .pl files in ~/.gaim will be loaded
automatically. You can also load new scripts from the 'Perl' menu in 'Tools'.
From that menu, you can load a new script (similarly to how you loaded a
plugin above), unload all your loaded scripts, and list which scripts you have
loaded.

1.5  I'm not a native English speaker and I would like a translated version of
gaim.

Gaim currently has a few translations (French, Spanish, Korean, and Simplified
Chinese); however, most of them are out of date. If you would like to update
or add a translation of gaim, email or IM either Rob or Eric and they can tell
you how to go about it.

1.6  Why can I import my buddylist but not export it?

Because you don't have to.  Gaim, out of the kindness of its sweet little 
heart, automagically exports your buddylist for you.  You can find a copy
of your list in ~/.gaim/YOURNAME.PROTO.BLIST.  For example, if you're
using AIM, and your name is JoeUser, then your buddy list could be found
in: ~/.gaim/JOEUSER.0.blist.

2  Multiple Connections

2.1  What do you mean by "multiple connections"?

Multiple Connections means that it's possible to connect to the AOL servers
using more than one screenname at a time. It's just a way of not having to run
three copies of gaim for each of your screennames.

2.2  How do I sign on more than one account?

The Account Editor controls all of your accounts, and lets you add, delete,
modify, and sign on/off accounts. It is accessible from the login window or
from the 'Tools' menu in the buddy list as 'Accounts'. Simply highlight the
account you want to sign on, and click the 'Sign On/Off' button. To sign on
another account, highlight it and click the 'Sign On/Off' button. There is a
column labeled 'Currently Online' to let you know if the account is online or
not.

2.3  How do buddy lists work for multiple connections?

"The same as they did before" is the simple answer. Each account you have will
have its own buddy list, which you can add buddies to and remove from. In the
'Edit Buddies' tab of your buddy list, you'll see the name of each of your
online accounts (unless if you only have one), with its buddy list nested
underneath it.

2.4  What's a PRPL?

PRPL stands for Protocol Plugin. It's a way to dynamically add new protocols
to gaim. This allows you to use gaim as your AIM, ICQ, Yahoo, and even IRC
client, all at the same time. Loading a PRPL is just like loading any other
plugin - simply load the .so file from the plugins dialog.

2.5  How do I use a different protocol?

In the Account Editor,  click the 'Add' button to add a new account. Below the
password entry, you should see a menu labeled 'Protocol', with a list of the
protocols available for you to use. (If you don't see the protocol you want to
use, make sure you have the proper PRPL loaded.) Enter in your username (for
ICQ this should be your UIN) and password, and you're set. You can then sign
the account on by clicking the 'Sign On/Off' button when the account is
highlighted.


3  About the Protocols (what they support, and how to do things with them)

3.0  Introduction

This really only describes the protocol, and how gaim is able to use it. For
a listing of what gaim has implemented with each protocol, please read the
STATUS file.

3.1  TOC

TOC is an open protocol (meaning that there's open documentation from the
people who developed it), developed by AOL, for clients to use to connect to
the AIM server. It has stopped being supported by AOL (though they do still
make changes to the TOC server). It is a strip-down and simplified version of
their "real" protocol, Oscar.

TOC is a TCP protocol, and will only ever make one TCP connection (unless if
you accept a file transfer request). Your buddy list is stored on the server,
and gaim keeps a locally cached copy as well. When you sign on the server and
local lists are merged.

3.2  Oscar

Oscar is the protocol that the Windows version of AIM uses (and actually,
ICQ2000 uses it too). It's a closed protocol, meaning that in order for gaim
to use it, someone had to reverse-engineer it. For gaim, the libfaim authors
did this, and wrote a library so that we could use it.

Oscar is a TCP protocol, but it makes several connections: the authorizor (the
initial connection, who you send your screenname/password to), the BOS (which
is the "main" connection, through which all your messages go), ChatNav (which
lets you join chat rooms), as well as one for each chat room you join. Oscar
does let you store your buddy list on the server, but libfaim hasn't added
that functionality yet.

3.3  Yahoo!

Yahoo! uses a closed protocol; the authors of libyahoo reverse-engineered it
and gaim uses that library. It is a TCP protocol, and makes several
connections, though I'm not entirely sure at which points. It stores your
buddy list on the server, and gaim keeps a locally cached copy. When you sign
on the server and local lists are merged.

3.4  IRC

IRC is an open protocol (though I've heard that some servers deviate slightly
from it). It's a TCP protocol, and will only ever make one connection (outside
of DCC connections).

3.5  ICQ

ICQ is a closed protocol, though there have been several groups of people who
have reverse-engineered it, and there are several libraries available. Gaim
uses icqlib (which supports multiple connections, as opposed to libicq, which
does not). It is a mix of UDP and TCP: the connection to the server is UDP,
and conversations are TCP unless if they are sent through the server. This
means you'll make one UDP connection, and possibly very many TCP connections.

3.6  MSN

MSN is a weird TCP protocol written by Microsoft.  It requires multiple
connections and is a real headache :).

3.7  Jabber

Jabber is an open protocol, developed by the Jabber team, and is XML-encoded.
It is a TCP protocol, and you will only ever make one TCP connection. Jabber
has a feature it calls 'transports', where the server tells you which services
it has available (such as AIM or ICQ), and you tell it which service you would
like to use. This way you can have only one connection, but be connected to
AIM and ICQ (among others) several times. Anyone who gives a damn about Open
Source, especially open messaging, should use Jabber. They have the only Open
Source IM server.

3.8  Napster

Napster is, as you know, the protocol used by that wonderful little program
called napster.  You know the one!  It's what millions of college kids across
america are using to sastisfy their longing for music :-D.  Anyways, gaim supports
it.  It's kind of fiunky, though. Napster is a TCP protocol and only requires one
connection to the server.  All file transfers, however, are explicitly client to
client.  The plugin currently only supports one way file transfer (downloading)
from people who are _not_ firewalled.  You can also send private messages to each
other, join chat rooms, browse a user's files, and search.  More implementation
coming soon.

4  Problems

4.1  Sound doesn't work

./configure should autodetect whether or not you have ESD libraries. If you
have them it will compile with them; if not it won't. If it compiles with them
you don't need to be running the ESD daemon; it'll automatically fall back to
using /dev/dsp. Make sure gaim has the proper permissions to talk to /dev/dsp
and /dev/audio though!

4.2  Clicking on URLs doesn't open Netscape

Netscape either needs to be running on the current display (though gaim should
handle remote netscape windows OK), or 'netscape' needs to be in your path.

4.3  I don't use Netscape

There's the option to manually enter which browser you'd like to use. We're
interested in supporting browsers other than Netscape though; send us some
information about how to send a URL to your browser (source is nice :) ).

4.4  I have a bug not described here

We have a page at http://sourceforge.net/projects/gaim/, and from there you
can report your bug.


5  Programming

5.1  I have a patch for gaim!

Great! Send it over to the Patches section on our sourceforge page,
http://sourceforge.net/projects/gaim/. From there we'll take a look at it (no
promises that it'll get in, but we'll at least take a look at it).

5.2  I have a plugin/perl script for gaim!

Great! Post it to the Patches section on our sourceforge page, and mark it as
a plugin. Then other people will be able to see it and use it. (Make sure that
you understand that your plugin is necessarily GPL'd, and you must provide
source to your plugin.)

5.3  Can you teach me how to program GTK?

Actually, I can't. I'm a very bad teacher. I'm much too impatient. There is a
really great tutorial and API reference on the GTK website though,
http://www.gtk.org/. That's how I learned, anyway.


6  Miscellaneous

6.1  Can I talk to you on IM?

Sure. Our IM names can be found in the AUTHORS file. Keep in mind though that
we're busy people. We use those screennames as our main screen names, not just
to talk to gaim users. So please, don't IM us for us to answer questions about
Linux. We'd like to be able to answer everyone's questions, but we just don't
have the time. We aren't paid to hack gaim; we do have other jobs.  Also,
please don't waste our time with a simple "hi" or "hello."  Don't ask if
you can ask a question, just ask it.  We'll usually respond.

6.2  I want to write an IM client. Will you help me?

I'll give you advice, but other than that, no (unless you'd like to pay me).

6.3  I have money. I need software written. Can you help?

Oh yes. Our email addresses are [e-mail] (SeanEgn) and
[e-mail] (RobFlynn).

6.4  I have hardware here that's not being used. Can you use it?

Most certainly. IM me or email me and I'll tell you where you can ship it to
(I might be able to scratch together shipping money even).

6.5  I would like to send you beer.

OK.

6.6  Are you going to port this to Windows?

No. If you'd like to work on a port help yourself; but I really really dislike
Windows (in all its closed-source evilness).

6.7  Why no AOL logo?

AOL's legal staff told us no-no.

6.8  Why the GPL?

I like the GPL.

6.9  What is a wagii?

Interesting question that you ask, there. 'Wagii' is the official celebratory
cry of gaim. Anytime you are feeling happy or excited, just remember all of
the hard work that we have done to provide you with this wonderful, free piece
of software -- as the pure, raw, emotion flows through you, maybe you too will
let out the cry of -- Wagii.

It is also the sound a Penguin Samurai makes :)

6.10 What window manager/distribution/other crap do you use?

Rob uses Red Hat, with Ximian GNOME on top.  I dont really like Ximian but I like
Gnome.  On top of my Ximian Gnome is Sawfish.  Eric hates saw fish.  I kinda of
like it even though it makes me mad. 

Eric uses debian woody. He uses Enlightenment as his window manager; though
the only reason it would seem that Eric uses X at all is to support having
his 20 Eterms and 4 Mozilla windows open. Oh yeah, and gaim_applet.

6.11 Is XX a good hard drive, YY a good monitor and ZZ a good CPU?

You could send us one and we could tell you... :)

6.12 I want to contribute to the effort. Where can I send beer to?

IM RobFlynn or email him at [e-mail].