[Tkabber-dev] r865 - in trunk/tkabber: . doc

tkabber-svn at jabber.ru tkabber-svn at jabber.ru
Sat Jan 6 20:12:27 MSK 2007


Author: sergei
Date: 2007-01-06 20:12:23 +0300 (Sat, 06 Jan 2007)
New Revision: 865

Modified:
   trunk/tkabber/ChangeLog
   trunk/tkabber/README
   trunk/tkabber/doc/tkabber.html
   trunk/tkabber/doc/tkabber.xml
Log:
	* README, doc/tkabber.xtml, doc/tkabber.xml: Documented changes in
	  the config directory for different operating systems. Replaced
	  ~/.tkabber by $::configdir in docs. Documented searching in Tkabber
	  windows. Documented hook roster_group_popup_menu_hook (thanks to
	  Konstantin Khomoutov).


Modified: trunk/tkabber/ChangeLog
===================================================================
--- trunk/tkabber/ChangeLog	2007-01-06 15:40:32 UTC (rev 864)
+++ trunk/tkabber/ChangeLog	2007-01-06 17:12:23 UTC (rev 865)
@@ -1,3 +1,11 @@
+2007-01-06  Sergei Golovan  <sgolovan at nes.ru>
+
+	* README, doc/tkabber.xtml, doc/tkabber.xml: Documented changes in
+	  the config directory for different operating systems. Replaced
+	  ~/.tkabber by $::configdir in docs. Documented searching in Tkabber
+	  windows. Documented hook roster_group_popup_menu_hook (thanks to
+	  Konstantin Khomoutov).
+
 2007-01-05  Sergei Golovan  <sgolovan at nes.ru>
 
 	* plugins/general/autoaway.tcl, plugins/iq/last.tcl: Added support

Modified: trunk/tkabber/README
===================================================================
--- trunk/tkabber/README	2007-01-06 15:40:32 UTC (rev 864)
+++ trunk/tkabber/README	2007-01-06 17:12:23 UTC (rev 865)
@@ -9,7 +9,7 @@
                                                      New Economic School
                                                                M. Litvak
                                                   Information Centre ISP
-                                                         January 1, 2007
+                                                         January 6, 2007
 
 
                              Tkabber v0.9.9
@@ -63,48 +63,48 @@
    2.  Requirements . . . . . . . . . . . . . . . . . . . . . . . . .  7
    3.  Download, install and run  . . . . . . . . . . . . . . . . . . 10
    4.  Configuration  . . . . . . . . . . . . . . . . . . . . . . . . 12
-     4.1.  Pre-load . . . . . . . . . . . . . . . . . . . . . . . . . 12
-       4.1.1.  Tabbed Interface . . . . . . . . . . . . . . . . . . . 13
+     4.1.  Pre-load . . . . . . . . . . . . . . . . . . . . . . . . . 13
+       4.1.1.  Tabbed Interface . . . . . . . . . . . . . . . . . . . 14
        4.1.2.  Primary Look-and-Feel  . . . . . . . . . . . . . . . . 14
-       4.1.3.  Cryptography by default  . . . . . . . . . . . . . . . 14
+       4.1.3.  Cryptography by default  . . . . . . . . . . . . . . . 15
        4.1.4.  Using of external TclXML library . . . . . . . . . . . 15
-       4.1.5.  Use ispell to check spelling . . . . . . . . . . . . . 15
-       4.1.6.  Debugging Output . . . . . . . . . . . . . . . . . . . 15
+       4.1.5.  Use ispell to check spelling . . . . . . . . . . . . . 16
+       4.1.6.  Debugging Output . . . . . . . . . . . . . . . . . . . 16
        4.1.7.  Splash window  . . . . . . . . . . . . . . . . . . . . 16
-       4.1.8.  Periodically send empty string to server . . . . . . . 16
-       4.1.9.  I18n/L10n  . . . . . . . . . . . . . . . . . . . . . . 16
-     4.2.  Post-load  . . . . . . . . . . . . . . . . . . . . . . . . 16
-       4.2.1.  Look-and-Feel  . . . . . . . . . . . . . . . . . . . . 20
-       4.2.2.  The Autoaway Module  . . . . . . . . . . . . . . . . . 21
-       4.2.3.  The Avatar Module  . . . . . . . . . . . . . . . . . . 21
-       4.2.4.  The Chat Module  . . . . . . . . . . . . . . . . . . . 22
-       4.2.5.  The Clientinfo Module  . . . . . . . . . . . . . . . . 22
-       4.2.6.  The Conferenceinfo Module  . . . . . . . . . . . . . . 22
-       4.2.7.  The Cryptographic Module . . . . . . . . . . . . . . . 23
-       4.2.8.  The Emoticons Module . . . . . . . . . . . . . . . . . 23
-       4.2.9.  The File Transfer Module . . . . . . . . . . . . . . . 23
-       4.2.10. The Groupchat Module . . . . . . . . . . . . . . . . . 23
-       4.2.11. The Ispell Module  . . . . . . . . . . . . . . . . . . 24
-       4.2.12. The Stream Initiation Module . . . . . . . . . . . . . 24
-       4.2.13. The Jidlink Module . . . . . . . . . . . . . . . . . . 25
-       4.2.14. The Logger Module  . . . . . . . . . . . . . . . . . . 25
-       4.2.15. The Login Module . . . . . . . . . . . . . . . . . . . 26
-       4.2.16. The Message Module . . . . . . . . . . . . . . . . . . 27
-       4.2.17. The Raw XML Input Module . . . . . . . . . . . . . . . 27
-       4.2.18. The Roster Module  . . . . . . . . . . . . . . . . . . 27
-       4.2.19. The Sound Module . . . . . . . . . . . . . . . . . . . 28
-     4.3.  Menu-load  . . . . . . . . . . . . . . . . . . . . . . . . 29
-       4.3.1.  The Avatar Module  . . . . . . . . . . . . . . . . . . 30
-       4.3.2.  The Browser Module . . . . . . . . . . . . . . . . . . 30
-       4.3.3.  The Groupchat Module . . . . . . . . . . . . . . . . . 30
-       4.3.4.  The Login Module . . . . . . . . . . . . . . . . . . . 30
-       4.3.5.  The Message Module . . . . . . . . . . . . . . . . . . 30
-       4.3.6.  The Presence Module  . . . . . . . . . . . . . . . . . 31
-       4.3.7.  Miscellany . . . . . . . . . . . . . . . . . . . . . . 32
-     4.4.  Final-Load . . . . . . . . . . . . . . . . . . . . . . . . 32
-   5.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . . . 33
-     5.1.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 34
-     5.2.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 36
+       4.1.8.  Periodically send empty string to server . . . . . . . 17
+       4.1.9.  I18n/L10n  . . . . . . . . . . . . . . . . . . . . . . 17
+       4.1.10. Searching  . . . . . . . . . . . . . . . . . . . . . . 17
+     4.2.  Post-load  . . . . . . . . . . . . . . . . . . . . . . . . 17
+       4.2.1.  Look-and-Feel  . . . . . . . . . . . . . . . . . . . . 21
+       4.2.2.  The Autoaway Module  . . . . . . . . . . . . . . . . . 22
+       4.2.3.  The Avatar Module  . . . . . . . . . . . . . . . . . . 22
+       4.2.4.  The Chat Module  . . . . . . . . . . . . . . . . . . . 23
+       4.2.5.  The Clientinfo Module  . . . . . . . . . . . . . . . . 23
+       4.2.6.  The Conferenceinfo Module  . . . . . . . . . . . . . . 23
+       4.2.7.  The Cryptographic Module . . . . . . . . . . . . . . . 24
+       4.2.8.  The Emoticons Module . . . . . . . . . . . . . . . . . 24
+       4.2.9.  The File Transfer Module . . . . . . . . . . . . . . . 24
+       4.2.10. The Groupchat Module . . . . . . . . . . . . . . . . . 24
+       4.2.11. The Ispell Module  . . . . . . . . . . . . . . . . . . 25
+       4.2.12. The Stream Initiation Module . . . . . . . . . . . . . 25
+       4.2.13. The Jidlink Module . . . . . . . . . . . . . . . . . . 26
+       4.2.14. The Logger Module  . . . . . . . . . . . . . . . . . . 26
+       4.2.15. The Login Module . . . . . . . . . . . . . . . . . . . 27
+       4.2.16. The Message Module . . . . . . . . . . . . . . . . . . 28
+       4.2.17. The Raw XML Input Module . . . . . . . . . . . . . . . 28
+       4.2.18. The Roster Module  . . . . . . . . . . . . . . . . . . 28
+       4.2.19. The Sound Module . . . . . . . . . . . . . . . . . . . 29
+     4.3.  Menu-load  . . . . . . . . . . . . . . . . . . . . . . . . 30
+       4.3.1.  The Avatar Module  . . . . . . . . . . . . . . . . . . 31
+       4.3.2.  The Browser Module . . . . . . . . . . . . . . . . . . 31
+       4.3.3.  The Groupchat Module . . . . . . . . . . . . . . . . . 31
+       4.3.4.  The Login Module . . . . . . . . . . . . . . . . . . . 31
+       4.3.5.  The Message Module . . . . . . . . . . . . . . . . . . 31
+       4.3.6.  The Presence Module  . . . . . . . . . . . . . . . . . 32
+       4.3.7.  Miscellany . . . . . . . . . . . . . . . . . . . . . . 33
+     4.4.  Final-Load . . . . . . . . . . . . . . . . . . . . . . . . 33
+   5.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . . . 34
+     5.1.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 35
 
 
 
@@ -113,20 +113,23 @@
                              Tkabber v0.9.9                 January 2007
 
 
-     5.3.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 36
-     5.4.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 37
-     5.5.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 38
-   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 39
-     A.1.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 39
-     A.2.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 39
-     A.3.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 39
-     A.4.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 40
-     A.5.  Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 40
-   Appendix B.  XRDB  . . . . . . . . . . . . . . . . . . . . . . . . 41
-   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 44
-   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 45
-   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 46
-   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 47
+     5.2.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 37
+     5.3.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 37
+     5.4.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 38
+     5.5.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 39
+     5.6.  User Interface basics  . . . . . . . . . . . . . . . . . . 39
+       5.6.1.  Searching  . . . . . . . . . . . . . . . . . . . . . . 39
+   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 41
+     A.1.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 41
+     A.2.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 41
+     A.3.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 41
+     A.4.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 42
+     A.5.  Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 42
+   Appendix B.  XRDB  . . . . . . . . . . . . . . . . . . . . . . . . 43
+   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 46
+   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 47
+   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 48
+   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 49
 
 
 
@@ -161,9 +164,6 @@
 
 
 
-
-
-
 Shchepin, et al.                                                [Page 3]
 
                              Tkabber v0.9.9                 January 2007
@@ -619,14 +619,42 @@
 
 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_ maintains its configuration using a set of files placed in
+   a special configuration directory which location depends on the
+   operating system _Tkabber_ runs on.  These locations are:
 
+   o  Unix systems: ""~/.tkabber"";
+
+   o  Macintosh: ""~/Library/Application Support/Tkabber"";
+
+   o  Under Microsoft(R) Windows[TM] this location is governed by the
+      policy of the particular flavor of this OS, but the general rule
+      is that the _Tkabber_ configuration directory is named ""Tkabber""
+      and is located in the special system folder for storing
+      application-specific data.  For example, under Windows XP[TM] this
+      will be something like ""C:\Documents and
+      Settings\USERNAME\Application Data\Tkabber"", where ""USERNAME""
+      is the login name of a particular operating system's user.
+
+   _Tkabber_ also honors the value of the ""TKABBER_HOME"" environment
+   variable -- if it exists the whole OS-based guessing of the
+   configuration directory location is cancelled and the value of this
+   environment variable is used instead.
+
+   Once the pathname of the _Tkabber_ configuration directory is known,
+   its value is assigned to the ""configdir"" global Tcl variable which
+   can be accessed from within the main _Tkabber_ configuration file
+   (see below).
+
+   One of the first things that _Tkabber_ does when it's starting up is
+   reading a file located in its configuration directory under the name
+   ""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.)
+
    Note that almost all _Tkabber_ options can be cofigured using
    graphical interface (menu Tkabber->Customize), so editing
    configuration file is not strictly necessary.
@@ -636,6 +664,15 @@
    o  in the pre-load stage, configuration options which guide the
       loading process are set;
 
+
+
+
+
+Shchepin, et al.                                               [Page 12]
+
+                             Tkabber v0.9.9                 January 2007
+
+
    o  in the post-load stage, configuration options for each module are
       set;
 
@@ -667,12 +704,6 @@
           userDefault
 
 
-
-Shchepin, et al.                                               [Page 12]
-
-                             Tkabber v0.9.9                 January 2007
-
-
    # cryptography by default
 
    set ssj::options(sign-traffic)    0
@@ -691,6 +722,13 @@
 
    # debugging output
 
+
+
+Shchepin, et al.                                               [Page 13]
+
+                             Tkabber v0.9.9                 January 2007
+
+
    set debug_lvls {jlib warning}
 
 
@@ -721,14 +759,6 @@
    changes, in order to apply changed option
    "ifacetk::options(use_tabbar)" you have to restart _Tkabber_.  So,
    basically you have two options: set "ifacetk::options(use_tabbar)" at
-
-
-
-Shchepin, et al.                                               [Page 13]
-
-                             Tkabber v0.9.9                 January 2007
-
-
    the beginning of your configuration file, or using graphical
    interface save the option and restart _Tkabber_.
 
@@ -745,8 +775,16 @@
    options in an "xrdb" file, and then reference it this way:
 
        set load_default_xrdb 0
-       option readfile ~/.tkabber/newlook.xrdb userDefault
+       option readfile $::configdir/newlook.xrdb userDefault
 
+
+
+
+Shchepin, et al.                                               [Page 14]
+
+                             Tkabber v0.9.9                 January 2007
+
+
    The first line tells _Tkabber_ not to load its default "xrdb" file,
    whilst the second line tells _Tkabber_ the file to load instead.
 
@@ -778,13 +816,6 @@
    Next, you may want to _Tkabber_ to use cryptography by default.
    There are two options:
 
-
-
-Shchepin, et al.                                               [Page 14]
-
-                             Tkabber v0.9.9                 January 2007
-
-
    o  whether the traffic you send should be digitally-signed; and,
 
    o  if you have cryptographic information for someone, should the
@@ -802,6 +833,14 @@
    not suitable.  Then you can install _TclXML_ with built-in _expat_
    support and set variable "use_external_tclxml":
 
+
+
+
+Shchepin, et al.                                               [Page 15]
+
+                             Tkabber v0.9.9                 January 2007
+
+
    set use_external_tclxml 0
 
 4.1.5.  Use ispell to check spelling
@@ -830,17 +869,6 @@
    #    ...
    }
 
-
-
-
-
-
-
-Shchepin, et al.                                               [Page 15]
-
-                             Tkabber v0.9.9                 January 2007
-
-
    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
@@ -857,6 +885,18 @@
 
    set show_splash_window 0
 
+
+
+
+
+
+
+
+Shchepin, et al.                                               [Page 16]
+
+                             Tkabber v0.9.9                 January 2007
+
+
 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
@@ -879,6 +919,14 @@
 
    ::msgcat::mclocale en
 
+4.1.10.  Searching
+
+   _Tkabber_ allows the user to perform textual searching in certain
+   classes of its windows.  This searching is controlled by several
+   settings which can be specified in this section.
+
+   These settings are described in detail here (Section 5.6.1).
+
 4.2.  Post-load
 
    After _Tkabber_ reads your configuration file, it loads all of its
@@ -889,22 +937,22 @@
    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
 
+       set pixmaps::options(pixmaps_theme) Default
 
+       global alert colors alert_lvls
 
-Shchepin, et al.                                               [Page 16]
-
-                             Tkabber v0.9.9                 January 2007
+       set alert_lvls(error)        1
 
 
-   proc postload {} {
-   # look-and-feel
 
-       set pixmaps::options(pixmaps_theme) Default
+Shchepin, et al.                                               [Page 17]
+
+                             Tkabber v0.9.9                 January 2007
 
-       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
@@ -946,22 +994,23 @@
        set plugins::conferenceinfo::options(err_interval)  60
 
 
+   # the cryptographic module
 
+       set ssj::options(encrypt,fred at example.com) 1
 
-Shchepin, et al.                                               [Page 17]
-
-                             Tkabber v0.9.9                 January 2007
 
+   # the emoticon module
 
-   # the cryptographic module
 
-       set ssj::options(encrypt,fred at example.com) 1
 
 
-   # the emoticon module
+Shchepin, et al.                                               [Page 18]
+
+                             Tkabber v0.9.9                 January 2007
 
+
        set plugins::emoticons::options(theme) \
-           [file normalize ~/.tkabber/emoticons/rythmbox]
+                   $::configdir/emoticons/rythmbox
 
 
    # the file transfer module
@@ -998,22 +1047,24 @@
 
    # the logger module
 
-       set logger::options(logdir)        ~/.tkabber/logs
+       set logger::options(logdir)        [file join $::configdir logs]
        set logger::options(log_chat)      1
        set logger::options(log_groupchat) 1
 
 
+   # the login module
 
-Shchepin, et al.                                               [Page 18]
+       global loginconf loginconf1 loginconf2 autologin
+
+       set loginconf(user)           ""
+
+
+
+Shchepin, et al.                                               [Page 19]
 
                              Tkabber v0.9.9                 January 2007
 
 
-   # the login module
-
-       global loginconf loginconf1 loginconf2 autologin
-
-       set loginconf(user)           ""
        set loginconf(password)       ""
        set loginconf(server)         example.com
        set loginconf(resource)       tkabber
@@ -1058,17 +1109,18 @@
        set plugins::rawxml::set options(indent)       2
 
 
+   # the roster module
 
+       set roster::show_only_online            1
+       set roster::roster(collapsed,RSS)       1
 
-Shchepin, et al.                                               [Page 19]
+
+
+Shchepin, et al.                                               [Page 20]
 
                              Tkabber v0.9.9                 January 2007
 
 
-   # 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 at some.host) \
@@ -1106,25 +1158,25 @@
    themes.
 
    If you want, you can have _Tkabber_ use a different theme by putting
-   custom theme subdirectory to "~/.tkabber/pixmaps/" directory (tilde
+   custom theme subdirectory to "$::configdir/pixmaps/" directory (tilde
    means home directory). _Tkabber_ knows that it is a theme directory
    by looking for "icondef.xml" file in the directory.  To find out the
    structure of icon definition file, look through _XEP-0038_ and go to
    where you installed _Tkabber_ and take a look at the directory called
    ""pixmaps/default/"".
 
+   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
 
 
 
-Shchepin, et al.                                               [Page 20]
+Shchepin, et al.                                               [Page 21]
 
                              Tkabber v0.9.9                 January 2007
 
 
-   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
@@ -1168,21 +1220,19 @@
    There are two variables that you can set to control whether _Tkabber_
    will allow others to see your avatar:
 
+   o  "avatar::options(announce)" determines whether your presence
+      information indicates that you have an avatar; and,
 
+   o  "avatar::options(share)" determines whether requests for your
+      avatar will be honored.
 
 
 
-Shchepin, et al.                                               [Page 21]
+Shchepin, et al.                                               [Page 22]
 
                              Tkabber v0.9.9                 January 2007
 
 
-   o  "avatar::options(announce)" determines whether your presence
-      information indicates that you have an avatar; and,
-
-   o  "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
@@ -1225,18 +1275,20 @@
    set plugins::conferenceinfo::options(err_interval)  60
 
    The second variable defines how many minutes 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.
 
 
 
-Shchepin, et al.                                               [Page 22]
+
+
+
+Shchepin, et al.                                               [Page 23]
 
                              Tkabber v0.9.9                 January 2007
 
 
-   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 (Section 4.1) we saw an example where the "ssj::options"
@@ -1261,7 +1313,7 @@
    "plugins::emoticons::add", e.g.,
 
        plugins::emoticons::add ":beer:" \
-           [image create photo -file ~/.tkabber/beer.gif]
+           [image create photo -file $::configdir/emoticons/beer.gif]
 
    If you want to disable all emoticons, you can simply load empty
    directory.  Put in postload function
@@ -1279,19 +1331,20 @@
    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,
 
 
 
 
 
-Shchepin, et al.                                               [Page 23]
+
+
+Shchepin, et al.                                               [Page 24]
 
                              Tkabber v0.9.9                 January 2007
 
 
-   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.
 
@@ -1337,18 +1390,17 @@
 
    Stream initiation profile is defined in _XEP-0095_ with two
    transports (_XEP-0047_ - IBB, _XEP-0065_ - SOCKS5 bytestreams).  With
+   it you can specify what transports you can use, and via negotiation
+   choose more appropriate one. _Tkabber_ comes with two transport
+   implementations:
 
 
 
-Shchepin, et al.                                               [Page 24]
+Shchepin, et al.                                               [Page 25]
 
                              Tkabber v0.9.9                 January 2007
 
 
-   it you can specify what transports you can use, and via negotiation
-   choose more appropriate one. _Tkabber_ comes with two transport
-   implementations:
-
    bytestreams: that allows you to connect to any node that supports
       "bytestreams" transport (mediated connection is not supported
       yet);
@@ -1386,7 +1438,7 @@
 
    You can set directory to store logs:
 
-       set logger::options(logdir) ~/.tkabber/logs
+       set logger::options(logdir) [file join $::configdir logs]
 
    Also you can allow or disallow storing of private and group chats
    logs:
@@ -1396,7 +1448,11 @@
 
 
 
-Shchepin, et al.                                               [Page 25]
+
+
+
+
+Shchepin, et al.                                               [Page 26]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1452,7 +1508,7 @@
 
 
 
-Shchepin, et al.                                               [Page 26]
+Shchepin, et al.                                               [Page 27]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1508,7 +1564,7 @@
 
 
 
-Shchepin, et al.                                               [Page 27]
+Shchepin, et al.                                               [Page 28]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1564,7 +1620,7 @@
 
 
 
-Shchepin, et al.                                               [Page 28]
+Shchepin, et al.                                               [Page 29]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1620,7 +1676,7 @@
 
 
 
-Shchepin, et al.                                               [Page 29]
+Shchepin, et al.                                               [Page 30]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1676,7 +1732,7 @@
 
 
 
-Shchepin, et al.                                               [Page 30]
+Shchepin, et al.                                               [Page 31]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1732,7 +1788,7 @@
 
 
 
-Shchepin, et al.                                               [Page 31]
+Shchepin, et al.                                               [Page 32]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1788,7 +1844,7 @@
 
 
 
-Shchepin, et al.                                               [Page 32]
+Shchepin, et al.                                               [Page 33]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1844,7 +1900,7 @@
 
 
 
-Shchepin, et al.                                               [Page 33]
+Shchepin, et al.                                               [Page 34]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1900,7 +1956,7 @@
 
 
 
-Shchepin, et al.                                               [Page 34]
+Shchepin, et al.                                               [Page 35]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -1956,7 +2012,7 @@
 
 
 
-Shchepin, et al.                                               [Page 35]
+Shchepin, et al.                                               [Page 36]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2012,7 +2068,7 @@
 
 
 
-Shchepin, et al.                                               [Page 36]
+Shchepin, et al.                                               [Page 37]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2028,7 +2084,7 @@
 
 5.4.  Roster Hooks
 
-   When an item is added to the roster window, one of the three hooks is
+   When an item is added to the roster window, one of the four hooks is
    run to add stuff to the menu associated with that item:
 
    roster_conference_popup_menu_hook $path $connid $jid
@@ -2037,10 +2093,12 @@
 
    roster_jid_popup_menu_hook $path $connid $jid
 
-   The hook is given three parameters: the path of the _Tk_ menu widget;
-   the connection ID; and, a JID for which presence information is
-   available.
+   roster_group_popup_menu_hook $path $connid $name
 
+   When run, each hook is given three parameters: the path of the _Tk_
+   menu widget; the connection ID; and, a JID of the roster item (or the
+   name of the roster group for the last one).
+
    Also next hook is run to add stuff to the menu in groupchats:
 
    roster_create_groupchat_user_menu_hook $path $connid $jid
@@ -2066,9 +2124,7 @@
 
 
 
-
-
-Shchepin, et al.                                               [Page 37]
+Shchepin, et al.                                               [Page 38]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2086,36 +2142,74 @@
    The first two, by default, run the "postload" and "finload"
    procedures, respectively. _postload_hook_ is run after all code
    loaded and before initializing main _Tkabber_ window.  After that
-   _finload_hook_ is run.  The final hooks is called just before
+   _finload_hook_ is run.  The final hook is called just before
    _Tkabber_ terminates (cf., Section 4.3.7).
 
    You can add custom pages to userinfo window using
 
    userinfo_hook $path $connid $jid $editable
 
+5.6.  User Interface basics
 
+5.6.1.  Searching
 
+   Search panel may be invoked in certain classes of _Tkabber_ windows
+   using the "<<OpenSearchPanel>>" Tk virtual event which is bound by
+   default to the "<Control-S>" keyboard command.
 
+   Search panel can be dismissed by pressing the "<Escape>" key and the
+   default search action ("search down") is activated by pressing the
+   "<Return>" key while entering the search pattern.
 
+   Search panel is currenlty available in:
 
+   o  Chat and groupchat windows;
 
+   o  Service discovery window;
 
+   o  Chat history browser window.
 
+   Searching may be customized using the settings located under the
+   _Plugins --> Search_ group of the _Customize_ window.  These setings
+   are:
 
+   o  "::plugins::search::options(case)": perform case-sensitive
+      searching (_off_ by default);
 
 
 
 
 
+Shchepin, et al.                                               [Page 39]
+
+                             Tkabber v0.9.9                 January 2007
 
 
+   o  "::plugins::search::options(mode)": selects searching mode which
+      can be one of:
 
+      *  _substring_ -- use simple substring search: the typed search
+         string is taken verbatim and then the attempt to locate it is
+         performed.  This is the default mode.
 
+      *  _glob_ -- uses "glob-style" (or "shell-style") matching:
+         special symbols are recognized and they provide for
+         "wildcarding":
 
+         +  _*_ matches zero or more characters;
 
+         +  _?_ matches exactly one character;
 
+         +  _[_ and _]_ define character classes, e.g., "[A-Z]" will
+            match any character in the series "A", "B", ...  "Z".
 
+         The full syntax is described here.  That is, this search mode
+         can be convenient for those who want more general yet simple
+         approach to searching and is familiar with the "shell globbing"
+         concept found in Unix shells.
 
+      *  _regexp_ -- provides for searching using full-blown regular
+         expressions engine.  The full syntax is described here [22].
 
 
 
@@ -2124,7 +2218,25 @@
 
 
 
-Shchepin, et al.                                               [Page 38]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shchepin, et al.                                               [Page 40]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2180,7 +2292,7 @@
 
 
 
-Shchepin, et al.                                               [Page 39]
+Shchepin, et al.                                               [Page 41]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2236,7 +2348,7 @@
 
 
 
-Shchepin, et al.                                               [Page 40]
+Shchepin, et al.                                               [Page 42]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2292,7 +2404,7 @@
 
 
 
-Shchepin, et al.                                               [Page 41]
+Shchepin, et al.                                               [Page 43]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2348,7 +2460,7 @@
 
 
 
-Shchepin, et al.                                               [Page 42]
+Shchepin, et al.                                               [Page 44]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2404,7 +2516,7 @@
 
 
 
-Shchepin, et al.                                               [Page 43]
+Shchepin, et al.                                               [Page 45]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2460,7 +2572,7 @@
 
 
 
-Shchepin, et al.                                               [Page 44]
+Shchepin, et al.                                               [Page 46]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2516,7 +2628,7 @@
 
 
 
-Shchepin, et al.                                               [Page 45]
+Shchepin, et al.                                               [Page 47]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2572,7 +2684,7 @@
 
 
 
-Shchepin, et al.                                               [Page 46]
+Shchepin, et al.                                               [Page 48]
 
                              Tkabber v0.9.9                 January 2007
 
@@ -2628,5 +2740,5 @@
 
 
 
-Shchepin, et al.                                               [Page 47]
+Shchepin, et al.                                               [Page 49]
 

Modified: trunk/tkabber/doc/tkabber.html
===================================================================
--- trunk/tkabber/doc/tkabber.html	2007-01-06 15:40:32 UTC (rev 864)
+++ trunk/tkabber/doc/tkabber.html	2007-01-06 17:12:23 UTC (rev 865)
@@ -1,6 +1,6 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html lang="en"><head><title>Tkabber v0.9.9</title>
-<meta http-equiv="Expires" content="Mon, 01 Jan 2007 15:16:16 +0000">
+<meta http-equiv="Expires" content="Sat, 06 Jan 2007 17:05:45 +0000">
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <meta name="description" content="Tkabber v0.9.9">
 <meta name="generator" content="xml2rfc v1.30 (http://xml.resource.org/)">
@@ -132,7 +132,7 @@
 <tr><td class="header">&nbsp;</td><td class="header">New Economic School</td></tr>
 <tr><td class="header">&nbsp;</td><td class="header">M. Litvak</td></tr>
 <tr><td class="header">&nbsp;</td><td class="header">Information Centre ISP</td></tr>
-<tr><td class="header">&nbsp;</td><td class="header">January 1, 2007</td></tr>
+<tr><td class="header">&nbsp;</td><td class="header">January 6, 2007</td></tr>
 </table></td></tr></table>
 <div align="right"><span class="title"><br />Tkabber v0.9.9</span></div>
 
@@ -173,6 +173,8 @@
 Periodically send empty string to server<br />
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#s.preload-internation">4.1.9.</a>&nbsp;
 I18n/L10n<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#s.preload-searching">4.1.10.</a>&nbsp;
+Searching<br />
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#s.postload">4.2.</a>&nbsp;
 Post-load<br />
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#s.postload-looknfeel">4.2.1.</a>&nbsp;
@@ -243,6 +245,10 @@
 Roster Hooks<br />
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.5.</a>&nbsp;
 Miscellaneous Hooks<br />
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#s.user-interface">5.6.</a>&nbsp;
+User Interface basics<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#s.ui-searching">5.6.1.</a>&nbsp;
+Searching<br />
 <a href="#anchor6">Appendix&nbsp;A.</a>&nbsp;
 Releases History<br />
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">A.1.</a>&nbsp;
@@ -667,8 +673,50 @@
 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
 <a name="rfc.section.4"></a><h3>4.&nbsp;Configuration</h3>
 
-<p>One of the first thing that <span class="emph">Tkabber</span> does is read a file in your
-home directory called <span class="verb">".tkabber/config.tcl"</span>.
+<p><span class="emph">Tkabber</span> maintains its configuration using a set
+of files placed in a special configuration directory which
+location depends on the operating system <span class="emph">Tkabber</span>
+runs on. These locations are:
+</p>
+<ul class="text">
+<li>Unix systems: <span class="verb">"~/.tkabber"</span>;
+	
+</li>
+<li>Macintosh:
+	<span class="verb">"~/Library/Application Support/Tkabber"</span>;
+	
+</li>
+<li>Under Microsoft&reg; Windows&trade; this location
+	is governed by the policy of the particular flavor
+	of this OS, but the general rule is that the
+	<span class="emph">Tkabber</span> configuration directory is named
+	<span class="verb">"Tkabber"</span> and is located
+	in the special system folder for storing application-specific data.
+	For example, under Windows XP&trade; this will be something like
+	<span class="verb">"C:\Documents and Settings\USERNAME\Application Data\Tkabber"</span>,
+	where <span class="verb">"USERNAME"</span>
+	is the login name of a particular operating system's user.
+	
+</li>
+</ul><p>
+
+</p>
+<p><span class="emph">Tkabber</span> also honors the value of the
+<span class="verb">"TKABBER_HOME"</span> environment variable
+&mdash; if it exists the whole OS-based guessing of the
+configuration directory location is cancelled and the value of
+this environment variable is used instead.
+</p>
+<p>Once the pathname of the <span class="emph">Tkabber</span> configuration
+directory is known, its value is assigned to the
+<span class="verb">"configdir"</span> global Tcl variable
+which can be accessed from within the main
+<span class="emph">Tkabber</span> configuration file (see below).
+</p>
+<p>One of the first things that <span class="emph">Tkabber</span> does
+when it's starting up is reading a file
+located in its configuration directory under the name
+<span class="verb">"config.tcl"</span>.
 This is a <span class="emph">Tcl</span> source file,
 so obviously,
 it's a lot easier to maintain this file if you know the Tcl
@@ -803,7 +851,7 @@
 	    
 </p><pre>
     set load_default_xrdb 0
-    option readfile ~/.tkabber/newlook.xrdb userDefault
+    option readfile $::configdir/newlook.xrdb userDefault
 </pre>
 <p>
 	      The first line tells <span class="emph">Tkabber</span> not to load its default "xrdb"
@@ -963,6 +1011,18 @@
 </p><pre>
 ::msgcat::mclocale en
 </pre>
+<a name="s.preload-searching"></a><br /><hr />
+<table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
+<a name="rfc.section.4.1.10"></a><h3>4.1.10.&nbsp;Searching</h3>
+
+<p><span class="emph">Tkabber</span> allows the user to perform textual
+		searching in certain classes of its windows. This searching
+		is controlled by several settings which can be specified in
+		this section.
+</p>
+<p>These settings are described in detail
+		<a class="info" href="#s.ui-searching">here<span> (</span><span class="info">Searching</span><span>)</span></a>.
+</p>
 <a name="s.postload"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
 <a name="rfc.section.4.2"></a><h3>4.2.&nbsp;Post-load</h3>
@@ -1034,7 +1094,7 @@
 # the emoticon module
 
     set plugins::emoticons::options(theme) \
-	[file normalize ~/.tkabber/emoticons/rythmbox]
+		$::configdir/emoticons/rythmbox
 
 
 # the file transfer module
@@ -1071,7 +1131,7 @@
 
 # the logger module
 
-    set logger::options(logdir)        ~/.tkabber/logs
+    set logger::options(logdir)        [file join $::configdir logs]
     set logger::options(log_chat)      1
     set logger::options(log_groupchat) 1
 
@@ -1176,7 +1236,8 @@
 </p>
 <p>If you want,
 you can have <span class="emph">Tkabber</span> use a different theme by
-putting custom theme subdirectory to <span class="verb">~/.tkabber/pixmaps/</span>
+putting custom theme subdirectory to
+<span class="verb">$::configdir/pixmaps/</span>
 directory (tilde means home directory). <span class="emph">Tkabber</span> knows that it is a
 theme directory by looking for <span class="verb">icondef.xml</span> file in the
 directory.
@@ -1358,7 +1419,7 @@
 you can use the procedure called <span class="verb">plugins::emoticons::add</span>, e.g.,
 </p><pre>
     plugins::emoticons::add ":beer:" \
-        [image create photo -file ~/.tkabber/beer.gif]
+        [image create photo -file $::configdir/emoticons/beer.gif]
 </pre>
 <p>If you want to disable all emoticons, you can simply load empty directory.
 Put in postload function
@@ -1526,7 +1587,7 @@
 	      You can set directory to store logs:
 	    
 </p><pre>
-    set logger::options(logdir) ~/.tkabber/logs
+    set logger::options(logdir) [file join $::configdir logs]
 </pre>
 <p>
 	      Also you can allow or disallow storing of private and group chats
@@ -2196,7 +2257,7 @@
 <a name="rfc.section.5.4"></a><h3>5.4.&nbsp;Roster Hooks</h3>
 
 <p>
-	    When an item is added to the roster window, one of the three hooks is run to add
+	    When an item is added to the roster window, one of the four hooks is run to add
 	    stuff to the menu associated with that item:
 	  
 </p><pre>
@@ -2205,11 +2266,13 @@
 roster_service_popup_menu_hook $path $connid $jid
 
 roster_jid_popup_menu_hook $path $connid $jid
+
+roster_group_popup_menu_hook $path $connid $name
 </pre>
 <p>
-	    The hook is given three parameters: the path of the <span class="emph">Tk</span> menu
-	    widget; the connection ID; and, a JID for which presence information is
-	    available.
+	    When run, each hook is given three parameters: the path of the <span class="emph">Tk</span> menu
+	    widget; the connection ID; and, a JID of the roster item (or the name
+		of the roster group for the last one).
 	  
 </p>
 <p>
@@ -2252,13 +2315,96 @@
 run the <span class="verb">postload</span> and <span class="verb">finload</span> procedures,
 respectively. <span class="emph">postload_hook</span> is run after all code loaded and before initializing main
 <span class="emph">Tkabber</span> window. After that <span class="emph">finload_hook</span> is run.
-The final hooks is called just before <span class="emph">Tkabber</span> terminates
+The final hook is called just before <span class="emph">Tkabber</span> terminates
 (cf., <a class="info" href="#s.menuload-miscellany">Section&nbsp;4.3.7<span> (</span><span class="info">Miscellany</span><span>)</span></a>).
 </p>
 <p>You can add custom pages to userinfo window using
 </p><pre>
 userinfo_hook $path $connid $jid $editable
 </pre>
+<a name="s.user-interface"></a><br /><hr />
+<table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
+<a name="rfc.section.5.6"></a><h3>5.6.&nbsp;User Interface basics</h3>
+
+<a name="s.ui-searching"></a><br /><hr />
+<table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
+<a name="rfc.section.5.6.1"></a><h3>5.6.1.&nbsp;Searching</h3>
+
+<p>Search panel may be invoked in certain classes of
+<span class="emph">Tkabber</span> windows using the
+<span class="verb">&lt;&lt;OpenSearchPanel&gt;&gt;</span>
+Tk virtual event which is bound by default to the
+<span class="verb">&lt;Control-S&gt;</span> keyboard command.
+</p>
+<p>Search panel can be dismissed by pressing the
+<span class="verb">&lt;Escape&gt;</span> key
+and the default search action ("search down") is activated
+by pressing the <span class="verb">&lt;Return&gt;</span>
+key while entering the search pattern.
+</p>
+<p>Search panel is currenlty available in:
+</p>
+<ul class="text">
+<li>Chat and groupchat windows;
+</li>
+<li>Service discovery window;
+</li>
+<li>Chat history browser window.
+</li>
+</ul>
+
+<p>Searching may be customized using the settings located
+under the <span class="emph">Plugins &rarr; Search</span> group of the
+<span class="emph">Customize</span> window.
+These setings are:
+</p>
+<ul class="text">
+<li><span class="verb">::plugins::search::options(case)</span>:
+perform case-sensitive searching (<span class="emph">off</span> by default);
+
+</li>
+<li><span class="verb">::plugins::search::options(mode)</span>:
+selects searching mode which can be one of:
+	
+<ul class="text">
+<li><span class="emph">substring</span> &mdash; use simple substring search:
+	the typed search string is taken verbatim and then the attempt
+	to locate it is performed. This is the default mode.
+	
+</li>
+<li><span class="emph">glob</span> &mdash; uses "glob-style" (or "shell-style")
+	matching: special symbols are recognized and they provide for
+	"wildcarding":
+	
+<ul class="text">
+<li><span class="emph">*</span> matches zero or more characters;
+</li>
+<li><span class="emph">?</span> matches exactly one character;
+</li>
+<li><span class="emph">[</span> and <span class="emph">]</span> define
+		character classes, e.g., <span class="verb">[A-Z]</span>
+		will match any character in the series
+		"A", "B", ... "Z".
+</li>
+</ul>
+	The full syntax is described
+	<a href="http://www.tcl.tk/man/tcl8.4/TclCmd/string.htm#M35">here</a>.
+	That is, this search mode can be convenient for those who want more
+	general yet simple approach to searching and is familiar with the
+	"shell globbing" concept found in Unix shells.
+	
+</li>
+<li><span class="emph">regexp</span> &mdash; provides for searching using
+	full-blown regular expressions engine. The full syntax is
+	described <a href="http://www.tcl.tk/man/tcl8.4/TclCmd/re_syntax.htm">here</a>.
+	
+</li>
+</ul>
+
+</li>
+</ul><p>
+
+</p>
 <a name="anchor6"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
 <a name="rfc.section.A"></a><h3>Appendix A.&nbsp;Releases History</h3>

Modified: trunk/tkabber/doc/tkabber.xml
===================================================================
--- trunk/tkabber/doc/tkabber.xml	2007-01-06 15:40:32 UTC (rev 864)
+++ trunk/tkabber/doc/tkabber.xml	2007-01-06 17:12:23 UTC (rev 865)
@@ -398,8 +398,46 @@
 
 
 <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>.
+<t><spanx>Tkabber</spanx> maintains its configuration using a set
+of files placed in a special configuration directory which
+location depends on the operating system <spanx>Tkabber</spanx>
+runs on. These locations are:
+<list style='symbols'>
+	<t>Unix systems: <spanx style='verb'>"~/.tkabber"</spanx>;
+	</t>
+	<t>Macintosh:
+	<spanx style='verb'>"~/Library/Application Support/Tkabber"</spanx>;
+	</t>
+	<t>Under Microsoft&reg; Windows&trade; this location
+	is governed by the policy of the particular flavor
+	of this OS, but the general rule is that the
+	<spanx>Tkabber</spanx> configuration directory is named
+	<spanx style='verb'>"Tkabber"</spanx> and is located
+	in the special system folder for storing application-specific data.
+	For example, under Windows XP&trade; this will be something like
+	<spanx style='verb'>"C:\Documents and Settings\USERNAME\Application Data\Tkabber"</spanx>,
+	where <spanx style='verb'>"USERNAME"</spanx>
+	is the login name of a particular operating system's user.
+	</t>
+</list>
+</t>
+
+<t><spanx>Tkabber</spanx> also honors the value of the
+<spanx style='verb'>"TKABBER_HOME"</spanx> environment variable
+&mdash; if it exists the whole OS-based guessing of the
+configuration directory location is cancelled and the value of
+this environment variable is used instead.</t>
+
+<t>Once the pathname of the <spanx>Tkabber</spanx> configuration
+directory is known, its value is assigned to the
+<spanx style='verb'>"configdir"</spanx> global Tcl variable
+which can be accessed from within the main
+<spanx>Tkabber</spanx> configuration file (see below).</t>
+
+<t>One of the first things that <spanx>Tkabber</spanx> does
+when it's starting up is reading a file
+located in its configuration directory under the name
+<spanx style='verb'>"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
@@ -530,7 +568,7 @@
 	    </preamble>
 <artwork><![CDATA[
     set load_default_xrdb 0
-    option readfile ~/.tkabber/newlook.xrdb userDefault
+    option readfile $::configdir/newlook.xrdb userDefault
 ]]></artwork>
 	    <postamble>
 	      The first line tells <spanx>Tkabber</spanx> not to load its default "xrdb"
@@ -699,7 +737,16 @@
 ]]></artwork>
 	  </figure>
 	</section>
+
+	<section anchor='s.preload-searching' title="Searching">
+		<t><spanx>Tkabber</spanx> allows the user to perform textual
+		searching in certain classes of its windows. This searching
+		is controlled by several settings which can be specified in
+		this section.</t>
+		<t>These settings are described in detail
+		<xref target='s.ui-searching'>here</xref>.</t>
 	</section>
+	</section>
 
 <section anchor='s.postload' title='Post-load'>
 <t>After <spanx>Tkabber</spanx> reads your configuration file,
@@ -770,7 +817,7 @@
 # the emoticon module
 
     set plugins::emoticons::options(theme) \
-	[file normalize ~/.tkabber/emoticons/rythmbox]
+		$::configdir/emoticons/rythmbox
 
 
 # the file transfer module
@@ -807,7 +854,7 @@
 
 # the logger module
 
-    set logger::options(logdir)        ~/.tkabber/logs
+    set logger::options(logdir)        [file join $::configdir logs]
     set logger::options(log_chat)      1
     set logger::options(log_groupchat) 1
 
@@ -910,7 +957,8 @@
 	  
 <t>If you want,
 you can have <spanx>Tkabber</spanx> use a different theme by
-putting custom theme subdirectory to <spanx style='verb'>~/.tkabber/pixmaps/</spanx>
+putting custom theme subdirectory to
+<spanx style='verb'>$::configdir/pixmaps/</spanx>
 directory (tilde means home directory). <spanx>Tkabber</spanx> knows that it is a
 theme directory by looking for <spanx style='verb'>icondef.xml</spanx> file in the
 directory.
@@ -1091,7 +1139,7 @@
 you can use the procedure called <spanx style='verb'>plugins::emoticons::add</spanx>, e.g.,</preamble>
 <artwork><![CDATA[
     plugins::emoticons::add ":beer:" \
-        [image create photo -file ~/.tkabber/beer.gif]
+        [image create photo -file $::configdir/emoticons/beer.gif]
 ]]></artwork>
 </figure>
 <figure>
@@ -1248,7 +1296,7 @@
 	      You can set directory to store logs:
 	    </preamble>
 	    <artwork>
-    set logger::options(logdir) ~/.tkabber/logs
+    set logger::options(logdir) [file join $::configdir logs]
 </artwork>
 	  </figure>
 	  <figure>
@@ -1914,7 +1962,7 @@
       <section title='Roster Hooks'>
 	<figure>
 	  <preamble>
-	    When an item is added to the roster window, one of the three hooks is run to add
+	    When an item is added to the roster window, one of the four hooks is run to add
 	    stuff to the menu associated with that item:
 	  </preamble>
 <artwork><![CDATA[
@@ -1923,11 +1971,13 @@
 roster_service_popup_menu_hook $path $connid $jid
 
 roster_jid_popup_menu_hook $path $connid $jid
+
+roster_group_popup_menu_hook $path $connid $name
 ]]></artwork>
 	  <postamble>
-	    The hook is given three parameters: the path of the <spanx>Tk</spanx> menu
-	    widget; the connection ID; and, a JID for which presence information is
-	    available.
+	    When run, each hook is given three parameters: the path of the <spanx>Tk</spanx> menu
+	    widget; the connection ID; and, a JID of the roster item (or the name
+		of the roster group for the last one).
 	  </postamble>
 	</figure>
 	<figure>
@@ -1972,7 +2022,7 @@
 run the <spanx style='verb'>postload</spanx> and <spanx style='verb'>finload</spanx> procedures,
 respectively. <spanx stype='verb'>postload_hook</spanx> is run after all code loaded and before initializing main
 <spanx>Tkabber</spanx> window. After that <spanx stype='verb'>finload_hook</spanx> is run.
-The final hooks is called just before <spanx>Tkabber</spanx> terminates
+The final hook is called just before <spanx>Tkabber</spanx> terminates
 (cf., <xref target='s.menuload-miscellany'/>).</postamble>
 </figure>
 
@@ -1986,7 +2036,74 @@
 parameter which indicates whether the form is editable.
 </figure>
 </section>
+
+<section anchor='s.user-interface' title='User Interface basics'>
+
+<section anchor='s.ui-searching' title='Searching'>
+<t>Search panel may be invoked in certain classes of
+<spanx>Tkabber</spanx> windows using the
+<spanx style='verb'>&lt;&lt;OpenSearchPanel&gt;&gt;</spanx>
+Tk virtual event which is bound by default to the
+<spanx style='verb'>&lt;Control-S&gt;</spanx> keyboard command.</t>
+
+<t>Search panel can be dismissed by pressing the
+<spanx style='verb'>&lt;Escape&gt;</spanx> key
+and the default search action ("search down") is activated
+by pressing the <spanx style='verb'>&lt;Return&gt;</spanx>
+key while entering the search pattern.</t>
+
+<t>Search panel is currenlty available in:
+<list style='symbols'>
+<t>Chat and groupchat windows;</t>
+<t>Service discovery window;</t>
+<t>Chat history browser window.</t>
+</list></t>
+
+<t>Searching may be customized using the settings located
+under the <spanx>Plugins &rarr; Search</spanx> group of the
+<spanx>Customize</spanx> window.
+These setings are:
+<list style='symbols'>
+<t><spanx style='verb'>::plugins::search::options(case)</spanx>:
+perform case-sensitive searching (<spanx>off</spanx> by default);
+</t>
+<t><spanx style='verb'>::plugins::search::options(mode)</spanx>:
+selects searching mode which can be one of:
+	<list style='symbols'>
+	<t><spanx>substring</spanx> &mdash; use simple substring search:
+	the typed search string is taken verbatim and then the attempt
+	to locate it is performed. This is the default mode.
+	</t>
+	<t><spanx>glob</spanx> &mdash; uses "glob-style" (or "shell-style")
+	matching: special symbols are recognized and they provide for
+	"wildcarding":
+	<list style='symbols'>
+		<t><spanx>*</spanx> matches zero or more characters;</t>
+		<t><spanx>?</spanx> matches exactly one character;</t>
+		<t><spanx>[</spanx> and <spanx>]</spanx> define
+		character classes, e.g., <spanx style='verb'>[A-Z]</spanx>
+		will match any character in the series
+		"A", "B", ... "Z".</t>
+	</list>
+	The full syntax is described
+	<eref target='http://www.tcl.tk/man/tcl8.4/TclCmd/string.htm#M35'>here</eref>.
+	That is, this search mode can be convenient for those who want more
+	general yet simple approach to searching and is familiar with the
+	"shell globbing" concept found in Unix shells.
+	</t>
+	<t><spanx>regexp</spanx> &mdash; provides for searching using
+	full-blown regular expressions engine. The full syntax is
+	described <eref target='http://www.tcl.tk/man/tcl8.4/TclCmd/re_syntax.htm'>here</eref>.
+	</t>
+	</list>
+</t>
+</list>
+</t>
+
 </section>
+
+</section>
+</section>
 </middle>
 
   <back>



More information about the Tkabber-dev mailing list