Mercurial > pidgin

--- a/HACKING	Tue Sep 09 00:15:13 2003 +0000
+++ b/HACKING	Tue Sep 09 14:35:07 2003 +0000
@@ -1,3 +1,9 @@
+The majority of the below was written by Eric Warmenhoven way back in
+antiquity. I have taken the liberty of attempting to PARTIALLY update
+it. I still think its helpful, but use it at your own risk.
+--Luke
+
+
 A lot of people have tried to hack gaim, but haven't been able to because
 the code is just so horrid. Well, the code isn't getting better anytime
 soon (I hate GNU indent), so to help all you would-be hackers help out
@@ -38,17 +44,10 @@
 either post it on sf.net/projects/gaim in the patches section, or email it
 to gaim@marko.net.

-This file was last modified by $Author: lschiere $ on
-$Date: 2003-02-18 09:36:15 -0500 (Tue, 18 Feb 2003) $. Do not expect any information contained
-within to be current or correct.
-
-Here's something new. Someone requested that I comment the code. No. I'm a
-lazy bastard, and I understand most of the code, so I don't need the
-comments. I understand that some of you do though. So give me the names of
-specific functions that you'd like commented and I'll see what I can do.
-It's more likely that those comments will be updated with the code than
-this file is, though even that is still unlikely.
-
+Some Documentation is available on the Gaim api if you run the command
+$make docs
+after running ./configure (or ./autogen.sh). You will need doxygen and
+graphiz dot to generate these docs.

 CODING STYLE
 ============
@@ -79,13 +78,13 @@
 feel the need to use goto, you need to rethink your design and flow.


-PROGRAM FLOW
-============
+PROGRAM FLOW  (just about every function name from here on down is wrong.
+============   but many of the ideas still apply under different names.)

 Before gaim does anything you can see, it initializes itself, which is
-mostly just reading .gaimrc (handled by the functions in gaimrc.c) and
-parsing command-line options. It then draws the login window by calling
-show_login, and waits for input.
+mostly just reading ~/.gaim/*.xml (handled by the functions in prefs.[ch])
+and parsing command-line options. It then draws the login window by
+calling show_login, and waits for input.

 At the login window, when "Accounts" is clicked, account_editor() is
 called. This then displays all of the users and various information
@@ -137,7 +136,7 @@
 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.


-SOURCE FILES
+SOURCE FILES  (this should probly be utterly removed)
 ============

 about.c:
@@ -155,10 +154,11 @@
   Code for opening a browser window. Most of the code is trying to deal
   with Netscape. The most important function here is open_url. Have fun.

-buddy.c:
-  This takes care of the buddy list window and most things related to it.
-  It still has some functions that manage the list, but not many.
-
+blist.c:
+	This takes care of the buddy list backend, the blist.xml file,
+	importing old buddy list files, and related things like
+	finding buddies and groups.
+
 buddy_chat.c:
   This takes care of the buddy chat stuff. This used to be a lot bigger
   until the chat and IM windows got merged in the code. Now it mostly
@@ -189,6 +189,9 @@
   This controls everything about the .gaimrc file. There's not really much
   to say about it; this is probably one of the better designed and easier
   to follow files in gaim. The important functions are towards the bottom.
+  	This file is also utterly deprecated. It is used only for importing
+	on upgrade. the prefs.c and prefs.h files replace the control,
+	and gtkprefs.c replaces the gui component.

 gtkimhtml.c:
   This is gaim's HTML widget. It replaced the old widget, GtkHtml (which
@@ -207,11 +210,6 @@
   reporting idle time (imagine that). It's a pretty straight-forward file.
   This also takes care of the auto-away stuff.

-list.c:
-  This file contains all of the routines for managing buddy lists,
-  including importing them from a file, saving them, adding and removing
-  buddies and groups, etc.
-
 main.c:
   This is where the main() function is. It takes care of a lot of the
   initialization stuff, and showing the login window. It's pretty tiny
@@ -236,30 +234,17 @@
   now...). account_editor is really the only function that the UI needs
   to be concerned with.

-perl.c:
-  This was basically copied straight from X-Chat through the power of
-  the GPL.  Perl is the biggest, most confusing piece of C code I've ever
-  seen in my life (and keep in mind I'm a gaim hacker). I have a basic
-  idea of what's going on in it, but I couldn't tell you exactly. The
-  top half sets up perl and tells it what's going on and the bottom half
-  implements the AIM module.
-
 prefs.c:
-  The important function in here is build_prefs, but the most useful
-  function is gaim_button. build_prefs draws the window, and calls
-  gaim_button probably 30 or 40 times. (I don't really wanna run grep
-  | wc to count.) This is where you add the toggle button for gaim
-  preferences. It's very simple, and if you look at a couple of the
-  calls to gaim_button you'll figure it out right away. The new prefs
-  window uses a CList instead of a Notebook, and there's a pretty bad
-  hack to get it to work. I won't tell you what though.
+	Read the documentation on this file. This handles the backend
+	side of prefs.

 proxy.c:
   Adam (of libfaim glory) got bored one day and rewrote this file, so
   now everything actually works. The main function is proxy_connect,
   which figures out which proxy you want to use (if you want to use one
   at all) and passes off the data to the appropriate function. This file
-  should be pretty straight-forward.
+  should be pretty straight-forward.
+  	Except I STRONGLY suspect that time has broken this file.

 prpl.c:
   This file is what lets gaim dynamically load protocols, sort of. All
@@ -303,70 +288,7 @@
 the name of the protocol is ICQ; for that it's gaim_icq.c. But ICQ is
 deprecated and you should be using Oscar for ICQ anyway.

-HOW BUDDY LISTS WORK
-====================
-
-The buddy list is a pain in the ass. Let me start off by saying that. The
-most difficult part about getting gaim to do multiple connections was
-the buddy list. In its current state it's very much like the UI for
-0.10.x and earlier, which is what I was aiming for. However, the code
-is completely different. And not much better.
-
-There are two parts to the buddy list: the lists for the connections and
-the Buddy List window. list.c contains code to manage the lists themselves
-and buddy.c contains the code for the Buddy List window.
-
-Each buddy needs to belong to a connection, it cannot belong to a
-"protocol" like in EveryBuddy. The reason is because when you are adding
-buddies, you tell the server who is on your buddy list so it can tell you
-about them; in order to tell the server, it needs to go out over a
-connection. Going out over all connections would not be good, so you need
-to specify which connection they go out on.
-
-Managing lists is therefore fairly easy, each group and buddy has an
-associated connection. Management functions like add_buddy/remove_buddy
-and add_group/remove_group all take a gaim_connection. These are all in
-list.c. They're boring.
-
-The window is a lot more fun. There's really only one function that
-does anything interesting, and that's set_buddy. (There's also things
-like build_edit_tree, but that's boring.) set_buddy is called by
-serv_got_update (and should only be called by that function) any time
-a user signs on, signs off, goes away, comes back, goes idle, etc, etc,
-etc. Various things happen depending on the new state of the buddy.
-
-struct buddy has a member, present, which is set to either 0, 1, or
-2. You can check if the buddy is online with "if (b->present)". This
-becomes important. present is set to either 0 or 1 by serv_got_update,
-or is not set at all. When the buddy is passed to set_buddy, if present
-is 1 then set_buddy plays the BUDDY_ARRIVE sound, and sets present to 2,
-to indicate it has already received notification of arrival. It then
-does other signin-related stuff: setting the pixmap to the login icon;
-updating the conversation windows; etc.
-
-The most important thing it does though, if a buddy is present, is it
-checks for the existance of the appropriate group_show and buddy_show for
-that buddy.  Each buddy must belong to a group. group_shows are based on
-name; there can only be one group_show for each group name. buddy_shows
-are based both on name and on group_show; there can only be one buddy_show
-in a group_show for each name. However, there can be two buddy_shows
-with the same name as long as they have different group_shows.
-
-Each buddy_show has a GList of connections that has registered its related
-buddy as being online. set_buddy makes sure that the connection that it's
-being passed is part of the connlist for the buddy_show associated with
-the struct buddy that it's passed (it helps to know your data structures).
-
-If a buddy logs off (b->present == 0), and a buddy_show exists for
-that buddy, then set_buddy will play the logoff sound, change the icon,
-remove the connection from the connlist for the buddy_show, etc.
-
-And that's how that works. For the buddy lists, connections own buddies;
-for the window, the buddies own the connections. When the buddy_show
-connlist count drops to zero it disappears from existance.
-
-
-PLUGINS
+PLUGINS (read the plugins howto, this is really out of date)
 =======

 OK, so you want to load a plugin. You go through whatever UI (you
--- a/README	Tue Sep 09 00:15:13 2003 +0000
+++ b/README	Tue Sep 09 14:35:07 2003 +0000
@@ -98,16 +98,16 @@
 icons; it also can't make file transfer requests.


-Oscar (Eric)
+Oscar (Mark)
 =====

 Oscar is the default protocol. It is recommended that you use Oscar for
 both AIM and ICQ, as TOC isn't very featureful and the old ICQ protocol no
-longer works.
+longer works.

 For AIM, Oscar can get people's away messages. It can request and accept
-Direct IM connections, but it cannot yet transfer files through this (or
-through any other means). It can send and receive buddy icons if you have
+Direct Connections, and has limited support for file transfer. IM Image
+does not currently work. It can send and receive buddy icons if you have
 GdkPixbuf.

 For ICQ, it supports nearly everything that the old ICQ plugin supported,
@@ -116,16 +116,16 @@
 client to register a new ICQ account if you don't have one yet.


-Yahoo (Eric)
+Yahoo (Sean)
 =====

 Yahoo is currently using the new YMSG protocol that newer official Yahoo
 clients are using. This protocol is much better than the old one, and
 tends to be somewhat more reliable. However, the Yahoo service is still
-flaky at best. Group chats aren't supported yet.
+flaky at best.


-IRC (Eric)
+IRC (Ethan)
 ===

 There are three ways to join an IRC chat room. The first is the File->Join
@@ -136,7 +136,7 @@
 IRC, /help will give you a list of them.


-MSN (Eric)
+MSN (Christian)
 ===

 With MSN you can join a conversation with several people, but you can't
@@ -152,7 +152,7 @@
 one yet.


-Jabber (Eric)
+Jabber (Nathan)
 ======

 Transports aren't currently supported at all, though if you have a
--- a/README.CVS	Tue Sep 09 00:15:13 2003 +0000
+++ b/README.CVS	Tue Sep 09 14:35:07 2003 +0000
@@ -1,10 +1,10 @@
 If you plan to use gaim CVS, PLEASE read this message in its entirety!

-Gaim is a fast-moving project with a regular release schedule.  Due to
-the rate of gaim development, CVS undergoes frequent bursts of massive
-changes, often leaving behind brokenness and partial functionality
-while the responsible developers rewrite some portion of code or seek
-to add new features.
+Gaim is a fast-moving project with a regular somewhat release schedule.
+Due to the rate of gaim development, CVS undergoes frequent bursts of
+massive changes, often leaving behind brokenness and partial
+functionality while the responsible developers rewrite some portion of
+code or seek to add new features.

 What this all boils down to is that CVS _WILL_ sometimes be broken.
 Because of this, we ask that users who are not interested in