add some documents

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@4793 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ext/tcltklib/MANIFEST

@@ -1,6 +1,8 @@
 MANIFEST
+README.1st
 README.euc
 MANUAL.euc
+MANUAL.eng
 tcltklib.c
 stubs.c
 depend

ext/tcltklib/MANUAL.eng

@@ -0,0 +1,264 @@
+(tof)
+                                    2003/10/17  Hidetoshi NAGAI
+
+This document discribes about the 'tcltklib' library. Although there
+is the 'tcltk' library (tcltk.rb) under this directory, no description
+in this document (because it is not maintained recently). 
+
+==============================================================
+module TclTklib
+  : Defines methods to do operations which are independed on 
+  : Tcl/Tk interpreters
+
+  module TclTkLib::EventFlag
+    : Defines flags to define taget events on 'do_one_event' methos. 
+    : When to give, please use bit-operator (e.g. WINDOW | DONT_WAIT). 
+
+    [constants]
+       NONE
+         : Is 0. It means "there is no target". But on the real
+         : operation, it is same to ALL.
+
+       WINDOW
+         : 'window' event is processed.
+
+       FILE
+         : 'file' event is processed.
+
+       TIMER
+         : 'timer' event is processed.
+
+       IDLE
+         : 'idle' operation (e.g. 're-draw'; the operations when the
+         : other kinds of events doesn't occur) is processed. 
+
+       ALL
+         : All kinds of events are processed. 
+         : Same to 'WINDOW | FILE | TIMER | IDLE'. 
+
+       DONT_WAIT
+         : Without this flag, 'do_one_event' waits the occurence of 
+         : a target event. With this flag, doesn't wait and returns 
+         : false if there is no target event for processing. 
+
+    [module methods]
+       mainloop(check_root = true)
+         : Starts the eventloop. If 'check_root' is true, this method 
+	 : doesn't return when a root widget exists. 
+         : If 'check_root' is false, doen't return by the other
+         : reasons than exceptions.
+
+      mainloop_watchdog(check_root = true)
+         : On the normal eventloop, some kinds of callback operations 
+         : cause deadlock. To avoid some of such deadlocks, this
+         : method starts an eventloop and a watchdog-thread.
+
+      do_one_event(flag = TclTkLib::EventFlag::ALL | 
+                            TclTkLib::EventFlag::DONT_WAIT)
+         : Do one event for processing. When processed an event, 
+         : returns true. 
+         : If NOT set DONT_WAIT flag, this method waits occurrence of
+         : a target event. 
+         : If set DONT_WAIT flag and no event for processing, returns 
+         : false immediately. 
+         : If $SAFE >= 4,  or $SAFE >= 1 and the flag is tainted, 
+         : force to set DONT_WAIT flag.
+
+      set_eventloop_tick(timer_tick)
+         : Define the interval of thread-switching with an integer
+         : value of mili-seconds. 
+         : Default timer_tick is 0. It means that thread-switching 
+         : is based on the count of processed events. 
+         : ( see 'set_eventloop_weight' method )
+         : However, if the eventloop thread is the only thread, 
+         : timer_tick cannt be set to 0. If 0, then is set to 100 ms 
+         : automatically (see NO_THREAD_INTERRUPT_TIME on tcltklib.c). 
+         : On $SAFE >= 4, cannot call this method. 
+
+      get_eventloop_tick
+         : Get current value of 'timer_tick'
+
+      set_no_event_wait(no_event_wait)
+         : Define sleeping time of the eventloop when two or more 
+         : thread are running and there is no event for processing. 
+         : Default value is 20 (ms).
+         : If the eventloop thread is the only thread, this value is 
+         : invalid. 
+         : On $SAFE >= 4, cannot call this method. 
+
+      get_no_event_wait
+         : Get current value of 'no_event_wait'.
+
+      set_eventloop_weight(loop_max, no_event_tick)
+         : Define the weight parameters for the eventloop thread. 
+         : That is invalid when the eventloop is the only thread. 
+         : 'loop_max' is the max events for thread-switching. 
+         : 'no_event_tick' is the increment value of the event count 
+         : when no event for processing (And then, the eventloop thead
+         : sleeps 'no_event_wait' mili-seconds). 
+         : 'loop_max == 800' and 'no_event_tick == 10' are defalut. 
+         : On $SAFE >= 4, cannot call this method. 
+
+      get_eventloop_weight
+         : Get current values of 'loop_max' and 'no_event_tick'.
+
+      mainloop_abort_on_exception=(bool)
+         : Define whether the eventloop stops on exception or not. 
+         : If true (default value), stops on exception. 
+         : If false, show a warinig message but ignore the exception.
+         : If nil, no warning message and ignore the excepsion. 
+         : This parameter is sometimes useful when multiple Tk
+         : interpreters are working. Because the only one eventloop 
+         : admins all Tk interpreters, sometimes exception on a
+         : interpreter kills the eventloop thread. Even if such
+         : situation, when abort_on_exception == false or nil, 
+         : the eventloop ignores the exception and continue to working. 
+         : On $SAFE >= 4, cannot call this method. 
+
+      mainloop_abort_on_exception
+         : Get current status of that. 
+
+      num_of_mainwindows
+         : Returns the number of main-windows (root-widget). 
+         : Because there is only one main-window for one Tk interpreter, 
+         : the value is same to the number of interpreters which has 
+         : available Tk functions.
+
+
+class TclTkIp
+  [class methods]
+      new(ip_name=nil, options='')
+         : Generate an instance of TclTkIp class. 
+         : If 'ip_name' argument is given as a string, it is the name
+         : of the Tk interpreter which is shown by 'winfo interps'
+         : command. 
+         : 'options' argument accepts a string which is the command 
+         : line options of wish; such as '-geometry' or '-use'. 
+         : The information is used to generate the root widget of the 
+         : interpreter. 
+         : ( e.g. TclTkIp.new('FOO', '-geometry 500x200 -use 0x2200009') )
+         : If is given nil or falsr for the 'option' argument, generates
+         : the Tcl interpreter without Tk library. Then the interpreter 
+         : doesn't need GUI environment. Therefore, even if a window
+         : system doesn't exist or cannot be used, Ruby can control the
+         : Tcl interpreter and the extention libraries loaded on the 
+         : interpreter. 
+
+   [instance methods]
+      create_slave(name, safe=false)
+         : Create a slave interpreter. 
+         : The parent of the interpreter is the receiver of this method.
+         : The name of the slave interpreter is given by 'name' argument. 
+         : The 'safe' argument decides whether the slave interpreter is
+         : created as a safe interpreter or not. If true, create a safe
+         : interpreter. Default is false. However, if the parent
+         : interpreter is a safe interpreter, the created interpreter is
+         : a safe interpreter (ignore 'safe' argument value). 
+         : If $SAFE >= 4, can create a safe interpreter only. 
+
+      make_safe
+         : Make the interpreter to the safe interpreter, and returns
+         : self. If fail, raise RuntimeError.
+
+      safe?
+         : Check whether the interpreter is the safe interpreter. 
+         : If is the safe interpreter, returns true. 
+
+      delete
+         : Delete the interpreter. 
+         : The deleted interpreter doesn't accept command and then
+         : raise an exception.
+
+      deleted?
+         : Check whether the interpreter is already deleted.
+         : If deleted, returns true. 
+
+      restart
+         : Restart Tk part of the interpreter. 
+         : Use this when you need Tk functions after destroying the
+         : root widget. 
+         : On $SAFE >= 4, cannot call this method. 
+
+      _eval(str)
+      _invoke(*args)
+         : Estimates the arguments as a command on the Tk interpreter. 
+         : The argument of _eval is a script of Tcl/Tk.
+         : Each argument of _invoke is a token of one command line of
+         : Tcl/Tk. 
+         : Because the operation of _invoke doesn't through the
+         : command line parser of Tk interpreter, the cost of
+         : estimation is smaller than _eval. However, auto_load
+         : mechanism of the Tk interpreter doesn't work on _invoke. 
+         : So _invoke can call only the command which already
+         : registered on the interpreter by 'load' command and so on. 
+         : On _eval command, auto_load mechanism words. So if succeed 
+         : to _eval and regist the command once, after that, the
+         : command can be called by _invoke. 
+
+      _toUTF8(str, encoding)
+      _fromUTF8(str, encoding)
+         : Call the function (which is internal function of Tcl/Tk) to
+         : convert to/from a UTF8 string.
+
+      _thread_vwait(var_name)
+      _thread_tkwait(mode, target)
+         : 'vwait' or 'tkwait' with thread support. 
+         : The difference from normal 'vwait' or 'tkwait' command is 
+         : doing independent wait from the vwait stack when they are
+         : called on the other thread than the eventloop thread.
+         : In the case of Tcl/Tk's vwait / tkwait, if 2nd vwait /
+         : tkwait is called on waiting for 1st vwait / tkwait, 
+         : returns the order of [2nd]->[1st] regardless of the order
+         : of when the wait condition was fulfilled.  
+         : If _thread_vwait / _thread_tkwait is called on the
+         : eventloop thread, there is no difference from vwait /
+         : tkwait. But if called on the other thread than the
+         : eventloop, stops the thread.  And when the wait condition 
+         : is fulfilled, the thread restarts. The meaning of
+         : "independent from the vwait stack" is that the timing of 
+         : restarting is independent from the waiting status of the 
+         : other threads. That is, even if the eventloop thread is 
+         : waiting by vwait and is not fulfilled the condition, 
+         : _thread_vwait completes the waiting when its waiting
+         : condition is fulfilled and the thread which stopped by
+         : _thread_vwait can continue the operation. 
+
+      _return_value
+         : Get the last result value on the interpreter. 
+
+      mainloop
+      mainloop_watchdog
+         : If on the slave interpreter, never start an eventloop and
+         : returns nil. 
+         : With the exception that, same to the TclTkLib module method
+         : with the same name. 
+
+      do_one_event
+         : With the exception that the argument is forced to set
+         : DONT_WAIT flag on the slave interpreter, same to
+         : TclTkLib#do_one_event. 
+
+      set_eventloop_tick
+      get_eventloop_tick
+      set_no_event_wait
+      get_no_event_wait
+      set_eventloop_weight
+      get_eventloop_weight
+      mainloop_abort_on_exception
+      mainloop_abort_on_exception=
+         : With the exception that it is ignored to set value on the
+         : slave interpreter, same to the TclTkLib module method with
+         : the same name. 
+
+class TkCallbackBreak < StandardError
+class TkCallbackContinue < StandardError
+   : They are exception classes to break or continue the Tk callback 
+   : operation. 
+   : If raise TkCallbackBreak on the callback procedure, Ruby returns 
+   : 'break' code to Tk interpreter (Then the Tk interpreter will 
+   : break the operation for the current event). 
+   : If raise TkCallbackContinue, returns 'continue' code (Then the Tk
+   : interpreter will break the operateion for the current bindtag and 
+   : starts the operation for the next buindtag for the current event).
+
+(eof)

ext/tcltklib/MANUAL.euc

@@ -1,5 +1,5 @@
 (tof)
-                                    2003/10/12  Hidetoshi NAGAI
+                                    2003/10/17  Hidetoshi NAGAI
 
 本ドキュメントには古い tcltk ライブラリ，tcltklib ライブラリの説明
 が含まれていますが，その記述内容は古いものとなっています．
@@ -151,7 +151,8 @@ require "tcltklib"
       : 指定 ) を定数として定義したモジュール．以下の定数が含まれる．
 
       定数  NONE
-         : いかなる種類のイベントも処理対象としない ( == 0 )
+         : 値は 0 で，値としてはいかなる種類のイベントも指定していない
+         : ことになるが，実際の処理上は ALL と同じとして扱われる．
 
       定数  WINDOW
          : window イベントを処理対象とする
@@ -212,7 +213,7 @@ require "tcltklib"
          : チングだけが行われる ( see set_eventloop_weight )．
          : ただし，稼働しているスレッドがイベントループだけの場合，
          : timer_tick を 0 に設定することはできない．もし設定されて
-         : いたら，200 ms ( see NO_THREAD_INTERRUPT_TIME ) に自動設
+         : いたら，100 ms ( see NO_THREAD_INTERRUPT_TIME ) に自動設
          : 定される．
          : 詳細な説明は略すが，これは CPU パワーを節約しつつ安全で
          : 安定した動作を実現するために実装した仕様である．

ext/tcltklib/README.1st

@@ -0,0 +1,33 @@
+To compile 'tcltklib', you must have Tcl/Tk libraries on your environment. 
+Although 'extconf.rb' script searches Tcl/Tk libraries and header files, 
+sometimes fails to find them. And then, 'tcltklib' cannot be compiled. If 
+Tcl/Tk libraries or header files are installed but are not found, you can 
+give the information by arguments of the 'configure' script. Please give 
+some or all of the following options. 
+
+ --with-tcllib=<libname>    (e.g. libtcl8.3.so ==> --with-tcllib=tcl8.3)
+ --with-tklib=<libname>     (e.g. libtk8.3.so  ==> --with-tklib=tk8.3)
+
+ --enable_tcltk_stubs       (if you force to enable stubs)
+
+ --with-tcl-dir=<path> 
+      equal to "--with-tcl-include=<path>/include --with-tcl-lib=<path>/lib"
+
+ --with-tk-dir=<path> 
+      equal to "--with-tk-include=<path>/include --with-tk-lib=<path>/lib"
+
+ --with-tcl-include=<dir>   the directry containts 'tcl.h'
+ --with-tk-include=<dir>    the directry containts 'tk.h'
+
+ --with-tcl-lib=<dir>       the directry containts 'libtcl<version>.so'
+ --with-tk-lib=<dir>        the directry containts 'libtk<version>.so'
+
+If you forgot to give the options when do 'configure' on toplevel
+directry of Ruby sources, please try something like as the followings.
+
+ $ cd ext/tcltklib
+ $ rm Makefile
+ $ CONFIGURE_ARGS='--with-tcl-include=/usr/local/include/tcl8.3/ --with-tcllib=tcl8.3 --with-tklib=tk8.3 --enable-tcltk_stubs' ruby extconf.rb
+
+==========================================================
+                Hidetoshi NAGAI (nagai@ai.kyutech.ac.jp)

ext/tk/MANIFEST

@@ -1,4 +1,5 @@
 MANIFEST
+README.1st
 extconf.rb
 depend
 tkutil.c

ext/tk/README.1st

@@ -0,0 +1,21 @@
+If you want to use Ruby/Tk (tk.rb and so on), you must have
+tcltklib.so which is working collectry. If you fail to call 
+'require "tcltklib"', you may not have tcltklib.so. 
+Even if there is a tcltklib.so on your Ruby library directry, 
+it will not work without Tcl/Tk libraries (e.g. libtcl8.4.so) 
+on your environment. You must also check that your Tcl/Tk is 
+installed properly. 
+
+--------------------------------------------
+ ( the following is written in EUC-JP )
+
+Ruby/Tk (tk.rb など) を使いたい場合には，tcltklib.so が正しく
+動いていなければなりません．もし require "tcltklib" に失敗する
+ようなら，tcltklib.so が存在していないのかもしれません．
+たとえ Ruby のライブラリディレクトリに tcltklib.so が存在して
+いたとしても，実行環境に Tcl/Tk ライブラリ (libtcl8.4.so など) 
+がなければ機能しません．Tcl/Tk が正しくインストールされているか
+どうかもチェックしてください．
+
+==========================================================
+                Hidetoshi NAGAI (nagai@ai.kyutech.ac.jp)

ext/tk/lib/tk.rb

@@ -1577,6 +1577,9 @@ module Tk
     def self.new(str)
       super(str, 'utf-8')
     end
+    def self.new_without_escape(str)
+      super(str, 'utf-8')
+    end
   end
   def Tk.UTF8_String(str)
     Tk::UTF8_String.new(str)