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

tkabber-svn at jabber.ru tkabber-svn at jabber.ru
Fri Dec 27 11:57:07 MSK 2013


Author: sergei
Date: 2013-12-27 11:57:07 +0400 (Fri, 27 Dec 2013)
New Revision: 2029

Modified:
   trunk/tkabber/ChangeLog
   trunk/tkabber/README
   trunk/tkabber/doc/tkabber.html
   trunk/tkabber/doc/tkabber.xml
Log:
	* README, doc/tkabber.html, doc/tkabber.xml: Added a short description
	  for proxy profiles management.


Modified: trunk/tkabber/ChangeLog
===================================================================
--- trunk/tkabber/ChangeLog	2013-12-26 17:07:18 UTC (rev 2028)
+++ trunk/tkabber/ChangeLog	2013-12-27 07:57:07 UTC (rev 2029)
@@ -1,3 +1,8 @@
+2013-12-27  Sergei Golovan  <sgolovan at nes.ru>
+
+	* README, doc/tkabber.html, doc/tkabber.xml: Added a short description
+	  for proxy profiles management.
+
 2013-12-26  Sergei Golovan  <sgolovan at nes.ru>
 
 	* README, doc/tkabber.html, doc/tkabber.xml: Added a few hooks

Modified: trunk/tkabber/README
===================================================================
--- trunk/tkabber/README	2013-12-26 17:07:18 UTC (rev 2028)
+++ trunk/tkabber/README	2013-12-27 07:57:07 UTC (rev 2029)
@@ -103,8 +103,8 @@
        7.2.13. The Stream Initiation Module . . . . . . . . . . . . . 34
        7.2.14. The Logger Module  . . . . . . . . . . . . . . . . . . 35
        7.2.15. The Proxy Module . . . . . . . . . . . . . . . . . . . 35
-       7.2.16. The Login Module . . . . . . . . . . . . . . . . . . . 35
-       7.2.17. The Message Module . . . . . . . . . . . . . . . . . . 36
+       7.2.16. The Login Module . . . . . . . . . . . . . . . . . . . 37
+       7.2.17. The Message Module . . . . . . . . . . . . . . . . . . 38
 
 
 
@@ -113,43 +113,43 @@
                                Tkabber 1.0                  January 2014
 
 
-       7.2.18. The Raw XML Input Module . . . . . . . . . . . . . . . 36
-       7.2.19. The Roster Module  . . . . . . . . . . . . . . . . . . 37
-       7.2.20. The Sound Module . . . . . . . . . . . . . . . . . . . 37
-     7.3.  Menu-load  . . . . . . . . . . . . . . . . . . . . . . . . 39
-       7.3.1.  The Avatar Module  . . . . . . . . . . . . . . . . . . 39
-       7.3.2.  The Browser Module . . . . . . . . . . . . . . . . . . 40
-       7.3.3.  The Groupchat Module . . . . . . . . . . . . . . . . . 40
-       7.3.4.  The Login Module . . . . . . . . . . . . . . . . . . . 40
-       7.3.5.  The Message Module . . . . . . . . . . . . . . . . . . 40
-       7.3.6.  The Presence Module  . . . . . . . . . . . . . . . . . 40
-       7.3.7.  Miscellany . . . . . . . . . . . . . . . . . . . . . . 41
-     7.4.  Final-Load . . . . . . . . . . . . . . . . . . . . . . . . 41
-   8.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . . . 42
-     8.1.  Message Hooks  . . . . . . . . . . . . . . . . . . . . . . 43
-     8.2.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 44
-     8.3.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 45
-     8.4.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 46
-     8.5.  Info/Query Hook  . . . . . . . . . . . . . . . . . . . . . 46
-     8.6.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 47
-     8.7.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 47
-   9.  User Interface basics  . . . . . . . . . . . . . . . . . . . . 49
-     9.1.  Searching  . . . . . . . . . . . . . . . . . . . . . . . . 49
-   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 53
-     A.1.  Main changes in 1.0  . . . . . . . . . . . . . . . . . . . 53
-     A.2.  Main changes in 0.11.1 . . . . . . . . . . . . . . . . . . 53
-     A.3.  Main changes in 0.11.0 . . . . . . . . . . . . . . . . . . 54
-     A.4.  Main changes in 0.10.0 . . . . . . . . . . . . . . . . . . 54
-     A.5.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 55
-     A.6.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 56
-     A.7.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 56
-     A.8.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 57
-     A.9.  Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 57
-   Appendix B.  Tk option database resources  . . . . . . . . . . . . 58
-   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 62
-   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 63
-   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 64
-   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 65
+       7.2.18. The Raw XML Input Module . . . . . . . . . . . . . . . 38
+       7.2.19. The Roster Module  . . . . . . . . . . . . . . . . . . 38
+       7.2.20. The Sound Module . . . . . . . . . . . . . . . . . . . 39
+     7.3.  Menu-load  . . . . . . . . . . . . . . . . . . . . . . . . 40
+       7.3.1.  The Avatar Module  . . . . . . . . . . . . . . . . . . 41
+       7.3.2.  The Browser Module . . . . . . . . . . . . . . . . . . 41
+       7.3.3.  The Groupchat Module . . . . . . . . . . . . . . . . . 41
+       7.3.4.  The Login Module . . . . . . . . . . . . . . . . . . . 41
+       7.3.5.  The Message Module . . . . . . . . . . . . . . . . . . 42
+       7.3.6.  The Presence Module  . . . . . . . . . . . . . . . . . 42
+       7.3.7.  Miscellany . . . . . . . . . . . . . . . . . . . . . . 43
+     7.4.  Final-Load . . . . . . . . . . . . . . . . . . . . . . . . 43
+   8.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . . . 44
+     8.1.  Message Hooks  . . . . . . . . . . . . . . . . . . . . . . 45
+     8.2.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 46
+     8.3.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 47
+     8.4.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 48
+     8.5.  Info/Query Hook  . . . . . . . . . . . . . . . . . . . . . 48
+     8.6.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 49
+     8.7.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 49
+   9.  User Interface basics  . . . . . . . . . . . . . . . . . . . . 51
+     9.1.  Searching  . . . . . . . . . . . . . . . . . . . . . . . . 51
+   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 55
+     A.1.  Main changes in 1.0  . . . . . . . . . . . . . . . . . . . 55
+     A.2.  Main changes in 0.11.1 . . . . . . . . . . . . . . . . . . 55
+     A.3.  Main changes in 0.11.0 . . . . . . . . . . . . . . . . . . 56
+     A.4.  Main changes in 0.10.0 . . . . . . . . . . . . . . . . . . 56
+     A.5.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 57
+     A.6.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 58
+     A.7.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 58
+     A.8.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 59
+     A.9.  Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 59
+   Appendix B.  Tk option database resources  . . . . . . . . . . . . 60
+   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 64
+   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 65
+   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 66
+   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 67
 
 
 
@@ -1528,15 +1528,15 @@
      set proxy3(match)    *
      set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
 
-     set proxyconf1(profile) work
-     set proxyconf1(tunnel)  {proxy1 proxy3}
-     set proxyconf1(http)    {proxy2}
+     set proxyconf1(profile) Home
+     set proxyconf1(tunnel)  {}
+     set proxyconf1(http)    {}
 
-     set proxyconf2(profile) home
-     set proxyconf2(tunnel)  {}
-     set proxyconf2(http)    {}
+     set proxyconf2(profile) Work
+     set proxyconf2(tunnel)  {proxy1 proxy3}
+     set proxyconf2(http)    {proxy2}
 
-     array set proxyconf [array get proxyconf1]
+     array set proxyconf [array get proxyconf2]
 
  # the login module
 
@@ -1919,6 +1919,104 @@
 
 7.2.15.  The Proxy Module
 
+   Starting from versio 1.0 _Tkabber_ does not keep proxy settings in
+   the "loginconf" array.  It uses proxy profiles defined in separate
+   arrays.
+
+   First, you may want to specify a set of proxy servers.  You can have
+   multiple proxy servers defined in the config file (to use in
+   different environments, or if in your company different proxies are
+   used to connect to different hosts).  To do so, define global arrays
+   (their names could be arbitrary, but "proxy<number>" looks natural):
+
+       set proxy1(type)     https
+       set proxy1(host)     proxy.example.com
+       set proxy1(port)     3128
+       set proxy1(username) ""
+       set proxy1(password) ""
+       set proxy1(match)    *
+       set proxy1(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+
+       set proxy2(type)     http
+       set proxy2(host)     proxy.example.com
+       set proxy2(port)     3128
+       set proxy2(username) ""
+       set proxy2(password) ""
+       set proxy2(match)    *
+       set proxy2(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+
+       set proxy3(type)     socks5
+       set proxy3(host)     proxy.example.com
+       set proxy3(port)     1080
+       set proxy3(username) ""
+       set proxy3(password) ""
+       set proxy3(match)    *
+       set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+
+
+
+
+Shchepin, et al.                                               [Page 35]
+

+                               Tkabber 1.0                  January 2014
+
+
+   Field "type" is one of the following: _"socks4"_, _"socks5"_,
+   _"https"_, _"http"_.  The firat three types are tunnelling proxies.
+   If you enable them, _Tkabber_ will use them to tunnel its TCP
+   connections (in case of _"https"_ this means using _CONNECT_ method
+   for HTTP proxy).  The other one is used when _Tkabber_ needs to fetch
+   some data via _GET_ or _POST_ method of the HTTP protocol (e.g., when
+   utilizing BOSH or HTTP-poll connection).
+
+   Fields "host", "port", "username" and "password" are selfexplanatory.
+
+   There are two fields which need some explanation: "match" and
+   "exclude".  When Tkabber needs to connect to a certain _host_ or to
+   get an HTTP document it searches proxies in order they appear in the
+   corresponding proxyconf list (see below) and uses the first proxy for
+   which the _host_ matches one of the patterns from the "match" field
+   but doesn't match any of the patterns from the "exclude" field.  The
+   matching uses patterns convention from the "string match" _Tcl_
+   command.
+
+   Second, you may want to define proxy profiles, and switch between
+   them when the environment changes (it's useful for portable
+   computers).  To do so, you may define global arrays named
+   "proxyconf<number>" where numbers must start from 1 and be
+   consecutive, otherwise _Tkabber_ GUI wouldn't be able to switch to
+   them:
+
+       set proxyconf1(profile) Home
+       set proxyconf1(tunnel)  {}
+       set proxyconf1(http)    {}
+
+       set proxyconf2(profile) Work
+       set proxyconf2(tunnel)  {proxy1 proxy3}
+       set proxyconf2(http)    {proxy2}
+
+       array set proxyconf [array get proxyconf2]
+
+   Here, two proxy profiles are defined.  The first one instructs
+   _Tkabber_ not to use any proxies and directly connect to any host.
+   The second one defines two tunnel proxies and one HTTP proxy.  Note
+   that HTTPS and HTTP proxy are the same, but they should appear in
+   both "tunnel" and "http" fields anyway.  The last line chooses the
+   default proxy profile, which is _Work_ in the example above.
+
+   Also, you can edit proxy settings using _Tkabber_ GUI under
+   _Tkabber->Manage proxy servers_ menu item.
+
+
+
+
+
+
+Shchepin, et al.                                               [Page 36]
+

+                               Tkabber 1.0                  January 2014
+
+
 7.2.16.  The Login Module
 
    The first task is to initialize the configuration defaults for the
@@ -1953,14 +2051,6 @@
    "loginconf(usealtserver)" to "1").
 
    Another option is to use _BOSH_ (XEP-0124 and XEP-0206) connect
-
-
-
-Shchepin, et al.                                               [Page 35]
-

-                               Tkabber 1.0                  January 2014
-
-
    method (if your server supports it) and tunnel _XMPP_ traffic through
    _HTTP_.  To enable _BOSH_ set "loginconf(usebosh)" to "1". _Tkabber_
    then tries to find connect _URL_ using _TXT_ record in _DNS_ (see
@@ -1975,6 +2065,14 @@
    "loginconf(pollurl)".
 
    This collection of elements, which is termed a login profile, is what
+
+
+
+Shchepin, et al.                                               [Page 37]
+

+                               Tkabber 1.0                  January 2014
+
+
    populates the dialog window you'll see when _Tkabber_ wants to
    connect to the server.
 
@@ -2009,14 +2107,6 @@
 
    With this module you can monitor incoming/outgoing traffic from
    connection to server and send custom XML stanzas.  Also you can
-
-
-
-Shchepin, et al.                                               [Page 36]
-

-                               Tkabber 1.0                  January 2014
-
-
    switch on "pretty print" option to see incoming and outgoing XML
    stanzas pretty printed.  Note, that with this option they may be
    drawed incorrectly, e.g. for XHTML tags.  Also you can set
@@ -2031,6 +2121,14 @@
    Similarly by default, each item in every category is shown in the
    roster.  If you want to hide the items in a given category, the array
    called "roster::roster" lets you do this.  In the example, we see
+
+
+
+Shchepin, et al.                                               [Page 38]
+

+                               Tkabber 1.0                  January 2014
+
+
    that two groups (""RSS"" and ""Undefined"") start with their items
    hidden.
 
@@ -2064,15 +2162,6 @@
    set sound::options(mute_groupchat_delayed) 1
    set sound::options(mute_chat_delayed)      0
 
-
-
-
-
-Shchepin, et al.                                               [Page 37]
-

-                               Tkabber 1.0                  January 2014
-
-
    If you want to use external program for playing sounds and possibly
    this program's options, then also add something like this (these
    options are suitable for Linux users with ALSA installed):
@@ -2087,6 +2176,15 @@
    _Tkabber_ allows you to specify the filename it will play notifying
    about some more or less important events.  These are:
 
+
+
+
+
+Shchepin, et al.                                               [Page 39]
+

+                               Tkabber 1.0                  January 2014
+
+
    o  "sound::options(connected_sound)" -- sound playing when _Tkabber_
       is connected to the server;
 
@@ -2115,20 +2213,6 @@
       playing when you receive highlighted (usually personally
       addressed) groupchat message from another user.
 
-
-
-
-
-
-
-
-
-
-Shchepin, et al.                                               [Page 38]
-

-                               Tkabber 1.0                  January 2014
-
-
    If you want to disable sound notification for some of the events,
    then you can add line like this:
 
@@ -2149,6 +2233,14 @@
    The default version of this procedure is the identity function,
    i.e..,
 
+
+
+
+Shchepin, et al.                                               [Page 40]
+

+                               Tkabber 1.0                  January 2014
+
+
    proc menuload {description} { return $description }
 
    If you _really_ want to change the menubar specification, then here's
@@ -2176,15 +2268,6 @@
    The procedure called "avatar::store_on_server" stores your avatar on
    the server.
 
-
-
-
-
-Shchepin, et al.                                               [Page 39]
-

-                               Tkabber 1.0                  January 2014
-
-
 7.3.2.  The Browser Module
 
    The procedure called "browser::open" opens a new browser window.
@@ -2204,6 +2287,16 @@
    "logout" does just that; however, if you want get a dialog window for
    confirmation, use "show_logout_dialog" instead.
 
+
+
+
+
+
+Shchepin, et al.                                               [Page 41]
+

+                               Tkabber 1.0                  January 2014
+
+
 7.3.5.  The Message Module
 
    If you want to send a message to someone, the procedure called
@@ -2233,14 +2326,6 @@
        userinfo::open \
            ${loginconf(user)}@$loginconf(server)/$loginconf(resource) 1
 
-
-
-
-Shchepin, et al.                                               [Page 40]
-

-                               Tkabber 1.0                  January 2014
-
-
    There are also two variables that you can use to set your own
    presence: "userstatus" and "textstatus".  The first variable takes
    one of five values:
@@ -2259,6 +2344,15 @@
 
    The second variable takes any textual value.
 
+
+
+
+
+Shchepin, et al.                                               [Page 42]
+

+                               Tkabber 1.0                  January 2014
+
+
    Changes to your presence information are propagated only when
    "userstatus" is changed.  Accordingly, if you make a change to
    "textstatus", be sure to write "userstatus" immediately afterwards,
@@ -2292,7 +2386,25 @@
 
 
 
-Shchepin, et al.                                               [Page 41]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shchepin, et al.                                               [Page 43]
 

                                Tkabber 1.0                  January 2014
 
@@ -2348,7 +2460,7 @@
 
 
 
-Shchepin, et al.                                               [Page 42]
+Shchepin, et al.                                               [Page 44]
 

                                Tkabber 1.0                  January 2014
 
@@ -2404,7 +2516,7 @@
 
 
 
-Shchepin, et al.                                               [Page 43]
+Shchepin, et al.                                               [Page 45]
 

                                Tkabber 1.0                  January 2014
 
@@ -2460,7 +2572,7 @@
 
 
 
-Shchepin, et al.                                               [Page 44]
+Shchepin, et al.                                               [Page 46]
 

                                Tkabber 1.0                  January 2014
 
@@ -2516,7 +2628,7 @@
 
 
 
-Shchepin, et al.                                               [Page 45]
+Shchepin, et al.                                               [Page 47]
 

                                Tkabber 1.0                  January 2014
 
@@ -2572,7 +2684,7 @@
 
 
 
-Shchepin, et al.                                               [Page 46]
+Shchepin, et al.                                               [Page 48]
 

                                Tkabber 1.0                  January 2014
 
@@ -2628,7 +2740,7 @@
 
 
 
-Shchepin, et al.                                               [Page 47]
+Shchepin, et al.                                               [Page 49]
 

                                Tkabber 1.0                  January 2014
 
@@ -2684,7 +2796,7 @@
 
 
 
-Shchepin, et al.                                               [Page 48]
+Shchepin, et al.                                               [Page 50]
 

                                Tkabber 1.0                  January 2014
 
@@ -2740,7 +2852,7 @@
 
 
 
-Shchepin, et al.                                               [Page 49]
+Shchepin, et al.                                               [Page 51]
 

                                Tkabber 1.0                  January 2014
 
@@ -2796,7 +2908,7 @@
 
 
 
-Shchepin, et al.                                               [Page 50]
+Shchepin, et al.                                               [Page 52]
 

                                Tkabber 1.0                  January 2014
 
@@ -2852,7 +2964,7 @@
 
 
 
-Shchepin, et al.                                               [Page 51]
+Shchepin, et al.                                               [Page 53]
 

                                Tkabber 1.0                  January 2014
 
@@ -2908,7 +3020,7 @@
 
 
 
-Shchepin, et al.                                               [Page 52]
+Shchepin, et al.                                               [Page 54]
 

                                Tkabber 1.0                  January 2014
 
@@ -2964,7 +3076,7 @@
 
 
 
-Shchepin, et al.                                               [Page 53]
+Shchepin, et al.                                               [Page 55]
 

                                Tkabber 1.0                  January 2014
 
@@ -3020,7 +3132,7 @@
 
 
 
-Shchepin, et al.                                               [Page 54]
+Shchepin, et al.                                               [Page 56]
 

                                Tkabber 1.0                  January 2014
 
@@ -3076,7 +3188,7 @@
 
 
 
-Shchepin, et al.                                               [Page 55]
+Shchepin, et al.                                               [Page 57]
 

                                Tkabber 1.0                  January 2014
 
@@ -3132,7 +3244,7 @@
 
 
 
-Shchepin, et al.                                               [Page 56]
+Shchepin, et al.                                               [Page 58]
 

                                Tkabber 1.0                  January 2014
 
@@ -3188,7 +3300,7 @@
 
 
 
-Shchepin, et al.                                               [Page 57]
+Shchepin, et al.                                               [Page 59]
 

                                Tkabber 1.0                  January 2014
 
@@ -3244,7 +3356,7 @@
 
 
 
-Shchepin, et al.                                               [Page 58]
+Shchepin, et al.                                               [Page 60]
 

                                Tkabber 1.0                  January 2014
 
@@ -3300,7 +3412,7 @@
 
 
 
-Shchepin, et al.                                               [Page 59]
+Shchepin, et al.                                               [Page 61]
 

                                Tkabber 1.0                  January 2014
 
@@ -3356,7 +3468,7 @@
 
 
 
-Shchepin, et al.                                               [Page 60]
+Shchepin, et al.                                               [Page 62]
 

                                Tkabber 1.0                  January 2014
 
@@ -3412,7 +3524,7 @@
 
 
 
-Shchepin, et al.                                               [Page 61]
+Shchepin, et al.                                               [Page 63]
 

                                Tkabber 1.0                  January 2014
 
@@ -3468,7 +3580,7 @@
 
 
 
-Shchepin, et al.                                               [Page 62]
+Shchepin, et al.                                               [Page 64]
 

                                Tkabber 1.0                  January 2014
 
@@ -3524,7 +3636,7 @@
 
 
 
-Shchepin, et al.                                               [Page 63]
+Shchepin, et al.                                               [Page 65]
 

                                Tkabber 1.0                  January 2014
 
@@ -3580,7 +3692,7 @@
 
 
 
-Shchepin, et al.                                               [Page 64]
+Shchepin, et al.                                               [Page 66]
 

                                Tkabber 1.0                  January 2014
 
@@ -3636,5 +3748,5 @@
 
 
 
-Shchepin, et al.                                               [Page 65]
+Shchepin, et al.                                               [Page 67]
 


Modified: trunk/tkabber/doc/tkabber.html
===================================================================
--- trunk/tkabber/doc/tkabber.html	2013-12-26 17:07:18 UTC (rev 2028)
+++ trunk/tkabber/doc/tkabber.html	2013-12-27 07:57:07 UTC (rev 2029)
@@ -1629,15 +1629,15 @@
     set proxy3(match)    *
     set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
 
-    set proxyconf1(profile) work
-    set proxyconf1(tunnel)  {proxy1 proxy3}
-    set proxyconf1(http)    {proxy2}
+    set proxyconf1(profile) Home
+    set proxyconf1(tunnel)  {}
+    set proxyconf1(http)    {}
 
-    set proxyconf2(profile) home
-    set proxyconf2(tunnel)  {}
-    set proxyconf2(http)    {}
+    set proxyconf2(profile) Work
+    set proxyconf2(tunnel)  {proxy1 proxy3}
+    set proxyconf2(http)    {proxy2}
 
-    array set proxyconf [array get proxyconf1]
+    array set proxyconf [array get proxyconf2]
 
 # the login module
 
@@ -2090,6 +2090,85 @@
 <a name="rfc.section.7.2.15"></a><h3>7.2.15. 
 The Proxy Module</h3>
 
+<p>Starting from versio 1.0 <em>Tkabber</em> does not keep proxy settings
+in the <tt>loginconf</tt> array. It uses proxy profiles defined in
+separate arrays.
+</p>
+<p>First, you may want to specify a set of proxy servers. You can have multiple
+proxy servers defined in the config file (to use in different environments, or
+if in your company different proxies are used to connect to different hosts).
+To do so, define global arrays (their names could be arbitrary, but
+<tt>proxy<number></tt> looks natural):
+</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
+    set proxy1(type)     https
+    set proxy1(host)     proxy.example.com
+    set proxy1(port)     3128
+    set proxy1(username) ""
+    set proxy1(password) ""
+    set proxy1(match)    *
+    set proxy1(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+
+    set proxy2(type)     http
+    set proxy2(host)     proxy.example.com
+    set proxy2(port)     3128
+    set proxy2(username) ""
+    set proxy2(password) ""
+    set proxy2(match)    *
+    set proxy2(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+
+    set proxy3(type)     socks5
+    set proxy3(host)     proxy.example.com
+    set proxy3(port)     1080
+    set proxy3(username) ""
+    set proxy3(password) ""
+    set proxy3(match)    *
+    set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+</pre></div>
+<p>
+Field <tt>type</tt> is one of the following: <em>"socks4"</em>, <em>"socks5"</em>,
+<em>"https"</em>, <em>"http"</em>. The firat
+three types are tunnelling proxies. If you enable them, <em>Tkabber</em> will use them to tunnel its TCP
+connections (in case of <em>"https"</em> this means using <em>CONNECT</em> method for HTTP proxy).
+The other one is used when <em>Tkabber</em> needs to fetch some data via <em>GET</em> or
+<em>POST</em> method of the HTTP protocol (e.g., when utilizing BOSH or HTTP-poll connection).
+
+</p>
+<p>Fields <tt>host</tt>, <tt>port</tt>, <tt>username</tt> and <tt>password</tt> are selfexplanatory.
+</p>
+<p>There are two fields which need some explanation: <tt>match</tt> and <tt>exclude</tt>. When Tkabber needs to connect to a certain <em>host</em> or to get an HTTP
+document it searches proxies in order they appear in the corresponding proxyconf list
+(see below) and uses the first proxy for which the <em>host</em> matches one of the patterns from the
+<tt>match</tt> field but doesn't match any of the patterns from the <tt>exclude</tt> field. The matching uses patterns convention from the <tt>string
+match</tt>
+<em>Tcl</em> command.
+</p>
+<p>Second, you may want to define proxy profiles, and switch between them when the environment changes
+(it's useful for portable computers). To do so, you may define global arrays named
+<tt>proxyconf<number></tt> where numbers must start from 1 and be consecutive, otherwise
+<em>Tkabber</em> GUI wouldn't be able to switch to them:
+
+</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
+    set proxyconf1(profile) Home
+    set proxyconf1(tunnel)  {}
+    set proxyconf1(http)    {}
+
+    set proxyconf2(profile) Work
+    set proxyconf2(tunnel)  {proxy1 proxy3}
+    set proxyconf2(http)    {proxy2}
+
+    array set proxyconf [array get proxyconf2]
+</pre></div>
+<p>
+Here, two proxy profiles are defined. The first one instructs <em>Tkabber</em> not to use any proxies and
+directly connect to any host. The second one defines two tunnel proxies and one HTTP proxy. Note that HTTPS and
+HTTP proxy are the same, but they should appear in both <tt>tunnel</tt> and
+<tt>http</tt> fields anyway. The last line chooses the default proxy profile, which is
+<em>Work</em> in the example above.
+
+</p>
+<p>Also, you can edit proxy settings using <em>Tkabber</em> GUI under <em>Tkabber->Manage proxy
+servers</em> menu item.
+</p>
 <a name="s.postload-login"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.7.2.16"></a><h3>7.2.16. 

Modified: trunk/tkabber/doc/tkabber.xml
===================================================================
--- trunk/tkabber/doc/tkabber.xml	2013-12-26 17:07:18 UTC (rev 2028)
+++ trunk/tkabber/doc/tkabber.xml	2013-12-27 07:57:07 UTC (rev 2029)
@@ -1202,15 +1202,15 @@
     set proxy3(match)    *
     set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
 
-    set proxyconf1(profile) work
-    set proxyconf1(tunnel)  {proxy1 proxy3}
-    set proxyconf1(http)    {proxy2}
+    set proxyconf1(profile) Home
+    set proxyconf1(tunnel)  {}
+    set proxyconf1(http)    {}
 
-    set proxyconf2(profile) home
-    set proxyconf2(tunnel)  {}
-    set proxyconf2(http)    {}
+    set proxyconf2(profile) Work
+    set proxyconf2(tunnel)  {proxy1 proxy3}
+    set proxyconf2(http)    {proxy2}
 
-    array set proxyconf [array get proxyconf1]
+    array set proxyconf [array get proxyconf2]
 
 # the login module
 
@@ -1641,6 +1641,91 @@
         </section>
 
 <section anchor='s.postload-proxy' title='The Proxy Module'>
+<t>Starting from versio 1.0 <spanx>Tkabber</spanx> does not keep proxy settings
+in the <spanx style='verb'>loginconf</spanx> array. It uses proxy profiles defined in
+separate arrays.</t>
+
+<figure>
+<preamble>First, you may want to specify a set of proxy servers. You can have multiple
+proxy servers defined in the config file (to use in different environments, or
+if in your company different proxies are used to connect to different hosts).
+To do so, define global arrays (their names could be arbitrary, but
+<spanx style='verb'>proxy<number></spanx> looks natural):</preamble>
+<artwork><![CDATA[
+    set proxy1(type)     https
+    set proxy1(host)     proxy.example.com
+    set proxy1(port)     3128
+    set proxy1(username) ""
+    set proxy1(password) ""
+    set proxy1(match)    *
+    set proxy1(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+
+    set proxy2(type)     http
+    set proxy2(host)     proxy.example.com
+    set proxy2(port)     3128
+    set proxy2(username) ""
+    set proxy2(password) ""
+    set proxy2(match)    *
+    set proxy2(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+
+    set proxy3(type)     socks5
+    set proxy3(host)     proxy.example.com
+    set proxy3(port)     1080
+    set proxy3(username) ""
+    set proxy3(password) ""
+    set proxy3(match)    *
+    set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"
+]]></artwork>
+<postamble>
+Field <spanx style='verb'>type</spanx> is one of the following: <spanx>"socks4"</spanx>, <spanx>"socks5"</spanx>,
+<spanx>"https"</spanx>, <spanx>"http"</spanx>. The firat
+three types are tunnelling proxies. If you enable them, <spanx>Tkabber</spanx> will use them to tunnel its TCP
+connections (in case of <spanx>"https"</spanx> this means using <spanx>CONNECT</spanx> method for HTTP proxy).
+The other one is used when <spanx>Tkabber</spanx> needs to fetch some data via <spanx>GET</spanx> or
+<spanx>POST</spanx> method of the HTTP protocol (e.g., when utilizing BOSH or HTTP-poll connection).
+</postamble>
+</figure>
+
+<t>Fields <spanx style='verb'>host</spanx>, <spanx style='verb'>port</spanx>, <spanx
+style='verb'>username</spanx> and <spanx style='verb'>password</spanx> are selfexplanatory.</t>
+
+<t>There are two fields which need some explanation: <spanx style='verb'>match</spanx> and <spanx
+style='verb'>exclude</spanx>. When Tkabber needs to connect to a certain <spanx>host</spanx> or to get an HTTP
+document it searches proxies in order they appear in the corresponding proxyconf list
+(see below) and uses the first proxy for which the <spanx>host</spanx> matches one of the patterns from the
+<spanx style='verb'>match</spanx> field but doesn't match any of the patterns from the <spanx
+style='verb'>exclude</spanx> field. The matching uses patterns convention from the <spanx style='verb'>string
+match</spanx>
+<spanx>Tcl</spanx> command.</t>
+
+<figure>
+<preamble>Second, you may want to define proxy profiles, and switch between them when the environment changes
+(it's useful for portable computers). To do so, you may define global arrays named
+<spanx style='verb'>proxyconf<number></spanx> where numbers must start from 1 and be consecutive, otherwise
+<spanx>Tkabber</spanx> GUI wouldn't be able to switch to them:
+</preamble>
+<artwork><![CDATA[
+    set proxyconf1(profile) Home
+    set proxyconf1(tunnel)  {}
+    set proxyconf1(http)    {}
+
+    set proxyconf2(profile) Work
+    set proxyconf2(tunnel)  {proxy1 proxy3}
+    set proxyconf2(http)    {proxy2}
+
+    array set proxyconf [array get proxyconf2]
+]]></artwork>
+<postamble>
+Here, two proxy profiles are defined. The first one instructs <spanx>Tkabber</spanx> not to use any proxies and
+directly connect to any host. The second one defines two tunnel proxies and one HTTP proxy. Note that HTTPS and
+HTTP proxy are the same, but they should appear in both <spanx style='verb'>tunnel</spanx> and
+<spanx style='verb'>http</spanx> fields anyway. The last line chooses the default proxy profile, which is
+<spanx>Work</spanx> in the example above.
+</postamble>
+</figure>
+
+<t>Also, you can edit proxy settings using <spanx>Tkabber</spanx> GUI under <spanx>Tkabber->Manage proxy
+servers</spanx> menu item.</t>
 </section>
 
 <section anchor='s.postload-login' title='The Login Module'>



More information about the Tkabber-dev mailing list