Introduction to tsh

How to get started with tsh.

Updated Sat Sep 19 12:35:45 EDT 2009 for tsh 3.330.


tsh is a program for managing a Scrabble tournament. Preferably long before the tournament begins, you need to decide the basics of how the tournament will run: how many players will play in how many separately paired divisions, how many rounds they will play, when any breaks will be, how the pairings will be determined and what prizes will be awarded. All of this information goes into an event configuration file.

As players register for your tournament, you should enter their names and pretournament ratings (if any) into the appropriate division’s data file. When you have a reasonable number, you can start running mock tournaments to make sure that you are familiar with the software and that the pairing system you have chosen works the way you want it to. If you are using to keep track of registration, you can download your division data files from the director’s area on that web site. If you are using a supported rating system, you can download and use current ratings and check for membership status.

The event configuration files and the division data files belong in an event subfolder (subdirectory) of your tsh folder. You can and should use the “update” command to update your tsh folder whenever you have an Internet connection; it will not overwrite data in your event subfolders.

When all players are present or accounted for, you ask tsh for the pairings for the first round. tsh will display them on your screen and save a copy of the pairings to a printable web page. tsh saves a copy of most useful information that you’ve asked for in web pages. You may use this just for printing, or you may specify a public location for those files so that players and spectators can view the information directly. You can also tsh for a printable file containing scorecards for all players, including any pairings that have been computed.

As games finish, players submit their scores to you. You enter them into tsh, correct them if necessary, and at the appropriate time ask for the next round’s pairings. This goes on until the end of your tournament.

If you have prizes that can be automatically calculated (anything based on game scores, rather than individual plays or words), tsh will calculate them for you. If you are submitting your data for ratings purposes, tsh will prepare the data in the appropriate format.

Running tsh

This section, dealing with how to actually run tsh once you have it set up on your computer, is likely to be mostly unnecessary for most users and mystifying for many others, and is therefore addressed to those few who lie between.

Once you have installed and configured tsh, you’re ready to run tsh. Now tsh is a Perl script that runs under many different operating systems, and each operating system has a different way of starting programs. Broadly speaking, we can divide them into graphical methods and command-line methods. With the graphical methods, you need to find the icon appropriate for your operating system and (typically) double-click on it with your mouse to launch tsh, which will behave as though it was run from the command line with no “arguments”.

From the command line, you should in general enter some sort of incantation necessary to persuade your operating system to run tsh, followed by an optional “argument” giving the name of the subdirectory (folder) that contains the files for the event with which you want to work. If you do not specify an event, tsh will look first for the most recently updated configuration file it can find, or if none are available the oldstyle “tsh.config” file. Here’s what to do for some popular operating systems.

Operating System Instructions
(Mac) OS/X Either open a Finder window to your tsh folder and double-click on the ‘osx-tsh.command’ icon, or follow the generic Unix command-line instructions. If you get a message saying that the file is not executable, see Troubleshooting.
Classic MacOS I have not supported Classic MacOS since 2003. If you need to use tsh with MacOS 9 or earlier, please contact me and I’ll fix a number of compatibility issues and create a double-clickable icon for launching tsh.
Any Unix (including Linux) Open a shell (terminal) window, cd to your tsh directory and enter “./” (or just “” if your path permits) followed optionally by a space and the name of the subdirectory with your event files. For example: “./ toronto-2005”.
Windows Open a window to your tsh folder, then double-click on the “tsh” icon (if you have a properly installed version of Perl and a modern version of Windows) or “dos-run.bat” icon (otherwise).
DOS Type “perl”. If you want to override tsh’s choice of event directory, enter it on the same line: “perl myevent”. (To get a DOS command window under Windows, Choose “Run Command” from the Windows Start menu, then enter “command”.)
Other Check the “perlrun(1)” manual page concerning how to run Perl programs. Contact John Chew to have specific instructions added to this document.

If you get a message complaining that the configuration file can’t be found, make sure that your ‘.t’ files and ‘config.tsh’ file are together in one subdirectory, of the main tsh directory.

When you successfully start tsh, you should see a sequence of messages something like the following.

Loading configuration file test/config.tsh. [iloadcfg]
Welcome to tsh version 3.200. [iwelcome]
Loading division A. [iloaddiv]
Loading division B. [iloaddiv]
Loading division C. [iloaddiv]
Event loaded: Anytown AS, 2007-12-25. [ievtname]

The “tsh>” is your main prompt. If you have a system which supports it, the prompt will be in a distinctive colour. When you see it, you can type a command. After you type your command, don’t forget to press the return key.

Tournament Workflow

Here are the basic steps to follow in using tsh to run a tournament.

  1. Use the “ROSTERS” command to generate and print a list of all your players, to check at registration time that everyone is accounted for.
  2. Use the “ShowPairings” command to generate and display the next round’s pairings. For example, to show the first round pairings for Division A, enter “sp 1 a
  3. Use the “BrowseLast” command to open a browser window showing a nicely formatted version of the pairings you just created (enter: “bl”), and print it.
  4. Use the “Addscore” command to begin entering game scores. Follow the link for detailed instructions, which vary according to your input options.
  5. Use the “MISSING” command if you want to see which results are still missing.
  6. Use the “EditScores” command to correct scores.
  7. Use the “CheckRoundScores” command to prepare a list of entered scores for double-checking.
  8. Use the “BrowseLast” command to open a browser window showing a nicely formatted version of the scores you just listed (enter: “bl”), and print it.
  9. Use the “RATings” command to prepare a report of the current standings.
  10. Use the “BrowseLast” command to open a browser window on the standings, and print them.
  11. Optionally use the “STATisticS” command to update a large number of statistics, use the “Browse” command to list what's available, and print whichever you like.
  12. If you’re not at the end of the tournament, and are not using Portland pairings, go back to Step 2.
  13. Use the “PRiZes” command at the end of the tournament to display a list of prizewinners.

Make sure at a minimum that your data entry staff are well versed in using the commands listed above. A technically minded but untrained person should require 10–15 minutes of initial training, and a half-day's worth of supervised data entry to acquire good fluency with the program.