# Installing tsh

How to obtain and install what you need to run tsh.

Updated 2019-10-10T23:30:00+05 for tsh 3.330.

## What You Need

To run a tournament using tsh, you need the following:

- Perl: a cross-platform programming language
- a text editor to edit configuration files
- master sheets from which to print score slips and other forms
- the ZIP archive of the complete tsh distribution

## Perl

First, you should make sure that you have a recent version of the freely available Perl interpreter installed on your machine. tsh is currently regularly tested with Perl 5.10.0 and Perl 5.14.2, should run with any version of Perl 5 beginning with 5.6, and might run with Perl 6. Perl runs under several operating systems, including but not limited to Unix, MacOS, VMS and Windows. Please follow the appropriate instructions below.

OS/X, Linux | Windows | Pre-OS/X MacOS | Other
--- | --- | --- | ---
You already have a copy of Perl on your machine. | See the Perl for Windows section immediately below. | Download a copy of MacPerl from www.macperl.com, but be warned that the current version is not guaranteed to be Classic MacOS compatible — contact me for details. | If you don’t have a copy installed on your machine, you can download one from www.perl.com.

### Perl for Windows

There are two popular versions of Perl for Windows: ActivePerl and Strawberry Perl. I used to recommend ActivePerl, because it came with some Perl Windows modules that tsh requires. Since 2019 though (and in Perl terms, version 5.28.0), ActiveState has made it very difficult to install those modules; and at about the same time Strawberry Perl fortuitously started including them.

If you want to use ActivePerl, you will need to create a free account to download what used to be called the community edition. Once you log in, you'll be taken to a page where you can download one of three installers. You’ll want the one that ends in “`.msi`”, but don’t download it yet. Go to the Overview tab and ask it to add the following modules: “`Win32::API`”, “`Win32::Console`”, “`Win32::Internet`”, “`Win32::TieRegistry`”. Then wait a half hour or so while for the webpage to think about that, then download and run that installer.

If you skipped ahead and downloaded a copy of ActivePerl without those modules, run its installer again to uninstall it. Then go back to the webpage to add those modules, and download and run a new installer.

If you want to use Strawberry Perl, just go ahead and download and run its installer.

Getting programs to run when icons are clicked is surprisingly complicated in Windows, so I have provided two batch script icons called `dos64-tsh3` (for ActivePerl users) and `strawberry-tsh` (for Strawberry Perl users). If you end up installing your copy of Perl in a nonstandard location, you may find that neither one works, and you will have to open a DOS window manually to launch Perl.

## Text Editor

You will also need a text editor. You will use it to set up config.tsh, your settings file. You may also use it to edit tournament (".t") files if you find you need to do something in the heat of a tournament that I didn’t expect you to need. If you’re a Unix user, you know which editor is the One True Editor and don’t need to be told. (It’s vim, of course.) If you’re a Classic MacOS user, SimpleText will do in a pinch, but BBEdit is much better. Mac OS/X users can use vim, vi, pico, or TextEdit, but they should not use a Classic mode editor like BBEdit unless they are careful to specify Unix line breaks. Windows users can use Notepad or Wordpad.

## Forms

Score slips should be prepared to work best with tsh’s workflow. If you are entering scores and not just spread, the slips should contain the following information in the following layout:

    1st player (start): 1ST-NUMBER 1ST-SCORE 1ST-NAME 1ST-INITIALS
    2nd player (reply): 2ND-NUMBER 2ND-SCORE 2ND-NAME 2ND-INITIALS

The fields may be rearranged to some extent to suit layout constraints, but the important thing is that the numeric information that needs to be entered into tsh appears in the “1st-player-number, 1st-score, 2nd-player-number, 2nd-score” order in which it will be needed.

If you have configured spread-based entry, your slip should look something like this:

    1st player (start): 1ST-NUMBER 1ST-NAME 1ST-INITIALS
    2nd player (reply): 2ND-NUMBER 2ND-NAME 2ND-INITIALS
                        SPREAD

If you use a self-posting wall chart, it should be set up so that the player names read down the left side and the round numbers across the top. I have master sheets for stickers and score slips available for download in PDF format. You should consider instead bringing in an external monitor and using it to display an electronic scoreboard, which will give the players the same immediate feedback on current standings, while saving paper, time and effort.

## tsh.zip

All of the basic files you need to use tsh, except for configuration files specific to your event, can be downloaded in one zip archive. When you have downloaded and expanded the archive, you then need to set up those configuration files. Windows users please note that the best place for you to expand your archive is a folder called “tsh” on your desktop; the worst place to expand it is anywhere in “Program Files”, where some versions of Windows may not give you permission to run tsh.

## Updating tsh

tsh is a work in progress: it’s updated several times per year to include helpful suggestions from its users. Older versions are available for download from the tsh web site but are not supported. You should be sure to upgrade to the current version when you get ready to run a tournament.

If you have a copy of tsh 2.975 or later and a modern operating system (such as OS/X or some other kind of Unix, or even Windows XP), you can update your copy of tsh by simply entering the “`update`” command at the “tsh>” prompt. Your machine must be connected to the Internet when you enter the command for this to work, and any personal firewall must permit Perl to connect to external web sites at port 80. If you lose your connection during an update, just enter “`update`” again when your connection is restored.

The “`update`” command gives you the newest possible version of each file, which may be newer than the currently posted official ZIP archive.

If you can’t run tsh to use the “`update`” command, try running the “get-tsh.pl” script in your tsh folder.

If you have an older version of tsh, download the current ZIP archive, and don’t forget to copy over your event files to the newly created folder.

## Extras

The main distribution described above does not a number of optional extras, which are kept separate because they are large, possibly realm-specific, and not every director may find them necessary.

Player Photos
  Some commands will display photos of players when they are available. To install a photo database, set your realm or photo database in your configuration file, then use the “`UPDATEPIX`” command. See below for instructions about administering a tsh photo database.
Ratings
  Some commands will display and update ratings for players when they are available. To download the most recent ratings from the web, set your realm or rating list in your configuration file, then use the “`UPDATERATINGS`” command. This stores a local copy of the full rating list for your rating system, but does not update any division data files. To update your division data files based on the most recently downloaded full rating list, use the “`USERATINGS`” command.
Word Adjudication
  The “`LOOK`” command can be used for word adjudication; it currently checks the words entered in all available dictionaries. To use the command, you must first install the dictionary files using the The “`UPDATE-DICT`” command.
Plug-ins
  Some features of limited or local interest are available only as plug-in modules. Contact the author for information about installing them.

## Administering a Photo Database

tsh photo databases are stored on webservers and typically updated using an FTP client. The files in a database are all stored in one directory on the server, and possibly in its subdirectories. There are two index files which must be located in the root directory: “photos.txt” and “MANIPICS.txt”. You will edit the “photos.txt” file tells tsh which photo belongs to which player. The “MANIPICS.txt” file is automatically updated as described below and describes when each file was last changed, so that tsh knows which ones need to be downloaded.

Here is what to do whenever you make a change to your realm’s photo database: adding, deleting or renaming a photo.

1. Upload new photos to the FTP server. Photos should all be the same size (I recommend 128x128 pixels) and have the head occupying the same proportion of the photo (I recommend no more than 10% margin at top and bottom). Put them in sub-folders “a/”, “b/”, “c/”, ... to keep things tidy. Feel free to make sub-sub-folders or additional sub-folders.
2. For each photo, you need a line in the “photos.txt” file. It should have three tab-separated fields, no more, no less. If you have a player who will appear in a “*.t” file as “`Chew, John`”, and his photo is called (case-sensitive) “chew_john.jpg” is in the “c/” sub-folder, then his entry should read (representing tabs as <tab>)
   `John<tab>Chew<tab>c/chew_john.jpg`
   If you have a player who only has one name, appearing in the “*.t” file as “`Winter`”, and his photo called “winter.jpg” is in the “w/” sub-folder, then his entry should read
   `Winter<tab><tab>w/winter.jpg`
   Upload a new copy of the “photos.txt” to the server whenever you make a change to your photos.
3. Open your web browser to the page that you have been assigned that rebuilds the “MANIPICS.txt” file. The URL should end in “/cgi-bin/update-pdb.pl”
4. Finally, in each copy of tsh that you are using, make sure the config.tsh file specifies the realm or photo database and run the “`UPDATEPIX`” command.