diff doc/TCL-HOWTO.dox @ 24318:73e827a93ae9

Update the TCL-HOWTO to some more modern nomenclature

--- a/doc/TCL-HOWTO.dox	Sat Nov 08 19:26:28 2008 +0000
+++ b/doc/TCL-HOWTO.dox	Sun Nov 09 16:42:04 2008 +0000
@@ -4,11 +4,11 @@
 
 NOTA BENE: This documentation is badly out of date for 2.x.
 
-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.
+The libpurple Tcl interface provides a Tcl API for many useful libpurple
+functions.  Like the perl API, the Tcl API does not provide access to
+every corner of libpurple exposed by the @e C interface.  It does,
+however, provide a very powerful interface to many of libpurple'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
@@ -19,7 +19,7 @@
 
 @section start Getting Started
 
-The only requirement placed on a Gaim Tcl script by Gaim is the
+The only requirement placed on a purple Tcl script by libpurple 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
@@ -42,56 +42,57 @@
 @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.
+notification of various purple (or Pidgin, or finch, or ...) 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),
+libpurple 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.
+The purple-specific functions are provided in a statically-linked
+package called @c purple; this means that if you spawn a child
+interpreter and wish to use the purple-specific functions, you will need
+to execute <tt>load {} purple</tt> in that interpreter.
 
-@section internals Gaim Internal Procedures and Variables
+@section internals purple 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
+All of the information provided for your use by purple will be in the @c
+::purple namespace.  This means that in order to access it you will either
+have to import the purple namespace (e.g. via the command <tt>namespace
+import purple::*</tt>) or reference it explicitly.  The following
 descriptions will reference it explicitly for clarity.
 
 @li Variables
 
 @code
-gaim::version
+purple::version
 @endcode
 
-  This contains the version of the gaim process which loaded the
+  This contains the version of the libpurple library 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
+purple::account alias account
+purple::account connect account
+purple::account connection account
+purple::account disconnect account
+purple::account find username protocol
+purple::account handle
+purple::account isconnected account
+purple::account list ?option?
+purple::account protocol account
+purple::account username account
 @endcode
 
-  The @c gaim::account command consists of a set of subcommands
-  pertaining to gaim accounts.
+  The @c purple::account command consists of a set of subcommands
+  pertaining to purple 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.
@@ -101,24 +102,24 @@
   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
+  or 0 if it is not.  This @c gc is the gc used by purple::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 
+  <tt>purple::account username</tt> and <tt>purple::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>).
+  signals.  (See <tt>purple::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
+  libpurple.  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.
@@ -130,13 +131,13 @@
   @c account.
 
 @code
-gaim::buddy alias buddy
-gaim::buddy handle
-gaim::buddy info ( buddy | account username )
-gaim::buddy list
+purple::buddy alias buddy
+purple::buddy handle
+purple::buddy info ( buddy | account username )
+purple::buddy list
 @endcode
 
-  @c gaim::buddy is a set of commands for retrieving information about
+  @c purple::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",
@@ -157,73 +158,73 @@
   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>).
+  signals to buddy list events.  (See <tt>purple::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 info causes the purple-using UI 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
+purple::connection account gc
+purple::connection displayname gc
+purple::connection handle
+purple::connection list
 @endcode
 
-  @c gaim::connection is a collection of subcommands pertaining to
+  @c purple::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
+  @c account returns the purple account associated with @c gc.  This
+  account is the same account used by @c purple::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>.
+  <tt>purple_connection_get_display_name(gc)</tt>.
 
-  @c handle returns the gaim connections instance handle.  (See
-  <tt>gaim::signal connect</tt>).
+  @c handle returns the purple connections instance handle.  (See
+  <tt>purple::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.
+  @c purple::connection subcommands or other commands requiring a gc.
 
 @code
-gaim::conv_send account who text
+purple::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
+  @c purple::conv is simply a convenience wrapper for @c purple::send_im and
+  <tt>purple::conversation write</tt>.  It sends the IM, determines the from
+  and to arguments for <tt>purple::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.
+  may view the source for it by typing <tt>info body purple::conv_send</tt> at
+  a Purple Commander prompt.
 
-  Note that an error in either @c gaim::send_im or <tt>gaim::conversation
+  Note that an error in either @c purple::send_im or <tt>purple::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
+purple::conversation find ?-account account? name
+purple::conversation handle
+purple::conversation list
+purple::conversation new ?-chat? ?-im? account name
+purple::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.
+  @c purple::conversation provides an API for dealing with
+  conversations.  Given that libpurple clients are instant messenger
+  programs, 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>).
+  of signal connection.  (See <tt>purple::signal connect</tt>).
 
   @c list returns a list of all currently open conversations.
 
@@ -235,56 +236,56 @@
 
   @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
+  from the purple user (style @c send), being sent to the purple 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
+purple::core handle
+purple::core quit
 @endcode
 
-  This command exposes functionality provided by the gaim core API.
+  This command exposes functionality provided by the purple core API.
 
-  <tt>gaim::core handle</tt> returns a handle to the gaim core for signal
-  connection.  (See <tt>gaim::signal connect</tt>).
+  <tt>purple::core handle</tt> returns a handle to the purple core for signal
+  connection.  (See <tt>purple::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.)
+  @c quit exits the libpurple client 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
+purple::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).
+  Equivalent to the C purple_debug function, this command outputs
+  debugging information to the libpurple UI's debug window (or,
+  typically, stdout if that UI 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 purple_debug), no trailing \\n is
+  required.  (However, embedded newlines may be generated with \\n).
 
 @code
-gaim::notify ?type? title primary secondary
+purple::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.
+  Also a direct equivalent to a C function, purple_notify, this command
+  causes libpurple 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 purple
+  UI being used, but @c title should generally be the title of the
+  window, and @c primary and @c secondary text within that window; in
+  the Pidgin UI, @c primary is slightly larger than @c secondary and
+  displayed in a @b boldface font.
 
 @code
-gaim::send_im gc who text
+purple::send_im gc who text
 @endcode
 
   This sends an IM in the fashion of serv_send_im.  @c gc is the GC of
@@ -293,31 +294,31 @@
   and @c text is the text of the message.
 
 @code
-gaim::signal connect instance signal args proc
-gaim::signal disconnect instance signal
+purple::signal connect instance signal args proc
+purple::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).
+  @c purple::signal is a set of subcommands for dealing with purple
+  signals.
 
   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,
+  commands from the various parts of libpurple. @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.
+  connect a second procedure to the same signal will remove the existing
+  binding and replace it with the new procedure.  <tt>purple::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
+purple::unload
 @endcode
 
   This unloads the current plugin.  Note that preferences will not be
@@ -338,9 +339,9 @@
 might look like this:
 
 @code
-gaim::signal connect [gaim::conversation handle] receiving-im-msg {
+purple::signal connect [purple::conversation handle] receiving-im-msg {
 	if {[ string match "*shizzle*" $event::buffer ]} {
-		gaim::notify -info "tcl plugin" "Fo' shizzle" \
+		purple::notify -info "tcl plugin" "Fo' shizzle" \
 			"$event::sender is down with the shizzle"
 	}
 }
@@ -348,7 +349,7 @@
 
 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
+change the message itself from libpurple's vantage.  For those signals
 whose return value is meaningful, returning a value from the Tcl event
 will return that value as it would in C.