_TOC_
  A. Shchepin
  Innovation Center of Information
  Technologies (Sevcom)
  M. Rose
  Dover Beach Consulting, Inc.
  S. Golovan
  New Economic School
  M. Litvak
  Information Centre ISP
  July 27, 2004

                                                          Tkabber v0.9.6 (beta)
**** Abstract ****
Tkabber is an open source Jabber client, written in Tcl/Tk. This memo describes
the installation, configuration, and extension of Tkabber.

===============================================================================
**** Table of Contents ****
1.  Features
2.  Requirements
3.  Download, install and run
4.  Configuration
4.1  Pre-load
4.1.1  Tabbed Interface
4.1.2  Primary Look-and-Feel
4.1.3  Cryptography by default
4.1.4  Using of external TclXML library
4.1.5  Use ispell to check spelling
4.1.6  Debugging Output
4.1.7  Splash window
4.1.8  Periodically send empty string to server
4.1.9  I18n/L10n
4.2  Post-load
4.2.1  Look-and-Feel
4.2.2  The Autoaway Module
4.2.3  The Avatar Module
4.2.4  The Chat Module
4.2.5  The Clientinfo Module
4.2.6  The Conferenceinfo Module
4.2.7  The Cryptographic Module
4.2.8  The Emoticons Module
4.2.9  The File Transfer Module
4.2.10  The Groupchat Module
4.2.11  The Ispell Module
4.2.12  The Jidlink Module
4.2.13  The Logger Module
4.2.14  The Login Module
4.2.15  The Message Module
4.2.16  The Raw XML Input Module
4.2.17  The Roster Module
4.2.18  The Sound Module
4.3  Menu-load
4.3.1  The Avatar Module
4.3.2  The Browser Module
4.3.3  The Groupchat Module
4.3.4  The Login Module
4.3.5  The Message Module
4.3.6  The Presence Module
4.3.7  Miscellany
4.4  Final-Load
5.  Extensibility
5.1  Chat Hooks
5.2  Login Hooks
5.3  Presence Hooks
5.4  Roster Hooks
5.5  Miscellaneous Hooks
  Authors' Addresses
A.  Releases History
A.1  Main changes in 0.9.7
A.2  Main changes in 0.9.6beta
A.3  Main changes in 0.9.5beta
B.  XRDB
C.  Documentation TODO
D.  Acknowledgements
E.  Copyrights


===============================================================================
                                                                          _TOC_
**** 1. Features ****
Tkabber provides a Tcl/Tk interface to the Jabber instant messaging and
presence service.
Tcl/Tk is a graphical scripting language that runs on the Unix, Windows, and
Macintosh platforms. The choice of Tcl/Tk for a Jabber client is three-fold:
    * it is portable: once you install a Tcl/Tk interpreter on your system, the
      Tkabber script "just runs"  without having to compile anything;
    * it is customizable: Tkabber reads a configuration file when it starts
      that tells it the settings of various parameters; and,
    * it is extensible: the configuration file is actually a Tcl script, so you
      can replace or augment entire portions of Tkabber (if you're so
      inclined).
Although relatively new software, Tkabber is fully-featured:
       sessions:
               * hashed passwords
               * encrypted sessions (if you install an optional extension)
               * login via HTTP proxy
               * user-defined hooks for connection establishment and
                 release
               * XMPP/Jabber MIME type
       messages:
               * emoticons
               * signed/encrypted messages (if you install an optional
                 extension)
               * file transfers (HTTP, DTCP and IBB transports)
               * filters
               * groupchat (GroupChat-1.0 and Multi-User Chat conferencing
                 protocols)
               * headline messages
               * message events
               * completions of nick and commands
               * hyperlinks
               * user-defined hooks for chat window events
       presence:
               * avatars
               * browsing
               * groupchat and roster invitations
               * signed presence (if you install an optional extension)
               * vCards
               * user-defined hooks for presence changes
       windowing:
               * configurable look-and-feel via a resources database
               * unicode
               * tabbed/non-tabbed interface
               * sound notifications
               * nested roster groups
               * for Unix: auto-away, spell checking, KDE docking, and
                 WMaker icons
               * for Windows: auto-away, and taskbar icons

===============================================================================
                                                                          _TOC_
**** 2. Requirements ****
You should already have installed:
    * Tcl/Tk_version_8.3.3 (or later)
    * tcllib_version_1.2 (or later)
    * BWidget_1.3 (or later)
Most systems already come with these packages pre-installed. If not, various
Unix systems have them available as ready-made packages. Otherwise, go to the
URLs above and click on the appropriate download link for your system. Both
tcllib and BWidget are script libraries  no compiling is necessary. In the
case of Tcl/Tk, there are many ready-made binary packages available on the
download site.
The ActiveTcl distribution contains all three packages (along with the Img
package mentioned next); so, you may want to use that instead of three separate
downloads.
At your discretion, there are several optional packages that you may also
install. Tkabber will run just fine without them, but if they're available
Tkabber will make additional features available to you. So, here's the list:
    * Tcl/Tk supports only a small number of image formats (i.e., bitmaps, GIFs
      and portable pixmaps). If presence information contains avatars, these
      may be in other formats (e.g., PNGs or JPGs).

      Accordingly, you may want to install Img_version_1.2 (or later). This
      package works on both Unix and Windows.
    *

    * By default, communications between the server and client take place over
      a plaintext connection. While this may not be a problem in some local,
      wired environments, if your server is distant or your client is wireless,
      then you may want to encrypt all the client/server traffic.

      Accordingly, you may to install tls_version_1.4.1 (or later). This
      package works on both Unix and Windows. Note that if you're using Unix,
      then you'll also need to have OpenSSL installed. Fortunately, this comes
      preinstalled on many Unix systems. If it's not on your system, check
      here. (The Windows distribution of tls comes with all the necessary
      DLLs.)
    *

    * By default, end-to-end communications between two or more Jabber clients
      is plaintext. Depending on your environment, this may not be a problem
      for you. Alternatively, you may want to digitally-sign all of your
      outgoing messages, and allow others to encrypt their messages to you.

      Accordingly, you may want to install the gpgme package, which, at
      present, works only on Unix. Depending on what's already installed on
      your system, you may have to download upto three files:
          o Tcl_GPGME_version_1.0 (or later);
          o GPGME_version_0.3.11 (or later); and,
          o GPG_version_1.0.7 (or later).
    *

    * If you're running Unix or Windows, then you may want Tkabber to
      automatically mark you as away after a priod of inactivity.

      Accordingly, on Unix, you may want to install Tk_Xwin_version_1.0 (or
      later), whilst on WIndows, you may want to install Tcl_Winidle_version
      0.1 (or later).
    *

    * If you're running KDE, then you may want Tkabber to use the docking tray.


      Accordingly, you may want to install Tk_Theme_version_1.20 (or later).
    *

    * If you're running Windows, then you may want Tkabber to use the system
      tray.

      Accordingly, you may want to install Winico_version_0.3 (or later).
      Alternatiavely, Winico version 0.3 (with simpler installation) could be
      downloaded from_here.
    *

    * If you're a Tcl/Tk guru, then you may want to access the Tk console to
      debug things.

      Accordingly, you may want to install tkcon_version_2.3 (or later).
Please keep in mind that these are all "optional extras"  if they're not right
for you or your environment, don't bother with them!

===============================================================================
                                                                          _TOC_
**** 3. Download, install and run ****
Latest stable version is 0.9.7.
You can always find the latest development version via CVS. Do following steps:
    * export CVSROOT=:pserver:anonymous@jabberstudio.org:/home/cvs
    * cvs login
    * Enter empty password
    * cvs -z3 co tkabber/tkabber
    * And if you want to test some plugins, then do cvs -z3 co tkabber/tkabber-
      plugins
If you use the Debian GNU/Linux distribution, you may want to get the latest
stable version and all required packages using by apt. Just execute apt-get
install tk tcllib bwidget tkabber
No real installation is required, simply copy the tkabber/ directory to a
commonly-available area, and then either:
    * put this directory in your search-path; or,
    * make a calling script/shortcut to the file tkabber.tcl in that directory.
Although Tkabber comes with a Makefile, there's really not much to do  most
folks prefer to simply copy the distribution directory to somewhere in their
home directory.
From the shell, you can invoke Tkabber as:
% tkabber.tcl
whilst on a windowing system, simply double-click on that file or a short-cut
to it.
If you're a Tcl/Tk guru and have installed tkcon, then you may want to invoke
Tkabber as:
% tkcon.tcl -exec "" -root .tkconn -main "source tkabber.tcl"
Tkabber will automatically know that it's running under tkcon and will start by
hiding the Tk console window. Look under the Help menu to find the checkbutton
to show the console.
Also you can setup Tkabber as handler for XMPP/Jabber_MIME_Type. For this you
need to set hanler for application/xmpp+xml MIME type in your browser to
something like this:
tkabber -mime %s

===============================================================================
                                                                          _TOC_
**** 4. Configuration ****
One of the first thing that Tkabber does is read a file in your home directory
called ".tkabber/config.tcl". This is a Tcl source file, so obviously, it's a
lot easier to maintain this file if you know the Tcl programming language. If
you're not familiar with it, that's okay  most things you'll need to do are
pretty simple! (In fact, if you don't have your own configuration file, you'll
get the vanilla Tkabber, which hopefully you'll find quite usable.)
Tkabber is configured in four stages:
    * in the pre-load stage, configuration options which guide the loading
      process are set;
    * in the post-load stage, configuration options for each module are set;
    * in the menu-load stage, the user is given an option to re-arrange
      Tkabber's menu bar; and,
    * the final-load stage allows any last changes to be made before the
      "login" dialog window is displayed to the user.
Let's look at each, in turn.
*** 4.1 Pre-load ***
There are a few things that Tkabber needs to know immediately. These are:
# tabbed interface

set usetabbar 1


# primary look-and-feel

set pixmaps_theme default

set load_default_xrdb 1


# cryptography by default

set ssj::options(sign-traffic)    0
set ssj::options(encrypt-traffic) 0


# using of external tclxml library

set use_external_tclxml 0


# use ispell to check spelling

set use_ispell 0


# debugging output

set debug_lvls {jlib warning}


# splash window

set show_splash_window 0


# periodically send empty string to server

set keep_alive           0
set keep_alive_interval 10


# force english labels instead of native language

# ::msgcat::mclocale en
*** 4.1.1 Tabbed Interface ***
The first of these options, usetabbar, tells Tkabber whether you want a tabbed
interface or not. If not, here's what to put in your configuration file:
set usetabbar 0
Although tkabber is tolerant of a lot of configuration changes, the only time
you're allowed to change usetabbar is at the beginning of your configuration
file. After that, it must not be changed!
*** 4.1.2 Primary Look-and-Feel ***
Tkabber is shameless in borrowing icons from other Jabber clients. By setting
pixmaps_theme, you can select a family of related icons. Besides "default", you
can choose one of "gabber", "jajc", "jarl", "psi", or "icq".
If you want, you can have Tkabber use a different theme by setting
pixmaps_theme to a string that ends in "/", e.g.,
set pixmaps_theme ~/.tkabber/pixmaps/
The theme directory should have four directories named "browser", "roster",
"services", and, "tkabber". Each of these directories contains the icons that
make up the theme. To find out the names of the icons that go in each
directory, go to where you installed Tkabber and take a look at the directory
called "pixmaps/default/".
All of the windows, dialogs, etc., used by Tkabber are called "widgets". Each
widget determines most of its "look" from an "resource" database. On Unix, try
man palette to see what the primary "look-and-feel" options are, and man option
to see how to modify them. (On Windows, from the Start menu, select Tcl and
then Tcl Help, and then enter either "palette" or "option".)
Most folks who want to define a new look-and-feel put all their options in an
"xrdb" file, and then reference it this way:
    set load_default_xrdb 0
    option readfile ~/.tkabber/newlook.xrdb userDefault
The first line tells Tkabber not to load its default "xrdb" file, whilst the
second line tells Tkabber the file to load instead.
See Appendix_B for a list of all the resources that you can set to control
Tkabber's look-and-feel.
Directory "examples" contains several examples of resource database files
"*.xrdb".
Alternatively, if you're a Tcl "old timer", you can always do:
    set load_default_xrdb 0
    tk_bisque
to set the palette to a pleasing color scheme.
*** 4.1.3 Cryptography by default ***
Next, you may want to Tkabber to use cryptography by default. There are two
options:
    * whether the traffic you send should be digitally-signed; and,
    * if you have cryptographic information for someone, should the default
      action be to encipher your traffic for them.
(By defining these options early on, Tkabber will complain immediately if it
isn't able to load its cryptographic module; otherwise, the default behavior is
to proceed without any cryptographic buttons, menus, and so on.)
*** 4.1.4 Using of external TclXML library ***
By default Tkabber use version of TclXML library that come with it
distribution. This version is pure-Tcl, and it performance can be not suitable.
Then you can install TclXML with built-in expat support and set variable
use_external_tclxml:
set use_external_tclxml 0
*** 4.1.5 Use ispell to check spelling ***
On Unix, Tkabber can check spelling of what you entered by calling an external
program ispell. To enable this feature, add following line:
set use_ispell 1
*** 4.1.6 Debugging Output ***
Tkabber has a lot of debugging output. By default, it gets printed to the
standard output by a Tcl procedure called debugmsg. However, only information
about those modules listed in a variable called debug_lvls will be printed.
If you know how to program Tcl, then this will seem rather obvious:
set debug_lvls [list message presence ssj warning]

# if you want a different behavior,
#     define your own...

proc debugmsg {module msg} {
#    ...
}
Most users won't care about debugmsg because they're running Tkabber under an
application launcher so the standard output is never seen. However, if this
isn't the case for you, and you just don't want to see any of this stuff, put
this one line in your configuration file:
set debug_lvls {}
*** 4.1.7 Splash window ***
By default, when Tkabber startup, it show loading process in splash window. To
disable this feature, put this in your configuration file:
set show_splash_window 0
*** 4.1.8 Periodically send empty string to server ***
If you're using a proxy to talk to a Jabber server, after a period of
inactivity, the proxy may decide to disconnect you. To avoid this, you can tell
Tkabber to send an empty string to the server every keep_alive_interval
minutes:
set keep_alive 1
set keep_alive_interval 10
*** 4.1.9 I18n/L10n ***
Tkabber can show all messages in user's native language. This is done by using
Tcl's built-in msgcat package which looks for a directory called msgs/ wherever
you installed Tkabber, and then uses the LC_MESSAGES environment variable (or
LANG if LC_MESSAGES not set) to select the appropriate file. If you wish, you
can force use of a particular language by putting a line like this in your
configuration file:
::msgcat::mclocale en
*** 4.2 Post-load ***
After Tkabber reads your configuration file, it loads all of its own modules,
it then invokes a procedure called postload. This procedure is supposed to
perform module-specific configuration.
The default version of this procedure doesn't do anything. If you want to
configure one more module modules, then you need to define the procedure in
your configuration file, e.g.,
proc postload {} {
# look-and-feel

    global alert colors alert_lvls

    set alert_lvls(error)        1
    set alert_lvls(server)       1
    set alert_lvls(message)      2
    set alert_lvls(mesg_to_user) 3
    set alert_colors             {Black DarkBlue Blue Red}

    set raise_new_tab            1


# the autoaway module

    set plugins::autoaway::options(awaytime)      [expr  5*60*1000]
    set plugins::autoaway::options(xatime)        [expr 15*60*1000]
    set plugins::autoaway::options(status)        "Automatically away due to
idle"
    set plugins::autoaway::options(drop_priority) 1


# the avatar module

    set avatar::options(announce) 0
    set avatar::options(share)    0


# the chat module

    set chat::options(default_message_type) chat
    set chat::options(stop_scroll)          0
    set plugins::options(timestamp_format)  {[%R]}


# the clientinfo module

    set plugins::clientinfo::options(autoask) 0


# the conferenceinfo module

    set plugins::conferenceinfo::options(autoask)         0
    set plugins::conferenceinfo::options(interval)       60
    set plugins::conferenceinfo::options(err_interval) 3600


# the cryptographic module

    set ssj::options(encrypt,fred@example.com) 1


# the emoticon module

    emoteicons::load_dir ~/.tkabber/emoticons/rythmbox


# the file transfer module

    set ft::options(download_dir) "/tmp"


# the groupchat module

    global gra_group gra_server
    global gr_nick gr_group gr_server gr_v2
    global defaultnick

    set defaultnick(adhoc@conference.example.com) publius
    set defaultnick(*@conference.example.com) cicerone


# the ispell module

    set plugins::ispell::options(executable)          /usr/bin/ispell
    set plugins::ispell::options(dictionary)          russian
    set plugins::ispell::options(dictionary_encoding) koi8-r
    set plugins::ispell::options(check_every_symbol)  1


# the jidlink module

    set jidlink::transport(allowed,dtcp-passive) 0


# the logger module

    set logger::options(logdir)        ~/.tkabber/logs
    set logger::options(log_chat)      1
    set logger::options(log_groupchat) 1


# the login module

    global loginconf loginconf1 loginconf2 autologin

    set loginconf(user)          ""
    set loginconf(password)      ""
    set loginconf(resource)      tkabber
    set loginconf(server)        example.com
    set loginconf(port)          5222
    set loginconf(priority)      8
    set loginconf(usessl)        1
    set loginconf(sslport)       5223
    set loginconf(useproxy)      0
    set loginconf(httpproxy)     localhost
    set loginconf(httpproxyport) 3128
    set loginconf(httplogin)     ""
    set loginconf(httppassword)  ""

    # The following variables are useful when your jabber-server
    # (example.com) does not have A-record in DNS
    set loginconf(usealtserver)  1
    set loginconf(altserver)     "jabber.example.com"

    set loginconf1(profile)      "Default Account"
    set loginconf1(user)         mrose

    set loginconf2(profile)      "Test Account"
    set loginconf2(user)         test

    array set loginconf          [array get loginconf1]

    set autologin 0


# the message module

    set message::options(headlines,cache)    1
    set message::options(headlines,multiple) 1


# the raw xml input module

    set plugins::rawxml::set options(pretty_print) 0
    set plugins::rawxml::set options(indent)       2


# the roster module

    set roster::show_only_online            1
    set roster::roster(collapsed,RSS)       1
    set roster::roster(collapsed,Undefined) 1

    set roster::aliases(friend@some.host) \
        {friend@other.host friend@another.host}
    set roster::use_aliases                 1


# the sound module

    set sound::options(sound)                  1
    set sound::options(mute)                   0
    set sound::options(mute_groupchat_delayed) 1
    set sound::options(mute_chat_delayed)      0
    set sound::options(external_play_program) /usr/bin/play
}
This isn't nearly as complicated as it seems. Let's break it down by individual
module
*** 4.2.1 Look-and-Feel ***
If you're using the tabbed window interface, Tkabber needs a way of telling you
that something has changed in a window that's not on top. This is where the an
array called alert_lvls and a list called alert_colors come in. The array maps
an incoming message to a priority number from zero to three. The list, which is
indexed starting at zero, indicates what color the tab should use to let you
know that something's changed. So, the way to read the example is that
receiving:
    * an error or server message will cause the tab of a lowered window to go
      dark blue;
    * a groupchat or headline message will cause the tab to go blue; and,
    * a chat message addressed directly to you will cause the tab to go red.
By default, whenever a tab has new activity, it is automatically raised. If you
don't like this behavior, add this line:
set raise_new_tab 0
*** 4.2.2 The Autoaway Module ***
This module is presently available only if either:
    * on UNIX, if you have the Tk Xwin extension installed; or,
    * On Windows, if you have the Tcl Winidle extension installed.
There are two variables that control when Tkabber automatically marks you as
away: plugins::autoaway::options(awaytime) and plugins::autoaway::options
(xatime). Both define the idle threshold in milli-seconds.
If variable plugins::autoaway::options(drop_priority) is set in 1 then Tkabber
will set priority to 0 when moving in extended away state.
Variable plugins::autoaway::options(status) allows to specify text status,
which is set when Tkabber is moving in away state.
*** 4.2.3 The Avatar Module ***
There are two variables that you can set to control whether Tkabber will allow
others to see your avatar:
    * avatar::options(announce) determines whether your presence information
      indicates that you have an avatar; and,
    * avatar::options(share) determines whether requests for your avatar will
      be honored.
*** 4.2.4 The Chat Module ***
Most instant messaging users prefer to see all the back-and-forth communication
in a single window. If you prefer to see each line sent back-and-forth in a
separate window, here's what to put in your postload:
set chat::options(default_message_type) normal
The variable named chat::options(stop_scroll) determines whether a chat window
should automatically scroll down to the bottom whenever something new comes in.
You can also set format of time stamp that displayed in beginning of each chat
message. Refer to Tcl documentation for description of format. E.g., to display
it in "dd:mm:ss" format, add this line:
set plugins::options(timestamp_format) {[%T]}
*** 4.2.5 The Clientinfo Module ***
This module shows in popup balloons information of used by this user client
name, version, and OS. You can allow or deny automatic asking of this info from
users by setting this variable to 1 or 0:
set plugins::clientinfo::options(autoask) 1
*** 4.2.6 The Conferenceinfo Module ***
After you join a conference that's listed in your roster, then whenever you
mouse over that roster entry, you'll see a popup listing the conference's
participants. If you want to see this popup, regardless of whether you are
currently joined with the conference, add this line to your post-load:
set plugins::conferenceinfo::options(autoask) 1
You can also set interval between these requests with these two variables:
set plugins::conferenceinfo::options(interval)       60
set plugins::conferenceinfo::options(err_interval) 3600
The second variable defines how many seconds to wait after receiving an error
reply before trying again. (Usually an error reply indicates that the server
hosting the conference doesn't support browsing, so it makes sense not to try
that often.
*** 4.2.7 The Cryptographic Module ***
Earlier we saw an example where the ssj::options array from the cryptographic
module was set during the preload.
In addition to signed-traffic and encrypt-traffic, you can also tell Tkabber
whether to encrypt for a particular JID, e.g.,
    set ssj::options(encrypt,fred@example.com) 1
*** 4.2.8 The Emoticons Module ***
The procedure called emoteicons::load_dir is used to load emoticon definitions
from a directory. The directory contains a file called "icondef.xml", which
defines the mapping between each image and its textual emoticon (To find out
what this file looks like, go to where you installed Tkabber and take a look at
the file called "emoticons-tkabber/icondef.xml" or read JEP-0038.)
If you have just a few icons, and you don't want to create a directory and a
textual mapping, you can use the procedure called emoteicons::add, e.g.,
    emoteicons::add ":beer:" [image create photo -file ~/.tkabber/beer.gif]
*** 4.2.9 The File Transfer Module ***
You can set directory in which files will be saved by default:
    set ft::options(download_dir) "/tmp"
*** 4.2.10 The Groupchat Module ***
There are several variables that set the dialog window defaults for adding a
groupchat to your roster, or joining a groupchat:
       add to roster dialog window:
           gra_group and gra_server specify the default room and
           conference server, repectively; and,
       join dialog window:
           gr_nick, gr_group and gr_server specify the default nickname,
           room, and conference server, respectively, whilst gr_v2
           indicates whether the version 2 protocol should be used.
Note that variables gra_server, gr_nick and gr_server overriden in login
procedure, so better place for changing them is in connected_hook (see below).
You may want to have different nicknames for different groupchats. Accordingly,
the array called defaultnick is used to set the default nickname for when you
enter a conference. The array is indexed by the JID of the room, e.g.,
    set defaultnick(adhoc@conference.example.com) publius
Another possibility is to put pattern in parentheses. The following example
shows how to specify default nickname for all conferences at
conference.example.com:
    set defaultnick(*@conference.example.com) ciceroni
Exact JID's take the higher precedence than patterns.
*** 4.2.11 The Ispell Module ***
If you enabled this module earlier, then you can define:
    * the path to the ispell executable by setting plugins::ispell::options
      (executable)
    * the path to the dictionary by setting plugins::ispell::options
      (dictionary); and,
    * the encoding of the output by setting plugins::ispell::options
      (dictionary_encoding).
If you don't care about putting a large load on your process, then you can also
set plugins::ispell::options(check_every_symbol) to 1 to check correctness of
current word after every entered symbol. (Usually you don't need to set this
option.)
*** 4.2.12 The Jidlink Module ***
Jidlink is a simple negotiation protocol for setting up a bytestream between
two JIDs. With it you can specify what transports you can use, and via
negotiation choose more appropriate one. Tkabber comes with three transport
implementations:
       dtcp-active:
           that allows you to connect to any node that supports dtcp-
           passive;
       dtcp-passive:
           that allows any node that supports dtcp-active to connect to
           you; and,
       inband-bytestream:
           that uses your Jabber connection to transmit the data (which
           may slowdown other traffic to you).
If your machine is behind a firewall, then you can't use the dtcp-passive
transport, so you should disable it:
    set jidlink::transport(allowed,dtcp-passive) 0
*** 4.2.13 The Logger Module ***
You can set directory to store logs:
    set logger::options(logdir) ~/.tkabber/logs
Also you can allow or disallow storing of private and group chats logs:
    set logger::options(log_chat)      1
    set logger::options(log_groupchat) 1
*** 4.2.14 The Login Module ***
The first task is to initialize the configuration defaults for the login
module. As you can see above, the global array loginconf has a whole bunch of
elements, e.g., user, password, and so on. This collection of elements, which
is termed a login profile, is what populates the dialog window you'll see when
Tkabber wants to connect to the server.
It turns out that Tkabber lets you have as many different login profiles as you
want. If you want more than just one, they're named loginconf1, loginconf2, and
so on.
What the example above shows is the default values for all profiles being set
in loginconf, and then two profiles, one called "Default Account" and the other
called "Test Account" being created.
If you want to automatically login to server, then you can set the autologin
variable to 1.
If you set the autologin variable to -1, then Tkabber will not automatically
login and will not show login dialog.
Default value for autologin is 0. In this case Tkabber shows login dialog.
*** 4.2.15 The Message Module ***
By default, when you restart Tkabber it won't remember the headlines you
received. If you want Tkabber to remember headlines whenever you run it, set
message::options(headlines,cache) to 1.
By default, Tkabber will put all headline messages into a single window. If you
want Tkabber to use a seperate window for each headline source, set message::
options(headlines,multiple) to 1.
*** 4.2.16 The Raw XML Input Module ***
With this module you can monitor incoming/outgoing traffic from connection to
server and send custom XML stanzas. Also you can switch on pretty print option
to see incoming and outgoing XML stanzas pretty printed. Note, that with this
option they may be drawed incorrectly, e.g. for XHTML tags. Also you can set
indentation level via indent option.
*** 4.2.17 The Roster Module ***
By default, your entire roster is shown, even those items that aren't online.
The variable called roster::show_only_online controls this.
Similarly by default, each item in every category is shown in the roster. If
you want to hide the items in a given category, the array called roster::roster
lets you do this. In the example, we see that two groups ("RSS" and
"Undefined") start with their items hidden.
Some peoples use several JIDs. Tkabber lets you specify an alias for people
like these, so it will show only one entry in the roster. In the example, we
see that user friend@some.host have aliases friend@other.host and
friend@another.host. You can also disable all aliases by setting roster::
use_aliases to 0.
*** 4.2.18 The Sound Module ***
Tkabber can play sounds on some events. It can use for this snack library or
external program that can play WAV files. To enable sound notifications, you
can add following line:
set sound::options(sound) 1
If you want to start Tkabber with sound muted add the following line:
set sound::options(mute) 1
You can also mute sounds of delayed groupchat messages and delayed personal
chat messages:
set sound::options(mute_groupchat_delayed) 1
set sound::options(mute_chat_delayed)      0
If you want to use external program for playing sounds, then also add something
like this:
set sound::options(external_play_program) /usr/bin/play
You can also set minimal interval (in milliseconds) between playing different
sounds.
set sound::options(delay) 200
If you want to use another sound theme, then you can add line like this:
set sound::options(theme) "sound_theme"
Then Tkabber load sound files from directory called tkabber/sounds/sound_theme
if theme name not started with / or ~, else it consider theme name as path to
theme directory.
*** 4.3 Menu-load ***
After Tkabber invokes your postload procedure, it starts building the GUI. One
of the most important things it does is build up a list that specifies its menu
bar. It then invokes a procedure called menuload, which is allowed to modify
that specification before Tkabber uses it.
The default version of this procedure is the identity function, i.e..,
proc menuload {description} { return $description }
If you really want to change the menubar specification, then here's how to get
started:
   1. Go to where you installed the BWidget library and take a look at the file
      called "BWman/MainFrame.html". The documentation for the "-menu" option
      explains the syntax of the specification.
   2. Go to where you installed Tkabber and take a look at the file called
      "iface.tcl". Look for the line that starts with "set descmenu". This will
      show you the specification given to your menuload procedure.
   3. Go to where you installed Tkabber and take a look at the file called
      "examples/mtr-config.tcl". Look at the menuload procedure defined there.
      It lays out Tkabber's menu bar similar to Gabber's.
   4. Finally, study the procedures listed here.
*** 4.3.1 The Avatar Module ***
The procedure called avatar::store_on_server stores your avatar on the server.
*** 4.3.2 The Browser Module ***
The procedure called browser::open opens a new browser window.
*** 4.3.3 The Groupchat Module ***
The procedure called add_group_dialog displays a dialog window when you want to
add a groupchat to your roster. Similarly, the procedure called
join_group_dialog displays a dialog window when you want to join a groupchat.
*** 4.3.4 The Login Module ***
The procedure called show_login_dialog displays a dialog window when you want
to login to the server. (Prior to attempting to login, if necessary it will
logout). Naturally, the procedure called logout does just that; however, if you
want get a dialog window for confirmation, use show_logout_dialog instead.
*** 4.3.5 The Message Module ***
If you want to send a message to someone, the procedure called message::
send_dialog will put up a dialog window. It takes upto three optional
arguments: the recipient JID, the subject, and the thread.
If you want to get added to someone's roster, the procedure called message::
send_subscribe_dialog will put up a dialog window. It takes one optional
argument: the recipient JID.
If you want to adjust your message filters, the procecure called filters::open
will put up a dialog window.
*** 4.3.6 The Presence Module ***
If you want to display information about a user, the procecure called
userinfo::open will put up a dialog window. It takes two optional arguments:
the user's JID; and, whether or not the dialog window should be editable.
Obviously, the second argument makes sense only if it's your own information,
i.e.,
    global loginconf

    userinfo::open \
        ${loginconf(user)}@$loginconf(server)/$loginconf(resource) 1
There are also two variables that you can use to set your own presence:
userstatus and textstatus. The first variable takes one of five values:
    * available;
    * chat;
    * away;
    * xa;
    * dnd; or,
    * invisible.
The second variable takes any textual value.
Changes to your presence information are propagated only when userstatus is
changed. Accordingly, if you make a change to textstatus, be sure to write
userstatus immediately afterwards, even if it's a no-op, e.g.,
    global userstatus textstatus

    set textstatus "Out to lunch"
    set userstatus $userstatus
*** 4.3.7 Miscellany ***
Finally, you can use the procedure named help_window to display some textual
help. This procedure takes two arguments: the title for the window; and, the
text to display.
Also, instead of calling exit to terminate Tkabber, please use the quit
procedure instead.
*** 4.4 Final-Load ***
Finally, right before Tkabber goes to display the login dialog, it invokes a
procedure called finload, which does whatever you want it to.

===============================================================================
                                                                          _TOC_
**** 5. Extensibility ****
In addition to various configuration mechanisms, Tkabber lets you define
procedures, termed "hooks" that get run when certain events happen.
Here's an example. When Tkabber receives a chat message, how does it know what
to process and what to draw? The short answer is that it doesn't need to know
anything, all it does is:
hook::run draw_message_hook $jid $from $type $body $extras
The hook::run procedure invokes whatever hooks have been defined for
draw_message_hook. In fact, upto ten procedures may get invoked to satisfy this
hook!
Here's how it works: Tkabber comes with a number of plugins, which get loaded
automatically. Each plugin makes one or more calls that look like this:
hook::add draw_message_hook [namespace current]::my_draw_hook $prio
where the last two parameters are: the name of a procedure to run; and, an
relative integer priority.
When hook::run is invoked for draw_message_hook, each of these procedures is
called, in the priority order (from smallest to largest). If one of the
procedures wants to prevent the later procedures from being called, it returns
the string "stop".
To continue with the example, in between the pre-load and post-load stages of
configuration, the following calls get made by different plugins:
hook::add draw_message_hook ...::draw_signed            6
hook::add draw_message_hook ...::draw_encrypted         7
hook::add draw_message_hook ...::handle_error          10
hook::add draw_message_hook ...::draw_timestamp        15
hook::add draw_message_hook ...::logger::log_message   15
hook::add draw_message_hook ...::handle_server_message 20
hook::add draw_message_hook ...::handle_me             50
hook::add draw_message_hook    ::wmdock::msg_recv      70
hook::add draw_message_hook ...::draw_normal_message   80
Many of these procedures look at the incoming chat message and operate on only
certain kinds of messages. Some of these procedures may return "stop", e.g.,
handle_me which handles chat bodies that start with "/me". (In this example,
the actual namespaces were replaced with "...:" to make it more readable).
Now let's look at the different kind of hooks that Tkabber knows about.
*** 5.1 Chat Hooks ***
When Tkabber decides that it needs to open a (tabbed) window for a chat or
groupchat, two hooks are run:
open_chat_pre_hook  $jid $type
open_chat_post_hook $jid $type
Both hooks are given two parameters: the JID of the user (or conference room);
and, and the type of chat (either "chat" or "groupchat").
Similarly, when Tkabber encounters activity on a tabbed window, a hook is run:
raise_chat_tab_hook $path $jid
The hook is given two parameters: the path of the Tk widget for the tabbed
window; and, the JID of the user (or conference room).
When you want to send a chat message, a hook is run:
chat_send_message_hook $jid $user $body $type
The hook is given four parameters: the JID of the recipient; the localpart of
your login identity; the body of the message; and, the type of chat.
draw_message_hook $jid $from $type $body $extras
The hook is given five parameters: the JID of the sender (including a
resource); the JID of the sender (without the resource); the type of chat; the
body of the message; and, a nested-list of additional payload elements. (This
last parameter isn't documented in this version of the documentation.)
Chat windows have menubuttons, and two hooks is used to add items in menu:
chat_create_user_menu_hook $path $jid
chat_create_conference_menu_hook $path $jid
The first is used in user chat windows, and second in groupchat ones. Hooks is
given two parameters: the path of the Tk menu widget; and, the JID of user or
conference.
In groupchat windows possible to complete participant's nicks or commands by
pressing TAB key. List of completions is generated by running this hook:
generate_completions_hook $jid $compsvar $wordstart $line
The hook is given four parameters: the JID of conference; name of global
variable, in which stored current list of possible completions; index of
position where completion must be inserted; and, content of text widget where
completion is requested.
When someone enters/exits conference, next hooks called:
hook::run chat_user_enter $group $nick
hook::run chat_user_exit  $group $nick
The hook is given two parameters: JID of conference and nick participant.
*** 5.2 Login Hooks ***
Two hooks are invoked whenever a session is connected or disconnected:
connected_hook

disconnected_hook
Neither hook is given any parameters.
*** 5.3 Presence Hooks ***
When our presence status changes, a hook is run:
change_our_presence_post_hook $status
The hook is given one parameter: the new presence status value, i.e., one of:
    * available;
    * chat;
    * away;
    * xa;
    * dnd;
    * invisible; or,
    * unavailable.
Similarly, when someone else's presence changes, a hook is run:
on_change_user_presence_hook $jid $status
The hook is given two parameters: the label associated with the JID (e.g.,
"fred") or the JID itself (e.g., "fred@example.com") if no label exists in the
roster; and, the user's new status.
And for all received presence packets, a hook is run:
client_presence_hook $from $type $x $args
The hook is given three parameters: who send this presence, type of presence
(e.g., "error", "unavailable"), list of extended subtags and parameters of this
presence (e.g., "-show xa -status online").
*** 5.4 Roster Hooks ***
When a user is added to the roster window, a hook is run to add stuff to the
menu associated with that user:
roster_create_user_menu_hook $path $jids
The hook is given two parameters: the path of the Tk menu widget; and, a list
of JIDs for which presence information is available.
Also next hook is run to add stuff to the menu in groupchats:
roster_create_groupchat_user_menu_hook $path $jid
The hook is given two parameters: the path of the Tk menu widget; and, a JID of
user.
Next hook is run to add stuff to the popup balloon for each roster item:
roster_user_popup_info_hook $varname $jid
The hook is given two parameters: the variable name in which current popup text
is stored, and the JID of the roster item.
*** 5.5 Miscellaneous Hooks ***
There are three "obvious" hooks:
postload_hook

finload_hook

quit_hook
The first two, by default, run the postload and finload procedures,
respectively. The final hooks is called just before Tkabber terminates (cf.,
Section_4.3.7).

===============================================================================
                                                                          _TOC_
**** Authors' Addresses ****
        Alexey Yurievich Shchepin
        Innovation Center of Information Technologies (Sevcom)
EMail:  alexey@sevcom.net
         
        Marshall T. Rose
        Dover Beach Consulting, Inc.
        POB 255268
        Sacramento, CA 95865-5268
        US
Phone:  +1 916 483 8878
  Fax:  +1 916 483 8848
EMail:  mrose@dbc.mtview.ca.us
         
        Sergei Vitalyevich Golovan
        New Economic School
EMail:  sgolovan@nes.ru
         
        Michail Yurievich Litvak
        Information Centre ISP
EMail:  mci@al.lg.ua

===============================================================================
                                                                          _TOC_
**** Appendix A. Releases History ****
*** A.1 Main changes in 0.9.7 ***
    * Updated support for file transfer (JEP-0095, JEP-0096, JEP-0047, JEP-
      0065)
    * Support for colored nicks and messages in conference
    * Better multiple logins support
    * Updated support for xml:lang
    * Support for IDNA (RFC3490)
    * Many fixes and enhancements
*** A.2 Main changes in 0.9.6beta ***
    * Multiple logins support
    * History now splitted by month
    * Animated emoteicons support
    * Many user interface improvements
    * More XMPP support
    * More translations
    * Bugfixes
*** A.3 Main changes in 0.9.5beta ***
    * Nested roster groups
    * Messages emphasizing
    * User interface improvements
    * Support for XMPP/Jabber MIME Type
    * Bugfixes

===============================================================================
                                                                          _TOC_
**** Appendix B. XRDB ****
Here is list of most Tkabber-specific XRDB resources that you need to change
look:
       Tkabber.geometry
           Geometry of main window.
       *Chat.chatgeometry
       *Chat.groupchatgeometry
       *Customize.geometry
       *RawXML.geometry
       *Stats.geometry
       *Messages.geometry
       *JBrowser.geometry
       *JDisco.geometry
           Geometry of various windows (when not using tabs).
       *Chat.inputheight
       *RawXML.inputheight
           Height of input windows in chat and raw XML windows.
       *Balloon.background
       *Balloon.foreground
           Background and foreground colors of popup balloon.
       *Balloon.style
           Behaviour of popup balloon: can be delay (balloon appeared
           after some time) and follow (balloon appeared immediately and
           follows mouse).
       *JBrowser.fill
           Color of browser item name.
       *JBrowser.nscolor
           Color of NS browser item.
       *JBrowser*Tree*background
           Background of browser.
       *Chat.meforeground
           Color of user's messages in chat windows.
       *Chat.theyforeground
           Color of other peoples messages in chat windows.
       *Chat.serverlabelforeground
           Color of label before server message.
       *Chat.serverforeground
           Color of server messages in chat windows.
       *Chat.errforeground
           Color of error messages in chat windows.
       *Chat.urlforeground
           Color of URLs in chat windows.
       *Chat.urlactiveforeground
           Color of mouse highlighted URLs in chat windows.
       *JDisco.fill
           Default color of items in Service Discovery Browser.
       *JDisco.featurecolor
           Default color of feature items in Service Discovery Browser.
       *JDisco.identitycolor
           Default color of identity items in Service Discovery Browser.
       *JDisco.optioncolor
           Default color of option items in Service Discovery Browser.
       *JDisco*Tree*background
           Default color of background in Service Discovery Browser.
       *NoteBook.alertColor0
       *NoteBook.alertColor1
       *NoteBook.alertColor2
       *NoteBook.alertColor3
           Tabs alert colors.
       *Roster.cbackground
           Roster background color.
       *Roster.groupindent
           Indentation for group title.
       *Roster.groupiconindent
           Indentation for group icon.
       *Roster.jidindent
           Indentation for item name.
       *Roster.jidmultindent
           Indentation for item with multiple resources.
       *Roster.subjidindent
           Indentation for item resource.
       *Roster.iconindent
           Indentation for item icon.
       *Roster.subitemtype
       *Roster.subiconindent
           Indentation for resource icon.
       *Roster.textuppad
           Top pad for item's names.
       *Roster.textdownpad
           Bottom pad for item's names.
       *Roster.linepad
           Vertical distance between items.
       *Roster.foreground
           Color of item's names.
       *Roster.jidfill
           Background of roster item.
       *Roster.jidhlfill
           Background of roster item when mouse is over.
       *Roster.jidborder
           Color of item's border.
       *Roster.groupfill
       *Roster.grouphlfill
       *Roster.groupborder
           The same to roster groups.
       *Roster.groupcfill
           Background color of collapsed group.
       *Roster.stalkerforeground
       *Roster.unavailableforeground
       *Roster.dndforeground
       *Roster.xaforeground
       *Roster.awayforeground
       *Roster.availableforeground
       *Roster.chatforeground
           Colors of item name for different presences.

===============================================================================
                                                                          _TOC_
**** Appendix C. Documentation TODO ****
The next revision of this documentation should discuss:
    * Pre-load:
          o browseurl
    * Post-load:
          o chat_height and chat_width (appear to be no-ops).
    * Menu-load:
          o change_password_dialog
          o conference::create_room_dialog
          o disco::browser::open_win
          o message::send_msg
          o privacy::request_lists
          o rawxml::open_window
          o userinfo::show_info_dialog
    * Hooks: the additional payload format.

===============================================================================
                                                                          _TOC_
**** Appendix D. Acknowledgements ****
Rebecca Malamud was kind enough to design the "enlightened feather" motif used
in the Tkabber look-and-feel.

===============================================================================
                                                                          _TOC_
**** Appendix E. Copyrights ****
(c) 2002--2004 Alexey Shchepin
Hold harmless the authors, and any lawful use is allowed.