User Manual

- The IGS client
- The game window
- The SGF editor
- Play with GnuGo
- Solving problems
- The RubyGo printing system
- Customizing RubyGo
- Changes from last version
- Troubles with Ruby

# Customizing RubyGo

> Configure RubyGo is done in the 'Unix fashion': it means that you use a basic text editor to modify configuration files. This manner is very powerful because it is actual Ruby code that is loaded and executed dynamically at run time.

> The basic principle is that you make the same files that exist in the 'lib' directory, but you put them in your personal directory. The path for that directory can be set in the global variable RUBYGO_USER_FILES. If it is not set, it is

> - for Unix : "$HOME/.rubygo"
> - for windows: $USERPROFILE\RUBYGO_USER_FILES if this variable is set (Win NT). $HOME\RUBYGO_USER_FILES if set. Otherwise, C:\RUBYGO_USER_FILES is taken.

> Examples of these files are found in 'rubygo.sample', you can simply copy them to the final location. You can also review the distribution files of the same names to learn how to make your own files . These files are:

> - TkDefaults.rb
> - Defaults.rb
> - scripts.rb
> - ENTRY.rb : This file is handled by RubyGo to store its setting. You should not edit this file since it is rewritten each time rubygo is closed.

> By doing this way you can update the client with new versions without losing your own preferences, such as your username and password.

> There are many ways to customize the client:

> 1. Configure TK options in the file 'TkDefaults.rb': I have implemented a 'tree system' a little like X resources, so that, for example, setting a color background for 'GoClient.frame' will change the color of both 'GoClient.frame.user' and 'GoClient.frame.password'.
> 2. Configure RubyGo options in the file 'Defaults.rb': changing 'skins', icons, and some 'intelligent' things (hooks) like the way the clock blinks, or the manner in which the list of players is filtered. This is also where you define the 'players' and 'games' menus.
> 3. add your own commands to the console in the file 'scripts.rb'.
> One thing to keep in mind is that when you type into the entry fields in the gui, these values are remembered. For example the username and hostname settings when you click on Play IGS, at the beginning. These remembered values are loaded after the original RubyGo Defaults, but before the users custom definitions, allowing you to fix some parameters to whatever you used last time.

> You have the complete source code, so if you know Ruby you should be able to make things go as you like. But feel free to send me any requests or suggestions about functionnality you would like to see in RubyGo.

> ## Defaults.rb

> This file must start with

>   module Defaults

>   and end with

>   end

>   Between these two lines, you can set some of the RubyGo variables:

>   - DEFS['Server'] the adress of the server, hostname or IP address.
>   - DEFS['Port'] port
>   - DEFS['User'] your handle
>   - DEFS['Password'] be careful that nobody can read this file !
>   - DEFS['auto_start_Players'] launch Players window automatically when connected to the server
>   - DEFS['auto_start_Games'] idem games
>   - DEFS['auto_start_Chat'] open a separate window when you receive a message from a player
>   - DEFS['ReplyText'] text send when 'auto-reply' is set
>   - DEFS['show_coordinates'] ...
>   - DEFS['match_message']= 'Hello, would you like a game?'
>     If this option is defined, RubyGo will send this message using 'tell' automatically when you send a match request to a player.If you don't want that, simply add:
>     `DEFS['match_message'] = nil`
>     to your Defaults.rb file.
>   - etc ... definition names should be self explanatory, otherwise email me below.
>   - REPLAY['fast_forward'] = 10, number of moves when moving fast forward/backward
>   - etc ...

>   You can redefine these functions too:

>   - Defaults.clock_alarm: function responsible for making the clock blink when the time is small.
>   - Defaults.config_console_tags: configure the attributes of the text (such as color, background color) displayed at the console.Depend of a keyword.
>   - Defaults.console_show: for each line received form the server, the console call this function. If it return a keyword, the console will use it for display the text. If it return false, the text is not show (usually displayed another way by another plugin).
>   - Defaults.show_player: if this function returns true, the player is shown in the players list.

>   others functions are to be described here later. In fact if you care to explore RubyGo and even document this further, you are welcomed to do so and contribute it back here for the community!

>   see RubyGo/lib/Defaults.rb for original setting of parameters. (... to be finished)

>   ## scripts.rb

>   Here is an exemple of scripts.rb file that you can put in your personnal directory. You can find this file in rubygo.sample. I will use it to explain how to add your own commands and keyboard shortcuts to the console.

>       def user_make_bindings(window)
>         window.bind('F1', proc  {set_cmd 'set_auto_reply  ' })
>         window.bind('Shift-F1', proc  {set_cmd 'cancel_auto_reply  ' })
>         window.bind ('Control-o', proc { observe_pro_game(window)} )
>         end

>       def user_do_help(window)

>          putline "\n"
>          putline "my personnal scripts: \n"
>          putline "Control-o : observe last pro game started\n"
>          putline "hit  to print 'set_auto_reply' \n"
>          putline "hit  to print 'cancel_auto_reply' \n"
>       end

>           def observe_pro_game(window)
>             return if @pro_game.nil?
>             send_command ('observe '+ @pro_game)
>           end

>           def  user_make_vars(code,line)
>              if  m= /Match (\d+): (\S+) \[(.+)\] vs. (\S+) \[(.+)\]/.match(line)
>               if m[3].index( 'p') or m[5].index( 'p')
>       	  @pro_game= m[1]
>       	  putline ( line[1...-1]+"\n", 'info')
>       	  putline ( "Pro Game is started, hit 'Ctrl-O' to observe.\n",'tell')
>        	end
>              end
>           end

>   user_make_bindings is called once at the start by the console to set the keys shortcuts.set_cmd allow you to set the text of the console's entry as if it were typed by you at the console.The function observe_pro_game is defined later in the same file.
>   user_do_help is called when you hit 'Control-h'. putline display text in the output of the console. Note that you can use a key, defined in Defaults.config_console_tags, to choose a special color for the text.
>   user_make_vars(code,line) is called each time the console receive a line from the server. The code is defined in client/igsprotocol.rb. you can use regular expressions on the line to extract information. Here you look if there is a game starting with a pro player (5p* for ex). If so, you store the number in an instance variable (starting with @).
>   Next when the user hit 'Control-o' as defined in user_make_bindings, the function observe_pro_game(window) is called. 'window' is the console itself.send_command allow you to send a command directly to the server.

>   ## TkDefaults.rb

>   This file is where you can define much of the graphic aspect of RubyGo. The options are standard Tk options. One of the use of this file is internationalisation (i18n). RubyGo will look if there is a variable defined in your environment called 'LANG'. If there is one it will look for a file named TkDefaults.$LANG. If there is such a file it will be loaded the same way as your personal TkDefaults.rb file. I have made the file TkDefaults.fr for french users. This file can be taken as an example for other languages. If you wish to add your own country to RubyGo, please tell me.

>   ### example of personal TkDefaults.rb

>   Like for the others, you can define your personal TkDefaults.rb file in your RUBYGO_USER_FILES directory. ($HOME/.rubygo under linux) This file must start with
>   module TkDefaults
>   and end with
>   end
>   Between these two lines, you can define much GUI options (in fact you can change almost everything :-)

>   Changing the font of the console: this parameter is defined in the 'Dialog.text.Console' property. This property inherits all of the 'Dialog.text' properties, but you can change only the 'font' parameter for the console with two lines like this:

>       my_font= TkFont.new('terminal') # font with a fixed width
>       GUI['Dialog.text.Console'] = { 'font'=> my_font }

>   To display the list of fonts available on your system, open a terminal (xterm or dos) and type :

>        ruby -rtk -e 'puts TkFont.families'

>   You can choose a size for the font by adding it as a parameter:

>       my_font= TkFont.new('terminal',12)

>   For further information, send me a mail