<?xml version='1.0'?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>

<?rfc compact='no'?>
<?rfc toc='yes'?>
<?rfc tocdepth='3'?>
<?rfc private=' '?>

<rfc>
<front>
<title>Tkabber v0.9.6 (beta)</title>

    <author initials='A.Y.' surname='Shchepin'
	    fullname='Alexey Yurievich Shchepin'>
      <organization>
	Innovation Center of Information Technologies (Sevcom)
      </organization>
      <address>
	<email>alexey@sevcom.net</email>
      </address>
    </author>

<author initials='M.T.' surname='Rose' fullname='Marshall T. Rose'>
<organization>Dover Beach Consulting, Inc.</organization>
<address>
<postal>
<street>POB 255268</street>
<city>Sacramento</city> <region>CA</region> <code>95865-5268</code>
<country>US</country>
</postal>
<phone>+1 916 483 8878</phone>
<facsimile>+1 916 483 8848</facsimile>
<email>mrose@dbc.mtview.ca.us</email>
</address>
</author>

    <author initials='S.V.' surname='Golovan' fullname='Sergei Vitalyevich Golovan'>
	<organization>New Economic School</organization>
	<address>
	    <email>sgolovan@nes.ru</email>
	</address>
    </author>

<author initials='M.Y.' surname='Litvak'
        fullname='Michail Yurievich Litvak'>
<organization>Information Centre ISP</organization>
<address>
<email>mci@al.lg.ua</email>
</address>
</author>

<date month='July' year='2004' />

<abstract><t><spanx>Tkabber</spanx> is an open source Jabber client,
written in <spanx>Tcl/Tk</spanx>.
This memo describes the installation, configuration, and extension of
<spanx>Tkabber</spanx>.</t></abstract> 
</front>

<middle>

<section anchor='s.features' title='Features'>
<t><eref target='http://tkabber.jabberstudio.org/'>Tkabber</eref>
provides a <spanx>Tcl/Tk</spanx> interface to the
<eref target='http://www.jabber.org/'>Jabber</eref> instant messaging
and presence service.</t>

<t><spanx>Tcl/Tk</spanx> is a graphical scripting language that runs on the Unix,
Windows, and Macintosh platforms.
The choice of <spanx>Tcl/Tk</spanx> for a Jabber client is three-fold:
<list style='symbols'>
<t>it is portable:
once you install a <spanx>Tcl/Tk</spanx> interpreter on your system,
the <spanx>Tkabber</spanx> script "just runs" &#151; without having to compile
anything;</t>

<t>it is customizable:
<spanx>Tkabber</spanx> reads a configuration file when it starts that tells it the
settings of various parameters;
and,</t>

<t>it is extensible:
the configuration file is actually a <spanx>Tcl</spanx> script,
so you can replace or augment entire portions of <spanx>Tkabber</spanx>
(if you're so inclined).</t>
</list></t>

<t>Although relatively new software,
<spanx>Tkabber</spanx> is fully-featured:
	<list style='hanging'>
	  <t hangText='sessions:'>
	    <list style='symbols'>
	      <t>hashed passwords</t>
	      <t>encrypted sessions (if you install an optional extension)</t>
	      <t>login via HTTP proxy</t>
	      <t>
		user-defined hooks for connection establishment and
		release
	      </t>
	      <t>XMPP/Jabber MIME type</t>
	    </list>
	  </t>

	  <t hangText='messages:'>
	    <list style='symbols'>
	      <t>emoticons</t>
	      <t>
		signed/encrypted messages (if you install an optional
		extension)
	      </t>
	      <t>file transfers (HTTP, DTCP and IBB transports)</t>
	      <t>filters</t>
	      <t>
		groupchat (GroupChat-1.0 and Multi-User Chat conferencing
		protocols)
	      </t>
	      <t>headline messages</t>
	      <t>message events</t>
	      <t>completions of nick and commands</t>
	      <t>hyperlinks</t>
	      <t>user-defined hooks for chat window events</t>
	    </list></t>

<t hangText='presence:'>
<list style='symbols'>
<t>avatars</t>
<t>browsing</t>
<t>groupchat and roster invitations</t>
<t>signed presence (if you install an optional extension)</t>
<t>vCards</t>
<t>user-defined hooks for presence changes</t>
</list></t>

	  <t hangText='windowing:'>
	    <list style='symbols'>
	      <t>configurable look-and-feel via a resources database</t>
	      <t>unicode</t>
	      <t>tabbed/non-tabbed interface</t>
	      <t>sound notifications</t>
	      <t>nested roster groups</t>
	      <t>
		for Unix: auto-away, spell checking, KDE docking, and WMaker
		icons
	      </t>
	      <t>
		for Windows: auto-away, and taskbar icons
	      </t>
	    </list>
	  </t>
	</list>
      </t>
</section>

<section anchor='s.requirements' title='Requirements'>
<t>You should already have installed:
<list style='symbols'>
<t><eref target='http://sourceforge.net/project/showfiles.php?group_id=10894'>Tcl/Tk
version 8.3.3</eref> (or later)</t>

<t><eref target='http://sourceforge.net/project/showfiles.php?group_id=12883'>tcllib
version 1.2</eref> (or later)</t>

<t><eref target='http://sourceforge.net/project/showfiles.php?group_id=12883'>BWidget
1.3</eref> (or later)</t>
</list>
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 <spanx>tcllib</spanx> and <spanx>BWidget</spanx> are script libraries &#151;
no compiling is necessary.
In the case of <spanx>Tcl/Tk</spanx>,
there are many ready-made binary packages available on the download site.</t>

<t>The <eref target='http://www.activestate.com/Products/ActiveTcl'>ActiveTcl</eref>
distribution contains all three packages
(along with the <spanx>Img</spanx> package mentioned next);
so,
you may want to use that instead of three separate downloads.</t>

<t>At your discretion,
there are several optional packages that you may also install.
<spanx>Tkabber</spanx> will run just fine without them,
but if they're available <spanx>Tkabber</spanx> will make additional features
available to you.
So,
here's the list:
<list style='symbols'>
<t><spanx>Tcl/Tk</spanx> 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).
<vspace blankLines='1' />
Accordingly,
you may want to install 
<eref target='http://purl.oclc.com/net/nijtmans/img.html'>Img version
1.2</eref> (or later).
This package works on both Unix and Windows.</t>
<!-- http://www.xs4all.nl/~nijtmans/img.html -->
<vspace blankLines='1' />

<t>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.
<vspace blankLines='1' />
Accordingly,
you may to install
<eref target='http://sourceforge.net/project/showfiles.php?group_id=13248'>tls
version 1.4.1</eref> (or later).
This package works on both Unix and Windows.
Note that if you're using Unix,
then you'll also need to have <spanx>OpenSSL</spanx> installed.
Fortunately,
this comes preinstalled on many Unix systems.
If it's not on your system,
check <eref target='http://www.openssl.org/source/'>here</eref>.
(The Windows distribution of <spanx>tls</spanx> comes with all the necessary DLLs.)</t>
<vspace blankLines='1' />

<t>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.
<vspace blankLines='1' />
Accordingly,
you may want to install the <spanx>gpgme</spanx> 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:
<list style='symbols'>
<t><eref target="http://beepcore-tcl.sourceforge.net/tclgpgme-1.0.tgz">Tcl
GPGME version 1.0</eref> (or later);</t>

<t><eref target='ftp://ftp.gnupg.org/gcrypt/alpha/gpgme/'>GPGME
version 0.3.11</eref> (or later); and,</t>

<t><eref target="http://www.gnupg.org/download.html">GPG version 1.0.7</eref>
(or later).</t>
</list></t>
<vspace blankLines='1' />

<t>If you're running Unix or Windows,
then you may want <spanx>Tkabber</spanx> to automatically mark you as away after a
priod of inactivity.
<vspace blankLines='1' />
Accordingly,
on Unix,
you may want to install
<eref target="http://beepcore-tcl.sourceforge.net/tkXwin-1.0.tgz">Tk
Xwin version 1.0</eref> (or later),
whilst on WIndows,
you may want to install
<eref target="http://sgolovan.nes.ru/jabber/tclWinidle/">Tcl
Winidle version 0.1</eref> (or later).</t>
<vspace blankLines='1' />

<t>If you're running <spanx>KDE</spanx>,
then you may want <spanx>Tkabber</spanx> to use the docking tray.
<vspace blankLines='1' />
Accordingly,
you may want to install
<eref target="http://www.xmission.com/~georgeps/Tk_Theme/">Tk Theme
version 1.20</eref> (or later).</t>
<vspace blankLines='1' />

<t>If you're running Windows,
then you may want <spanx>Tkabber</spanx> to use the system tray.
<vspace blankLines='1' />
Accordingly,
you may want to install
<eref target="http://ftp.bj-ig.de/pub/tcltk/winico31.zip">Winico
version 0.3</eref> (or later).
Alternatiavely, Winico version 0.3 (with simpler installation) could be downloaded
<eref target="http://sgolovan.nes.ru/jabber/tclWinidle/winico.zip">from here.</eref>
</t>
<vspace blankLines='1' />

<t>If you're a Tcl/Tk guru,
then you may want to access the Tk console to debug things.
<vspace blankLines='1' />
Accordingly,
you may want to install
<eref target="http://tkcon.sourceforge.net">tkcon version 2.3</eref>
(or later).</t>
</list>
Please keep in mind that these are all "optional extras" &#151;
if they're not right for you or your environment,
don't bother with them!</t>
</section>

<section anchor='s.download' title='Download, install and run'>
<t>Latest stable version is <eref target='http://www.jabberstudio.org/projects/tkabber/releases/'>0.9.7</eref>.</t>

<t>You can always find the latest development version via CVS. Do following steps:
<list style='symbols'>
<t><![CDATA[export CVSROOT=:pserver:anonymous@jabberstudio.org:/home/cvs]]></t>
<t><![CDATA[cvs login]]></t>
<t>Enter empty password</t>
<t><![CDATA[cvs -z3 co tkabber/tkabber]]></t>
<t>And if you want to test some plugins, then do <![CDATA[cvs -z3 co tkabber/tkabber-plugins]]></t>
</list>
</t>
<t>If you use the Debian GNU/Linux distribution, you may want to get the latest 
stable version and all required packages using by <spanx>apt</spanx>. 
Just execute <![CDATA[apt-get install tk tcllib bwidget tkabber]]>
</t> 

<t>No real installation is required, simply copy the <spanx style='verb'>tkabber/</spanx> directory to a commonly-available area,
and then either:
<list style='symbols'>
<t>put this directory in your search-path; or,</t>

<t>make a calling script/shortcut to the file <spanx style='verb'>tkabber.tcl</spanx> in that directory.</t>
</list>
Although <spanx>Tkabber</spanx> comes with a Makefile,
there's really not much to do &#151; most folks prefer to simply copy
the distribution directory to somewhere in their home directory.</t>

<figure>
<preamble>From the shell,
you can invoke <spanx>Tkabber</spanx> as:</preamble>
<artwork><![CDATA[
% tkabber.tcl
]]></artwork>
<postamble>whilst on a windowing system,
simply double-click on that file or a short-cut to it.</postamble>
</figure>

<figure>
<preamble>If you're a Tcl/Tk guru and have installed <spanx>tkcon</spanx>,
then you may want to invoke <spanx>Tkabber</spanx> as:</preamble>
<artwork><![CDATA[
% tkcon.tcl -exec "" -root .tkconn -main "source tkabber.tcl"
]]></artwork>
<postamble>
<spanx>Tkabber</spanx> will automatically know that it's running under <spanx>tkcon</spanx>
and will start by hiding the <spanx>Tk</spanx> console window.
Look under the <spanx style='verb'>Help</spanx> menu to find the checkbutton to show the
console.</postamble>
</figure>
	<figure>
	  <preamble>
	    Also you can setup <spanx>Tkabber</spanx> as handler for
	    <eref target="http://jabber.org/jeps/jep-0081.html">
	      XMPP/Jabber MIME Type
	    </eref>.  For this you need to set hanler for
	    <spanx style='verb'>application/xmpp+xml</spanx> MIME type in your
	    browser to something like this:
	  </preamble>
	  <artwork>
tkabber -mime %s
</artwork>
	</figure>
</section>

<section anchor='s.configuration' title='Configuration'>
<t>One of the first thing that <spanx>Tkabber</spanx> does is read a file in your
home directory called <spanx style='verb'>".tkabber/config.tcl"</spanx>.
This is a <spanx>Tcl</spanx> 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 &#151; 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 <spanx>Tkabber</spanx>,
which hopefully you'll find quite usable.)</t>

<t><spanx>Tkabber</spanx> is configured in four stages:
<list style='symbols'>
<t>in the pre-load stage,
configuration options which guide the loading process are set;</t>

<t>in the post-load stage,
configuration options for each module are set;</t>

<t>in the menu-load stage,
the user is given an option to re-arrange <spanx>Tkabber's</spanx> menu bar; and,</t>

<t>the final-load stage allows any last changes to be made before the
"login" dialog window is displayed to the user.</t>
</list>
Let's look at each,
in turn.</t>

<section anchor='s.preload' title='Pre-load'>
<figure>
<preamble>There are a few things that <spanx>Tkabber</spanx> needs to know
immediately.
These are:</preamble>
<artwork><![CDATA[
# 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
]]></artwork>
</figure>

<section anchor='s.preload.tab' title='Tabbed Interface'>
<figure>
<preamble>The first of these options,
<spanx style='verb'>usetabbar</spanx>,
tells <spanx>Tkabber</spanx> whether you want a tabbed interface or not.
If not,
here's what to put in your configuration file:</preamble>
<artwork><![CDATA[
set usetabbar 0
]]></artwork>
<postamble>Although tkabber is tolerant of a lot of configuration
changes,
the only time you're allowed to change <spanx style='verb'>usetabbar</spanx> is at the
beginning of your configuration file.
After that,
it must not be changed!</postamble>
</figure>
</section>

	<section anchor='s.preload-looknfeel' title='Primary Look-and-Feel'>
	  <t>
	    <spanx>Tkabber</spanx> is shameless in borrowing icons from other Jabber
	    clients.  By setting <spanx style='verb'>pixmaps_theme</spanx>, you can select a family of
	    related icons.  Besides <spanx style='verb'>"default"</spanx>, you can choose one of
	    <spanx style='verb'>"gabber"</spanx>, <spanx
	    style='verb'>"jajc"</spanx>, <spanx
	    style='verb'>"jarl"</spanx>, <spanx
	    style='verb'>"psi"</spanx>, or <spanx style='verb'>"icq"</spanx>.
	  </t>
	  
	  <figure>
<preamble>If you want,
you can have <spanx>Tkabber</spanx> use a different theme by setting
<spanx style='verb'>pixmaps_theme</spanx> to a string that ends in
<spanx style='verb'>"/"</spanx>, e.g.,</preamble>
<artwork><![CDATA[
set pixmaps_theme ~/.tkabber/pixmaps/
]]></artwork>
<postamble>The theme directory should have four directories named
<spanx style='verb'>"browser"</spanx>, <spanx
style='verb'>"roster"</spanx>, <spanx style='verb'>"services"</spanx>,
and, <spanx style='verb'>"tkabber"</spanx>.
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 <spanx>Tkabber</spanx> and take a look at the directory 
called <spanx style='verb'>"pixmaps/default/"</spanx>.</postamble>
</figure>


<t>All of the windows, dialogs, etc.,
used by <spanx>Tkabber</spanx> are called "widgets".
Each widget determines most of its "look" from an "resource"
database.
On Unix,
try <spanx style='verb'>man palette</spanx> to see what the primary "look-and-feel" options are,
and <spanx style='verb'>man option</spanx> to see how to modify them.
(On Windows,
from the <spanx>Start</spanx> menu,
select <spanx>Tcl</spanx> and then <spanx>Tcl Help</spanx>,
and then enter either <spanx style='verb'>"palette"</spanx> or <spanx style='verb'>"option"</spanx>.)</t>

	  <figure>
	    <preamble>
	      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:
	    </preamble>
<artwork><![CDATA[
    set load_default_xrdb 0
    option readfile ~/.tkabber/newlook.xrdb userDefault
]]></artwork>
	    <postamble>
	      The first line tells <spanx>Tkabber</spanx> not to load its default "xrdb"
	      file, whilst the second line tells <spanx>Tkabber</spanx> the file to load
	      instead.
	    </postamble>
	  </figure>

<t>See <xref target='XRDB' /> for a list of all the resources that you
can set to control <spanx>Tkabber's</spanx> look-and-feel.</t>
<t>Directory <spanx style='verb'>"examples"</spanx> contains several
examples of resource database files <spanx style='verb'>"*.xrdb"</spanx>.</t>

<figure>
<preamble>Alternatively,
if you're a Tcl "old timer", you can always do:
</preamble>
<artwork><![CDATA[
    set load_default_xrdb 0
    tk_bisque
]]></artwork>
<postamble>to set the palette to a pleasing color scheme.
</postamble>
</figure>
</section>

<section anchor='s.preload-crypto' title='Cryptography by default'>
<t>Next,
you may want to <spanx>Tkabber</spanx> to use cryptography by default.
There are two options:
<list style='symbols'>
<t>whether the traffic you send should be digitally-signed; and,</t>

<t>if you have cryptographic information for someone,
should the default action be to encipher your traffic for them.</t>
</list>
(By defining these options early on,
<spanx>Tkabber</spanx> 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.)</t>
</section>

	<section anchor='s.preload-tclxml' title="Using of external TclXML library">
	  <figure>
	    <preamble>
	      By default <spanx>Tkabber</spanx> use version of <spanx>TclXML</spanx> library that come
	      with it distribution.  This version is pure-Tcl, and it
	      performance can be not suitable.  Then you can install <spanx>TclXML</spanx>
	      with built-in <spanx>expat</spanx> support and set variable
	      <spanx style='verb'>use_external_tclxml</spanx>:
	    </preamble>
<artwork>
set use_external_tclxml 0
</artwork>
	  </figure>
	</section>

	<section anchor='s.preload-ispell' title="Use ispell to check spelling">
	  <figure>
	    <preamble>
	      On Unix, <spanx>Tkabber</spanx> can check spelling of what you entered by
	      calling an external program <spanx>ispell</spanx>.  To enable this feature, add
	      following line:
	    </preamble>
<artwork>
set use_ispell 1
</artwork>
	  </figure>
	</section>

<section anchor='s.preload-debugoutput' title='Debugging Output'>
<t><spanx>Tkabber</spanx> has a lot of debugging output.
By default,
it gets printed to the standard output by a Tcl procedure called
<spanx style='verb'>debugmsg</spanx>.
However,
only information about those modules listed in a variable called
<spanx style='verb'>debug_lvls</spanx> will be printed.</t>

<figure>
<preamble>If you know how to program Tcl,
then this will seem rather obvious:</preamble>
<artwork><![CDATA[
set debug_lvls [list message presence ssj warning]

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

proc debugmsg {module msg} {
#    ...
}
]]></artwork>
</figure>

<figure>
<preamble>Most users won't care about <spanx style='verb'>debugmsg</spanx> because they're
running <spanx>Tkabber</spanx> 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:</preamble>
<artwork><![CDATA[
set debug_lvls {}
]]></artwork>
</figure>
</section>
	<section anchor='s.preload-splashwindow' title='Splash window'>
	  <figure>
	    <preamble>
	      By default, when <spanx>Tkabber</spanx> startup, it show loading process in
	      splash window.  To disable this feature, put this in your
	      configuration file:
	    </preamble>
<artwork><![CDATA[
set show_splash_window 0
]]></artwork>
	  </figure>
	</section>

	<section anchor='s.preload-sendempty' title="Periodically send empty string to server">
	  <figure>
	    <preamble>
	      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 <spanx>Tkabber</spanx> to send an empty
	      string to the server every <spanx>keep_alive_interval</spanx> minutes:
	    </preamble>
<artwork><![CDATA[
set keep_alive 1
set keep_alive_interval 10
]]></artwork>
	  </figure>
	</section>

	<section anchor='s.preload-internation' title="I18n/L10n">
	  <figure>
	    <preamble>
	      <spanx>Tkabber</spanx> can show all messages in user's native language.  This
	      is done by using Tcl's built-in <spanx>msgcat</spanx> package which looks for
	      a directory called <spanx style='verb'>msgs/</spanx> wherever you installed <spanx>Tkabber</spanx>,
	      and then uses the <spanx
	      style='verb'>LC_MESSAGES</spanx> environment variable
	      (or <spanx style='verb'>LANG</spanx>
	      if <spanx style='verb'>LC_MESSAGES</spanx> 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:
	    </preamble>
<artwork><![CDATA[
::msgcat::mclocale en
]]></artwork>
	  </figure>
	</section>
	</section>

<section anchor='s.postload' title='Post-load'>
<t>After <spanx>Tkabber</spanx> reads your configuration file,
it loads all of its own modules,
it then invokes a procedure called <spanx style='verb'>postload</spanx>.
This procedure is supposed to perform module-specific configuration.</t>

<figure>
<preamble>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.,</preamble>
<artwork><![CDATA[
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
}
]]></artwork>
<postamble>This isn't nearly as complicated as it seems.
Let's break it down by individual module</postamble>
</figure>

	<section anchor='s.postload-looknfeel' title='Look-and-Feel'>
	  <t>
	    If you're using the tabbed window interface, <spanx>Tkabber</spanx> 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 <spanx>alert_lvls</spanx> and a list
	    called <spanx>alert_colors</spanx> come in.  The array maps an incoming message
	    to a priority number from zero to three.  The list, which is
	    indexed starting at <spanx>zero</spanx>, 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:
	    <list style='symbols'>
	      <t>
		an error or server message will cause the tab of a lowered
		window to go dark blue;
	      </t>
	      <t>
		a groupchat or headline message will cause the tab to go blue;
		and,
	      </t>
	      <t>
		a chat message addressed directly to you will cause the tab to
		go red.
	      </t>
	    </list>
	  </t>
	  <figure>
	    <preamble>By default, whenever a tab has new activity,
it is automatically raised.
If you don't like this behavior,
add this line:
	    </preamble>
	    <artwork>set raise_new_tab 0</artwork>
	  </figure>
	</section>

<section anchor='s.postload-autoaway' title='The Autoaway Module'>
<t>This module is presently available only if either:
<list style='symbols'>
<t>on UNIX, if you have the <spanx>Tk Xwin</spanx> extension installed; or,</t>

<t>On Windows, if you have the <spanx>Tcl Winidle</spanx> extension installed.</t>
</list></t>

<t>There are two variables that control when <spanx>Tkabber</spanx> automatically
marks you as away:
<spanx style='verb'>plugins::autoaway::options(awaytime)</spanx> and
<spanx style='verb'>plugins::autoaway::options(xatime)</spanx>.
Both define the idle threshold in milli-seconds.</t>

<t>If variable <spanx style='verb'>plugins::autoaway::options(drop_priority)</spanx> is set in 1 then
<spanx>Tkabber</spanx> will set priority to 0 when moving in extended away state.</t>

<t>Variable <spanx style='verb'>plugins::autoaway::options(status)</spanx> allows to specify text status, which
is set when <spanx>Tkabber</spanx> is moving in away state.</t>
</section>

<section anchor='s.postload-avatar' title='The Avatar Module'>
<t>There are two variables that you can set to control whether
<spanx>Tkabber</spanx> will allow others to see your avatar:
<list style='symbols'>
<t><spanx style='verb'>avatar::options(announce)</spanx> determines whether your presence
information indicates that you have an avatar; and,</t>

<t><spanx style='verb'>avatar::options(share)</spanx> determines whether requests for your
avatar will be honored.</t>
</list></t>
</section>

<section anchor='s.postload-chat' title='The Chat Module'>
<figure>
<preamble>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 <spanx style='verb'>postload</spanx>:</preamble>
<artwork><![CDATA[
set chat::options(default_message_type) normal
]]></artwork>
</figure>

<t>The variable named <spanx style='verb'>chat::options(stop_scroll)</spanx> determines whether
a chat window should automatically scroll down to the bottom whenever
something new comes in.</t>

	  <figure>
	    <preamble>
	      You can also set format of time stamp that displayed in beginning
	      of each chat message.  Refer to <spanx>Tcl</spanx> documentation
	      for description of format.  E.g., to display it in
	      <spanx style='verb'>"dd:mm:ss"</spanx> format, add this line:
	    </preamble>
	    <artwork>
set plugins::options(timestamp_format) {[%T]}
</artwork>
	  </figure>

</section>

	<section anchor='s.postload-clientinfo' title="The Clientinfo Module">
	  <figure>
	    <preamble>
	      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:
	    </preamble>
	    <artwork>set plugins::clientinfo::options(autoask) 1</artwork>
	  </figure>
	</section>

	<section anchor='s.postload-confinfo' title="The Conferenceinfo Module">
	  <figure>
	    <preamble>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:
	    </preamble>
	    <artwork>set plugins::conferenceinfo::options(autoask) 1</artwork>
	  </figure>
	  <figure>
	    <preamble>
	      You can also set interval between these requests with
	      these two variables:
	    </preamble>
<artwork><![CDATA[
set plugins::conferenceinfo::options(interval)       60
set plugins::conferenceinfo::options(err_interval) 3600
]]></artwork>
	    <postamble>
	    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.
	    </postamble>
	  </figure>
	</section>

<section anchor='s.postload-crypto' title='The Cryptographic Module'>
<t><xref target='s.preload'>Earlier</xref> we saw an example where
the <spanx style='verb'>ssj::options</spanx> array from the cryptographic module was set during
the preload.</t>

<figure>
<preamble>In addition to <spanx style='verb'>signed-traffic</spanx>
and <spanx style='verb'>encrypt-traffic</spanx>,
you can also tell <spanx>Tkabber</spanx> whether to encrypt for a particular JID,
e.g.,</preamble>
<artwork><![CDATA[
    set ssj::options(encrypt,fred@example.com) 1
]]></artwork>
</figure>
</section>

	<section anchor='s.postload-emoti' title='The Emoticons Module'>
	  <t>
	    The procedure called <spanx>emoteicons::load_dir</spanx> is used to load
	    emoticon definitions from a directory.  The directory contains a
	    file called <spanx style='verb'>"icondef.xml"</spanx>, which defines the mapping between
	    each image and its textual emoticon (To find out what this file
	    looks like, go to where you installed <spanx>Tkabber</spanx> and take a look at
	    the file called <spanx style='verb'>"emoticons-tkabber/icondef.xml"</spanx> or read <eref
	    target='http://www.jabber.org/jeps/jep-0038.html'>JEP-0038</eref>.)
	  </t>

<figure>
<preamble>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 <spanx style='verb'>emoteicons::add</spanx>, e.g.,</preamble>
<artwork><![CDATA[
    emoteicons::add ":beer:" [image create photo -file ~/.tkabber/beer.gif]
]]></artwork>
</figure>
</section>

	<section anchor='s.postload-filexfer' title="The File Transfer Module">
	  <figure>
	    <preamble>
	      You can set directory in which files will be saved by default:
	    </preamble>
	    <artwork><![CDATA[
    set ft::options(download_dir) "/tmp"
]]></artwork>
	  </figure>
	</section>

	<section anchor='s.postload-groupchat' title='The Groupchat Module'>
	  <t>
	    There are several variables that set the dialog window defaults for
	    adding a groupchat to your roster, or joining a groupchat:
	    <list style='hanging'>
	      <t hangText='add to roster dialog window:'>
		<spanx style='verb'>gra_group</spanx> and <spanx style='verb'>gra_server</spanx> specify the default room and
		conference server, repectively; and,
	      </t>
	      
	      <t hangText='join dialog window:'>
		<spanx style='verb'>gr_nick</spanx>, <spanx
		style='verb'>gr_group</spanx> and <spanx style='verb'>gr_server</spanx> specify the default
		nickname, room, and conference server, respectively, whilst
		<spanx style='verb'>gr_v2</spanx> indicates whether the version 2 protocol should be
		used.
	      </t>
	    </list>
	    Note that variables <spanx
	    style='verb'>gra_server</spanx>, <spanx
	    style='verb'>gr_nick</spanx> and <spanx style='verb'>gr_server</spanx>
	    overriden in login procedure, so better place for changing them is
	    in <spanx style='verb'>connected_hook</spanx> (see below).
	  </t>

<figure>
<preamble>You may want to have different nicknames for different groupchats.
Accordingly,
the array called <spanx>defaultnick</spanx> 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.,</preamble>
<artwork><![CDATA[
    set defaultnick(adhoc@conference.example.com) publius
]]></artwork>
</figure>
<figure>
<preamble>Another possibility is to put pattern in parentheses. The following example
shows how to specify default nickname for all conferences at <spanx>conference.example.com</spanx>:
</preamble>
<artwork><![CDATA[
    set defaultnick(*@conference.example.com) ciceroni
]]></artwork>
<postamble>
Exact JID's take the higher precedence than patterns.
</postamble>
</figure>
</section>

	<section anchor='s.postload-ispell' title="The Ispell Module">
	  <t>
	    If you enabled this module <xref target="s.preload-ispell">earlier</xref>,
	    then you can define:
<list style='symbols'>
<t>the path to the <spanx>ispell</spanx> executable by setting
<spanx style='verb'>plugins::ispell::options(executable)</spanx></t>

<t>the path to the dictionary by setting
<spanx style='verb'>plugins::ispell::options(dictionary)</spanx>; and,</t>

<t>the encoding of the output by setting
<spanx style='verb'>plugins::ispell::options(dictionary_encoding)</spanx>.</t>
</list>
If you don't care about putting a large load on your process,
then you can also set
	    <spanx style='verb'>plugins::ispell::options(check_every_symbol)</spanx> to 1 to check
	    correctness of current word after every entered symbol.  (Usually
	    you don't need to set this option.)
	  </t>
	</section>

	<section anchor='s.postload-jidlink' title="The Jidlink Module">
	  <t>
	    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.  <spanx>Tkabber</spanx> comes with three transport implementations:
	    <list style='hanging'>
	      <t hangText='dtcp-active:'>
	        that allows you to connect to any node that supports
	        <spanx style='verb'>dtcp-passive</spanx>;</t>
	      <t hangText='dtcp-passive:'>that allows any node that
	        supports <spanx style='verb'>dtcp-active</spanx> to connect to you; and,
	      </t>
	      <t hangText='inband-bytestream:'>that uses your
		<spanx style='verb'>Jabber</spanx> connection to transmit the data (which may
		slowdown other traffic to you).
	      </t>
	    </list>
	  </t>
	  <figure>
	    <preamble>
	      If your machine is behind a firewall, then you can't use the
	      <spanx style='verb'>dtcp-passive</spanx> transport, so you should disable it:
	    </preamble>
	    <artwork>
    set jidlink::transport(allowed,dtcp-passive) 0
</artwork>
	  </figure>
	</section>

	<section anchor='s.postload-log' title="The Logger Module">
	  <figure>
	    <preamble>
	      You can set directory to store logs:
	    </preamble>
	    <artwork>
    set logger::options(logdir) ~/.tkabber/logs
</artwork>
	  </figure>
	  <figure>
	    <preamble>
	      Also you can allow or disallow storing of private and group chats
	      logs:
	    </preamble>
	    <artwork>
    set logger::options(log_chat)      1
    set logger::options(log_groupchat) 1
</artwork>
	  </figure>
	</section>

<section anchor='s.postload-login' title='The Login Module'>
<t>The first task is to initialize the configuration defaults for the
<spanx>login</spanx> module.
As you can see above,
the global array <spanx style='verb'>loginconf</spanx> has a whole bunch of elements,
e.g., <spanx style='verb'>user</spanx>, <spanx style='verb'>password</spanx>, and so on.
This collection of elements,
which is termed a login profile,
is what populates the dialog window you'll see when <spanx>Tkabber</spanx> wants
to connect to the server.</t>

<t>It turns out that <spanx>Tkabber</spanx> lets you have as many different login
profiles as you want.
If you want more than just one,
they're named <spanx style='verb'>loginconf1</spanx>, <spanx style='verb'>loginconf2</spanx>, and so on.</t>

<t>What the example above shows is the default values for all profiles
being set in <spanx style='verb'>loginconf</spanx>,
and then two profiles,
one called <spanx style='verb'>"Default Account"</spanx> and the other
called <spanx style='verb'>"Test Account"</spanx>
being created.</t>

	  <t>
	    If you want to automatically login to server, then you can
	    set the <spanx style='verb'>autologin</spanx> variable to
	    <spanx style='verb'>1</spanx>.
	  </t>
	  <t>
	    If you set the <spanx style='verb'>autologin</spanx>
	    variable to <spanx style='verb'>-1</spanx>, then <spanx>Tkabber</spanx>
	    will not automatically login and will not show login dialog.
	  </t>
	  <t>
	    Default value for <spanx style='verb'>autologin</spanx> is
	    <spanx style='verb'>0</spanx>. In this case <spanx>Tkabber</spanx>
	    shows login dialog.
	  </t>
</section>

<section anchor='s.postload-message' title='The Message Module'>
<t>By default,
when you restart <spanx>Tkabber</spanx> it won't remember the headlines you received.
If you want <spanx>Tkabber</spanx> to remember headlines whenever you run it,
set <spanx style='verb'>message::options(headlines,cache)</spanx> to
<spanx style='verb'>1</spanx>.</t>

<t>By default,
<spanx>Tkabber</spanx> will put all headline messages into a single window.
If you want <spanx>Tkabber</spanx> to use a seperate window for each headline source,
set <spanx style='verb'>message::options(headlines,multiple)</spanx>
to <spanx style='verb'>1</spanx>.</t>
</section>

	<section anchor='s.postload-rawxml' title="The Raw XML Input Module">
	  <t>
	    With this module you can monitor incoming/outgoing traffic from
	    connection to server and send custom XML stanzas.  Also you can
	    switch on <spanx style='verb'>pretty print</spanx> 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 <spanx style='verb'>indent</spanx> option.
	  </t>
	</section>

	<section anchor='s.postload-roster' title='The Roster Module'>
	  <t>
	    By default, your entire roster is shown, even those items that
	    aren't online.  The variable called <spanx style='verb'>roster::show_only_online</spanx>
	    controls this.
	  </t>

	  <t>
	    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 <spanx style='verb'>roster::roster</spanx> lets you do this.  In the example,
	    we see that two groups (<spanx style='verb'>"RSS"</spanx>
	    and <spanx style='verb'>"Undefined"</spanx>) start with
	    their items hidden.
	  </t>

	  <t>
	    Some peoples use several JIDs.  <spanx>Tkabber</spanx> 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 <spanx style='verb'>friend@some.host</spanx> have
	    aliases <spanx style='verb'>friend@other.host</spanx> and
	    <spanx style='verb'>friend@another.host</spanx>.
	    You can also disable all aliases by setting
	    <spanx style='verb'>roster::use_aliases</spanx> to <spanx style='verb'>0</spanx>. 
	  </t>
	</section>
	
	<section anchor='s.postload-sound' title="The Sound Module">
	  <figure>
	    <preamble>
	      <spanx>Tkabber</spanx> can play sounds on some events.  It can use for this
	      <spanx>snack</spanx> library or external program that can play <spanx>WAV</spanx> files.
	      To enable sound notifications, you can add following line:
	    </preamble>
	    <artwork>set sound::options(sound) 1</artwork>
	  </figure>
	  <figure>
	    <preamble>
	      If you want to start <spanx>Tkabber</spanx> with sound muted
	      add the following line:
	    </preamble>
	    <artwork>set sound::options(mute) 1 </artwork>
	  </figure>
	  <figure>
	    <preamble>
	      You can also mute sounds of delayed groupchat messages and
	      delayed personal chat messages:
	    </preamble>
	    <artwork>
set sound::options(mute_groupchat_delayed) 1
set sound::options(mute_chat_delayed)      0
</artwork>
	  </figure>
	  <figure>
	    <preamble>
	      If you want to use external program for playing sounds, then also
	      add something like this:
	    </preamble>
	    <artwork>
set sound::options(external_play_program) /usr/bin/play
</artwork>
	  </figure>
	  <figure>
	    <preamble>
	      You can also set minimal interval (in milliseconds) between
	      playing different sounds.
	    </preamble>
	    <artwork>set sound::options(delay) 200</artwork>
	  </figure>
	  <figure>
	    <preamble>
	      If you want to use another sound theme, then you can add line
	      like this:
	    </preamble>
	    <artwork>set sound::options(theme) "sound_theme"</artwork>
	    <postamble>
	      Then <spanx>Tkabber</spanx> load sound files from directory called
	      <spanx style='verb'>tkabber/sounds/sound_theme</spanx>
	      if theme name not started with <spanx style='verb'>/</spanx>
	      or <spanx style='verb'>~</spanx>, else it consider theme name as path to theme directory.
	    </postamble>
	  </figure>
	</section>
</section>

<section anchor='s.menuload' title='Menu-load'>
<t>After <spanx>Tkabber</spanx> invokes your <spanx style='verb'>postload</spanx> 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 <spanx style='verb'>menuload</spanx>,
which is allowed to modify that specification before <spanx>Tkabber</spanx> uses it.</t>

<figure>
<preamble>The default version of this procedure is the identity function,
i.e..,</preamble>
<artwork><![CDATA[
proc menuload {description} { return $description }
]]></artwork>
</figure>

<t>If you <spanx>really</spanx> want to change the menubar specification,
then here's how to get started:
<list style='numbers'>
<t>Go to where you installed the <spanx>BWidget</spanx> library and take a look at
the file called <spanx style='verb'>"BWman/MainFrame.html"</spanx>.
The documentation for the <spanx style='verb'>"-menu"</spanx> option explains the syntax of the
specification.</t>

<t>Go to where you installed <spanx>Tkabber</spanx> and take a look at the file
called <spanx style='verb'>"iface.tcl"</spanx>.
Look for the line that starts with <spanx style='verb'>"set descmenu"</spanx>.
This will show you the specification given to your <spanx style='verb'>menuload</spanx>
procedure.</t>

<t>Go to where you installed <spanx>Tkabber</spanx> and take a look at the file
called
<spanx style='verb'>"examples/mtr-config.tcl"</spanx>.
Look at the <spanx style='verb'>menuload</spanx> procedure defined there.
It lays out <spanx>Tkabber's</spanx> menu bar similar to <spanx>Gabber's</spanx>.</t>

<t>Finally,
study the procedures listed here.</t>
</list></t>

<section anchor='s.menuload-avatar' title='The Avatar Module'>
<t>The procedure called <spanx style='verb'>avatar::store_on_server</spanx> stores your avatar
on the server.</t>
</section>

<section anchor='s.menuload-browser' title='The Browser Module'>
<t>The procedure called <spanx style='verb'>browser::open</spanx> opens a new browser window.</t>
</section>

<section anchor='s.menuload-groupchat' title='The Groupchat Module'>
<t>The procedure called <spanx style='verb'>add_group_dialog</spanx> displays a dialog window
when you want to add a groupchat to your roster.
Similarly,
the procedure called <spanx style='verb'>join_group_dialog</spanx> displays a dialog window
when you want to join a groupchat.</t>
</section>

<section anchor='s.menuload-login' title='The Login Module'>
<t>The procedure called <spanx style='verb'>show_login_dialog</spanx> 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 <spanx style='verb'>logout</spanx> does just that;
however,
if you want get a dialog window for confirmation,
use <spanx style='verb'>show_logout_dialog</spanx> instead.</t>
</section>

<section anchor='s.menuload-message' title='The Message Module'>
<t>If you want to send a message to someone,
the procedure called <spanx style='verb'>message::send_dialog</spanx> will put up a dialog window.
It takes upto three optional arguments:
the recipient JID, the subject, and the thread.</t>

<t>If you want to get added to someone's roster,
the procedure called <spanx style='verb'>message::send_subscribe_dialog</spanx> will put up a
dialog window.
It takes one optional argument:
the recipient JID.</t>

<t>If you want to adjust your message filters,
the procecure called <spanx style='verb'>filters::open</spanx> will put up a dialog window.</t>
</section>

<section anchor='s.menuload-presence' title='The Presence Module'>
<t>If you want to display information about a user,
the procecure called <spanx style='verb'>userinfo::open</spanx> 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.</t>

<figure>
<preamble>Obviously,
the second argument makes sense only if it's your own information,
i.e.,</preamble>
<artwork><![CDATA[
    global loginconf

    userinfo::open \
        ${loginconf(user)}@$loginconf(server)/$loginconf(resource) 1
]]></artwork>
</figure>

<t>There are also two variables that you can use to set your own
presence:
<spanx style='verb'>userstatus</spanx> and <spanx style='verb'>textstatus</spanx>.
The first variable takes one of five values:
<list style='symbols'>
<t>available;</t>
<t>chat;</t>
<t>away;</t>
<t>xa;</t>
<t>dnd; or,</t>
<t>invisible.</t>
</list>
The second variable takes any textual value.</t>

<figure>
<preamble>Changes to your presence information are propagated only
when <spanx style='verb'>userstatus</spanx> is changed.
Accordingly,
if you make a change to <spanx style='verb'>textstatus</spanx>,
be sure to write <spanx style='verb'>userstatus</spanx> immediately afterwards,
even if it's a no-op,
e.g.,</preamble>
<artwork><![CDATA[
    global userstatus textstatus

    set textstatus "Out to lunch"
    set userstatus $userstatus
]]></artwork>
</figure>
</section>

<section  anchor='s.menuload-miscellany' title='Miscellany'>
<t>Finally,
you can use the procedure named <spanx style='verb'>help_window</spanx> to display some textual
help.
This procedure takes two arguments:
the title for the window;
and,
the text to display.</t>

<t>Also, instead of calling <spanx style='verb'>exit</spanx> to terminate <spanx>Tkabber</spanx>,
please use the <spanx style='verb'>quit</spanx> procedure instead.</t>
</section>
</section>

<section anchor='s.finalload' title='Final-Load'>
<t>Finally,
right before <spanx>Tkabber</spanx> goes to display the login dialog,
it invokes a procedure called <spanx style='verb'>finload</spanx>,
which does whatever you want it to.</t>
</section>
    </section>

<section anchor='s.extensibility' title='Extensibility'>
<t>In addition to various configuration mechanisms,
<spanx>Tkabber</spanx> lets you define procedures,
termed "hooks" that get run when certain events happen.</t>

<figure>
<preamble>Here's an example.
When <spanx>Tkabber</spanx> 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:</preamble>
<artwork><![CDATA[
hook::run draw_message_hook $jid $from $type $body $extras
]]></artwork>
<postamble>The <spanx style='verb'>hook::run</spanx> procedure invokes whatever hooks have been
defined for <spanx style='verb'>draw_message_hook</spanx>.
In fact,
upto ten procedures may get invoked to satisfy this hook!</postamble>
</figure>

<figure>
<preamble>Here's how it works:
<spanx>Tkabber</spanx> comes with a number of plugins,
which get loaded automatically.
Each plugin makes one or more calls that look like this:</preamble>
<artwork><![CDATA[
hook::add draw_message_hook [namespace current]::my_draw_hook $prio
]]></artwork>
<postamble>where the last two parameters are:
the name of a procedure to run;
and,
an relative integer priority.</postamble>
</figure>

<t>When <spanx style='verb'>hook::run</spanx> is invoked for <spanx style='verb'>draw_message_hook</spanx>,
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 <spanx style='verb'>"stop"</spanx>.</t>

<figure>
<preamble>To continue with the example,
in between the pre-load and post-load stages of configuration,
the following calls get made by different plugins:</preamble>
<artwork><![CDATA[
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
]]></artwork>
<postamble>Many of these procedures look at the incoming chat message
and operate on only certain kinds of messages.
Some of these procedures may return <spanx style='verb'>"stop"</spanx>,
e.g., <spanx style='verb'>handle_me</spanx> which handles chat bodies
that start with <spanx style='verb'>"/me"</spanx>.
(In this example,
the actual namespaces were replaced with <spanx style='verb'>"...:"</spanx> to make it more
readable).</postamble>
</figure>

<t>Now let's look at the different kind of hooks that <spanx>Tkabber</spanx> knows
about.</t>

<section title='Chat Hooks'>
<figure>
<preamble>When <spanx>Tkabber</spanx> decides that it needs to open a (tabbed)
window for a chat or groupchat,
two hooks are run:</preamble>
<artwork><![CDATA[
open_chat_pre_hook  $jid $type
open_chat_post_hook $jid $type
]]></artwork>
<postamble>Both hooks are given two parameters:
the JID of the user (or conference room);
and,
and the type of chat
(either <spanx style='verb'>"chat"</spanx> or <spanx style='verb'>"groupchat"</spanx>).</postamble>
</figure>

<figure>
<preamble>Similarly,
when <spanx>Tkabber</spanx> encounters activity on a tabbed window,
a hook is run:</preamble>
<artwork><![CDATA[
raise_chat_tab_hook $path $jid
]]></artwork>
<postamble>The hook is given two parameters:
the path of the <spanx>Tk</spanx> widget for the tabbed window;
and,
the JID of the user (or conference room).</postamble>
</figure>

<figure>
<preamble>When you want to send a chat message,
a hook is run:</preamble>
<artwork><![CDATA[
chat_send_message_hook $jid $user $body $type
]]></artwork>
<postamble>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.</postamble>
</figure>

<figure>
<artwork><![CDATA[
draw_message_hook $jid $from $type $body $extras
]]></artwork>
<postamble>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.)
</postamble>
</figure>

	<figure>
	  <preamble>
	    Chat windows have menubuttons, and two hooks is used to add items
	    in menu:
	  </preamble>
<artwork><![CDATA[
chat_create_user_menu_hook $path $jid
chat_create_conference_menu_hook $path $jid
]]></artwork>
	  <postamble>
	    The first is used in user chat windows, and second in groupchat
	    ones.  Hooks is given two parameters: the path of the <spanx>Tk</spanx> menu
	    widget; and, the JID of user or conference.
	  </postamble>
	</figure>

	<figure>
	  <preamble>
	    In groupchat windows possible to complete participant's nicks or
	    commands by pressing TAB key.  List of completions is generated by
	    running this hook:
	  </preamble>
<artwork><![CDATA[
generate_completions_hook $jid $compsvar $wordstart $line
]]></artwork>
	  <postamble>
	    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.
	  </postamble>
	</figure>
	<figure>
	  <preamble>
	    When someone enters/exits conference, next hooks called:
	  </preamble>
	  <artwork>
hook::run chat_user_enter $group $nick
hook::run chat_user_exit  $group $nick
</artwork>
	  <postamble>
	    The hook is given two parameters: JID of conference and nick
	    participant.
	  </postamble>
	</figure>
      </section>

<section title='Login Hooks'>
<figure>
<preamble>Two hooks are invoked whenever a session is connected or
disconnected:</preamble>
<artwork><![CDATA[
connected_hook

disconnected_hook
]]></artwork>
<postamble>Neither hook is given any parameters.</postamble>
</figure>
</section>

<section title='Presence Hooks'>
<figure>
<preamble>When our presence status changes,
a hook is run:</preamble>
<artwork><![CDATA[
change_our_presence_post_hook $status
]]></artwork>
</figure>

<t>The hook is given one parameter:
the new presence status value,
i.e., one of:
<list style='symbols'>
<t>available;</t>
<t>chat;</t>
<t>away;</t>
<t>xa;</t>
<t>dnd;</t>
<t>invisible; or,</t>
<t>unavailable.</t>
</list></t>

<figure>
<preamble>Similarly,
when someone else's presence changes,
a hook is run:</preamble>
<artwork><![CDATA[
on_change_user_presence_hook $jid $status
]]></artwork>
<postamble>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.</postamble>
</figure>
	
	<figure>
	  <preamble>
	    And for all received presence packets, a hook is run:
	  </preamble>
<artwork><![CDATA[
client_presence_hook $from $type $x $args
]]></artwork>
	  <postamble>
	    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").
	  </postamble>
	</figure>
      </section>

      <section title='Roster Hooks'>
	<figure>
	  <preamble>
	    When a user is added to the roster window, a hook is run to add
	    stuff to the menu associated with that user:
	  </preamble>
	  <artwork>roster_create_user_menu_hook $path $jids</artwork>
	  <postamble>
	    The hook is given two parameters: the path of the <spanx>Tk</spanx> menu
	    widget; and, a list of JIDs for which presence information is
	    available.
	  </postamble>
	</figure>
	<figure>
	  <preamble>
	    Also next hook is run to add stuff to the menu in groupchats:
	  </preamble>
	  <artwork>roster_create_groupchat_user_menu_hook $path $jid</artwork>
	  <postamble>
	    The hook is given two parameters: the path of the <spanx>Tk</spanx> menu
	    widget; and, a JID of user.
	  </postamble>
	</figure>
	<figure>
	  <preamble>
	    Next hook is run to add stuff to the popup balloon for each roster
	    item:
	  </preamble>
	  <artwork>roster_user_popup_info_hook $varname $jid</artwork>
	  <postamble>
	    The hook is given two parameters: the variable name in which
	    current popup text is stored, and the JID of the roster item.
	  </postamble>
	</figure>
      </section>

<section title='Miscellaneous Hooks'>
<figure>
<preamble>There are three "obvious" hooks:</preamble>
<artwork><![CDATA[
postload_hook

finload_hook

quit_hook
]]></artwork>
<postamble>The first two,
by default,
run the <spanx style='verb'>postload</spanx> and <spanx style='verb'>finload</spanx> procedures,
respectively.
The final hooks is called just before <spanx>Tkabber</spanx> terminates
(cf., <xref target='s.menuload-miscellany' />).</postamble>
</figure>
</section>
</section>
</middle>

  <back>


    <section title="Releases History">
      <section title="Main changes in 0.9.7">
	<t>
	  <list style='symbols'>
	    <t>Updated support for file transfer (JEP-0095, JEP-0096, JEP-0047, JEP-0065)</t>
	    <t>Support for colored nicks and messages in conference</t>
	    <t>Better multiple logins support</t>
	    <t>Updated support for xml:lang</t>
	    <t>Support for IDNA (RFC3490)</t>
	    <t>Many fixes and enhancements</t>
	  </list>
	</t>
      </section>

      <section title="Main changes in 0.9.6beta">
	<t>
	  <list style='symbols'>
	    <t>Multiple logins support</t>
	    <t>History now splitted by month</t>
	    <t>Animated emoteicons support</t>
	    <t>Many user interface improvements</t>
	    <t>More XMPP support</t>
	    <t>More translations</t>
	    <t>Bugfixes</t>
	  </list>
	</t>
      </section>

      <section title="Main changes in 0.9.5beta">
	<t>
	  <list style='symbols'>
	    <t>Nested roster groups</t>
	    <t>Messages emphasizing</t>
	    <t>User interface improvements</t>
	    <t>Support for XMPP/Jabber MIME Type</t>
	    <t>Bugfixes</t>
	  </list>
	</t>
      </section>
    </section>


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

<section title='Documentation TODO'>
<t>The next revision of this documentation should discuss:
<list style='symbols'>
<t>Pre-load:
<list style='symbols'>
<t><spanx style='verb'>browseurl</spanx></t>
</list></t>

<t>Post-load:
<list style='symbols'>
<t><spanx style='verb'>chat_height</spanx> and <spanx style='verb'>chat_width</spanx> (appear to be no-ops).</t>
</list></t>

<t>Menu-load:
<list style='symbols'>
<t><spanx style='verb'>change_password_dialog</spanx></t>
<t><spanx style='verb'>conference::create_room_dialog</spanx></t>
<t><spanx style='verb'>disco::browser::open_win</spanx></t>
<t><spanx style='verb'>message::send_msg</spanx></t>
<t><spanx style='verb'>privacy::request_lists</spanx></t>
<t><spanx style='verb'>rawxml::open_window</spanx></t>
<t><spanx style='verb'>userinfo::show_info_dialog</spanx></t>
</list></t>

<t>Hooks: the additional payload format.</t>
</list></t>
</section>

<section title='Acknowledgements'>
<t>Rebecca Malamud was kind enough to design the "enlightened feather"
motif used in the <spanx>Tkabber</spanx> look-and-feel.</t>
</section>

<section title='Copyrights'>
<t>(c) 2002--2004 Alexey Shchepin</t>

<t>Hold harmless the authors, and any lawful use is allowed.</t>
</section>
</back>
</rfc>