changeset 10409:68d6065fc32f

[gaim-migrate @ 11657] sf patch #1083616, from Balwinder Singh Dheeman Convert the TCL-HOWTO to a doxygen version committer: Tailor Script <[e-mail]>

--- a/COPYRIGHT	Fri Dec 24 02:29:24 2004 +0000
+++ b/COPYRIGHT	Fri Dec 24 02:50:25 2004 +0000
@@ -37,6 +37,7 @@
 Felipe Contreras
 Adam Cowell
 Jeramey Crawford
+Balwinder Singh Dheeman
 Finlay Dobbie
 Mark Doliner
 Nuno Donato

--- a/doc/Makefile.am	Fri Dec 24 02:29:24 2004 +0000
+++ b/doc/Makefile.am	Fri Dec 24 02:50:25 2004 +0000
@@ -6,6 +6,7 @@
 	CREDITS \
 	FAQ \
 	PERL-HOWTO.dox \
+	TCL-HOWTO.dox \
 	account-signals.dox \
 	blist-signals.dox \
 	connection-signals.dox \

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/TCL-HOWTO.dox	Fri Dec 24 02:50:25 2004 +0000
@@ -0,0 +1,354 @@
+/** @page tcl-howto Tcl Scripting HOWTO
+
+@section Intoduction
+
+The Gaim Tcl interface provides a Tcl API for many useful gaim
+functions.  Like the perl API, the Tcl API does not provide
+access to every corner of gaim exposed by the @e C interface.  It does,
+however, provide a very powerful interface to many of Gaim's functions
+through a simple to learn and extend scripting language.
+
+If you are not familiar with Tcl, you will probably find it somewhat
+different from what you are used to.  Despite being somewhat unique
+(more akin to shell programming than other traditional scripting
+languages such as @e perl or @e python), it is simple to learn for
+beginners and experienced programmers alike.  There are numerous books
+on the subject; we will not discuss it any further here.
+
+@section start Getting Started
+
+The only requirement placed on a Gaim Tcl script by Gaim is the
+existence of a procedure called @c plugin_init.  This procedure has
+some limitations placed upon it; it will be parsed and evaluated before
+the rest of the Tcl script, so it cannot reference any other variables
+or procedures declared in the script.  In practice this is not a
+problem, as the only thing this procedure should do is return a simple
+list containing five items: the @b name of the script, its @b version
+number, a @b summary (just a few words) of its function, a short (longer
+than the summary, but no more than a couple of sentences if possible)
+@b description, the @b author, and a @b URL to web page.  For example:
+
+@code
+proc plugin_init { } {
+  return [ list "Example Plugin" \
+                "1.0" \
+		"Example plugin registration" \
+		"Example of how to register a plugin for the Tcl HOWTO" \
+		"Ethan Blanton <[e-mail]>" \
+		"http://gaim.sf.net/" ]
+}
+@endcode
+
+The rest of the script will generally be registration to recieve
+notification of various Gaim signals (more about this below) and
+definitions of procedures to be executed when those signals occur.
+
+@section details Interpreter Details
+
+Gaim initializes and drives the Tcl event loop (similar to Tk),
+meaning that commands like @c fileevent and @c after are available and
+do not require @c vwait etc.  The @c vwait actually seems to be somewhat
+broken due to a bug somewhere in the Tcl/Glib event loop glue, and it
+should not be used for now.
+
+The gaim-specific functions are provided in a statically-linked
+package called @c gaim; this means that if you spawn a child
+interpreter and wish to use the gaim-specific functions, you will need
+to execute <tt>load {} gaim</tt> in that interpreter.
+
+@section internals Gaim Internal Procedures and Variables
+
+All of the information provided for your use by Gaim will be in the @c
+::gaim namespace.  This means that in order to access it you will either
+have to import the gaim namespace (e.g. via the command <tt>namespace
+import gaim::*</tt>) or reference it explicitly.  The following
+descriptions will reference it explicitly for clarity.
+
+@li Variables
+
+@code
+gaim::version
+@endcode
+
+  This contains the version of the gaim process which loaded the
+  script.
+
+@li Commands
+
+@code
+gaim::account alias account
+gaim::account connect account
+gaim::account connection account
+gaim::account disconnect account
+gaim::account find username protocol
+gaim::account handle
+gaim::account isconnected account
+gaim::account list ?option?
+gaim::account protocol account
+gaim::account username account
+@endcode
+
+  The @c gaim::account command consists of a set of subcommands
+  pertaining to gaim accounts.
+
+  @c alias returns the alias for the account @c account.  If there is no
+  alias for the given account, it returns the empty string.
+
+  The subcommand @c connect connects the named account if it is not
+  connected, and does nothing if it is.  In either case, it returns
+  the @c gc for the account.
+
+  @c connection returns the @c gc of the given account if it is connected,
+  or 0 if it is not.  This @c gc is the gc used by gaim::connection and
+  other functions.
+
+  @c disconnect disconnects the given @c account if it is connected, or
+  does nothing if it is.
+
+  @c find finds an account by its @c username and @c protocol (as returned by
+  <tt>gaim::account username</tt> and <tt>gaim::account protocol</tt>) and 
+  returns the account if found, or 0 otherwise.
+
+  @c handle returns the instance handle required to connect to account
+  signals.  (See <tt>gaim::signal connect</tt>).
+
+  The @c isconnected query returns true if the given account is
+  connected and false otherwise.
+
+  The @c list subcommand returns a list of all of the accounts known to
+  Gaim.  The elements of this lists are accounts appropriate for the
+  @c account argument of the other subcommands.  The @c -all option
+  (default) returns all accounts, while the @c -online option returns
+  only those accounts which are online.
+
+  The @c protocol subcommand returns the protocol ID (e.g. "prpl-msn")
+  for the given account.
+
+  The @c username subcommand returns the username for the account
+  @c account.
+
+@code
+gaim::buddy alias buddy
+gaim::buddy handle
+gaim::buddy info ( buddy | account username )
+gaim::buddy list
+@endcode
+
+  @c gaim::buddy is a set of commands for retrieving information about
+  buddies and manipulating the buddy list.  For the purposes of Tcl,
+  a "buddy" is currently a list of several elements, the first of
+  which being the type.  The currently recognized types are "group",
+  "buddy", and "chat".  A group node looks like:
+@code
+	{ group name { buddies } }
+@endcode
+  A buddy node is:
+@code
+	{ buddy name account }
+@endcode
+  And a chat node is:
+@code
+	{ chat alias account }
+@endcode
+
+  The @c alias subcommand returns the alias for the given buddy if it
+  exists, or the empty string if it does not.
+
+  @c handle returns the blist handle for the purposes of connecting
+  signals to buddy list events.  (See <tt>gaim::signal connect</tt>).
+
+  @c info causes gaim to display the info dialog for the given buddy.
+  Since it is possible to request user info for a buddy not in your
+  buddy list, you may also specify a buddy by his or her username and
+  the account through which you wish to retrieve info.
+
+  @c list returns a list of @c group structures, filled out with buddies
+  and chats as described above.
+
+@code
+gaim::connection account gc
+gaim::connection displayname gc
+gaim::connection handle
+gaim::connection list
+@endcode
+
+  @c gaim::connection is a collection of subcommands pertaining to
+  account connections.
+
+  @c account returns the Gaim account associated with @c gc.  This
+  account is the same account used by @c gaim::account and other
+  commands.
+
+  @c displayname returns the display name (duh) of @c gc as reported by
+  <tt>gaim_connection_get_display_name(gc)</tt>.
+
+  @c handle returns the gaim connections instance handle.  (See
+  <tt>gaim::signal connect</tt>).
+
+  @c list returns a list of all known connections.  The elements of
+  this list are appropriate as @c gc arguments to the other
+  @c gaim::connection subcommands or other commands requiring a gc.
+
+@code
+gaim::conv_send account who text
+@endcode
+
+  @c gaim::conv is simply a convenience wrapper for @c gaim::send_im and
+  <tt>gaim::conversation write</tt>.  It sends the IM, determines the from
+  and to arguments for <tt>gaim::conversation write</tt>, and prints the text
+  sent to the conversation as one would expect.  For the curious, you
+  may view the source for it by typing <tt>info body gaim::conv_send</tt> at
+  a Gaim Commander prompt.
+
+  Note that an error in either @c gaim::send_im or <tt>gaim::conversation
+  write</tt> will not be caught by this procedure, and will be propagated
+  to the caller.
+
+@code
+gaim::conversation find ?-account account? name
+gaim::conversation handle
+gaim::conversation list
+gaim::conversation new ?-chat? ?-im? account name
+gaim::conversation write conversation style from to text
+@endcode
+
+  @c gaim::conversation provides an API for dealing with conversations.
+  Given that Gaim is an instant messenger program, you'll probably
+  spend a lot of time here.
+
+  The command @c find attempts to find an existing conversation with
+  username @c name.  If the @c -account option is given, it refines its
+  search to include only conversations on that account.
+
+  @c handle returns the conversations instance handle for the purposes
+  of signal connection.  (See <tt>gaim::signal connect</tt>).
+
+  @c list returns a list of all currently open conversations.
+
+  The @c new subcommand can be used to create a new conversation with
+  a specified user on a specified account if one does not exist, or
+  retrieve the existing conversation if it does.  The @c -chat and
+  @c -im options specify whether the created conversation should be a
+  chat or a standard IM, respectively.
+
+  @c write is used to write to the specified conversation.  The @c style
+  argument specifies how the text should be printed -- as text coming
+  from the gaim user (style @c send), being sent to the gaim user
+  (style @c recv), or as a system message (such as "so-and-so has
+  signed off", style @c system).  From is the name to whom the text
+  should be attributed -- you probably want to check for aliases here,
+  lest you confuse the user.  @c text is the text to print.
+
+@code
+gaim::core handle
+gaim::core quit
+@endcode
+
+  This command exposes functionality provided by the gaim core API.
+
+  <tt>gaim::core handle</tt> returns a handle to the gaim core for signal
+  connection.  (See <tt>gaim::signal connect</tt>).
+
+  @c quit exits gaim cleanly, and should be used in preference to the
+  tcl @c exit command.  (Note that @c exit has not been removed,
+  however.)
+
+@code
+gaim::debug level category message
+@endcode
+
+  Equivalent to the C gaim_debug function, this command outputs
+  debugging information to the gaim debug window (or stdout if gaim is
+  invoked with -d|--debug).  The valid levels are, in increasing level
+  of severity, @c -misc, @c -info, @c -warning, and, or @c -error.  @c
+  category is a short (a few characters ... for instance, "tcl" or "tcl
+  plugin") "topic" type name for this message, and @c message is the text
+  of the message. In the style of Tcl @e puts (and differing from
+  @e gaim_debug), no trailing \\n is required.  (However, embedded newlines
+  may be generated with \\n).
+
+@code
+gaim::notify ?type? title primary secondary
+@endcode
+
+  Also a direct equivalent to a C function, gaim_notify, this command
+  causes gaim to present the provided notification information to the
+  user via some appropriate UI method.  The @c type argument, if
+  present, must be one of @c -error, @c -warning, or @c -info. The following
+  three arguments' absolute meanings may vary with the Gaim UI being
+  used (presently only a Gtk2 UI is available), but @c title should
+  generally be the title of the window, and @c primary and @c secondary
+  text within that window; in the Gtk2 UI, @c primary is slightly
+  larger than @c secondary and displayed in a @b boldface font.
+
+@code
+gaim::send_im gc who text
+@endcode
+
+  This sends an IM in the fashion of serv_send_im.  @c gc is the GC of
+  the connection on which you wish to send (as returned by most event
+  handlers), @c who is the nick of the buddy to which you wish to send,
+  and @c text is the text of the message.
+
+@code
+gaim::signal connect instance signal args proc
+gaim::signal disconnect instance signal
+@endcode
+
+  @c gaim::signal is a set of subcommands for dealing with gaim signals
+  (known as "events" prior to gaim 0.68).
+
+  The @c connect subcommand registers the procedure @c proc as a handler
+  for the signal @c signal on the instance @c instance.  @c instance
+  should be an instance handle as returned by one of the @c handle
+  commands from the various parts of gaim. @c args and @ proc are as in
+  the Tcl @e proc command; note that the number of arguments in @c args
+  must match the number of arguments emitted by the signal exactly,
+  although you need not use them all.  The procedure @c proc may be
+  either a simple command or a procedure in curly brackets.  Note that
+  only one procedure may be associated with each signal; an attempt to
+  connect a second procedure to the same signal will remove the
+  existing binding and replace it with the new procedure.
+  <tt>gaim::signal connect</tt> returns 0 on success and 1 on failure.
+
+  @c disconnect removes any existing signal handler for the named
+  signal and instance.
+
+@code
+gaim::unload
+@endcode
+
+  This unloads the current plugin.  Note that preferences will not be
+  updated (yet).
+
+@section Signals
+
+Check the signals documentation for the meaning of these signals; this is
+intended to be a list only of their arguments.  Signal callbacks will
+be made in their own namespace, and arguments to those signal
+callbacks will live in the namespace @c event underneath that
+namespace.  To briefly illustrate, the signal @c receiving-im-msg is
+provided with three arguments; the account on which the IM was
+received, the screen name of the user sending the IM, and the text of
+the IM.  These arguments live in the variables @c event::account,
+@c event::sender, and @c event::buffer, respectively.  Therefore a callback
+which notifies the user of an incoming IM containing the word 'shizzle'
+might look like this:
+
+@code
+gaim::signal connect [gaim::conversation handle] receiving-im-msg {
+	if {[ string match "*shizzle*" $event::buffer ]} {
+		gaim::notify -info "tcl plugin" "Fo' shizzle" \
+			"$event::sender is down with the shizzle"
+	}
+}
+@endcode
+
+Note that for some signals (notably @c receiving-im-msg, @c sending-im-msg,
+and their chat counterparts), changes to the event arguments will
+change the message itself from Gaim's vantage.  For those signals
+whose return value is meaningful, returning a value from the Tcl event
+
+*/
+
+// vim: syntax=c tw=75 et

--- a/plugins/tcl/TCL-HOWTO	Fri Dec 24 02:29:24 2004 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,317 +0,0 @@
-Gaim Tcl plugin-writing HOWTO
-
-INTRODUCTION
-
-The Gaim Tcl interface provides a Tcl API for many useful gaim
-functions.  Like the perl API, the Tcl API does not provide access to
-every corner of gaim exposed by the C interface.  It does, however,
-provide a very powerful interface to many of Gaim's functions through
-a simple to learn and extend scripting language.
-
-If you are not familiar with Tcl, you will probably find it somewhat
-different from what you are used to.  Despite being somewhat unique
-(more akin to shell programming than other traditional scripting
-languages such as perl or python), it is simple to learn for beginners
-and experienced programmers alike.  There are numerous books on the
-subject, we will not discuss it any further here.
-
-GETTING STARTED
-
-The only requirement placed on a Gaim Tcl script by Gaim is the
-existence of a procedure called 'plugin_init'.  This procedure has
-some limitations placed upon it; it will be parsed and evaluated
-before the rest of the Tcl script, so it cannot reference any other
-variables or procedures declared in the script.  In practice this is
-not a problem, as the only thing this procedure should do is return a
-simple list containing five items: the name of the script, its version
-number, a summary (just a few words) of its function, a short (longer
-than the summary, but no more than a couple of sentences if possible)
-description, the author, and a web page.  For example:
-
-proc plugin_init { } {
-  return [ list "Example Plugin" \
-                "1.0" \
-		"Example plugin registration" \
-		"Example of how to register a plugin for the Tcl HOWTO" \
-		"Ethan Blanton <[e-mail]>" \
-		"http://gaim.sf.net/" ]
-}
-
-The rest of the script will generally be registration to recieve
-notification of various Gaim signals (more about this below) and
-definitions of procedures to be executed when those signals occur.
-
-INTERPRETER DETAILS
-
-Gaim initializes and drives the Tcl event loop (similar to Tk),
-meaning that commands like fileevent and after are available and
-do not require 'vwait' etc.  'vwait' actually seems to be somewhat
-broken due to a bug somewhere in the Tcl/Glib event loop glue, and it
-should not be used for now.
-
-The gaim-specific functions are provided in a statically-linked
-package called 'gaim'; this means that if you spawn a child
-interpreter and wish to use the gaim-specific functions, you will need
-to execute 'load {} gaim' in that interpreter.
-
-GAIM INTERNAL PROCEDURES AND VARIABLES
-
-All of the information provided for your use by Gaim will be in the
-::gaim namespace.  This means that in order to access it you will
-either have to import the gaim namespace (e.g. via the command
-'namespace import gaim::*') or reference it explicitly.  The following
-descriptions will reference it explicitly for clarity.
-
-* Variables
-
-gaim::version
-
-  This contains the version of the gaim process which loaded the
-  script.
-
-* Commands
-
-gaim::account alias account
-gaim::account connect account
-gaim::account connection account
-gaim::account disconnect account
-gaim::account find username protocol
-gaim::account handle
-gaim::account isconnected account
-gaim::account list ?option?
-gaim::account protocol account
-gaim::account username account
-
-  The 'gaim::account' command consists of a set of subcommands
-  pertaining to gaim accounts.
-
-  'alias' returns the alias for the account 'account'.  If there is no
-  alias for the given account, it returns the empty string.
-
-  The subcommand 'connect' connects the named account if it is not
-  connected, and does nothing if it is.  In either case, it returns
-  the gc for the account.
-
-  'connection' returns the gc of the given account if it is connected,
-  or 0 if it is not.  This gc is the gc used by gaim::connection and
-  other functions.
-
-  'disconnect' disconnects the given account if it is connected, or
-  does nothing if it is.
-
-  'find' finds an account by its username and protocol (as returned by
-  'gaim::account username' and 'gaim::account protocol') and returns
-  the account if found, or 0 otherwise.
-
-  'handle' returns the instance handle required to connect to account
-  signals.  (See 'gaim::signal connect').
-
-  The 'isconnected' query returns true if the given account is
-  connected and false otherwise.
-
-  The 'list' subcommand returns a list of all of the accounts known to
-  Gaim.  The elements of this lists are accounts appropriate for the
-  'account' argument of the other subcommands.  The '-all' option
-  (default) returns all accounts, while the '-online' option returns
-  only those accounts which are online.
-
-  The 'protocol' subcommand returns the protocol ID (e.g. "prpl-msn")
-  for the given account.
-
-  The 'username' subcommand returns the username for the account
-  'account'.
-
-gaim::buddy alias buddy
-gaim::buddy handle
-gaim::buddy info ( buddy | account username )
-gaim::buddy list
-
-  'gaim::buddy' is a set of commands for retrieving information about
-  buddies and manipulating the buddy list.  For the purposes of Tcl,
-  a "buddy" is currently a list of several elements, the first of
-  which being the type.  The currently recognized types are "group",
-  "buddy", and "chat".  A group node looks like:
-	{ group name { buddies } }
-  A buddy node is:
-	{ buddy name account }
-  And a chat node is:
-	{ chat alias account }
-
-  The 'alias' subcommand returns the alias for the given buddy if it
-  exists, or the empty string if it does not.
-
-  'handle' returns the blist handle for the purposes of connecting
-  signals to buddy list events.  (See 'gaim::signal connect').
-
-  'info' causes gaim to display the info dialog for the given buddy.
-  Since it is possible to request user info for a buddy not in your
-  buddy list, you may also specify a buddy by his or her username and
-  the account through which you wish to retrieve info.
-
-  'list' returns a list of 'group' structures, filled out with buddies
-  and chats as described above.
-
-gaim::connection account gc
-gaim::connection displayname gc
-gaim::connection handle
-gaim::connection list
-
-  'gaim::connection' is a collection of subcommands pertaining to
-  account connections.
-
-  'account' returns the Gaim account associated with 'gc'.  This
-  account is the same account used by gaim::account and other
-  commands.
-
-  'displayname' returns the display name (duh) of 'gc' as reported by
-  gaim_connection_get_display_name(gc).
-
-  'handle' returns the gaim connections instance handle.  (See
-  'gaim::signal connect').
-
-  'list' returns a list of all known connections.  The elements of
-  this list are appropriate as 'gc' arguments to the other
-  gaim::connection subcommands or other commands requiring a gc.
-
-
-gaim::conv_send account who text
-
-  'gaim::conv' is simply a convenience wrapper for 'gaim::send_im' and
-  'gaim::conversation write'.  It sends the IM, determines the from
-  and to arguments for 'gaim::conversation write', and prints the text
-  sent to the conversation as one would expect.  For the curious, you
-  may view the source for it by typing 'info body gaim::conv_send' at
-  a Gaim Commander prompt.
-
-  Note that an error in either gaim::send_im or 'gaim::conversation
-  write' will not be caught by this procedure, and will be propagated
-  to the caller.
-
-gaim::conversation find ?-account account? name
-gaim::conversation handle
-gaim::conversation list
-gaim::conversation new ?-chat? ?-im? account name
-gaim::conversation write conversation style from to text
-
-  'gaim::conversation' provides an API for dealing with conversations.
-  Given that Gaim is an instant messenger program, you'll probably
-  spend a lot of time here.
-
-  The command 'find' attempts to find an existing conversation with
-  username 'name'.  If the '-account' option is given, it refines its
-  search to include only conversations on that account.
-
-  'handle' returns the conversations instance handle for the purposes
-  of signal connection.  (See 'gaim::signal connect').
-
-  'list' returns a list of all currently open conversations.
-
-  The 'new' subcommand can be used to create a new conversation with
-  a specified user on a specified account if one does not exist, or
-  retrieve the existing conversation if it does.  The '-chat' and
-  '-im' options specify whether the created conversation should be a
-  chat or a standard IM, respectively.
-
-  'write' is used to write to the specified conversation.  The 'style'
-  argument specifies how the text should be printed -- as text coming
-  from the gaim user (style 'send'), being sent to the gaim user
-  (style 'recv'), or as a system message (such as "so-and-so has
-  signed off", style 'system').  From is the name to whom the text
-  should be attributed -- you probably want to check for aliases here,
-  lest you confuse the user.  'text' is the text to print.
-
-gaim::core handle
-gaim::core quit
-
-  This command exposes functionality provided by the gaim core API.
-
-  'gaim::core handle' returns a handle to the gaim core for signal
-  connection.  (See 'gaim::signal connect').
-
-  'quit' exits gaim cleanly, and should be used in preference to the
-  tcl 'exit' command.  (Note that 'exit' has not been removed,
-  however.)
-
-gaim::debug level category message
-
-  Equivalent to the C gaim_debug function, this command outputs
-  debugging information to the gaim debug window (or stdout if gaim is
-  invoked with -n).  The valid levels are, in increasing level of
-  severity, -misc, -info, -warning, and -error.  'category' is a short
-  (a few characters ... for instance, "tcl" or "tcl plugin") "topic"
-  type name for this message, and 'message' is the text of the
-  message. In the style of Tcl 'puts' (and differing from gaim_debug),
-  no trailing \n is required.  (However, embedded newlines may be
-  generated with \n).
-
-gaim::notify ?type? title primary secondary
-
-  Also a direct equivalent to a C function, gaim_notify, this command
-  causes gaim to present the provided notification information to the
-  user via some appropriate UI method.  The 'type' argument, if
-  present, must be one of -error, -warning, or -info. The following
-  three arguments' absolute meanings may vary with the Gaim UI being
-  used (presently only a Gtk2 UI is available), but 'title' should
-  generally be the title of the window, and 'primary' and 'secondary'
-  text within that window; in the Gtk2 UI, 'primary' is slightly
-  larger than 'secondary' and displayed in a boldface font.
-
-gaim::send_im gc who text
-
-  This sends an IM in the fashion of serv_send_im.  'gc' is the GC of
-  the connection on which you wish to send (as returned by most event
-  handlers), 'who' is the nick of the buddy to which you wish to send,
-  and 'text' is the text of the message.
-
-gaim::signal connect instance signal args proc
-gaim::signal disconnect instance signal
-
-  'gaim::signal' is a set of subcommands for dealing with gaim signals
-  (known as "events" prior to gaim 0.68).
-
-  The 'connect' subcommand registers the procedure 'proc' as a handler
-  for the signal 'signal' on the instance 'instance'.  'instance'
-  should be an instance handle as returned by one of the 'handle'
-  commands from the various parts of gaim. 'args' and 'proc' are as in
-  the Tcl 'proc' command; note that the number of arguments in 'args'
-  must match the number of arguments emitted by the signal exactly,
-  although you need not use them all.  The procedure 'proc' may be
-  either a simple command or a procedure in curly brackets.  Note that
-  only one procedure may be associated with each signal; an attempt to
-  connect a second procedure to the same signal will remove the
-  existing binding and replace it with the new procedure.
-  'gaim::signal connect' returns 0 on success and 1 on failure.
-
-  'disconnect' removes any existing signal handler for the named
-  signal and instance.
-
-gaim::unload
-
-  This unloads the current plugin.  Note that preferences will not be
-  updated (yet).
-
-SIGNALS
-
-Check the file SIGNALS for the meaning of these signals; this is
-intended to be a list only of their arguments.  Signal callbacks will
-be made in their own namespace, and arguments to those signal
-callbacks will live in the namespace 'event' underneath that
-namespace.  To briefly illustrate, the signal receiving-im-msg is
-provided with three arguments; the account on which the IM was
-received, the screen name of the user sending the IM, and the text of
-the IM.  These arguments live in the variables event::account,
-event::sender, and event::buffer, respectively.  Therefore a callback
-which notifies the user of an incoming IM containing the word 'shizzle'
-might look like this:
-
-gaim::signal connect [gaim::conversation handle] receiving-im-msg {
-	if {[ string match "*shizzle*" $event::buffer ]} {
-		gaim::notify -info "tcl plugin" "Fo' shizzle" \
-			"$event::sender is down with the shizzle"
-	}
-}
-
-Note that for some signals (notably receiving-im-msg, sending-im-msg,
-and their chat counterparts), changes to the event arguments will
-change the message itself from Gaim's vantage.  For those signals
-whose return value is meaningful, returning a value from the Tcl event