# About tsh

... and its documentation.

tsh is a Perl application for managing Scrabble tournaments, first written in 1999, continuously maintained since then and freely distributed for noncommercial use by John Chew <poslfit@gmail.com>. This document and tsh are copyright © 2014 John J. Chew, III.

tsh is a program that deals with the logistics of running a tournament. With it, you can automatically or manually pair players, enter results, print standings, debug scorecard errors, estimate new player ratings and prepare data submissions for official ratings systems. tsh has been used at dozens of tournaments, producing high-quality pairings and reports with an estimated maximum operator:player ratio of 1:250. Among the many events that have been run using tsh are: the World Championship, the U.S. National Championship, the U.K. National Championship, the Canadian Championship, the U.S. Players’ Championship, and the King’s Cup as well as countless smaller weekend and one-day tournaments throughout the English, Italian, German, Polish and Norwegian Scrabble communities.

tsh comes with detailed documentation describing all of its features. Not everyone needs to read all of this document, and U.K. users in particular should begin by reading Stewart Holden’s Beginners’ Guide to TSH. NASPA users may benefit from reading Vince Castellano’s TSH QuickStart.

If this is your first time using tsh, or if you have not yet used version 3.000 or later, you must read the Introduction. You may then continue with other sections listed at the top of this page. All users should at least skim the section on commands. Data entry staff should read the sections on data entry, generating generating reports and troubleshooting. At least one person at each tournament should have browsed all sections of the manual before the tournament begins, including those on installation, configuration and pairing theory. If you want to print a copy for your reference during the tournament, the entire reference manual is also available in one file.

Before each tournament, you should update your copy of tsh and read the news of what has changed in recent versions, and follow the links there to changes in the other manual sections.

Free telephone support is available by prior arrangement. If you are planning to use tsh at a tournament, please contact me (John Chew) at least a few weeks in advance for help in setting up configuration files, and to discuss your support needs. If there is a specific feature that you need added to tsh, or support for a new language, please ask for it as far in advance of your event as possible. There is also a Yahoo group devoted to the needs of tsh users.

If you would like to make a donation to help make it possible for me to continue improving and supporting tsh, I welcome them via the “Make A Donation” PayPal button at the bottom of my poslfit home page. I am also available for hire to help run or webcast tournaments and games, on site or remotely, but am frequently booked 6-12 months in advance.

## System Requirements

tsh is written in Perl, the multiplatform scripting language. Every released version is tested with OS/X and should therefore also run on common versions of Unix. tsh versions are tested a few times a year with Windows XP, and whenever a user requests it. If you are using an operating system not mentioned here, please allow a few extra weeks for any software changes that may be needed to bring the current version of tsh into compatibility with it.

Disk space and memory requirements are minimal, a fairly small number of megabytes each. One computer is recommended for every 250 or so players, and one networked printer per tournament, though having more of each will reduce data entry and report printing time and improve redundancy.

If an Internet connection is available at the event site, tsh can be used to automatically update web coverage of the tournament, and last-minute patches to the program itself can be automatically downloaded. If not, tsh can run without these features.

# Troubleshooting tsh

What to do when things go wrong with tsh.

## Installation

It's possible that some OS/X browsers may download a non-executable version of this file. If so, please contact me for instructions. If you can't reach me, move your tsh folder to your home directory, open a “Terminal” window, enter the command “`cd tsh-nnnn`” replacing “`nnnn`” with the version number that you downloaded, and finally enter the command “`chmod a+x osx*`” to mark the command executable.

Some security-conscious users may have their personal firewall settings set too aggressively to allow the “`update`” command to function. tsh uses only port 80 (the standard port for HTTP service), so it should suffice to add tsh and/or Perl to the list of applications authorized to connect to this service.

If your update command does not seem to work, try the following in order. You may have a corrupt manifest file: move the ‘MANIFEST.txt’ file out of the tsh folder to make tsh lose track of what files it has, rerun tsh and the update. You may be having networking problems: make sure your browser can connect to the tsh web site. You may be having local system resource problems preventing tsh from beginning the update process: try restarting your Windows machine. You may have encountered a problem I didn't expect: download a fresh ZIP archive of either the current development release or the last stable release from the tsh web site, then copy your event folders into it.

## Correcting Tournament Data

You can delete bad pairings using the “`UnPairRound`” command, edit scores (and correct who went first, etc.) using the “`EditScore`” command (if you are in the middle of adding scores and you want to correct the most recently entered game, just type “es” at the game score prompt) and delete bad scores using the “`DELETEscore`” command. See the command reference for the syntax of those commands.

If you have made a serious error, you can manually revert to an earlier version of any tournament data (“.t”) file. tsh journals a copy of the tournament data file into a subdirectory or folder named "old" after each major change. Quit out of tsh, then look for the last good data file (either by checking the timestamps or inspecting the contents of the files), rename the bad “.t” file to “.t.bad” and put a copy of the journalled “.t.lotsofnumbers” file in its place as a new “.t” file.

You can also edit “.t” files using a text editor such as vim, gVim, BBEdit, TextEdit, NotePad, WordPad or emacs. If you do so, first quit from tsh, because tsh keeps an internal copy of its data that will overwrite any changes you make when tsh next updates its files.

## Crashes

If you are testing a new tsh feature, it’s possible that a program bug may put tsh into an infinite loop or dump core. In the former case, when tsh doesn’t give you a prompt, you’ll have to interrupt tsh and restart it. In OS/X and Unix, you interrupt terminal processes by pressing Control-C. In Windows, you can close the window that tsh is running in.

Some early versions of some pairings commands took a very long time to run. It’s possible that some bugs remain undiscovered. If you find that generating pairings in one particular situation takes excessively long (more than a few seconds), you may interrupt tsh, restart it, and then manually enter a faster pairing command. Allowing an extra repeat should in most cases substantially speed up the pairings calculations, or you can use the “`PAIR`” command to manually pair key players and then a regular command to pair the rest. In any case, in the unlikely event that this happens to you, please e-mail John a copy of the “.t” file involved.

As mentioned above, tsh journals its data after each major command, so if you are unsure about the condition of its files after a crash, revert to the last versions that were saved before the crash.

## Players Who Miss Games

If a player misses a paired game (e.g. due to illness or tardiness), you should manually repair him and his opponent to assign them both byes, then enter appropriate spreads for their scores. If you don’t do this, the unplayed game will count for ratings, and some players may end up getting multiple byes before others get any. If players 1 and 2 in division A were supposed to play each other in round 3 but player 1 didn’t show up, then enter “`floss a 1 3`”.

If a player gives you notice that he will be missing one or more games, or you end up determining that he is a no-show after the tournament has begun, you can prevent them from being considered for pairings using the “`EditScore`” command. If player 4 in division A should no longer be paired, enter “`es a 4 0`” to begin editing the player's scoresheet, then enter “`off -50`” give them forfeit losses whenever pairings are computed. (“`off 50`” will give them a 50-point bye, and “`off 0`” will record a missed game without assigning a win or loss). If the player subsequently returns to the tournament, you can re-enable their pairings by entering “`on`” while editing their scorecard.

## Errors and Informational Messages

If you aren't sure what an error message means, look to see if it has a code in [square brackets] at its end. If so, use the “`HUH`” command to ask for an explanation. If not, contact John and ask him to add an explanation.

## If All Else Fails...

My phone number is +1 416 876 7675, and I am more often in Canada’s Eastern time zone than not (UTC-4 or -5 depending on the time of year). If you arrange with me beforehand, I’ll make sure that I’m easily reachable at that number during your tournament; if not, I’ll find someone else who can be reached. If you didn’t prearrange my availability and you’re reading this because something has just gone unexpectedly wrong during a tournament, please try calling me anyway. I am also reachable when online by email, AIM, Facebook, Gmail Chat and (by prearrangement) Skype.

Whether or not you reach me right away, when you have an Internet connection please use the “`BUGreport`” command to send diagnostic information about any problems that you may encounter, so that I can fix it promptly.

# Introduction to tsh

How to get started with tsh.

## Overview

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 cross-tables.com 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 “`./tsh.pl`” (or just “`tsh.pl`” if your path permits) followed optionally by a space and the name of the subdirectory with your event files. For example: “`./tsh.pl 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 tsh.pl`”. If you want to override tsh’s choice of event directory, enter it on the same line: “`perl tsh.pl 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]
    tsh>

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.

# tsh Commands

The basics of how to operate tsh.

## How to Enter Commands

tsh is a command shell. If you’re familiar with using shells such as any Unix shell, OS/X Terminal or even DOS, you can probably skip this paragraph. A command shell is a no-frills way of interacting with a computer. In a large window, the computer displays a prompt, inviting you to type in a command that the computer understands. When you do so and then press the “return” key (analogous to hitting your clock in Scrabble), the computer takes some action based on what you’ve entered, then prompts you for your next command. Sometimes your command is modal, causing the computer to prompt for and expect a different set of commands until the mode is complete.

Pay attention to the changing prompts, which indicate what information tsh needs. Don’t forget to press the “return” key to confirm each command.

If you make a mistake and want to correct a previous command, or if you just want to repeat it, you may (depending on your system configuration) be able to scroll back by using the arrow keys on your keyboard. If pressing the arrow keys instead adds garbage to your screen, you can’t, but might consider installing the appropriate `Term::ReadLine` module that got left out of your Perl distribution (for OS/X users it's Term::ReadLine::Perl).

If you want to enter more than one command on a line, separate them with semicolons. Each one will be executed in turn before you are returned to the main prompt.

## The Most Important Commands

The most important commands to remember are “`quit`”, “`help`” and “`huh`”.

### Quit

The “`quit`” command makes tsh stop running.

### HELP

If you’re not sure how to use a command, then try typing “`help the-name-of-the-command`”. Here’s an example, showing what one version of tsh shows when you enter “`help help`”:

    Usage: help topic

    Use this command to view built-in documentation.  For fuller details, please
    consult the HTML reference manual.  Enter “help index” to see a list of
    available commands, and “help” followed by a command name to find out more
    about that command.

The first line tells you that when you use the “`help`” command you are expected to enter a topic after the word “help” so that tsh will know what you are asking for help about. Most commands require some supplementary information (called arguments) such as a division name, round number or player number.

The DOCumentation command opens a web browser to this reference documentation. If you enter “`doc`”, a window should appear displaying this manual’s introductory page.

### HUH

If you’re not sure what a message means, and it has a code in [square brackets] after it, enter “`huh the-message-code`”. Again, messages are documented in this way, and soon all of them will be. If you enter “`huh`” on its own, the last message you saw will be explained. To take a mostly random example, if you saw the message “`If you are sure you want to pair Round 12 based on Round 10, please specify config session_breaks. [eacpnsb]`” you might want to know more and enter “`huh eacpnsb`”. You would then see the message:

    [eacpnsb] It looks like you are relying on the default Chew pairing system, but
    the program is not sure whether you wanted to compute pairings for the upcoming
    round based on the first or second preceding round.  You can resolve the
    ambiguity by setting a value for the configuration variable 'session_breaks' in
    your configuration file.

This tries to explain the original, brief message. If neither the detailed explanation nor the related documentation is clear to you, please ask John to provide further clarification.

## tsh Command Reference

All currently available tsh commands are listed below in tables for reference, grouped by function. Most users will not use most of these commands. Each command has a name which verbosely describes its purpose, but which can be abbreviated to the portion shown in capital letters as shown in its example. Most commands must be followed (on the same line, before pressing “return”) by one or more arguments. These arguments are represented in examples by names, which must be replaced by actual values. If you don’t enter correct arguments, tsh will tell you what the correct ones should be, and where it stopped understanding what you were typing. Within modal commands, the syntax of what you are supposed to type varies, but is usually shown in the prompt.

To take one case, the example for the “`RoundStandings`” command, which displays standings in a division as of a specified round, reads `rs r d`. This means that “`RoundStandings`” can be abbreviated to its capitalised letters “`rs`”, and that it must be followed by a round number and a division name. You would enter “`rs 5 b`” and press the “return” key to ask for Division B standings as of Round 5. If you have only one division in your tournament, you may omit division names as arguments to commands. In the preceding example, you would just enter “`rs 5`”.

If you can’t remember a player number, you may enter enough of the player’s last and/or first names to unambiguously identify them, joined by a comma. For example, if “`Chew, John`” is the only player who has “`HEW`” in their last name, then you can see his scorecard by typing “`sc hew,`”. The comma is optional if you include at least two letters from one of the player’s names. As of the current release, this is not consistently implemented in modal commands such as the “`Addscore`” command, where the comma is not optional.

### Data Entry Commands

The following commands are used for entering tournament results, as well as checking and correcting them:

Command | Example | Description
--- | --- | ---
Addscore | a r d | Begin entering new game scores for round `r`, division `d`. This command is modal, and keeps prompting for scores until you press “return” on a line without scores.
CheckRoundScores | crs r d | List all entered scores for round `r`, division `d`, to facilitate checking of data entry.
DELETEscore | delete p1 s1 p2 s2 r d | Delete the previously entered scores `s1` for player `p1` and `s2` for player `p2` in round `r` division `d`. To delete a forfeit or bye, enter the spread as `s1` and 0 for `p2` and `s2`. This syntax is intentionally verbose to discourage the use of this command.
EditScore | es d p r | Begin editing previously entered game scores, starting with player `p` in round `r`, division `d`. This command is modal and fully documented in the data entry section.
FIX | fix d p | (Experimental) Begin graphically editing previously entered game scores for player `p` in division `d`.
ForfeitLOSS | floss d pn r spr | Delete any previous pairings for player `pn` in division `d` for round `r` and instead assign them a forfeit loss with a spread of `spr`. If the spread is omitted, use a default value
MISSING | missing r div | List all players in division `div` whose round `r` scores have not yet been entered. If `div` is omitted, all divisions are included.
showScoreCard | sc d p | Show the correct scorecard for player `p` in division `d`, for checking.

### Report Generation Commands

The following commands generate reports based on tournament results. You can use the “`Browse`” command to open your web browser to an index page showing what reports you have generated so far. The “`BrowseLast`” command opens your web browser to the most recent report that you requested, so that you can easily print it.

Command | Example | Description
--- | --- | ---
ABSPgrid | absp [d...] | Shows a results grid suitable for submission for ABSP ratings. Omit divisions unless you only want to submit results from some division.
AUPAIR | aupair d | Creates a .TOU file named for the division, containing ratings input information in AUPAIR.EXE format.
AverageOpponentScores | ave div | List average opponent scores for all players in a division.
AVErages | ave div | List average scores for all players in a division.
EnhancedScoreBoard | esb d | Create an HTML-only scoreboard that uses AJAX technology to dynamically display division `d`.
HighCombined | hc n div | List top n high combined scores (of both players in a game) in a division.
HighLoss | hl n div | List top n high losing scores in a division.
HighRatingChanges | hrc div | List the players whose ratings have increased by the most in a division.
HighRoundLosses | hrl r1-r2 div | List the high losing score in each round in a range of rounds in a division.
HighRoundWins | hrl r1-r2 div | List the high winning score in each round in a range of rounds in a division.
HighSpread | hs n div | List top n high spreads (winning margins) in a division.
HighWin | hw n div | List top n high winning scores in a division.
LowCombined | lc n div | List top n low combined scores (of both players in a game) in a division.
LowLoss | ll n div | List bottom n low losing scores in a division.
LowSpread | ls n div | List top n low spreads (winning margins) in a division.
LowWin | lw n div | List bottom n low winning scores in a division.
luckySTIFF | stiff n div | List players according to the total of their n closest wins, the opposite of a TUFFluck prize.
PRiZes | prizes d | List all prizes to be awarded, based on current division standings.
RATings | rat d | Show current division standings (with ratings estimates) for division `d`. See the “`config rating_system`” option.
ResultsByRound | rbr r1-r2 d | Rank players in division `d` based only on rounds `r1` through `r2`, typically to compute “best results, day n” prizes.
ROSTERS | rosters | List all players, with their player numbers and ratings.
ROTO | roto r | List rotisserie standings as of round r (if omitted, the current round).
RoundClassRATings | rcrat r1-r2 d | Show standings with ratings estimates for division `d` as of round `r2`, and refresh report files for rounds `r1` through `r2-1`, grouping players by class. The “`r1-`” is optional.
RoundHandiCap | rhc r1-r2 d | Show Thai handicaps in rounds `r1–r2` for division `d`.
RoundRATings | rrat r1-r2 d | Show standings with ratings estimates for division `d` as of round `r2`, and refresh report files for rounds `r1` through `r2-1`. The “`r1-`” is optional.
RoundStandings | rs r d | Show standings for division `d` as of round `r`.
saveJSON | json d | Used internally to store the state of a division on a web server, in a form usable by the “`EnhancedScoreBoard`” command. Often used with the “`hook_addscore_flush`” and “`hook_autopair`” options.
ScoreBoard | sb d rk1 rkn size cols secs | Create an HTML-only scoreboard showing what is going on in division `d` between ranks `rk1` and `rkn` with player photos (where available) scaled to `size` pixels wide in `cols` columns refreshed automatically every `secs`seconds. Often used with the “`hook_addscore_flush`” and “`hook_autopair`” options.
SHOW12 | show12 d | List firsts and seconds for all players in a division.
ShowDivisionScoreCards | sdsc d | Generate in HTML form the scorecards for every player in division `d`, for printing and distribution at the beginning of the tournament.
ShowManyPairings | smp r1-r2 d | Show pairings for rounds `r1-r2`, division `d`.
ShowNextPairings | sp d | Create an HTML report of pairings for the "next" round in the specified division, where "next" is the round following the lastest one for which scores have been entered, or round 1 if none. A single-round report of pairings for this round must already have been generated using `ShowPairings`. This command is intended to be used in conjunction with `config pairings_refresh` and `config hook_division_update` to provide an automatically-updating pairings display.
ShowPairings | sp r d | Show pairings for round `r`, division `d`.
STandings | st d | Show current standings for division `d`.
showRankedWallChart | rwc d | Show ranked wall chart for division `d`, as a summary of the entire tournament state.
showWallChart | wc d | Show correct wall chart for division `d`, to check against the physical chart.
SPITroast | spit r d | List UK rotisserie standings for division d as of round r.
STATisticS | stats | Report on summary statistics for a tournament.
TeamStandings | ts d | Show current team standings for division `d`.
TOTalScore | tots div | List players ranked according to the total number of points each has scored.
TotalTeamStandings | tts | Show current total team standings across all divisions.
TUFFluck | tuff n div | List players according to the total of their n closest losses, for the NSA’s “Tuff Luck” prize.
UPSETs | upset d | Show ratings upsets for division `d`.

### Pairing Commands

The following commands are used mainly for manually pairing rounds. You will need to know about them if you are configuring tsh before a tournament, or if you encounter an unexpected pairing situation and want to override automatic pairings. See the section on pairing theory for more detailed information about pairing systems.

Command | Example | Description
--- | --- | ---
AssignTeamsSnaked | ats r n d | Assign players to teams, usually so that you can then avoid pairing them with each other in early rounds using the “`exagony`” configuration option. You might instead want to use the TeamRoundRobin or TeamMultipleRoundRobin commands to have each player play players on other teams. The `n` teams will be called ‘GrpA’, ‘GrpB’, ‘GrpC’, ... in snaked (boustrophedonic) order (i.e., the top `n` players in division `d` as of round `r` (0 for pre-event seedings) are assigned to teams in order, the next `n` in reverse order, then forward again, etc.).
BASDFinal | basdf r d | Add Round `r` of BASD final pairings to division `d`.
BASDSemi | basds d | Add three rounds of BASD semifinal pairings to division `d`.
BRACKetpair | brack n d | Set up pairings for single-elimination with `n` repeated pairings in each stage for division `d`.
CAMbridgePair | camp d | Set up seven-round pairings as used in Cambridge ON for division `d`.
ChewPair | cp sr d | Set up Chew Pairings in division `d` based on round `sr` standings.
FactorPair | fp rd rpt sr d | Pair players permitting rpt repeats based on sr standings in division d, optimally matching players whose ranks differ by rd.
GREEN | green d | Set up pairings as used by John Green for division `d`.
GUELPH | guelph d | Set up pairings as used in Guelph ON CAN for division `d`.
InitFontes | if nr d | Set up fixed pairings for `nr` rounds (typically 3) in division `d` to give later Fontes pairings a place to start. Players are randomly chosen from quartiles and paired in round-robin quads.
KOTH | koth rpt sr d | Add king-of-the-hill pairings allowing `rpt` repeats (0 for none, 1 for simple repeats, 2 for threepeats), based on round `sr` standings in division `d`. To restrict the number of repeats after a certain round, e.g., KOTH pairings based on round 10 standings with no repeats after round 8, use `koth 0>8 10 a`.
LowerRoundRobins | lrr rk rds d | Add `rds` rounds of round robin groups pairings to division `d` starting at rank `rk`, allowing any number of repeats.
NAST | nast d | Add 4 or 5 rounds of fixed NAST pairings.
NewSwiss | ns rpt sr d | Add a round of Swiss pairings. See KOTH above for descriptions of arguments.
PAIR | pair p1 p2 r d | Manually pair players `p1` and `p2` in round `r`, division `d`. Use “`0`” as the player number of the opponent of a player with no opponent.
Pair1324 | p1324 rpt sr d | Pair 1–3, 2–4, 5–7, 6–8, and so on, i.e., factored pairings with factor two. See KOTH above for descriptions of arguments.
PairMany | pm r d | Begin manually pairing a large number of players in round `r`, division `d`. If you are tracking firsts and seconds, the first player entered goes first. This command is modal.
PairQuartiles | pq q rpt r d | Pair the top quartile at random against quartile `q`, based on round `r`, with at most `rpt` repeats, in division `d`.
RandomPair | rp rpt sr d | Add a round of random pairings to a division.
RoundRobin | rr n d | Add a full round robin to a division. If n is specified, it is the number of times each player should play each opponent consecutively; n defaults to the value 1.
TeamRoundRobin | trr n d | Pair each player in division `d` with every player on every other team. If `n` is specified, have them play each other `n` times in succession. tsh will use a fixed algorithm to schedule players; you can shuffle this by specifying an order other than “1,2,3,...,2t” for the value of the “`config round_robin_order`” configuration option.
TeamMultipleRoundRobin | tmrr rpt n d | Divide each team in division `d` into squads by standing as of round `n`, then pair each player with every player in the corresponding squad of every other team, in a round robin schedule that runs for `n` rounds. You should normally do this when the last paired round is fully paired; if it is partially paired, only the unpaired players will be involved in the team multiple round robins.
UnPairRound | upr r d | Delete all round `r` pairings from division `d`. Only the last round’s pairings may be deleted, and only if no scores have been entered. Use `DELETEscore` to delete scores, or edit the “.t” files directly.

The following pairing commands are deprecated, but are listed in case there is anyone who is still using them. All of these commands have been replaced by `NewSwiss`, which produces much better quality Swiss pairings.

Command | Example | Description
--- | --- | ---
BYE | bye p s r d | Deprecated: use `PAIR` and `Addscore` instead.
PrePreSwiss | ppsw rpt p1 p2 d | Deprecated: use `NewSwiss` instead.
PRESWiss | ppsw rpt p1 p2 d | Deprecated: use `NewSwiss` instead.
SWiss | sw rpt sr d | Deprecated: use `NewSwiss` instead.

### Testing Commands

The following commands are used mostly for testing your tsh configuration before your tournament begins.

Command | Example | Description
--- | --- | ---
DEBUG | debug code level | Turns debugging for sections labelled with `code` on if `level` is 1 or off if 0. Examine the tsh source code to find applicable codes.
DRYrun | dry r d | Simulates an entire tournament for a division, using random data and whatever pairings you have configured. If you specify a round number, the simulation begins after that round, and you must have exactly that many rounds completed in your data files. If you omit the round number or give it as 0, the simulation begins at the start of the tournament.
EVAL | eval code | Evaluate arbitary perl code. Use only if you know what you’re doing.
RANDomscores | rand d... | Give each player in division `d` a random score, to help simulate a tournament’s pairing system. Entering more than one division acts on each division, entering a division name more than once adds more than one round’s worth of random data.
RESETEVERYTHING | reseteverything | Delete all pairings, scores, start information and board assignments from tournament data files, and delete all journal and print files. Use with extreme caution.
TRUNCATEROUNDS | truncaterounds r d | Discards all data in a division after the given round (if 0, discard all data). Use with caution.

### Miscellaneous Commands

And here all the commands which don’t fit into one of the above categories:

Command | Example | Description
--- | --- | ---
BUGreport | bug note describing what went wrong | Uploads information about your TSH event to a webserver, along with a note explaining the problem, which all then gets sent to John Chew.
Browse | b | Opens your web browser to the tournament report index.
BrowseLast | bl | Opens your web browser to the last report you generated.
DivisionComplete | dc b | Manually triggers the commands given in the “`config hook_division_complete`” configuration option.
EXPORTRATINGS | exportratings | Creates a copy of the ratings database used by the “`USERATINGS`” command including the results of the current tournament.
HELP | help topic | Displays builtin documentation. `topic` is typically a command name.
HUH | huh code | Give a detailed explanation of a diagnostic message that included a [code].
LISTTourneys | listt | List all pending unrated tournaments (in realms that support this), so that you can find a value for the “`tournament_id`” configuration parameter.
LOOK | l word | Look up `word` in dictionary. CSW 2012 and TWL 2006 lexicon files available as a separate download. See also the “`count_good_words`” configuration option.
PROFILE | profile set key value | Set the value of configuration option “key” to “value” in your user profile.
profile show | Show all configuration options and values defined in your user profile.
Quit | q | Quit tsh.
setESBMeSsaGe | esbmsg set Games resume after lunch at 3:15 | Display a message on the Enhanced Scoreboard which optionally hides the ESB if the message mode is set to "hide" (the default mode is "reveal"). Three subcommands are recognized: "set" sets the message text; "mode" followed by "hide" or "reveal" sets the message mode; "off" turns off the message and reveals the ESB if it was hidden. Without any subcommand, reveals the current state of the ESB message.
SUBMIT | submit | Submit ratings data to the NSA web site.
TWEET | tweet d p1 p2 | Report to twitter about how players ranked `p1` through `p2` are doing in division `d`.
UPDATE | update | Update tsh software using a web connection.
UPDATEPIX | updatepix | Update the local photo database used by the “`ShowPairings`” command. Photos are copied from the local photo database into the ‘pix’ subdirectory of the event’ HTML directory when tsh starts up.
UpdatePLAYers | uplay | Update the player roster by referring to cross-tables.com. This will replace both player names and ratings; you may then wish to use the USERATINGS command to update just the ratings, if they haven’t yet been updated on cross-tables.com.
UPDATERATINGS | updateratings | Update the ratings database used by the “`USERATINGS`” command, currently available for the NASPA (NSA) and ABSP realms.
USERATINGS | useratings | Update all player ratings using the ratings database most recently updated by the “`UPDATERATINGS`” command.
VALET | valet d p r | (Experimental) Open a browser window for data entry.

### Plug-In Commands

There may also be external (plug-in) commands installed in your particular copy of tsh. These will be in a directory called ‘bin’, and listed in a configuration file there called ‘tshxcfg.txt’. They have been tested with OS/X (and should therefore work with most other flavours of Unix) and Windows XP, but may not work with more primitive operating systems. If not, you may still be able to use externals by running them separately from the command line. The following externals are part of the default distribution.

Command | Example | Description
--- | --- | ---
maketm | maketm div | Make a TourneyMan data file for a division.
nssc | nssc div | List School Championship prizes for a division.
update-dict | update-dict | Update the lexica (word lists) used by the LOOK command.

Some commands come bundled in plug-in modules:

Module | Command | Example | Description
--- | --- | --- | ---
TSH+ | LoadplayersCsV | lcv d | Load division data from an appropriately named CSV data file.
TSH+ | MergeplayersCsV | mcv d | Merge division data from an appropriately named CSV data file.
TSH+ | SaveplayersCsV | scv d | Save division data to an appropriately named CSV data file.

### Utility Commands

There are also a number of standalone utilities found in the “util/” directory, which are currently provided on an as-is basis. They are ‘standalone’ in that they have to be run in a separate window from tsh. Documentation will be provided here for any command upon request.

Command | Example | Description
--- | --- | ---
mirror-ftp | mirror-ftp -u username -p password event-name... | This separate program will mirror (constantly copy as needed) your TSH report files to your webserver using the FTP protocol. Use it to publish your tournament’s results live to the Internet. If you do not have a webserver, email poslfit@gmail.com to have one set up for your event. Because this is a separate program, you will typically need to run it in a separate window (COMMAND/DOS in Windows, Terminal in OS/X, some sort of term window in other flavours of Unix). Windows users should try running one of the .bat script files in the util folder (such as mirror-ftp.bat); others should open a window, cd to the tsh directory, and run “`util/mirror-ftp`” with command-line arguments as described below. Under most circumstances, the program will keep running without further attention. You should kill it when you are done with it (typically using Control+C); if you change Internet connections while it is running, you may need to kill and rerun it. This script needs to know five things to run. They can be specified in various ways. Tournament(s) Specify this the same way as when you are running tsh. If you don’t specify a tournament, the one whose config.tsh file is newest will be used. To explicitly specify one or more tournaments, list their directory names at the end of the command line (this only works when invoking the program from the command line). Unlike tsh, this program can work with multiple simultaneous tournaments. FTP Host You must specify your FTP host name (or IP address) in your config.tsh file using the “`ftp_host`” configuration parameter. FTP Path You must specify the directory path of your TSH coverage folder/directory on your webserver’s FTP system in your config.tsh file using the “`ftp_path`” configuration parameter. Your files will be copied into a subfolder/subdirectory of this path, named the same as the folder/directory containing your local copy of your event. FTP Username You may specify the username that you use to log onto your FTP account in three ways: using the “`ftp_username`” configuration parameter, using the “`-u MYUSERNAME`” command-line option, or having the program prompt you for your username. The last way is the most secure; the second way is secure if your local computer is secure. FTP Password You may specify the password that you use to log onto your FTP account in three ways: using the “`ftp_password`” configuration parameter, using the “`-p MYPASSWORD`” command-line option, or having the program prompt you for your password. The last way is the most secure; the second way is secure if your local computer is secure; the first way exposes your password to the Internet and is not recommended. “util/mirror-ftp” uploads the following files: the event config.tsh file, each division’s ‘.t’ file, and the contents of the directory specified by the ‘`html_directory`’ configuration option. Files ending in ‘.css, ‘.html’, ‘.htm’, ‘.t’ or ‘.txt’ are sent in text (ASCII) mode; others are transmitted in binary mode. “util/mirror-ftp” decides whether or not a file is stale and needs to be transmitted by comparing it to a zero-size file of the same name in ‘flags/event-name’ in the tsh directory.

# Data Entry with tsh

How to enter tournament results using tsh.

## Entering Results

tsh supports three styles of data entry, controlled by the “`config entry`” configuration option. The default value of the option is “`'scores'`”, meaning that tsh keeps track of the number of points that each player has scored in each game. Another possible value is “`'spread'`”, meaning that tsh keeps track only of the difference between the two players’ scores in each game. The third possible value is “`'both'`”, meaning that you must enter both the scores and the correct spread for each game.

You should use whatever information players enter on their score slips. If you are free to specify what this is, I recommend either scores mode or both mode. If you have staff to find players who have entered spread that does not correspond to scores, use both; if not, use scores.

### Entering Scores

At the end of the round, have players or runners bring their scoreslips to you. Sort them by division, and then for each division do the following.

Scores Entry | Spread Entry | Both Entry
--- | --- | ---
Enter the command (e.g.) “`a 3 d`” to add Round 3 scores for Division D. At the sub-prompt (which will look something like “[D3]:pn1 ps1 pn2 ps2? (9 scores left)”) enter the numbers as they appear on the score slip: player 1’s number, player 1’s score, player 2’s number, player 2’s score. Put spaces or periods between the numbers, press return at the end. If your entry is accepted, it will be repeated back to you with the players’ names and new cumes and this game’s spread displayed, and you’ll get another prompt. If the player numbers don’t match, you’ll be told so. If you enter a score that is too large or too small, it will be rejected; if someone really does score more than 1500 points, you must enter the result using “`EditScore`”. If you enter a score that is less than 100, you will be warned that the score looks suspicious, and you should check to make sure you did not leave out a digit. If the player has not recorded their player number, or has misrecorded it, you can enter their name instead of their number. To do so, enter as much as is necessary of their last and first names to disambiguate them from anyone else in the division, joined by a comma, and with no spaces. For example, you might enter “`Chew,Jo 400 Chew,Ja 300`” if John and Jamie Chew left out their player numbers. You may enter a name for one player and a number for the other. If you don’t enter enough of a player’s name, a list of matching player names will be shown and you will be asked to try again. If a player has a sufficiently unique partial first or last name, you may enter just that: “`John 400 Jamie 300`” will work if there is only one John and one Jamie. | Enter the command (e.g.) “`a 3 d`” to add Round 3 scores for Division D. At the sub-prompt (which will look something like “[D3]:winner loser spread? (9 scores left)”) enter the winner’s number, the loser’s number and the game spread. Put spaces or periods between the numbers, press return at the end. If your entry is accepted, it will be repeated back to you with the players’ names and new cumes displayed, and you’ll get another prompt. If the player numbers don’t match, you’ll be told so. If you enter a score that is negative or is too large, it will be rejected; if someone really does win a game by 1000 points, you must enter the result using “`EditScore`”. If the player has not recorded their player number, or has misrecorded it, you can enter their name instead of their number. To do so, enter as much as is necessary of their last and first names to disambiguate them from anyone else in the division, joined by a comma, and with no spaces. For example, you might enter “`Chew,Jo Chew,Ja 100`” if John and Jamie Chew left out their player numbers. You may enter a name for one player and a number for the other. If you don’t enter enough of a player’s name, a list of matching player names will be shown and you will be asked to try again. If a player has a sufficiently unique partial first or last name, you may enter just that: “`John Jamie 100`” will work if there is only one John and one Jamie. | Enter the command (e.g.) “`a 3 d`” to add Round 3 scores for Division D. At the sub-prompt (which will look something like “[D3]:pn1 ps1 pn2 ps2 spr? (9 scores left)”) enter the numbers as they appear on the score slip: player 1’s number, player 1’s score, player 2’s number, player 2’s score, spread (the signed difference between the two scores). Put spaces or periods between the numbers, press return at the end. If your entry is accepted, it will be repeated back to you with the player’s names and new cumes and this game’s spread displayed, and you’ll get another prompt. If the player numbers don’t match or the spread you entered is incorrect, you’ll be told so. If you enter a score that is too large or too small, it will be rejected; if someone really does score more than 1500 points, you must enter the result using “`EditScore`”. If you enter a score that is less than 100, you will be warned that the score looks suspicious, and you should check to make sure you did not leave out a digit. If the player has not recorded their player number, or has misrecorded it, you can enter their name instead of their number. To do so, enter as much as is necessary of their last and first names to disambiguate them from anyone else in the division, joined by a comma, and with no spaces. For example, you might enter “`Chew,Jo 400 Chew,Ja 300`” if John and Jamie Chew left out their player numbers. You may enter a name for one player and a number for the other. If you don’t enter enough of a player’s name, a list of matching player names will be shown and you will be asked to try again. If a player has a sufficiently unique partial first or last name, you may enter just that: “`John 400 Jamie 300`” will work if there is only one John and one Jamie.

If you want to enter a bye, just enter one player number and one score. (In most cases, tsh will automatically enter byes for you.) If you want to switch to entering results for a different division, enter the name of the division by itself. If you want to correct a mistake in the scores that you just entered, enter “`es`” (see below). If you want to see which results are still missing, enter “`missing`” or just “`m`”. Whenever you want to save what you’ve entered, press the return key without entering any scores to return to the “`tsh>` ” prompt. You will also be returned to the “`tsh>` ” prompt if you enter something that tsh does not understand.

If you have tsh set to track but not assign who went first or second in each game, you must enter game scores in player order, with the number and score of the player who went first appearing first on the line. If tsh knows who was supposed to go first (because that player had had fewer firsts than his/her opponent), then it will complain that the players determined who went first incorrectly. If it doesn’t know, it will assume that you have entered them correctly and update its information about who went first. You can use the “`EditScore`” command to edit whom tsh thinks went first or should go first.

When you’re close to having all the scores in for a round, entering “`missing 6 b`” (e.g.) will list all the results you’re still missing for round 6 in division B. Omitting the “`b`” will list missing players in all divisions. You can then ask a runner or word judge to politely ask the players to pause their post mortem long enough to fill out their paperwork. As noted above, you can also just enter “`m`” in `AddScore` mode.

## Checking and Correcting Results

If you make a mistake entering the score for division B player 4 in round 3, enter “`es b 4 3`” at the “`tsh>` ” prompt. You’ll get a mockup of the player’s scorecard as it currently reads, a sub-prompt that gives you that player’s score that round and their opponent’s score that round, and you can then enter one of the following commands, or press enter to return to the main “tsh>” prompt.

Sub-Command | Example | Description
--- | --- | ---
new-scores | ps os | Set the player’s score in the current round to `ps` and the opponent’s score to `os`, if in scores data entry mode.
new-spread | ps | Set the player’s spread in the current round to `ps` and the opponent’s spread (if any) to `−os`, if in spread data entry mode or if the player has a bye or forfeit.
BOARD | BO b | Place the current player at board `b`.
D | D d | Switch to editing the corresponding player in division `d`.
FIRST | first | Record that this player went first (started) this round, and their opponent (if any) went second (replied).
GAMES | ga g | Set this player’s career game total prior to this tournament to `g`. This is necessary for accurate computation of some ratings.
OFF | OFF s | Mark this player inactive for pairings, and automatically assign them a spread of `s` in future.
ON | ON | Mark this player active for pairings.
P | P p | Switch to editing player number `p`.
PENALTY | PEN p | Assign a spread penalty to the current player in the current round: specify a positive value when compensating a player for a misadjudication, a negative value to penalize them for an infraction.
R | R r | Switch to editing the player’s results in round `r`.
RATING | RA r | Set the player’s pretournament rating to `r`.
SECOND | second | Record that this player went second (replied) this round, and their opponent (if any) went first (started).

As indicated in the table, you can also use the “`EditScore`” command to make corrections to player pretournament ratings and career game totals. If you have not entered any scores yet, you may ask to edit the scores for the fictitious “Round 0” in order to run the command.

If you catch your mistake while you’re still in “`Addscore`” mode, you can just enter “`es`” (without any additional arguments) at the “`Addscore`” prompt. You’ll go temporarily into “`EditScore`” mode, looking at the data that you just entered. When you leave “`EditScore`” mode, you will return to “`Addscore`” mode.

Similarly, you can use the “`LOOK`” command within “`Addscore`” mode to adjudicate challenges.

You may wish to check what you have entered against player scorecards or against the tournament wall charts. See the section on generating reports and in particular the “`CheckRoundScores`” command for information on how to do this.

If you have a serious problem, you may need to edit the tournament data files directly. Pay particular attention to the information in the preceding link about how to find copies of older, journalled versions of data files. For example, if you find after entering half of the results for a round that the other half of the players used a different round’s pairings to find their opponents, you will have some careful typing to do to fix the files. (Not that this has ever happened to the author, though he has lain awake at night worrying about similar scenarios.)

As soon as you have finished entering and checking results for a round, you should prepare and print all necessary reports for the next round.

# Preparing Reports with tsh

How to list standings, pairings and more using tsh.

As part of your regular workflow after you have entered scores for your tournament, you will likely want to produce and print reports such as standings and pairings tables using tsh. Each type of report is generated using its own command, and most report-generating commands display some information on your screen while saving it to an HTML file which you may print.

To print the most recent report that you generated, enter the “BrowseLast” command to open the report in a new browser window, then use your browser’s print command. To print older reports, and to see which ones are available, enter the “Browse” command to open a report index in a new browser window.

By default, HTML files are created in the “html” subdirectory of your event directory. If your computer runs its own locally accessible web server (most computers can be configured to do so), then you may wish to create the HTML files directly in the server directory using “`config html_directory`” so that your players can check reports on their laptops or at browser kiosks that you have set up at your tournament. If you would like to have the HTML files directly in the event directory as well as in a subdirectory, you may use the “`config html_in_event_directory`” configuration option (this was default behaviour prior to version 3.170).

The formatting of the HTML file is controlled by a CSS stylesheet called “tsh.css” If you want to copy your report files to a remote web server, you must include a copy of this file in the same directory as your report files, or they will not be displayed correctly. tsh includes master versions of the stylesheet for various realms, and if there is no stylesheet in your HTML directory, it installs a copy of the appropriate one. Once it has done so, you may make your own local changes to it if you do not care for the default style, but if you think your changes might be of general use, please send them in for inclusion in the tsh distribution.

For the sake of backward compatibility and in case tsh is run on a computer without a web browser, reports are also saved in text format. If you do not want text files to clutter your event directory, use the “`config no_text_files`” configuration option.

## Player Photos

Some commands will display photographs to help identify players, if the “`config player_photos = 1`” configuration option is specified in your configuration file, and if you have one of the optional photo databases installed. These currently include: “`EnhancedScoreBoard`”. “`ShowPairings`” and “`ScoreBoard`”. Use the “`photo_database`” configuration option to choose a photo database, then keep it updated using the “`updatepix`” command. (This may take a while on a slow Internet connection.) Use the “`player_photo_aspect_ratio`” configuration option if your photos are not square. Databases are currently available for NASPA and ABSP players; tournament directors from outside those jurisdictions shoudl contact John Chew to set up their own databases.

## Pairings

Before each round begins, you need to print up pairings, showing who is playing whom where. If you are using Fontes Swiss pairings, these pairings will typically be available sometime in the middle of the preceding round, as soon as you have finished entering and checking the second preceding round’s results. You should post them as quickly as possible, so that anyone who finishes their game early will know right away who their next opponent is. Using this command will also generate pages of tally slips preprinted with player information, if you want to cut and distribute them to players.

The pairings for a given division and round may have already been computed (and will be displayed right away), may need to be computed (and will be displayed after a brief delay), or may not yet be computable (and you’ll see an error message if you ask for them, instructing you to enter more scores before asking for the pairings).

You show pairings using the “`ShowPairings round division`” command. To list pairings (e.g.) for round 5, division C, enter the command “`sp 5 c`”. (If you have only one division, you may omit it, so you’d enter “`sp 5`”.) As noted at the beginning of this section, this will display on your screen who is playing whom where, create two printable HTML files called “C-alpha-pairings-005.html” (in alphabetical order of player name, in a two-column format if tsh thinks it will look better that way) and “C-pairings-005.html” (by player rank), and one text file called “C-pairings.doc”.

Several configuration options affect pairings reports. Their effects are described in the following table.

Option | Effect | Usefulness
--- | --- | ---
alpha_pair_first_page_break | Specifies how many rows of pairings to print on the first page of alpha pairings. | Use this if you have an unusually tall header that appears at the top of your reports.
alpha_pair_page_break | Specifies how many rows of pairings to print on each page of alpha pairings. | Use this if you find that the default settings are causing the bottom rows of some pages to appear on their own on a separate sheet of paper.
alpha_pair_single_column | If set, forces alphabetical pairings to appear in single-column format. | You might want to use this, if you have very long player names, as is the case at the U.S. NSSC.
assign_firsts | If set, tsh will assign who goes first (starts) in each game, and will never suggest that players draw to see who does so. | It’s always a good idea to use this option, to protect players from error and fraud.
no_ranked_pairings | If set, prevents ranked pairings reports from being generated. | You might want to use this, if you only want alphabetical pairings and don't like cluttered directories on your disk.
no_index_tally_slips | If set, prevents tally slip files from cluttering your web index. | You might want to use this, if you don't like cluttered indices in your browser.
no_text_files | If set, prevents “.doc” files from being generated. | You might want to use this, if you don't like cluttered directories on your disk.
player_photos | If set, displays a photo of each player’s opponent, where one is available. | You should use this, if photos and a good printer are available.
player_photo_aspect_ratio | Specifies the width:height ratio of player photos, defaulting to 1. If your photo database consists of photos with a 3:4 ratio, set this to 0.75. | If you are using player photos and your images are not square, you must use this to keep the photos from being stretched.
track_firsts | If set, tsh will keep track of who goes first (starts) or goes second (replies) in each game, and display this information in pairings reports, suggesting that they draw tiles if it doesn not know who should start. | It’s always a good idea to use this option.

You may also use the “`ShowManyPairings r1-r2 division`” command to produce pairings reports for multiple rounds, similar to those used at the U.S. Open. This is particularly appropriate when you are pairing many rounds at a time, as for example in a round-robin tournament.

## Standings and Ratings Estimates

The “`RATings division`” command shows current standings with estimates of new (Elo/NASPA, Elo/NASPA-LCT or ABSP depending on the values of “`config rating_system`” and “`config division_rating_system`” ) player ratings. “`rat a`” will tell you what Division A ratings would be if the tournament ended right now. If the previous round’s results are available when this command is used, an extra column will show who went first against whom and the game score unless “`config no_show_last = 1`” was specified If the next round pairings are available when this command is used, an extra column will show each player’s next opponent. Specifying “`config standings_refresh`” will make the HTML versions of these reports refresh themselves in the browser. You should use this command when all the scores are in for a round, and print its report. Files are created as with pairings.

You can show standings from earlier rounds using the “`RoundRATings round division`” command. Entering “`rrat 3 c`” will give you the standings as of round 3 for division C. Using the “`RoundClassRATings round division`” command instead will group players by class, then rank, rather than just rank.

The now deprecated “`STandings division`” command does what the “`RATings`” command does, but without the ratings estimates, and is kept largely for use at nonrated events. Entering “`st c`” will give you the current standings for Division C. Files are created as with pairings. You can show standings from earlier rounds using the “`RoundStandings round division`” command. Entering “`rs 4 d`” will give you the standings as of round 4 for division D.

If you used the “`classes`” configuration command, then the class to which each player belongs will be shown in standings and ratings reports.

If you need more precise control over which fields (columns) are shown in the rating and standings reports discussed above, you can list the fields you want using the “`rating_fields`” configuration option. If you do not, the following fields will be displayed.

Field Name | Description
--- | ---
rank | Current rank in standings
wl | Win-loss record. Not shown if no pairing system is in effect; i.e., for solo events.
scoresum | Sum of scores. Shown if the “`sum_before_spread`” configuration option is set.
spread | Cumulative spread. Not shown if the “`scores`” configuration option is set to “`'WL'`” or “`'WLT'`”.
thaipoints | Thai handicapped game points: 2 for a win, 1 for a tie, 0 for a loss, plus handicap values. Shown if the “`thai_points`” configuration option is set.
orat | Pretournament rating. Shown in ratings reports, but not in standings reports.
nrat | Estimated current post-tournament rating. Shown in ratings reports, but not in standings reports.
drat | Estimated current tournament rating change. Shown in ratings reports, but not in standings reports.
class | Class. Shown if the division appears to have classes configured.
name | Name. configured.
last | Previous game outcome. Not shown if no pairing system is in effect; i.e., for solo events. Also not shown in the first round of an event, because there would be no previous game.
next | Next game pairing information. Not shown if the next round has not yet been paired.

If you are using the “`team`” extension field in your “.t” file, you can use the “`TeamStandings division`” command to list team standings. If your teams are competing based on their aggregate performance across all divisions, you should use the “`TotalTeamStandings`” command.

(Deprecated) If you have a spare computer or external monitor, you can use the “`hook_addscore_flush`” and “`hook_autopair`” configuration options to automatically trigger the “`ScoreBoard`” command, which can show players up-to-the-minute scores and pairings information and act as a virtual replacement for paper wall charts.

The “`EnhancedScoreBoard`” command generates a display that is superficially similar to the now deprecated “`ScoreBoard`” command’s display, but differs substantially in its implementation and features. To use it, you must currently run the command once from the command line at the beginning of your event. This sets up a web page for your players, containing AJAX code that periodically fetches tournament results from your web server. (Note that to use this command, you must be serving your web pages from a web server, not just straight from your file system as is possible with many operating systems.) You should use the “`hook_addscore_flush`” and “`hook_autopair`” configuration options to trigger the “`saveJSON`” command, which saves a division's entire state in a form that can be read by the enhanced scoreboard. The main advantages of using the enhanced scoreboard are that there is less load on the web server, and users can browse the history of the tournament round by round, even after the event is over. You can also use it with the “`setESBMeSsaGe`” command to display announcements for players. Use the “`config esb_geometry`” configuration option to specify default numbers of rows, columns, and rank offset for each enhanced scoreboard.

## Ratings Data Submission

tsh creates ratings data files in three different formats, depending on which rating system you will be submitting your data to.

### NASPA Ratings

There are two ways to submit ratings data to the NASPA. The much easier way is to connect to the Internet, then enter the “`SUBMIT`” command. In order to use this command, you must correctly set the configuration parameters “`director_id`”, and “`tournament_id`” as in the following example:

    # This line gives your NASPA ID
    config director_id = "CM000003"
    # This line gives your NASPA tournament number (ask John Chew if you don't know how to get it)
    config tournament_id = 123

If you cannot directly connect your tsh machine to the Internet, try running the “`SUBMIT`” command anyway. This will create a file called “all.tsh” in your event directory, which you may upload through the Member services section of the NASPA website.

Use the “`config ratings_note`” configuration option if you want to include a note about the event for the rating officer. Use the “`director_name`” and “`event_name`” configuration options to include the director’s and event’s names for the historical record.

### ABSP Ratings

The “`ABSPgrid`” command generates a ratings grid for submission to the ABSP. The grid will be saved as a text file called “abspgrid.doc” in your event directory.

### AUPAIR Ratings

The “`AUPAIR`” command generates a “.TOU” file in the format used by the “AUPAIR.EXE” program. The file is not displayed on the screen. “AUPAIR.EXE” is used by Bob Jackman and his WESPA Rating System, and by many countries in southeast Asia.

## Prizes and Statistics

The “`PRiZes`” command generates a table listing all the prizes that you will be awarding, with the current leading candidate for each. To use it, you will need to add prize declarations to your configuration file, and you should print or preview a sample report after a dry run to check for completeness and correctness.

You can show standings based on a range of rounds using the “`ResultsByRound firstround-lastround division`” command. Entering “`rbr 1-7 b`” will give you the standings based on the first seven rounds for Division B. Files are created as with pairings.

The “`HighWin count division`”, “`HighLoss count division`”, “`HighCombined count division`”, “`HighSpread count division`”, “`LowWin count division`”, “`LowLoss count division`”, “`LowCombined count division`” and “`LowSpread count division`” commands list players who have excelled in each of those categories. For example, “`hw 20 a`” lists the top twenty game scores in division A, the rounds in which they took place, the losing score and the names of the players involved.

The “`HighRoundWins roundrange division`” and “`HighRoundLosses roundrange division`” commands list the players who have scored the highest wins or losses respectively in each round in a designated range. For example, “`hrl 2-5 b`” lists the high losing play in Division B in each round from Round 2 to Round 5.

The “`AVErages division`” commands lists average scores for all players in the given division. For example, “`ave d`” lists average scores for all players in division D.

The “`AverageOpponentScores division`” commands lists average scores for all players in the given division. For example, “`aos c`” lists average opponent scores for all players in division C.

The “`TOTalScore division`” commands lists total scores for all players in the given division. For example, “`ave d`” lists average scores for all players in division D.

The “`STATisticS`” commands lists summary statistics for each division in the tournament. For example, “`stats`” lists stats such as the minimum, mean, median and maximum rating in each division, the percentage of time the higher-rated or starting player won, etc. It also invokes most of the other commands in this section to update the web versions of the reports. Suggestions for additional statistics are very welcome.

There is a command for computing NASPA’s “Tuff Luck” prize based on the lowest total of six losing spreads: “`tuff 6 a`” lists the “Tuff Luck” standings for Division A. The opposite of this command is the “`luckySTIFF`” command, which lists players based on the sum of their closest winning spreads: “`stiff 3 b`” lists those players in Division B who have won three games by the smallest combined spread.

If you run a U.S.-style rotisserie pool, you can use the rotofile configuration option to specify the location of a text file giving the structure of that pool, then use the “`ROTO`” command to display current standings. Each team is represented by a list of names, followed by a blank line. The team owner’s name is preceded by the word “`owner`” and a space, each team member’s name is preceded by the word “`player`” and a space.

If you run a U.K.-style rotisserie pool, you can use the spitfile configuration option to specify the location of a text file giving the structure of that pool, then use the “`SPITroast`” command to display current standings. Each line in the text file consists of all the player numbers in the division in the order in which a team owner expects them to finish, a semicolon, the team owner’s name, a semicolon, and the team name. Team names must be unique.

The “`UPSETs`” command lists the top twenty ratings upsets: games in which a significant ratings underdog managed to win. The “`HighRatingChanges`” command lists players whose rating has increased by the largest amount.

## Checking Scorecards and Wall Charts

tsh includes commands for producing electronic versions of player scorecards and tournament wall charts. These were originally intended to allow you to check these documents and correct your data. As of 2005, the only official version of NSA/NASPA tournament results is deemed to be the data that you entered from the result slips, so these commands should be used only to point out and explain errors in the printed documents, or to replace a lost scorecard at a player’s request.

You may wish to recheck your data entry in the middle of each round. To facilitate your doing so, the “`CheckRoundScores round division`” will list what has been entered for each game. Entering “`crs 3 h`” will list scores for Round 3 in Division H. A file called “H-scores-003.html” will be created, which can be printed and given to a checker to work offline with the result slips.

You can show a scorecard using the “`ShowscoreCard division player`” command. Entering “`sc j 5`” will give you the scorecard for player J5. A file called “J-scorecard.html” will be created, which can be printed and given to a player who has lost their original scorecard. Scorecards are also displayed whenever you use the “`EditScores`” command. When a score has been added to a scorecard within the last two hours, the age of that modification in minutes is shown at the top of the card. This is to help determine whether an absent player may be away taking a break from a game that ran unusually late.

You can generate an HTML file containing all scorecards for a division with the “`ShowDivisionScoreCards division`” command. Entering “`sdsc a`” will create a file called “A-scorecard.html” containing the scorecards for all players, which can be printed and given to players at the beginning of the tournament. This is particularly useful when most or all of the pairings are predetermined, as for example in a round robin schedule. Depending on the length of your tournament, you may need to edit the CSS stylesheet to make the scorecards fit nicely on each page.

You can show a wallchart using the “`showWallChart division`” or “`showRankedWallChart division`” commands. Entering “`wc g`” will give you the wall chart for division G. Typing a round number before the division name will start the wall chart at that round, in case your wall chart would otherwise be too wide to print nicely. Files are created as with pairings; the HTML version includes much more information than can fit into the text or screen versions.

If you need a printed list of all the players with their player numbers and ratings, use the “`ROSTERS`” command. By default, they'll be listed by rank, unless you specify the “`config roster_order`” configuration option.

# Installing tsh

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

## 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. | Go to the ActiveState website, then navigate through the following (at time of writing, and please submit corrections when the website changes): Languages -> ActivePerl -> Download Now -> Download ActivePerl 5.16.3 for Windows (x86) (or possibly the similar 64-bit version, see Microsoft if unsure). When you have downloaded and run the install, restart your machine. | 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.

## 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 called “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.

# Configuring tsh

How to set up tsh for your particular tournament.

After you’ve installed tsh, you need to set up a subfolder (directory) of your tsh folder containing a configuration file (“config.tsh”, formerly known as “tsh.config”) describing your tournament, and one (“.t”) data file for each division. You can run as many tournaments as you like with one installation of tsh, but each one should have its own folder.

## About The “config.tsh” file

You need to have a text file called “config.tsh” in your tournament folder/directory. You can ask me (John Chew, poslfit@gmail.com) to create one for you if you give me a few weeks’ notice. There are also a few sample tournaments that come with the tsh distribution, and you can try modifying one of their configuration files to make your own.

Your configuration file consists of a sequence of lines. The order of the lines sometimes matters: you may run into trouble if you try to specify the properties of a division before you declare its existence. The first word on a line determines its type, of which there are currently eight:

- comment
- division declaration
- class declaration
- configuration option
- automatic pairing instructions
- prize declaration
- encoding directive
- Perl command

Note that the lines that appear in a configuration file are not regular tsh commands. Here is a very short sample “config.tsh” file.

    # This is a comment because it starts with a '#'.
    # The next line that you will store the data for Division a in file a.t.
    division a a.t
    # The next line says that the division has 3 prize classes
    classes a 3
    # The next line says that you want to keep track of 1sts/2nds (starts/replies)
    config track_firsts = 1
    # The next line says that Division A will play a simple round robin
    autopair a 0 1 rr a
    # The next line says that 1st place in Division A wins $25,000.
    prize rank 1 A $25000
    # The next line demonstrates the 'perl' command
    perl print "Hello, world\n";

The following subsections discuss each type of line in detail.

### Comments

Comments begin with a ‘`#`’.

You may add as many comments as you like to your configuration file, and it’s a good idea to be verbose so that the next person who runs your tournament for you will know what you were thinking.

### Division Declarations

Your configuration file must contain at least one division declaration, beginning with the word ‘`division`’, then followed by a space, a case-insensitive division name, another space, and a filename. Division declarations must come before any other reference to a division in a configuration line. Filenames may or may not be case-sensitive depending on your operating system. You may have as many divisions as you like, but each one has to have its own division name and file name. All divisions should play the same number of rounds at roughly the same schedule; if not, you should set up separate directories and configuration files for differently scheduled divisions, and run separate copies of tsh.

In a multi-division event, you should keep the division name short, as it will appear beside player numbers and you will need to type it to specify divisions. If you want a longer version of the name for display purposes, use the “`config division_name`” configuration option.

If you have only one division in your tournament, it does not matter what you name it, and you won’t ever have to type its name. Except: if you give your only division a name that could also be a player number, some commands may get confused if you don't type the division name, so use alphabetical division names where possible. If you have more than one division, you should keep your division names short as you will be typing them frequently.

### Class Declarations

Your configuration file may contain one or more class declarations, beginning with the word ‘`classes`’, then followed by a space, a case-insensitive division name, another space, and an integer greater than 1. Classes are typically used to award prizes to deserving lower-ranked players in a division.

If you specify how many classes a division has, then players will be assigned to equal-sized classes according to their pretournament ranking. Classes are named ‘A’, ‘B’, ‘C’... and are listed in the ratings and standings reports. This assignment takes place each time you run tsh: if you change player ratings, it may change player classes.

You can instead manually assign players to classes in the “.t” file using the “`class`” extension field, which you might want to do if labelling players in a particular group for use with the gibson_class configuration option to restrict opponents of Gibsonized players to members of one class.

### Configuration Options

There are a large number of configuration options that you can set using lines beginning with the “`config`” keyword. All configuration options are at least theoretically optional, because they either have reasonable default values (which may depend on your configuration realm, or not required by all commands (a notable counterexample is the “`max_rounds`” option, which tells tsh how many rounds long your tournament is, and which is therefore required for the proper functioning of several pairing commands.

Here are all currently available configuration options:

Option | Example | Description
--- | --- | ---
allow_gaps | allow_gaps = 1 | tsh usually assumes that each player plays their games in chronological order, round by round. If this is not the case, you can specify this option, but be warned that this will cause most pairing and report commands to fail.
alpha_pair_first_page_break | alpha_pair_first_page_break = 14 | tsh will force a page break after this many rows (defaulting to the value of “`config alpha_pair_page_break`”) are shown on the first page of two-column alpha pairings.
alpha_pair_page_break | alpha_pair_page_break = 15 | tsh will force a page break after this many rows (defaulting to 10) are shown in two-column alpha pairings. If you choose a value that is too small, then some rows may be split across pages and hard to read.
alpha_pair_single_column | alpha_pair_single_column = 1 | If set, will always show alphabetic pairings in a single column, even when there are a large number of them.
assign_firsts | assign_firsts = 1 | Have tsh randomly determine who goes first when players would otherwise have to draw.
autopair |  | Set using the `autopair` instruction. It’s not a good idea to mess with this directly.
auto_koth_repeats | auto_koth_repeats = 2 | If set, then KOTH pairings induced by “`config force_koth`” have the specified number of maximum repeats, rather than an unlimited number.
avoid_sr_runs | avoid_sr_runs = 1 | If set, try to assigning a player too many consecutive starts (1sts) or replies (2nds) when pairing a win group. Does not currently work with round robin pairings, which are carefully arranged to make players balance in the end.
backup_directory | backup_directory = './notold/' | Override the default “./old/” as a place to keep journalled “.t” files. Must end with a “/” or other locally appropriate path separator.
board_stability | board_stability = 1 | If set to `1`, try to keep one of the two players in each game at the same board in the next round during sessions (if you do not specify “`config session_breaks`” the entire tournament is treated as a single session). If not set, boards will be reassigned each round to place high-ranked players at low-numbered boards.
bracket_order | bracket_order = 'id' | If set to `id`, bracket_pairings will be seeded by player number; if `rating`, by pretournament rating.
bracket_prelims | bracket_prelims = 3 | Specifies a number of rounds of “`InitFontes`” pairings to precede any bracket pairings.
bracket_repeats | bracket_repeats = 3 | Specifies the number of times each pairing will repeat within a stage of bracket_pairings.
bye_firsts | bye_firsts = 'ignore' | If set to “`'alternate'`”, the default value, use the rule the NSA adopted on 2008-07-24 to assign alternating firsts and seconds to players who have forfeit losses. If set to “`'ignore'`”, ignore assign firsts and seconds when necessary by comparing firsts, then comparing seconds, and ignoring byes and forfeits.
bye_spread | bye_spread = 75 | Sets the number of points of spread awarded to a player who is assigned a bye. You should probably adjust the value of “`realm`” rather than change this directly; contact John Chew if this is not possible.
check_by_winner | check_by_winner = 1 | Instructs the “`CheckRoundScores`” command to sort rows by winning player rather than starting player.
chew_no_swiss_all | chew_no_swiss_all = 1 | Instructs the “`ChewPair`” command not to pair everyone Swiss when all as yet unpaired players are still contenders.
colour | colour = 'no' | Enables use of ANSI colour escape sequences to highlight text in the tsh session.
colour = 'yes'
count_good_words | count_good_words = 1 | If specified, the LOOK command will report how many good words were challenged, for penalty calculation purposes.
cross_tables_id | cross_tables_id = 12345 | Identifies the cross-tables.com ID for this tournament.
csv_encoding | csv_encoding = 'utf8' | Specifies a file encoding for CSV files manipulated using the “LoadplayersCsV”, “MergeplayersCsV” and “SaveplayersCsV” commands.
currency_symbol | currency_symbol = '£' | Specifies the currency symbol to be used with monetary values. Defaults to the dollar sign.
custom_stylesheet | custom_stylesheet = 'local.css' | Specifies a custom stylesheet to be loaded after the default CSS stylesheet.
director_id | director_id = "CM000003" | Used to identify a NASPA tournament director when submitting ratings data.
director_name | director_name = "John Chew" | Used to identify the tournament director.
director_password | director_password = "friend" | (Deprecated) Specifies director’s password for use with “`SUBMIT`
division_name | division_name{'A'} = 'Expert' | Override a division’s default name given in its division declaration.
division_rating_list | division_rating_list{'C'} = 'naspa-csw' | Overrides “`rating_list`” on a per-division basis.
division_rating_system | division_rating_system{'C'} = 'none' | Overrides “`rating_system`” on a per-division basis.
entry | entry = "spread" | Used to specify data entry mode. Default value is “`'scores'`”, where you enter scores; other common permitted values are “`'spread'`” (enter only the difference between scores) and “`'both'`” (enter both scores and spread). Less common values are “`'board'`”, “`'sudoku'`”, and “`'tagged'`”.
entry_pairing | entry_pairing = 1 | If specified, changes the behaviour of the “`Addscore`” command so that when presented with scores for unpaired players, it assumes that they played each other. Use with caution, as it prevents TSH from doing an important part of its normal data entry validation.
entry_tags | entry_tags = {'c'=>'csw', 'csw'=>'csw', 't'=>'twl', 'twl'=>'twl'} | Specifies accepted tags and synonyms for tagged data entry with the “`Addscore`” command.
esb_geometry | esb_geometry{'A'} = [[5,6,0],[5,4,30]] | Specifies a series of default geometry values for a given division’s enhanced scoreboard. Each triple specifies one scoreboard; within each triple the first number is the number of columns, the second the number of rows, the third the offset from top rank.
event_date | event_date = "September 30, 2005" | Used to specify the event date, particularly when submitting ratings data.
event_name | event_name = "Toronto 2005" | Used to identify the event, particularly when submitting ratings data.
exagony | exagony = 1 | If used, prevents players from the same team from facing each other. See also the list of commands compatible with this option and the “`team`” extension field.
exagony = [1,2,3] | If used, prevents players from the same team from facing each other in specified rounds. See also the list of commands compatible with this option and the “`team`” extension field.
external_path | external_path = ['./bin','../bin'] | Used to specify where external commands can be found. Default value is ['./bin'].
fat_tweets | fat_tweets = 1 | If enabled, the “`TWEET`” command sends more detailed social media reports not restricted to 140 characters. Use this if posting say to Facebook rather than to Twitter.
final_draw | final_draw = 1 | If used, players will be instructed to draw to see who starts (plays first) in the final round if their start/reply records are equal, even if firsts and seconds are otherwise being assigned.
flight_cap | flight_cap = 'TSH::PairingCommand::FlightCapNSC' | Lets you override the default algorithm for capping the number of players who can be considered in contention when using the Chew pairing algorithm. Talk to John Chew if you need to adjust this. The example given is suitable for a tournament which is used to select two finalists. This parameter is also used in estimating pairings flights when choosing an opponent for a Gibsonized player.
flight_cap = [12,12,8,4] | Lets you override the default algorithm for capping the number of players who can be considered in contention when using the Chew pairing algorithm. Talk to John Chew if you need to adjust this. The example given is suitable for a tournament which is used to select two finalists. This parameter is also used in estimating pairings flights when choosing an opponent for a Gibsonized player.
force_koth | force_koth = 1 | When using default pairings (not autopair), makes the last round be KOTH with unlimited repeats (unless overridden by “`config auto_koth_repeats`”), rather than Chew pairings. If a number of rounds greater than 1 is specified, then that number of round of KOTH pairings are used.
ftp_host | ftp_host = 'www.poslfit.com' | Required when using the “`mirror-ftp`” utility command, and specifies the FTP server to which events should be uploaded.
ftp_password | ftp_username = 'jamie' | Required when using the “`mirror-ftp`” utility command, and specifies the password with which to log onto the FTP server.
ftp_path | ftp_path = 'www/myevents' | Required when using the “`mirror-ftp`” utility command, and specifies the path on the FTP server to which events should be uploaded. An event subdirectory will be created within the designated directory.
ftp_username | ftp_username = 'john' | Required when using the “`mirror-ftp`” utility command, and specifies the username with which to log onto the FTP server.
gibson | gibson = 1 | Enable automatic detection of Gibson situations. When using default or Chew pairings, tsh always looks for possible Gibson situations. When using automatic pairings, tsh does or does not check depending on the value of this option.
gibson | gibson = 'strict' | Behaves as per “`config gibson = 1`” and in addition pairs Gibson with the highest-ranked player out of contention, regardless of repeats.
gibson_class | gibson_class = 'A' | Requires that opponents of Gibsonized players must belong to the named class. Use this option at events where some players may be competing for a special prize, such as qualification to another event, and should not be paired with Gibsonized players.
gibson_groups | gibson_groups{'A'} = [[1,2]] | Indicates final ranks that are to be considered equivalent when testing for Gibsonization. Works only with Chew pairings. If not specified, each final rank is considered to be of different value to a player. The example given should be used where the current event is a preliminary to qualify players for a two-player final match and it doesn’t matter whether a player finishes first or second. In the unlikely event that you wanted to have players ranked 3 through 6 compete in a separate final match, you could specify the value “`[[1,2],[3,4,5,6]]`”.
gibson_spread | gibson_spread = [250,175,150] | Overrides the default spread thresholds for Gibsonization. The nth value from the end gives the maximum spread by which a player may win a game in the nth last round; for earlier rounds, the maximum spread is given by the first value.
hook_addscore_flush | hook_addscore_flush = 'sb a;sb b;sb c;sb d' | Gives one or more semicolon-separated commands to be executed whenever the “`Addscore`” command updates score data.
hook_addscore_flush = 'json a;json b;json c;json d'
hook_autopair | hook_autopair = 'sb a;sb b;sb c;sb d' | Gives one or more semicolon-separated commands to be executed whenever pairings are automatically computed.
hook_autopair = 'json a;json b;json c;json d'
hook_division_complete | hook_division_complete{'A'} = 'tweet a 1 2' | Gives one or more semicolon-separated commands to be executed whenever the last scores have been entered for a division in a round. In the command text, the strings ‘$d’ and ‘$r’ are replaced respectively by the division and round number that have just completed.
hook_division_update | hook_division_update = 'tweet a 1 2' | Gives one or more semicolon-separated commands to be executed whenever a division data file is updated.
html_directory | html_directory = '/Library/WebServer/Documents/myevent/tsh/' | Override the default “./html/” as a place to keep round-by-round “.html” reports. Must end with a “/” or other locally appropriate path separator. The example given places reports on the local machine’s public web server under OS/X.
html_in_event_directory | html_in_event_directory = 1 | Stores an extra copy of printable HTML reports directly in the event directory, where they may be easy to find, but may cause clutter. Note that player photos will not be correctly linked in event directory web pages unless you manually copy the photo directory into the event directory as well.
html_bottom | html_bottom = '<p align=center><a href="event url"><img src="event logo"></a></p>' | If defined, appears at the bottom of each HTML page.
html_index_bottom | html_index_bottom = '<p align=center><a href="event url"><img src="event logo"></a></p>' | If defined, appears at the bottom of the event HTML index, overriding the value of “`config html_bottom`”, if any.
html_index_recent_first | html_index_recent_first = 1 | If set, the event HTML index lists recent (later) rounds higher on the page, for easier viewing of large indexes on small screens.
html_index_top | html_index_top = '<p align=center><a href="event url"><img src="event logo"></a></p>' | If defined, appears between the body and h1 tags at the top of the event HTML index, overriding the value of “`config html_top`”, if any.
html_suffix | html_suffix = '.shtml' | Overrides the default “.html” suffix (filename extension) appended to generated filenames.
html_top | html_top = '<p align=center><a href="event url"><img src="event logo"></a></p>' | If defined, appears between the body and h1 tags at the top of each HTML page.
index_top_extras | index_top_extras = { 'Live Coverage' => 'http://wherever.com' | If used, specifies additional entries to appear in the top section of the web coverage index.
initial_exagony | initial_exagony = 1 | If used, prevents players from the same team from facing each other in first-round random pairings. See also the “`team`” extension field.
initial_random | initial_random = 1 | When using Chew pairings either explicitly or as the default pairing algorithm, specifies one initial round of random pairings, as required at the WSC.
initial_schedule | initial_schedule = 3 | When using Chew pairings either explicitly or as the default pairing algorithm, it is often useful to start with a semirandomized fixed schedule generated by the InitFontes command. This parameter (which defaults to zero) specifies the number of rounds that that schedule should run.
initial_snaked | initial_snaked = 1 | If set, the “`InitFontes`” command assigns players to pairings groups in boustrophedonic order rather than randomly.
interleave_rr | interleave_rr = 1 | If set, the “`RoundRobin`” pairing command will add all rounds of a round robin before beginning the next round robin, rather than adding all of a player’s games with a given opponent before moving on to the next opponent.
locale | locale = 'no_NO' | Specify a standard locale code to be used by internationalization code in the Perl interpreter or the operating system.
manual_pairings | manual_pairings = 1 | Use neither auto-pairings even if configured, nor Chew pairings in the absence of auto-pairings. Deprecated in favour of “`pairing_system = 'manual'`”.
max_div_rounds | max_div_rounds{'A'} = 12 | Like “`config max_rounds`” but applies only to one division. If you only specify the maximum number of rounds in some divisions, the largest value you give is assumed for the rest.
max_rounds | max_rounds = 12 | Specify the last round in the tournament. Used in Gibson detection, and to check for illegal round numbers in commands.
message_encoding | message_encoding = 'utf8' | Specify a character encoding for ‘.t’ files other than the default ‘isolatin1’.
message_file | message_file = 'lib/messages/deu.txt' | Specify an alternate file containing the text messages displayed by tsh. Normally this is determined based on your realm.
mirror_directories | mirror_directories = [qw(c:\dir\subdir /tmp/copy)] | If specified, instructs tsh to keep a copy of all data and report files in the given locations.
next_round_style | next_round_style = 'brief' | Changes the style of the next-round pairing data shown at the end of ratings reports from the default 'nextrat' to one of: 'normal', 'half', 'balanced', 'brief' or 'nextrat'.
no_aupair_bye_ties | no_aupair_bye_ties = 1 | Omit byes and forfeits in AUPAIR rating data reports, rather than using standard notation. Not required with modern rating software.
no_boards | no_boards = 1 | Do not show board numbers anywhere. If set to 0, show board numbers even where they would not normally be shown; e.g., where table numbers have already been shown.
nohistory | nohistory = 1 | Used internally to prevent commands triggered by hooks from affecting the page to be displayed by “`BrowseLast`”.
no_index_tally_slips | no_index_tally_slips = 1 | The “`ShowPairings`” command will generate tally slips as usual, but they will not appear in the web index.
no_initial_rr | no_initial_rr = 1 | Do not start default pairings with a round robin, even if there is room to do so.
no_random | no_random = 1 | If set, do not use random tie-breaks for players tied in standings, use pre-tournament rating or player number instead.
no_ranked_pairings | no_ranked_pairings = 1 | Do not show ranked pairings in “`ShowPairings`”, only alphabetical ones.
no_show_last | no_show_last = 1 | Do not show information about the last round’s results in “`RoundRATings`” or “`RATings`”. Use if you find the information too cluttered or hard to understand.
no_text_files | no_text_files = 1 | Do not create text versions of reports. Useful if you only want HTML files, and don’t want your directories cluttered with text files.
oppless_spread | oppless_spread = 1 | Do not consider opponent scores in spread calculations, just some player’s own scores.
pairing_system | `pairing_system = 'auto'` | You do not need to explicitly specify the use of automatic pairings; they are selected if you include an “`autopair`” instruction in your configuration file.
`pairing_system = 'basd'` | BASD pairings pair players in a byzantine format developed by Ira Freehof for his Big Apple Showdown.
`pairing_system = 'bracket'` | Bracket pairings pair players in single-elimination format, seeded initially according to the value of the “`bracket_order`” configuration option and repeating each pairing a number of times specified by “`bracket_repeats`” configuration option, preceded optionally by a number of rounds of “`InitFontes`” pairings specified by the “`bracket_prelims`” configuration option.
`pairing_system = 'chew'` | You do not need to explicitly specify the use of Chew pairings; they are selected by default.
`pairing_system = 'green'` | Green pairings are used by John Green in Florida to pair groups of six to eight players using a fixed five-round schedule followed by a KOTH.
`pairing_system = 'guelph'` | Guelph pairings are used by Andy Saunders in Guelph, ON, CAN to pair six, eight or ten players in a six-round schedule.
`pairing_system = 'manual'` | You should explicitly specify the use of manual pairings if you do not want tsh to provide default pairings.
`pairing_system = 'nast'` | You should use NAST pairings if you are directing a satellite event of the North American Scrabble Tour, which has specific requirements for the pairings of such events. The exact system depends on the number of players in the tournament, and consists of either four rounds of fixed pairings and one round of Swiss pairings or five rounds of fixed pairings, followed by one round of KOTH pairings.
`pairing_system = 'none'` | Although tsh began as a program for generating pairings and reports, it can also be used at events like crossword or Sudoku tournaments, where players compete separately to attain individual scores. No pairings are generated or displayed, but standings reports and web features are available.
pair_page_break | pair_page_break = 15 | If this option is specified, tsh will force a page break after this many rows are shown in rank-ordered (not alpha) pairings. If this option is not used, player names may be split across page breaks.
pairings_refresh | pairings_refresh = 10 | If specified, HTML pairings reports will refresh themselves in web browsers at intervals of this many seconds.
photo_database | photo_database = 'nsa' | Choose a photo database. Currently available databases are ‘`nsa`’ and ‘`centrestar`’.
player_id_first | player_id_first = 1 | If enabled, display player IDs ahead of names.
player_number_format | player_number_format = "#%s" | Specify sprintf(3) formatting of player numbers. By default, a ‘#’ is prepended to the number for clarity if there is only one division.
player_photo_aspect_ratio | player_photo_aspect_ratio = 0.75 | Gives the ratio of player photo widths to heights (all photos must use the same value).
player_photos | player_photos = 1 | If specified, display photos of opponents in alpha pairings reports.
port | port = 7777 | If this is set to a nonzero value, tsh will use its web interface instead of its command-line interface. Still in early development and incomplete but feel free to see what is there so far.
prize_bands | prize_bands{'A'} = [2,3,4,5] | Specifies which final ranks are to be considered equivalent for pairings purposes: the numbers given mark the end of each band (range) of equivalent prizes (ranks). Only used in scoreboard displays and in Chew pairings, which try to pair players who are in contention for one prize band with each other. In the example, the top prize band goes from 1st place to 2nd place (presumably because the top two finalists qualify for a playoff); each of 3rd, 4th and 5th place is its own prize band (presumably awarding players cash prizes); and everything from 6th place on is the last prize band (presumably winning nothing). If this option is omitted when required, a warning is displayed and a default value is assigned which assumes prizes are assigned to the top quarter of the division. Note that Gibsonization won’t work with a value of “`[1]`”, because the “highest ranked player out of contention for prize money” that the Gibsonized player ought to play ends up being the second-ranked player.
prizes |  | Set using the “`prizes`” instruction. It’s not a good idea to mess with this directly.
random_rr_order | random_rr_order = 1 | Arrange the rounds of a round robin in random order, rather than presenting the top seed with opponents of increasing strength.
rating_fields | fields = [qw(rank newr name team)] | If you need complete flexibility in configuring which fields are listed in the output of the “`RATings`” and “`RoundRATings`” commands, you can list them here. See the description of Standings and Ratings reports for a list of permitted fields.
rating_list | rating_list = 'deu' | If set to “`deu`”, the “`UPDATERATINGS`” command will fetch the German rating list and not the NSA one.
rating_system | rating_system = 'absp' | Computes ABSP ratings wherever ratings are needed. This parameter must be set to this or one of the following values when using the “`SUBMIT`” command.
rating_system = 'aus' | Computes Australian ratings wherever ratings are needed.
rating_system = 'elo' | Computes Elo ratings without traditional NSA bugs wherever ratings are needed.
rating_system = 'none' | Prevents ratings from being calculated or displayed.
rating_system = 'nsa' | Computes oldstyle NSA ratings wherever ratings are needed.
rating_system = 'nsa lct' | Computes oldstyle NSA ratings for a local club tournament wherever ratings are needed.
rating_system = 'naspa' | Computes NASPA ratings wherever ratings are needed. This is the default value but may be implicitly overridden by a “`realm`”. Synonymous for historical reasons with the value “`'nsa2008'`”.
rating_system = 'naspa lct' | Computes NASPA ratings for a local club tournament wherever ratings are needed. Synonymous for historical reasons with the value “`'nsa2008 lct'`”
rating_system = 'wespa' | Computes WESPA ratings wherever ratings are needed.
ratings_note | ratings_note = "Please rate this after the early bird." | Specifies a note to include when submitting ratings data.
realm | realm = 'nsa' | Specifies default values for several parameters, as explained in the section on configuration realms.
reserved | reserved{'P'}[13] = 4 | Permanently assigns player P13 to board 4. Typically used when you have a player with special needs.
rotofile | rotofile = 'roto.txt' | Specify the name of a rotisserie pool file to be used in producing U.S.-style rotisserie pool reports.
roster_order | roster_order = 'alpha' | Specify the order in which players will be listed in the “`ROSTERS`” command: “`'alpha'`” (alphabetically), “`'rank'`” (by rank) or “`'team'`” (by team).
round_robin_order | round_robin_order = [4,9,8,7,6,5,10,3,2] | Specify the order of player 1’s round robin opponents, or the order in which players are assigned to the schedule by the “`TeamRoundRobin`” command.
save_interval | save_interval = 10 | Specifies how often results should be saved to disk in “`Addscore`”. Defaults to every ten new entries.
scoreboard_teams | scoreboard_teams = 1 | Show team flags in the enhanced scoreboard.
scorecards_refresh | scorecards_refresh = 15 | Specifies an integer interval in seconds at which scorecard webpages should refresh in the browser.
scores | scores = 'scrabble' | If set to “`'WL'`”, spread is ignored, and only wins and losses count. If set to “`'WLT'`”, spread is ignored, and only wins, losses and ties count. With the default value of “`'scrabble'`”, game results are understood to be a pair of integer scores, with win/loss/tie outcome based on their difference.
seats | seats = 1 | Enables display and tracking of seat numbers, for realms where seats are numbered instead of boards or tables.
session_breaks | session_breaks = [3,6,8,11,12] | Specifies after which rounds there is enough time in the schedule to wait for all results to come in before computing pairings. Used when the “`ChewPair`” is automatically invoked.
show_divname | show_divname = 1 | Show division names in report headings even when you have only one division. Use this if you have to split a tournament into different tsh events because you have more than one computer for data entry, but you want to be able to tell which reports came from which division.
show_honourable_mention | show_honourable_mention = 1 | If specified, the “`PRiZes`” command will list with honourable mention the additional prizes that a player would have won, were they eligible to earn more than one exclusive prize.
show_inactive | show_inactive = 1 | Normally, inactive players are not displayed in reports. Select this option to include them, for example if you had a player leave early who shoud still be listed in the final standings.
show_last_player_name | show_last_player_name = 1 | When displaying ratings reports, show the last player's name if known, and not just player number.
show_teams | show_teams = 1 | Show team names with player names.
sort_by_first_name | sort_by_first_name = 1 | Sort players by first name (when names are being presented in “given_names surnames” order).
spitfile | spitfile{'A'} = 'spita.txt' | Specify the name of a rotisserie pool file to be used in producing U.K. rotisserie pool reports for a given division.
split1 | split1 = 9 | Specifies after which round a long tournament should be split-rated when using Elo ratings. (This option is no longer needed, and is therefore deprecated.)
spread_cap | spread_cap = 350 | Specifies the maximum earnable spread in each round, for use in Thailand.
spread_cap = [350, 250, 100] | Specifies different values for maximum earnable spread in each round.
standings_hotlink | standings_hotlink = 1 | If enabled, player names in standings link to player scorecards.
standings_refresh | standings_refresh = 10 | If specified, HTML standings and ratings estimate reports will refresh themselves in web browsers at intervals of this many seconds.
standings_spread_cap | standings_spread_cap = [100, 150, 250, 250, 250, 250] | Specifies the maximum earnable spread in each round, for standings purposes but not pairings purposes, for use at the U.S. NSSC.
standings_with_ratings | standings_with_ratings = 1 | If enabled, ratings are displayed even in standings reports.
sum_before_spread | sum_before_spread = 1 | If specified, players should be ranked on W-L, then total points scored, then spread.
surname_last | surname_last = 1 | If specified, raw names of the form ‘surnames, given names’ in ‘.t’ files are translated to ‘given names surnames’ whenever displayed.
swiss_order | swiss_order = ['auto','koth','forced'] | Specifies how players are paired within Swiss-paired win groups in each round. If fewer values are specified than there are rounds, then the last value is repeated as necessary to fill out the event. Acceptable values are “`'auto'`” (do whatever TSH thinks is appropriate), “`'forced'`” (always pair the top half in order against the bottom half, disregarding things like firsts and seconds), and “`'koth'`” (minimize rank distance between opponents).
table_format | table_format = '%3s' | sprintf(3) description of how table numbers are formatted.
table_method | table_method = 'consecutive' | If set to “`consecutive`”, assigns boards to table numbers consecutively across divisions. If left unset, or set to the default value of “`none`”, does not assign boards to tables automatically.
table_title | table_title = "Room" | Specify what tables are called in titles. The default value is “`Table`”.
tables | tables{'A'} = [1,1,2,2,3,3,4,4,5,5] | List which board is at which table. Division name must be capitalized. If you don’t give information for enough boards, you’ll get cryptic error messages. You may use Perl expressions like “`1..20`” or “`map { $_, $_ } 1..20`” to save typing.
tally_slips_no_spread | tally_slips_no_spread = 1 | If specified, the tally slips generated as a side effect of the “`ShowPairings`” command will not include a box for spread.
terminology | terminology = 'deu' | Select the terminology that tsh uses in its reports and user interface. This feature is only partially implemented, in those areas of tsh where it has been requested. Currently supported terminology values are “`absp`”, “`deu`” and “`nsa`”. Contributions of additional terminology are welcome.
thai_points | thai_points = 1 | If set, compute and display Thai points (2 for win, 1 for tie, 0 for loss, plus handicap) where appropriate.
tfile_encoding | tfile_encoding = 'utf8' | Specify a character encoding for ‘.t’ files other than the default ‘isolatin1’.
top_down_swiss | top_down_swiss = 1 | If set, disable bidirectional optimization of Swiss pairings.
tournament_id | tournament_id = 123 | Identifies the tournament for the purpose of submitting rating data.
track_firsts | track_firsts = 1 | Make tsh care about who played first and second in each game. If this option is set and “`assign_firsts`” is not set, tsh will use the order in which scores are entered to determine who played first, and complain if the wrong player did. If this option is set and you use Chew pairings, the pairing algorithm will have a weak preference for pairing players due to go first with players due to go second.
twitter_command | twitter_command = 'ttytter -ssl -silent -status="%s"' | Specify the back-end command-line command to be used by the “`TWEET`” command.
twitter_password | twitter_password = 'whatever' | (Deprecated) Specified the password to be used to authenticate each message sent by the old version of the “`TWEET`” command.
twitter_prefix | twitter_prefix = 'Live from DO:' | Specify a prefix to be attached to each message sent by the “`TWEET`” command.
twitter_username | twitter_username = 'whoever' | (Deprecated) Specified the username to be used to authenticate each message sent by the old version of the “`TWEET`” command.
unfair_byes | unfair_byes = 1 | If specified, byes will always be assigned solely on standing, not taking into account how many byes each player has had.
zero_byes_tie | zero_byes_tie = 1 | Specify that a bye with zero spread is to be treated as a tie, rather than a nonevent.

### Configuration Realms

Because tsh is used in many different countries with many different Scrabble traditions (and it’s even sometimes used for non-Scrabble events), tsh has a quick way of specifying common default values for configuration options that vary from country to country: the “`realm`” configuration option. The following table shows which default values are set according to the value of this option.

Realm | Default Values Specified for Configuration Options
--- | ---
config realm = 'nsa' (This is the default realm.) | `alpha_pair_page_break = 10` `rating_list = 'nsa'` `rating_system = 'nsa2008'`
config realm = 'absp' | `alpha_pair_page_break = 10000` `assign_firsts = 1` `avoid_sr_runs = 1` `bye_firsts = 'ignore'` `bye_spread = 75` `currency_symbol = '£'` `html_in_event_directory = 1` `no_index_tally_slips = 1` `photo_database = 'centrestar'` `rating_list = 'absp'` `rating_system = 'absp'` `surname_last = 1` `table_method = 'consecutive'` `terminology = 'absp'` `track_firsts = 1`
config realm = 'deu' | `bye_firsts = 'ignore'` `currency_symbol = '€'` `locale = 'de_DE'` `message_file = 'lib/messages/deu.txt'` `photo_database = 'deu'` `rating_list = 'deu'` `rating_system = 'deu'` `terminology = 'deu'` `use_windows_code_page = 1`
config realm = 'go' | `assign_firsts = 1` `bye_spread = 2` `rating_system = 'nsa'` `scores = 'WL'` `track_firsts = 1`
config realm = 'naspa' | `rating_list = 'nsa'` `rating_system = 'nsa2008'`
config realm = 'naspa-csw' | `rating_list = 'naspa-csw'` `rating_system = 'naspa-csw'`
config realm = 'naspa-lct' | `rating_list = 'nsa'` `rating_system = 'nsa2008 lct'`
config realm = 'nor' | `currency_symbol = '€'` `locale = 'nb_NO'` `message_file = 'lib/messages/nor.txt'` `rating_list = 'nor'` `rating_system = 'nor'` `terminology = 'nor'` `use_windows_code_page = 1`
config realm = 'pak' | `bye_firsts = 'ignore'` `photo_database = 'pak'` `rating_list = 'pak'` `rating_system = 'pak'`
config realm = 'pol' | `all_byes_tie = 1` `assign_firsts = 1` `bye_spread = 300` `locale = 'pl_PL'` `message_encoding = 'utf8'` `message_file = 'lib/messages/pol.txt'` `rating_list = 'pol'` `rating_system = 'nsa2008'` `sum_before_spread = 1` `tally_slips_no_spread = 1` `terminology = 'pol'` `tfile_encoding = 'utf8'` `track_firsts = 1`
config realm = 'sgp' | `bye_firsts = 'ignore'` `rating_list = 'sgp'` `rating_system = 'nsa'` `surname_last = 1`
config realm = 'sudoku' | `entry = 'sudoku'` `pairing_system = 'none'` `rating_list = 'sudoku'` `rating_system = 'sudoku'` `scores = 'sudoku'` `terminology = 'sudoku'` `tfile_game = 'sudoku'`
config realm = 'thai' | `bye_spread = 100` `console_encoding = 'cp874'` `csv_encoding = 'windows-874'` `member_separator = '-'` `message_encoding = 'windows-874'` `rating_list = 'thai'` `rating_system = 'thai'` `spread_cap = 350` `terminology = 'thai'` `tfile_encoding = 'windows-874'`
config realm = 'wespa' | `bye_spread = 75` `rating_list = 'wespa'` `rating_system = 'wespa'`

### Configuring Pairings

tsh has a number of pairings commands, each of which adds one or more rounds of who-plays-whom information to the player data (“.t”) files. Pairing information must be entered before scoring information: the score entry command will not accept scores for players whose opponents are not yet known to the program. You should be familiar with the contents of the section on pairing theory and have decided on one or more of the pairing systems described in that section for your tournament before reading further.

There are four ways of telling tsh what kind of pairings to use: default, automatic, custom and manual pairings.

#### Default Pairings

With default pairings the only thing you need to tell tsh is how many rounds your tournament is:

    # The following config.tsh line says that this tournament has 12 rounds.
    config max_rounds = 12

After you enter the results for each round, ask tsh for the next round’s pairings using the “`ShowPairings`” command and it will compute Chew pairings. (If the number of rounds is large compared to the number of players, one or more round robins will be scheduled first.) The following configuration options can be set to control how these default pairings work. See the detailed description of configuration options for their syntax.

Option | Effect | Utility
--- | --- | ---
auto_koth_repeats | If set, any final KOTH pairings induced by “`config force_koth`” will have the specified number of repeats, rather than an unlimited number. | Sometimes used in South Africa for the sake of tradition.
avoid_sr_runs | If set, minimise consecutive starts (1sts) or replies (2nds) when pairing a win group. | You might use this, if your players are likely to complain about long runs of starts or replies, and you don't mind slowing down the pairings a little.
flight_cap | If set, overrides the cap on the size of the top flight. | Do not use, unless you are a pairings wizard.
gibson_class | If set, restricts opponents of Gibsonized players to one named class. | You might use this, some but not all of your players are competing in this tournament to qualify for something else, and should not be penalized in their qualification attempt by having to play a Gibsonized opponent.
gibson_groups | Indicates final ranks that are to be considered equivalent when testing for Gibsonization. | You should only use this if you are a pairings wizard.
gibson_spread | Overrides default spread thresholds for Gibsonization. | You should only use this in consultation with your governing rules body.
force_koth | If set, the last round will be KOTH even when default pairings are being used. | You might want to use this, if your (likely North American players) will rebel at the thought of a tournament that doesn’t end in a KOTH.
initial_snaked | If set, and “`InitFontes`” is invoked to generate first-round pairings, players are assigned to pairings groups in boustrophedonic order rather than randomly. | Use this if you mistakenly believe that is a good thing to allow players to engineer their first-round pairings in a high stakes tournament by sacrificing pretournament ratings points, or that ratings are sufficiently accurate for detailed seeding of players.
initial_schedule | If set, specifies a number of initial rounds that will be paired in a fixed schedule. | It’s not a bad idea to set this if you have the number of players is much larger than the number of rounds, or if you want to give yourself some breathing space early in your tournament.
interleave_rr | If set, players in a multiple round robin play each opponent in turn, rather than each opponent repeatedly before moving on to the next. | This option is not set by default, because tournaments run much faster when players don’t have to move from round to round. Some players get bored playing the same opponent repeatedly though, which is why we have this option.
max_rounds | Specifies the length of the tournament in rounds. | Required.
no_initial_rr | If set, there will be no initial round robin phase, even if there are enough rounds to accommodate one. | Used in large tournaments including players with widely ranging skill levels.
pairing_system | Explicitly set to indicate which of 'auto', 'chew', 'manual' or 'nast' pairings you want. | Required when using NAST pairings, optional otherwise.
prize_bands | Should be set to indicate which final ranks are equivalent. If you do not set it, you will be warned that you have not set it each time pairings are calculated. | Strongly advised.
random_rr_order | If set, the top seed in a round robin is paired against randomly ordered opponents; if not set, the top seed faces opposition of increasing strength. | Used in Ireland, and useful in reducing data input errors in multi-division events.
session_breaks | If set, pairings may be calculated based Fontes-style on the second preceding round’s scores during sessions. If not set, pairings will only be calculated once the immediately preceding round’s scores have all been entered. | Strongly advised.
top_down_swiss | If set, disable bidirectional optimization of Swiss pairings. | Use where strict Swiss pairings are required.

#### Automatic Pairings

If you prefer to have more control over your tournament’s pairings, or have advertised the use of a specific system that is not the tsh default, you should use automatic pairings. This involves pre-entering all the pairings commands that you expect to use into the configuration file, where they will be automatically triggered when the time is right.

Each auto-pairing configuration line consists of the command word “`autopair`”, a division name, the number of the round whose results must all be in before pairings can be calculated, the number of the round whose pairings will be calculated, and then a tsh command that generates the pairings.

For example, you can tell tsh that the first seven rounds of your two-division event is a round-robin, and the eighth round is a king-of-the-hill (KOTH):

    # When Div. A has no scores and needs Rd. 1 pairings: RoundRobin A
    autopair a 0 1 rr a
    # When Div. B has no scores and needs Rd. 1 pairings: RoundRobin B
    autopair b 0 1 rr b
    # When Div. A has Rd. 7 scores and needs Rd. 8 pairings:
    # KOTH with one repeat allowed based on Rd. 7 standings, Division A
    autopair a 7 8 koth 1 7 a
    # When Div. B has Rd. 7 scores and needs Rd. 8 pairings:
    # KOTH with one repeat allowed based on Rd. 7 standings, Division B
    autopair b 7 8 koth 1 7 b

When you ask for the first round’s pairings tsh will compute the round-robin, then later on when you have entered scores for the first seven rounds you can ask tsh for the eight round’s pairings and it will compute the KOTH. If you ask for Round 8 pairings before all results are in for Round 7, tsh will remind you that it can’t compute them yet.

Here’s a slightly more complicated example, for a six-round two-division tournament where the first three rounds are paired using the “`InitFontes`” command, the next two are paired Swiss based on Round 3 standings but with no repeats, and the last is a KOTH based on Round 5 standings with repeats permitted:

    autopair a 0 1 if 3 a
    autopair a 3 4 ns 0 3 a
    autopair a 3 5 ns 0 3 a
    autopair a 5 6 koth 1 5 a
    autopair b 0 1 if 3 b
    autopair b 3 4 ns 0 3 b
    autopair b 3 5 ns 0 3 b
    autopair b 5 6 koth 1 5 b

As explained in the section on manual pairings, you might still need to resort to manual pairings even when you have planned on using automatic pairings.

#### Custom Pairings

Some directors have developed regionally popular idiosyncratic pairing systems. For example, you might have a few rounds paired according to a fixed schedule, a few rounds of Swiss, and a few rounds of KOTH. You can select one of these by specifying a value for the “`pairing_system`” configuration option. The “`ShowPairings`” command will then generate pairings appropriate to the specified custom pairing system.

To add a new custom pairing system to tsh, please submit your request at least 1-2 months before its first planned use.

#### Manual Pairings

You should use manual pairings if you do not know in advance exactly how you will be pairing the tournament, such as when you haven’t decided when to start allowing repeats.

You might also find during your tournament that the automatic system you specified is impossible. For example, you might have asked for a round-robin followed by a KOTH with no repeats. You can quit tsh, edit the automatic pairing instructions and then try again, but if you’re under time pressure you’ll likely prefer to just enter the pairings commands directly and manually.

### Prize Declarations

The “`PRiZes`” command lists all the prizes you are awarding, and if it can be automatically determined, who won them. If you want to use this command, you need to list your prizes in your configuration file using the “`prize`” instruction. You need one instruction in the file for each prize you are awarding. For example, if you are awarding a high game prize in each of four divisions, it will take four instructions to describe them. Unlike with most other lines in your configuration file, the order in which you enter prize instructions is important, as that is the order in which they will appear in the subsequent report.

Here are some examples of actual prize instructions from the 2008 US NSC:

    prize note Place Prizes
    prize rank 1 1 $25000
    prize rank 2 1 $10000
    prize separator
    prize note Miscellaneous Automatically Calculated Prizes
    prize tuffluck 1 1 $50
    prize rank 1 1 $200 groupname='55+ Senior' members=[2,5,6,21,22,23,28,30,42,46,51,52,53,68,69,72,74,78,82,85,91,101,102]
    prize brlh 1 1 $200 first=15 last=21 prizename='Division 1 Best Record Day 3 Lower Half'
    prize highroundwin 1 1 $20 round=1
    prize highroundloss 1 1 $20 round=28
    prize lowwin 1 1 $20
    prize separator
    prize note Signup Prizes
    prize signup 'Division 1 Biggest Comeback' 1 $75

Each line has several items, separated by one or more spaces. If an item has a space in it, such as “`'Division 1 Biggest Comeback'`”, enclose it in matching single or double quotes.

1. The first item has to be the word “`prize`”, to identify the line as a prize declaration.
2. The second item is the prize type: a complete list can be found below.
3. The third item is the prize subtype: usually the rank a player has to attain in the category determined by the prize type in order to win the prize. In the example above, first place wins $25,000 and second place wins $10,000. Negative ranks count from the bottom of the field.
4. The fourth item is the name of the division to which the player must belong in order to qualify for the prize. In the example above, all prizes are in Division 1.
5. The fifth item is the amount of the prize. This may be a cash value, or a description of merchandise.

In addition to these five items, you may have extra items consisting of an item label, an equals sign, and an item value. A complete list of these can also be found below.

Here is a list of all currently defined prize types. If you want to compute a prize that is not listed below, please ask and it will be added.

Prize Type | Description
--- | ---
brlh | Computes the U.S. NSC's "Best Record Lower Half". Requires two extra items: “`first`” and “`last`”. Ranks players according to their record in the range of rounds that these specify, excluding any players who either did not play any games in that range, or began the range ranked in the upper half of the field.
highloss | Ranks players according to the highest-scoring loss they recorded.
highratingchange | Ranks players according to their rating changes.
highroundloss | Requires one extra item: “`round`”. Ranks players according to the highest-scoring loss they recorded in the designated round.
highroundwin | Requires one extra item: “`round`”. Ranks players according to the highest-scoring win they recorded in the designated round.
highwin | Ranks players according to the highest-scoring win they recorded.
lowwin | Ranks players according to the lowest-scoring win they recorded.
luckystiff | Ranks players according to their lucky stiffness (smallest margin by which they won six games).
note | Adds a note to the prize table.
overseed | Ranks players according to how high they climbed from their original rating-based seed.
rank | Ranks players according to their wins, losses and cumulative spread.
roundrecord | Ranks players according to their wins, losses and cumulative spread over a range of rounds specified by “`first`” and “`last`”.
separator | Leaves a blank line in the prize table; other arguments are ignored and may be omitted.
totalteam | Ranks teams according to the average record of their members in all divisions.
tuffluck | Ranks players according to the sum of the spreads of their six closest losses.
upset | Ranks players according to the difference between their rating and the rating of the highest stronger player whom they were able to defeat.

Here is a table of extra items that may be added to any prize declaration to refine the way prizes are awarded. Each must be followed by an “`=`” and a value. There must not be spaces before or after the “`=`”. If the value includes spaces, the entire value must be enclosed in “`'`”.

Label | Description
--- | ---
class | The value assigned should be a class name. If this extra item is used, it restricts prize eligibility to players belonging to the designated class.
exclusive | If a value is assigned to this item, it designates an exclusive prize category. A player may win at most one prize from any one exclusive prize category. If they are eligible for two prizes, they will be awarded the first one listed, and the second prize will go to the next contender. If you are using this to award class prizes, list your prizes in decreasing order of value, with class prizes ahead of place prizes of equal value. You may also wish to specify “`config show_honourable_mention`” to list the additional prizes that a player would have won had exclusivity not been in effect.
first | Specifies the first in a range of rounds for the “`brlh`” and “`roundrecord`” prize types.
groupname | If a value is assigned to this item, the default name for this prize will display it between the division name and the prize name.
last | Specifies the last in a range of rounds for the “`brlh`” and “`roundrecord`” prize types.
memberfile | The value assigned should be the name of a file which lists player names, exactly as they appear in data files. If this extra item is used, it restricts prize eligibility to the designated players, who might be of a particular age group or from a particular country.
members | The value assigned should be a comma-separated list of player IDs, enclosed in [square brackets]. If this extra item is used, it restricts prize eligibility to the designated players, who might be of a particular age group or from a particular country.

### Encoding Directives

If you need to have text in your configuration file that is not in the ISO 8859-1 (Latin) character encoding, use the “`encoding`” directive to specify an alternate encoding. The new encoding should be named in the directive following white space, and takes effect immediately. If you have no idea what this is about, be thankful.

### Raw Perl Commands

Experienced thrill-seekers may also add lines to the “config.tsh” file which begin with the keyword “`perl`”. This is about as safe as using the tsh shell command “`eval`”, and does the same thing: it evaluates its argument as a string. There is currently no good reason for using this feature.

## The “.t” Files

A “.t” file contains all the information for a division, and must be in the same subdirectory as your “config.tsh” file. It’s a text file that can be edited with a text editor if need be, and is usually created in the first place using a text editor. You may have received “.t” files for your tournament with your tsh distribution, but you should be familiar with the content of this section in case of no-shows and walk-ins.

There is an experimental script for importing data from TourneyMan files. It’s called “parsetm”, is found in the “util/” directory and can be invoked from the command-line to turn one “.ltm” file at a time into a “.t” file. It has been thoroughly tested on the version of TourneyMan to be used at the 2005 US NSC.

A “.t” file should contain one line per player. The line should look something like this:

    Chew, John   1850 400 450 350; 10 4 3; p12 1 2 2; board 1 1 3

In this example, a player named John Chew entered the tournament with a rating of 1850. In round 1, he played player #10 and scored 400 points. In round 2, he played player #4 and scored 450 points. In round 3, he played player #3 and scored 350 points. He went first in round 1 and second in rounds 2 and 3. He played at board #1 in rounds 1 and 2, and at board #3 in round 3. Anywhere where there is a space on the line, tsh will tolerate as many spaces as you like, but please do not use tabs. Of course, adding spaces within a player’s name will make many reports look odd.

Scores and opponent numbers may have the special value “`00`”, indicating that the value has not yet been assigned. This should not be confused with the “`0`” that indicates a bye.

Players must be listed in order of player number, beginning with player number 1. Note that this means that players must be numbered within each division starting at 1. Unless you feel strongly otherwise, you should number players beginning with the highest-rated. If you want to number players in two divisions in one numbering system without restarting from 1 at the top of the second division, you must call the two divisions one division for data entry purposes.

When you first set up a tournament file, it will probably contain only player names and ratings. So your file will look something like:

    Chew, John          1850
    Saint John, Sherrie 1300
    Chew, Kristen       1200

Player names may include any characters other than semicolons, and must not end in a digit. If you really have to have a player name that ends in a digit (it has happened), put a comma after the final digit and the comma will be silently omitted in reports. Player names should be entered as shown above, with the surname (last name) first followed by a comma. If you do not do so, a few commands which need to know how to split names into given names (first names) and surnames will not function.

Not all files contain the same information for players. Some information only appears if some optional features are enabled. Each set of optional data is preceded by a semicolon and an identifying keyword. At present, the following extensions are in use:

Keyword | Data
--- | ---
board | Lists at which board the player played in each round. This is typically set by the “`ShowPairings`” command the first time pairings for the round are shown, and not changed thereafter.
class | If present, should be followed by a single-word class name: typically ‘A’, ‘B’.... Will be set automatically by the “`classes`” configuration command, overriding any previously set values. Is used by report generation commands to indicate which class a player belongs to.
cume | Is present if the player’s cume must be set to a given value. It should be used with extreme caution, as it will override the regular calculation of cume in all rounds. This feature is not yet fully implemented.
cumeadj | Is present if the player’s cume must be adjusted, typically to compensate for a misadjudication. It should be followed by one or two values, the first the amount of the adjustment, the second the round in which the adjustment should first be applied. This feature is not yet fully implemented.
initrec | If set, specifies an initial record of wins, losses, spread, capped spread or score sum with which the player is understood to have begun the event.
lifeg | If set, indicates the number of games that the player has played in his life, used for ratings computations. If not set, a value of 50 is assumed.
off | Is present if the player is inactive for pairing purposes. It is followed by a single integer, indicating what spread ought to be awarded to them for each missed game. This feature is not yet fully implemented.
initrec | If present, specifies a record (e.g. “5 2 1000 800” for a player who had 5 wins, 2 losses, +1000 spread and +800 capped spread) that a player is credited with at the start of the event.
p12 | Lists whether the player went first (1) or second (2) in each round. Rounds where the player went neither first nor second are marked 0, rounds where the player is paired but has to randomly determine whether or not s/he goes first are marked 3, rounds where tsh is not sure who will go first or even whether a random determination will be required are marked 4.
pname | Specifies how a player’s name should be displayed in reports, possibly using Unicode characters not available at the console. You may need to specify a tfile_encoding to use certain characters.
password | Specifies a player’s password for self-service scoring.
sbname | Specifies how a player’s name should be displayed by the “``EnhancedScoreBoard``” command. You may need to specify a tfile_encoding to use certain characters.
seat | Specifies a player’s seat for realms where seats are numbered instead of boards.
tag | Tags a game with a user-specific label, used by NASPA for identifying game lexicon in hybrid CSW-TWL events.
team | Names the player’s team, for use in team tournaments. The value is a case-sensitive sequence of words; each instance of white space is collapsed to a single space.
twitter | Gives the player’s Twitter handle, which will replace their name in tweets issued by the “`TWEET`” command.

If you have an Internet connection, you can update the tournament ratings in your player data files at any time using first the “`UPDATERATINGS`” command and then the “`USERATINGS`” command. This command is not available for all realms. If it doesn't work in yours, please ask for rating support to be added.

## “.tsh” Archive Files

The “`BUGreport`” and “`SUBMIT`” commands generates (and depending on configuration may upload) an archive file which concatenates the configuration file with copies of each division data file wrapped between marker lines. Here’s a very simple example.

    config event_name = "Sample Event"
    config max_rounds = 2
    division A a.t
    division B b.t
    #begin_file name=a.t
    Chew, John    1800 2 2 ; 400 350
    Chew, Kristen 1400 1 1 ; 350 400
    #end_file name=a.t
    #begin_file name=b.t
    Chew, Jamie 1000 2 2 ; 400 350
    Chew, Liam   500 1 1 ; 350 400
    #end_file name=b.t

You may use this as an archive format for past events. tsh will accept an archive name as a command-line argument, but treats its data as read-only.

## User Profile

If you find yourself running a lot of similarly configured events and want to save the common configuration instructions in one place, you can do so in your user profile using the “`PROFILE`” command. This command lets you manipulate a file called “lib/profile.tsh” that is currently identical in format to your “config.tsh” files, but is not intended to be edited directly.

A good value to store in your profile is configuration realm.

## Dry Run

Once you have everything set up, preferably a few days before your tournament, you should try a dry run of your event. The easiest way to do this is to use the “`DRYrun`” command, which runs an entire tournament for one division on random data using the pairings you configured. After you’ve looked at all the reports it has generated, use the “`RESETEVERYTHING`” command to delete all the test data.

If you want finer control over the dry run, you can do what it does manually using the “`ShowPairings`” and “`RANDomscores`” commands.

There are also a number of unsupported scripts in the “util/” folder which do further analysis on dry runs, for the purposes of compiling statistics on pairing systems and predicting event winners.

## Backups and Redundancy

Now is a good time to think about what to do if disaster strikes. You should always bring an extra computer, extra printer and extra ink cartridges. If you are running a multidivision tournament and have extra staff, then you can use the extra equipment to split the data entry task across two installations of tsh, combining the two if some of your hardware fails.

tsh journals a copy of every “.t” file after every change, which is useful for correcting errors, but not helpful if your hard disk crashes or your computer dies. Follow the standard rule for backups: make a copy of important files often enough that you don’t mind having to type in any changes since your last backup. For “.t” files, this should be somewhere between every round (to be safe) and every session (to live dangerously). Back up files to other computers, the net, and/or removable media.

If your computer fails and you do not have a spare computer, announce what has happened, gather scorecards and any qualified directors and do pairings by hand. Then write out “I will not run a tournament without a spare computer” enough times by hand that you learn your lesson.

If your printer fails or you run out of ink, in a small tournament you can probably write out or announce pairings aloud, especially if you just need to cover until you can find a replacement cartridge.

# tsh GUI Notes

Development notes on the experimental GUI.

An experimental version of the tsh GUI first shipped with version 3.190. This file documents the GUI, and will be entitled Notes to remind the reader of the experimental status of the module until it is ready for formal release.

## Overview

The tsh graphical user interface (GUI) is implemented by having tsh run a lightweight web server on a nonstandard port. If the host machine supports it, the classic command-line interface (CLI) may be run simultaneously with the GUI.

## Requirements

The experimental code is tested regularly under OS/X 10.4 and Windows XP. It is not guaranteed to work at all under other operating systems.

Earlier versions of Perl 5.8 did not return the correct value from threads::shared::share(). 5.8.6 works, 5.8.0 does not. Always use the latest greatest version of Perl. (Of course, versions of Perl prior to 5.8 did not support the current threads library at all, and don’t have a hope of running the threaded code.)

## Configuration

To enable the GUI, add the line “`config port = 7777`” to your event’s ‘config.tsh’ file, where the value 7777 may be changed to any convenient value between 1024 and 65535.

To enable multithreaded operation, that is, simultaneous operation of the CLI and GUI, create a file called ‘threads.txt’ in the ‘lib’ directory. Yes, I know this is a hack, but it’s set up this way because enabling threading induces potential instability in the software (because of ridiculous restrictions on thread-shared data in the current release of the Perl threads library, which itself is not a mature product). I want to make sure that a user does not accidentally turn on multithreading until I’m 100% sure that the code won’t is sound. Another problem is that the way the code is written right now, and the way threads work in the current version of Perl, the obvious solution (a line in ‘config.tsh’) doesn’ work because by the time the configuration file is being read, it’s too late to activate multithreading (because the configuration file data itself would need to have been labelled as thread-shared).

If you’re successful, then when you run tsh, your CLI should appear briefly, then be superseded by a browser window showing something like a wall chart. If you’re running multithreaded, you can work alternately in the CLI and GUI windows.

## Using the GUI

It’s just a proof-of-concept right now, and I don’t like the way any of it looks or functions. I’ll be reworking it over the next few months, at which point suggestions will be welcome.

## Reconnecting to the GUI

If you close your browser window, you can reconnect to the GUI either by remembering the URL – ‘http://localhost:7777’ (if you chose 7777 as your port number), or looking for the URL in your browser history. If you have the CLI running too, you may use the “`GUI`” command to open a browser window to the GUI.

## Shutting down the GUI

If you have the CLI running, quitting the CLI should shut down the GUI. Actually, there's a bug in the current version that prevents it from doing so under Windows, so press Control-C to kill the tsh process.

If not, you'll just have to press Control-C for now. Eventually there will be a button in the GUI to shut down the server.

# Pairing Theory and tsh

Some background on how pairing systems work.

This section discusses the theory behind scheduling pairings for tournaments and the details of the pairing systems implemented in tsh. See elsewhere the table of tsh’s pairing commands, and the discussion of how and when to use them.

## Goals

The following are desirable properties of a pairing system. It is impossible to satisfy all of these properties simultaneously.

Property | Description
--- | ---
“Aristomachy” | Top players should be paired with each other, especially toward the end of the tournament. King-of-the-Hill pairings do this best, Round Robin pairings do this worst.
Division Sizing | Some pairing systems (notably round robin) require specific numbers of players. The number of players is usually not under the director’s control, though often their assignment to divisions is. A small number of large divisions permits smaller number of larger prizes but requires players to face opponents of more widely ranging ratings.
“Exagony” | Players travelling together to a tournament do not like to play each other, as many players travel to vary their opponents. At the World Championships, unnecessarily pairing together players from the same country may make it difficult for them to earn an additional place at the next WSC.
Fairness | The final ranking of players by the customary win-loss record and cumulative spread should be equivalent to a ranking according to their level of performance in the tournament. Three possible ways of measuring the latter are to average the final rankings of the opponents of each player (Average Opponent Ranking or AOR, to add the number of wins and spread of the opponents of each players (Sum of Opponent Scores, SOS or Buchholz), and uninitialised iterated performance ratings (IPR, the ratings that players would have if they had all arrived at the tournament unrated).
Implementability | A good human director can pair 50–100 players by hand if a dynamic pairing system is not too computationally demanding. Computers can currently do brute-force exhaustive searches for optimal pairings up to groups of about 16 (for which there are 2,027,025 possible pairings), use smarter algorithms for very difficult pairing situations involving twice as many players, and can easily apply complex rules to larger groups to find pairings which match well-designed criteria.
Incentivization | A player should not be placed in a position where tieing or losing is strategically preferably to winning. For example, a player who has clinched a place in a two-player final should not be paired with a possibly weak player whose victory would send him to the finals.
Inclusivity | A player should not needlessly be excluded from contention for a prize by being paired with someone who is out of contention. For example, if with one round left to play the top three players have N, N and N–1 wins and the top two have a 500-point spread advantage over #3, then #3 needs to play #1 or #2 in order to have any reasonable chance of finishing first.
“Monagony” | Players should play each other as few times as possible. Repeat pairings can prevent other players from catching up to the repeaters, and do not accurately measure the repeating players’ ability to defeat a wider field. Players also do not in general like playing each other in consecutive rounds.
Monotony | A lower-ranked player should not be paired so as to make it more likely that he will become the overall winner than that a higher-ranked player will.
Suspense | The outcome of the tournament should be determined as late as possible.

## Gibsonization

David Gibson, the all-time top money winner in the history of Scrabble, has made a habit of clinching victory in major events without waiting for the final round. Because of this, players are said to be “Gibsonized” when after clinching, they are paired with lower-ranked players to avoid affecting the ranking of runners-up. tsh has two mechanisms for detecting Gibson situations.

The Chew pairing system automatically detects and assign Gibson pairings. Gibson situations are detected based on wins and generalised NASPA spread thresholds (a player may hope to win one game by 250 points, two games by an average of 175 points, and more games by an average of 150 points each, or as overridden by the “`gibson_spread`” configuration option). If there is more than one Gibson, as many of them as possible (all of them if the total number is even) are paired with each other KOTH minimizing rematches and consecutive rematches. If all players are still in contention for some sort of prize, it will pair any remaining Gibson with the lowest ranked player who has played him/her least often. If some players are out of contention for any prize, it will pair any remaining Gibson with the highest ranked such player who has played him/her least often.

If you specify “`config gibson = 1`” in your configuration file, tsh will also perform Gibsonization when using KOTH or Swiss pairings.

It is important to note that if you are using Fontes pairings, a Gibson situation may develop in round n, paired based on round n–2, as a result of games played in round n–1. tsh does not currently check for this situation, and in practice the players involved might already even have started playing round n before anyone notices what has happened. If you do find yourself in this situation, try to manually repair the top few boards, if they have not already started their games. If no one has started a game, use the UnPairRound command to remove your previously calculated pairings, use the PAIR command to manually pair the Gibson with a reasonable victim, then recompute the pairings for the rest of the division.

## Pairing Systems

tsh currently supports the following pairing systems, in order of increasing sophistication. If you have a need for a different pairing system, please contact John Chew at least two months in advance of your tournament.

- None
- Random
- Manual
- King-of-the-Hill (KOTH)
- Quartiles
- Factored (FP)
- Round Robin (RR)
- Lower Round Robins (LRR)
- Team Round Robins (TRR)
- Bracket
- Green
- Guelph
- NAST
- BASD
- Swiss
- Chew

### No Pairings

Although tsh began as a program for generating pairings and reports, it can also be used at events like crossword or Sudoku tournaments, where players compete separately to attain individual scores. If you specify “`config pairing_system = 'none'`, all players effectively receive unscored byes, and after you enter their scores you can view standings reports.

### Random Pairings

Random pairings match players based on a statistical hashing function of their name and player number. They are random in that who plays whom will not appear to follow any pattern, but only pseudorandom in the sense that if you do not change the names and order of your players the pairings will always be generated the same way.

You might want to use random pairings when assigning first-round pairings for a group of players who do not have a reliable past tournament record.

The general command for random pairings in tsh is “`randompair repeats based-on-round division`”. For example, to ask for random pairings with no repeats allowed, based on standings in round 7 for division D, use the command “`rp 0 7 d`”. This example is somewhat contrived though, as after the first round it would be foolish to use random pairings rather than some sort of standings-based pairings.

See also the “`config initial_exagony`” configuration variable for avoiding pairing players from the same team in the first round. If you use this variable and do not assign players to teams, pairings will fail because everyone will appear to belong to the same unnamed team.

As it does with other pairing commands, tsh will try to minimize repeats and avoid successive repeats where possible, though in the first round this is irrelevant.

### Manual Pairings

Sometimes, you can’t use a computer to do all your pairings. For theatrical purposes you might have the first round’s pairings be done by a physical draw. You might need to tweak computer pairings because someone has taken ill after you’ve computed your pairings and some people have started to play. You might want to manually pair a few players and allow the rest to be automatically paired. Or something really weird and unexpected might have happened.

tsh provides two commands for manual pairings. If you’re just doing a few, then use “`PAIR p1 p2 round division`”. For example, “`pair 1 2 5 a`” pairs players 1 and 2 in round 5 in Division A. To assign a player a bye, pair them against the fictitious player 0.

If you need to do a lot of pairings, use the “`PairMany round division`” command. For example, “`pm 3 b`” lets you enter pairings for round 3, division B and prompts you to enter pairs of player numbers, one pair per line. If you enter a division name by itself, you will switch to entering pairings for that division. If you enter a round number preceded by an R and a space, e.g. “`r 5`” you will switch to entering pairings for that round. If you enter anything else, you will return to the main prompt.

You cannot assign pairings for a round until all previous pairings for both players have been assigned, and tsh will stop you if you try. You can reassign pairings for players who have already recorded scores, but should do so only with extreme caution, and you will likely need to use the “`EditScores`” or “`DELETEscore`” command. Use the “`ShowPairings`” command to check your pairings after any manual changes, to make sure that all players are paired and none are multiply paired (tsh will warn you of either situation).

If you want to pair partially manually and partially automatically, remember that tsh invokes its automatic and default pairing mechanisms when you use the “`ShowPairings`” command. Specify any manual pairings before using that command. If you forget and do a “`ShowPairings`” first, then use the “`UnPairRound`” command to un-pair all of the last round’s pairings from a division.

### King-of-the-Hill Pairings

In King-of-the-Hill (KOTH) pairings, the top two players are paired with each other, then the next two, and so on.

KOTH pairings are often used in the final round(s) of a tournament to ensure that contenders face each other, often with an extra repeat permitted so that contenders face each other again even when they have already played each other.

The general command for KOTH pairings in tsh is “`koth repeats based-on-round division`”. For example, to ask for KOTH with one repeat allowed, based on standings in round 11 for division B, use the command “`koth 1 11 b`”.

If the players who are supposed to play each other have already played each other too often, tsh will look for the nearest available player, breaking ties to avoid consecutive repeats, match starts with replies and minimize repeats. If the number of players is odd, tsh will assign a bye to the lowest-ranked player who has had the fewest byes.

### Quartile Pairings

Quartile pairings pair the top quartile of the field at random against a designated other quartile, and are typically used to begin large tournaments with unreliable rating data, such as the World Scrabble Championship.

The general command for quartile pairings in tsh is “`PairQuartiles quartile repeats based-on-round division`”. For example, to ask for the top quartile to be paired with the bottom, with no repeats allowed, based on standings in round 12 for division B, use the command “`pq 4 0 12 b`”.

### Factored Pairings

Factored Pairings (FP) are the same as KOTH except that the optimum rank separation of players is some fixed number (the factor) greater than the value of one used in KOTH.

A version of FP is used in the (US) NSC in preliminary rounds, with factors gradually decreasing from 20 to 2, to artificially control the rate at which the contender pool shrinks. (At the NSC, pairing is done in groups of four to eight players, three or four rounds at a time.)

The general command for FP in tsh is “`FactorPair distance repeats based-on-round division`”. For example, to ask for FP(2) with no repeats allowed, based on standings in round 14 for division C, use the command “`fp 2 0 14 c`”. The “`Pair1324`” command is a synonym for “`fp 2`”.

If the players who are supposed to play each other have already played each other too often, tsh will look for the nearest available player(s) to the optimum opponent(s), breaking ties to avoid consecutive repeats, match starts with replies and minimize repeats. If the number of players is odd, tsh will assign a bye to the lowest-ranked player who has had the fewest byes.

### Round Robin Pairings

In Round Robin (RR) pairings, every player plays every other player once.

RR pairings are used when the number of players is no more than one more than the number of rounds scheduled. If the number of players is a little less than that number, than the remaining rounds are often paired KOTH. While RR pairings are fair and give each player the widest possible field of opponents, if the skill levels of the players vary greatly then it may be more fair to use a more flexible system that will allow the top contenders to play each other more than once. It is also difficult but not always impossible to schedule an RR so that contenders face each other in the final round.

Where the number of rounds is much larger than the number of players, RR pairings can be repeated, either with players playing the same opponent consecutively, or interleaved (where one RR is completed before the next one begins).

The general command for RR pairings in tsh is “`rr n division`”. For example, to ask for a double set of RR pairings to be added to division A, use the command “`rr 2 a`”. If you leave out the number “`n`”, a single set of RR pairings will be added. If you want to override the default ordering of round robin rounds, use “`config random_rr_order = 1`” or “`config round_robin_order = [2,3,4,5,6,7,8,9,10]`”. If you want interleaved RR pairings, use “`config interleave_rr = 1`”.

There is also a specialized command for doing partial round robin pairings for use at Cambridge ON. Use the “`camp division`” command to add fixed pairings for a seven-round tournament with any number of players.

If you want to assign round robin groups to noncontenders toward the end of your tournament, you can use the “`LowerRoundrobins starting-rank rounds division`” command. For example, if you want players to play three-round round robins in groups of four if they are ranked 41st or below in Division B, use the command “`lrr 41 3 b`”. It is a better idea however to use Fontes pairings (either Swiss or Chew) instead, because they will not cause any greater delay in the running of your event, and they do not involve using as stale results.

In fact, if you want to assign round robins throughout the entire field (subject to the caveat in the preceding paragraph explaining why it is a bad idea to do so), you can use the the “`LowerRoundRobins starting-rank rounds division`” command with starting-rank 1. For example, if you want everyone in Division C to play five-round round robins in groups of six, use the command “`lrr 1 5 b`”.

If you have an even number of teams of equal size, and you would like each player to play every player on every other team you can use the “`teamroundrobin repeats division`” command. For example, if you want the teams in division C to play each other twice, use the command “`trr 2 c`”. If you want to do something like “`LowerRoundRobins`” for teams, see the “`TeamMultipleRoundRobin`” command.

### Bracket Pairings

Bracket pairings match players in a single-elimination format, with players out of contention playing KOTH. They can be tuned using the configuration options “`bracket_order`, “`bracket_prelims` and “`bracket_repeats`.

There is a manual command “`BRACKetpair`” that implements the pairing system, but you should never need to use it. It is available so that it can be invoked if you specify a bracket-paired event by adding the line “`config pairing_system = 'bracket'`” to your configuration file.

### Green Pairings

John Green’s tournaments in Florida use a system which pairs groups of six to eight players over six rounds, beginning with five fixed rounds.

There is a manual command “`GREEN`” that implements the pairing system, but you should never need to use it. It is available so that it can be invoked if you specify a Green-paired event by adding the line “`config pairing_system = 'green'`” to your configuration file.

### Guelph Pairings

Andy Saunders’ tournaments in Guelph, Ontario use a system which pairs groups of six, eight or ten players over six rounds.

Six-player groups play a round robin followed by KOTH with repeats.

Eight-player groups play as follows. In rounds 1–3, 1458 (A) and 2367 (B) each play a round robin. In round 4: A1–B2 B1–A2 A3–B4 A4–B3. In round 5: A1–B1 A2–B2 A3–B3 A4–B4. In round 6: KOTH with infinite repeats and Gibsonization.

Ten-player groups play a depleted five-round round robin followed by KOTH with repeats.

There is a manual command “`GUELPH`” that implements the pairing system, but you should never need to use it. It is available so that it can be invoked if you specify a Guelph-paired event by adding the line “`config pairing_system = 'guelph'`” to your configuration file.

### NAST Pairings

Steve Pellinen’s North American Scrabble Tour prescribes a specific hybrid pairing system for its satellite events. For most division sizes, this consists of four fixed rounds of pairings, one swiss-paired round with repeats allowed, and one KOTH round with unlimited repeats allowed.

There is a manual command “`NAST`” that generates the initial fixed schedule of four or five rounds, but you should never need to use it. It is available so that it can be invoked if you specify a NAST event by adding the line “`config pairing_system = 'nast'`” to your configuration file.

### BASD Pairings

Ira Freehof’s Big Apple Showdown has its own pairing system. Players are divided into two round robin groups in a first phase, semifinalists play each other while everyone else plays small round robins in a second phase, and finalists play each other while everyone else plays factored pairings in a third and final phase.

This is implemented using the “`config pairing_system = 'basd'`” configuration option, which invokes the “`BASDSemi`” and “`BASDFinal`” pairings commands.

### Swiss Pairings

In Swiss pairings, players are divided into “win groups” according to how many wins they have scored. The top half of each win group plays the bottom half, in order.

Several different systems of Swiss pairings are popular in Chess, where Swiss pairings originated. Swiss pairings work well for divisions where the number of players is large and the number of rounds is small.

Regular Swiss pairings cause delays in tournaments because the pairings for the next round cannot be computed until all the results are in for the previous round. Fontes (or Portland) Swiss pairings trade off some pairings accuracy for speed by computing pairings based on the second previous round’s results. As a compromise, some directors use regular Swiss pairings immediately after session breaks and Fontes Swiss pairings at other times.

The general command for Swiss pairings in tsh is “`ns repeats based-on-round division`”. For example, to ask for Swiss pairings with two repeats allowed, based on standings in round 17 for division C, use the command “`ns 2 17 c`”.

If you ask for Swiss pairings based on round 0, tsh will rank players by pretournament rankings, breaking ties randomly. This effectively pairs the top half of the field against the bottom, which may be something you want to do even if you aren’t pairing the rest of the tournament Swiss.

There is a special command for starting a Fontes Swiss tournament. Because you will need at least two rounds of scores before you can pair Fontes Swiss, the “`InitFontes number-of-rounds division`” command divides players into groups of four and schedules them to play in round robins. This takes three rounds (3 is the recommended value for `number-of-rounds`) and provides a fair start to the Swiss system, as well as giving you three hours to get used to doing data entry before you need to worry about pairings. If the number of players is not divisible by four, there may be a group of six players who play a partial round robin. The players in each group are chosen randomly, one from each quartile (or sextile).

Early in the tournament, you should use 0 repeats. At some point in a long tournament, you should start increasing the number of repeats or else the top players will begin much lower-ranked players because they have already all played each other. You can try simulating the outcome of the tournament to get a feel for when this is likely to happen, use your intuition based on past similar tournaments, or keep an eye on who the top-ranked player is playing each round and decide for example once they are paired with someone out of the top ten. Most Swiss tournaments end with one or two rounds of KOTH to ensure that contenders play each other often enough.

tsh chooses an opponent within the win group who (in decreasing order of importance): minimizes repeats, is not the previous round’s opponent, is due to play first if the current player is due to play second (and vice versa, but in either case only if “`config track_firsts`” is active), and is as close as possible to half a win group away in ranking. For the sake of computational efficiency, tsh looks for opponents first for those players who have the fewest candidate opponents (with ties broken by current ranking). If a win group is odd, the top player in the next group is promoted to join it. If a win group cannot be paired, two more players are promoted. If the entire division cannot be paired in one big group, an error message is displayed, and you should increase the number of allowed repeats. If the number of players is odd, tsh will assign a bye to the lowest-ranked player who has had the fewest byes.

By default, tsh pairs first the top win group, then the bottom win group, then the next win group at the top, then the next win group at the bottom, and so on. This saves time, because when the bottom players have all played each other, it saves tsh having to backtrack from every possible pairing of the higher ranked players. This optimization does however come at the cost of sometimes giving suboptimal pairings for mid-ranked players, especially in small divisions. To disable the optimization, use “`config top_down_swiss = 1`”.

By default, tsh pairs players within a win group by trying to match each player with an opponent who will balance firsts/seconds who is closest in rank to half the size of the win group away from the player. This behaviour can be changed using the “`config swiss_order`” configuration option, either to pair the top half in fixed order against the bottom half, or to minimize opponent rank distance.

### Chew Pairings

Chew pairings draw on Swiss pairings and the two-victor “Basic Approach” pairing system developed for the 2003 CNSC and refined at the 2004 NSC, 2005 CNSC and 2005 NSC. Tournament simulations determine which players are still in contention; the minimum number of repeats required to pair those players is computed; the contenders are split into leaders and nonleaders so as to minimize the number of leaders while not increasing the required number of repeats. Beginning at the top, each leader is paired with the lowest-ranked other leader who can catch up to him/her; the nonleaders are paired Swiss.

Chew (or similar) pairings should be used in tournaments where after a number of preliminary rounds two or more top players are selected to compete in final rounds. They are also sufficiently flexible that they may be used in any sort of tournament, and are therefore used as tsh’s default pairing algorithm. As with Swiss pairings, they may be computed based on the immediately preceding round’s standings or those of the second preceding round, depending on event scheduling.

The general command for Chew pairings in tsh is “`cp based-on-round division`”. For example, to ask for Chew pairings based on round 5 in division D, use the command “`cp 5 d`”. As explained in the discussion on default pairings, if you do not specify any pairing system, manual or automatic, tsh will use Chew pairings. You must specify “`config max_rounds`” and should specify “`config gibson_groups`”, “`config initial_schedule`” and “`config prize_bands`” when using Chew pairings.

Here is a very sketchy version of how Chew pairing works. We calculate who is still in contention for top prize money and try to pair them with each other, pairing everyone else Swiss. The number of contenders is typically capped to 8 in the antepenultimate round, 4 in the penultimate round and 2 in the last round, making the last round KOTH at the top of the field, barring Gibsonization. The contenders are divided into two groups, called the leaders and the non-leaders, if this can be done without increasing the number of repeats. The leaders are paired by pairing each top unpaired player with the lowest ranked player who can catch him; the non-leaders are paired Swiss.

For example, suppose six people are in contention in the next-to-last round. This is too many for that round, so only the top four players are paired with each other. The top four players can be paired by allowing repeats but not threepeats. They can also be split into (1,2) and (3,4) without requiring threepeats, i.e. the 1-2, 3-4 pairing does not involve threepeats. So we pair 1-2 and 3-4. If (1,2), (3,4) did require threepeats, then (1,2,3,4) would be paired together. If 4 can still catch 1, then 1-4, 2-3; else if 3 can still catch 1 then 1-3, 2-4; else 1-2, 3-4.

Here is the Chew pairing algorithm in greater detail.

- Sort players according to standing in the specified round.
- Repeat while players remain unpaired.
  - Count Gibsons based on wins and spread. The largest possible number of Gibsons is determined by the number of ranks that are declared to be equivalent using “`config gibson_groups`” and is typically 0, 1 or 2. That number is reduced by one at a time while the lowest-ranked possible Gibson can be caught by the next-ranked player. To try to catch a Gibson, a player is assumed to be paired repeatedly with that player, and to win all his/her games with a spread of +250 in one round, +175/round in two rounds, or +150/round for more rounds (these values may be overridden by the “`config gibson_spread`” configuration option).
  - Pair any Gibsons. If the number of Gibsons is even and positive, pair them with each other KOTH but minimizing repeats and consecutive repeats; else if the number is odd, pair all but the lowest ranked one in this way, then pair the last one with either the highest-ranked player in the lowest prize band (if nonempty) or the lowest-ranked player overall, in each case choosing only from the candidate opponents who have played the Gibson least often. If the number of unpaired players is odd, give an odd Gibson the bye.
  - If the number of unpaired players is now odd, give a bye to the lowest ranked among the players with the fewest byes.
  - Determine the highest prize band that is still being contended.
  - Count how many contenders there are to reach that prize band. Add one if odd. Cap at 2, 4, 8, 12, 12, 12, ... players when there are 1, 2, 3... rounds left (this may be overridden in the configuration file using “`config flight_cap`”). Note that when there is one round left, this means that contenders are paired KOTH.
  - Determine the minimum number of repeats necessary to pair all the contenders with each other with no other constraints.
  - If all remaining players are contenders (or if there are six or fewer noncontenders, and no more than twice as many contenders, and they cannot play each other without repeats) and “`config chew_no_swiss_all`” is not in effect
    - pair them Swiss with that many repeats permitted.
  - Else (some players are out of contention)
    - Divide the contenders into leaders and nonleaders, minimizing the number of leaders (but keeping at least four where possible) as long as the subgroup of leaders and the subgroup of nonleaders can each be paired amongst themselves without exceeding the minimum repeats for the whole group of contenders.
    - Pair the leaders as a group by repeatedly matching the top player with the lowest ranked player who can catch him/her, while not exceeding the minimum repeats and where possible avoiding consecutive repeats.
    - Pair the nonleaders Swiss, not exceeding the minimum repeats, and where possible minimizing repeats, avoiding consecutive repeats and matching players due to start with those due to reply.

# Ratings and tsh

How to maintain a rating system using tsh.

One of the more popular features of tsh is its calculation of tournament ratings. When you set up your tournament’s “.t” files with information about your players, you enter their pretournament ratings, and if necessary their career game totals (depending on your rating system, you may be able to use the “`USERATINGS`” command to do this automatically). As your tournament progresses, you can display current ratings using the “`RATings`” and “`ScoreBoard`” commands. At the end of your tournament, you can submit ratings data to your rating officer using the “`SUBMIT`” command (if your rating system is supported), or by generating a ratings report using commands like “`ABSPgrid`” or “`AUPAIR`” and emailing the results.

The rest of this section describes in greater technical detail what is involved in connecting tsh to a rating system, and its intended audience includes ratings officers and directors who want to discuss tsh with their ratings officers. As always, if there is anything that tsh doesn’t yet do that you would like it to do, please contact John Chew at poslfit@gmail.com. Each one of tsh’s features is there because someone asked for it; if a feature is missing, it’s just because you haven’t asked for it yet.

## Manual Rating Systems

Example users: Philippines, Toronto Speed

It’s easy to use tsh to run a small rating system. First, ask John Chew to assign you a unique rating system name. tsh will store your rating system’s data in a subdirectory of “lib/ratings”. For example, for historical reasons, NASPA ratings are stored in “lib/ratings/nsa”.

Then at the beginning of each rated event, use the “`USERATINGS`” command. This copies ratings from a file called “current.txt” in your rating system directory into your tournament data files.

At the end of your tournament, use the “`EXPORTRATINGS`” command. This will create a new rating data file called “new.txt” in your rating system directory.

Finally, save a copy of your old “current.txt” file in case you need to rerate a sequence of events (it happens more often than you would think), and replace it with “new.txt”.

## Legacy Rating Systems

Example users: ABSP

If you have an existing legacy rating system that cannot easily be connected to the web, you should determine what ratings data format it uses (tsh currently supports its native format, Homan, Aupair and ABSP grid formats), and have your tournament directors e-mail the appropriate reports to your ratings officer. If you can persuade your ratings officer to post current ratings online, your directors can use the “`USERATINGS`” command.

## Automated Ratings Systems

Example users: NASPA

If you have a large rating system or like automation, you should set up (or ask John Chew to set up) a web page to which your tournament directors can upload ratings data using the “`SUBMIT`” command. Once it’s uploaded, your web site may immediately calculate new ratings and make them available for download to the “`USERATINGS`” command, or it may hold them for manual verification, as NASPA currently does.

# Team Play using tsh

Managing team tournaments with tsh.

This section discusses specific issues related to running team tournaments using tsh and may safely be ignored if your tournament does not have teams.

## What is a Team Tournament?

A team tournament is one in which each player may be affiliated with a team for the purposes of calculating pairings and standings. Don’t confuse teams with what tsh calls classes or prize groups, which are used solely for calculating prize eligibility.

There are two types of team tournaments, which tsh handles in the same way, except that some commands will not work very well with one type or the other. In some team tournaments, such as the World Championships, you will want to avoid having players from the same team play each other under some circumstances, and you will want to report on team standings, but your event is otherwise essentially an individual one. In others, such as interclub matches, the entire pairing schedule is based on who is on which team, and individual results are secondary to team results.

## Setting up a Team Tournament

To begin, you will need to manually designate who is on which team. You do so by adding an extension field to your “.t” files. Here is a very short example.

    Man, Anpan   2000 ; ; team Good
    Ojisan, Jam  1500 ; ; team Good
    Man, Baikin  2000 ; ; team Evil
    Chan, Dokin  1800 ; ; team Evil

In your configuration file, you may want to use the “`config initial_exagony`” option to specify that teammates do not play each other in the first rounds (as at the Worlds), or the “`config exagony`” option to specify that they should never do so. You should probably use the “`config show_teams`” option to specify that team names should be displayed along with player names where appropriate. You may want to have a prize configuration line awarding prizes for best team records.

## Team Tournament Pairings

Most pairing commands that pair players in a single command will respect the exagony configuration options. These include the more commonly used commands: “`ChewPair`”, “`KOTH`”, “`NewSwiss`” “`PairQuartiles`”.

Unless otherwise indicated, commands which pair multiple rounds do not currently obey the exagony configuration options. These include the more commonly used commands: “`InitFontes`” and “`RoundRobin`”.

If you want something like initial Fontes pairings, you can use automatic pairings to specify three rounds of quartile pairings, pairing the top quartile successively with the bottom, third and second quartiles. This will differ from initial Fontes pairings in that the pairings in those three rounds are independent and will typically not consist of round-robin groups of four; they will resemble initial Fontes pairings in that each player will face opposition of collectively similar strength.

The usual round robin pairings are of course incompatible with team tournaments. Instead, you can use the “`TeamRoundRobin`” command to generate team round robin pairings: those in which each player plays everyone on every other team.

## Team Tournament Reports

If you use the “`config show_teams`” configuration option, then regular report-generating commands like “`RATings`” will display team names where player numbers are shown after player names. In the example above, you might see “`Man, Anpan (#1/Good)`”. If you use this example, it's a good idea to keep team names short: if your teams are countries, you could use ISO 3166-1 alpha-3 codes.

In addition to the usual tsh commands, you may wish to use the “`TeamStandings`” command to report on team standings on a division by division basis, or the “`TotalTeamStandings`” command to do so for the tournament as a whole.

## Caveat

A large majority of events run using tsh are not team tournaments. Please be sure to use the “`DRYRUN`” command before your event to make sure that tsh does what you want it to do, and contact John Chew well in advance of your event if you need new features added.

# What’s New in tsh

A chronological list of changes to tsh.

Changes are made to tsh for just about every tournament at which it is used. This means two things: firstly, you should be sure to update to the most recent version before your tournament; and secondly, if there’s a feature that you’d like added please be sure to mention it, preferably with about a month’s lead time.

Version | Event | Changes
--- | --- | ---
3.340 | Development |
3.330 | 2015 NASSC | The “`Addscore`” command will complain specifically if you enter an invalid player number. (Steve Perry) “`RANDomscores`” will not crash if you specify ratings with leading zeroes (Jack Hoch). The OS/X launcher works even if you manage to deselect it before it runs (Jack Hoch). The “`TWEET`” command works when there are more rounds paired than scored, does not run if the round is incompletely scored, and gives more data again (Vince Castellano). The “`RATings`” command works correctly even when only some players have classes (Jack Hoch). “`ShowPairings`” command now generates team pairing reports if “`show_teams`” configuration option is in effect. “`Addscore`” command division-switching data entry bug introduced in last version corrected. Added new “`config fat_tweets = 1`” configuration option for Facebook posting (Vince Castellano). Added new “`config next_round_style = 'brief'`” configuration option for adjusting reporting of next round in rating reports (Vince Castellano). Added new “`config player_id_first = 1`” configuration option for specifying player ID appearing ahead of name (Vince Castellano). Added new “`config scorecards_refresh = 1`” configuration option for browser refresh of scorecards (Vince Castellano). Added new “`config standings_hotlink = 1`” configuration option for linking standing reports to scorecards (Vince Castellano). Added new “`config standings_with_ratings = 1`” configuration option for displaying ratings even in standing reports (Vince Castellano). “`RANDomscores`” now uses normally distributed scores for Glixo/Elo-rated events. Initial round robins are not generated in default pairings after the first round, nor are they triggered in an unpaired division if you ask for pairings for a round after the first (Roy Kading). “`config roster_order = 'seed'`” configuration option added, sorts roster players in seed order. Added new command “`COMMentary`” to automatically generate event commentary (John Chew). Added new command “`TWeetPairings`” to automatically tweet pairings (John Chew). Added new “`config alpha_rating_file = 'winter-fruit.txt'`”, “`config alpha_rating_minimum = 0`” and “`config alpha_rating_maximum = 2300`” configuration option for fruit ratings (Winter). Tinkered with initial round robin/schedule logic. (John Chew) Added new command “`MIRROR`” to launch mirror-ftp in another window (John Chew). Added new command “`ShowNextPairings`” to show next pairings after current ones (Vince Castellano). “`util/mirror-ftp`” uses more modern command-line option parsing. Added new “`config team_rank_count_cap = 5`” configuration option for limiting number of ranks that count toward team standings. Improved “`UpdatePLAYers`” command’s to set player classes without reload (Jason Broersma) Corrected bug in Glixo rating code that would occasionally cause divide-by-zeroes. Corrected usage of verb "un-pair" to indicate unacceptability in Scrabble lexica (Mauro Pratesi). “`EnhancedScoreBoard`” command substantially rewritten, includes new control panel with several new settings. Added new command “`STOPMirror`” to stop mirror-ftp (John Chew). Added new “`config htm_doctype = ''`” configuration option for specifying the HTML doctype of generated reports. Added new “`config scoreboard_links= ''`” configuration option to enable HTML links between players in scoreboard scorecards.
3.320 | 2013 SCT | “`config interleave_rr = 1`” specifies that multiple round robins be interleaved, not paired with players playing each other repeatedly, for directors that like to slow down their schedule (Ryan Fischer). Added new command “`LISTTourneys`” to list your pending unrated NASPA tournaments (Ryan Fischer). “`EnhancedScoreBoard`” command now shows division name in multidivision events (Andy Saunders). Guelph pairing system (“`config pairing_system = 'guelph'`”) now works for six or ten players (Andy Saunders). Added new pairing system (“`config pairing_system = 'none'`”) for Sudoku tournaments (Ravee Joradol). Added new “`config realm = 'sudoku'`” (Amnuay Ploysangngam). It's easier to suppress index entries with CSS now. (Tim Fukawa-Connelly) Added new “`config zero_byes_tie = 1`” (Friedrich Engelke). Added more Norwegian vocabulary (Taral Seierstad). Added new “`config realm = 'naspa-csw'`” (John Chew). The “`KOTH`” command no longer crashes if called partway through data entry (Dan Stock). “`util/mirror-ftp`” reports the target host when a connection fails. Update scripts do not create empty files on download failure (Joel Sherman). “`ShowPairings`” command rewritten for code clarity, minor cosmetic improvements. “`TeamRoundRobin`” command works for even numbers of teams greater than two (Igho Fregene). “`config tables = [1..5]`” is deprecated, but no longer crashes when the division is omitted in a single-division tournament (Andy Saunders). Many reports have alternate lines shaded using CSS, more will follow (Taral Seierstad). “`PairQuartiles`” pairing command works better now when number of players is not divisible by four. “`config realm = 'pol'`” added (Adam Klimont). “`config sum_before_spread = 1`” specifies that players should be ranked on W-L, then total points scored, then spread, is default in Poland (Adam Klimont). “`tfile_encoding = 'utf8'`” specifies that ‘.t’ files should be read in the utf8 encoding, not isolatin1 (Adam Klimont). “`message_encoding = 'utf8'`” specifies that international terminology files should be read in the utf8 encoding, not isolatin1 (Adam Klimont). Added new “`encoding`” configuration directive for changing the character encoding of the remainder of the configuration file. “`config realm = 'absp'`” now specifies `config no_index_tally_slips = 1`” (Rick Blakeway). The value of the config hook_division_complete{'A'} configuration option is now parsed for expressions involving $d and $r, which are replaced respectively by the division and round number that have just completed (Rick Blakeway). Added new “`DivisionComplete`” command that manually triggers the commands given in the config hook_division_complete configuration option, for use after corrections are made to a division (Rick Blakeway). Added new “`config realm = 'naspa'`” (Dallas Johnson). Added new “`config realm = 'naspa-lct'`” (Dallas Johnson). “`config rating_system = 'naspa'`” is translated internally to “`config rating_system = 'nsa2008'`”, likewise for LCT rating system. Some configuration values that must be lists are now ignored if another data type is given instead (Mike Frentz). Added “`seat`” extension field in preparation for Thai school pairings (Ravee Joradol). Added new “`config index_top_extras = {'label' => 'URL', ...}`” configuration option for adding links to the top of the coverage index (Nawapadol Sayavesa). Corrected Collins lexicon, removing RECOLOUR+ and URIBILINOGEN+. (Rowan Webb). Corrected “`UpdatePLAYers`” command’s auto-capitalisation of “Mack”(Andy Saunders) Added new command “`HighRatingChanges`” to prepare new report (Jared Robinson). The “`PRiZes`” command can now compute highratingchange prizes (Jared Robinson). The “`AVErages`” command defaults to showing all players, not top 20 (Ross Brown). “`GUELPH`” pairings corrected for 6- and 10-player divisions (Brett Constantine). Improved documentation print formatting (Joe Petree). Added new “`config rating_fields = [qw(rank newr name team)]`” configuration option for customizing rating reports (Ravee Joradol). Added new “`config seats = 1`” configuration option for enabling seat number display (Ravee Joradol). Added new “`config no_random = 1`” configuration option for disabling random tie-breaks of players tied in standings (Ravee Joradol). Added new “`config top_down_swiss = 1`” configuration option for bidirectional optimization of Swiss pairings (Ravee Joradol). Added new “`config show_inactive = 1`” configuration option for displaying inactive players in rating lists (Ravee Joradol). “`config realm = 'pol'`” now sets “`config all_byes_tie = 1`” and “`config bye_spread = 300`” (Adam Klimont). The “`Addscore`” command will automatically enter bye scores if it looks like it can safely do so (Chris Cree). “`note`” prize type added. Configuration error reporting is a skosh clearer (Scott Jackson). Bug fixes for events with capped spread (Vince Castellano). CSS body class identifies division (Ross Brown). “`InitFontes`” round-off error that caused bad pairings for some large schedules fixed (Ryan Fischer). Corrected text output of “`ROSTERS`” command (Ross Brown). “`EnhancedScoreBoard`” renders better now in iOS Safari. “`config gibson_spread = [250,175,150]`” configuration option added. “`config no_boards = 0`” enables display of boards, when using tables (Chris Lennon). Added new command “`AssignTeamsSnaked`” to support SWILLLNS pairings (Chris Cree). Added new command “`TeamMultipleRoundRobin`” to support SWILLLNS pairings (Chris Cree). The “`Addscore`” command lets you enter scores separated by dots again (Reese Daniel). “`config alpha_pair_first_page_break = 10` ” specifies the number of pairings to show on the first page of alpha pairings, if it differs from subsequent pages. (Dan Stock) A plug-in architecture has been developed and implemented. Some features will be excluded from the general distribution, usually because they are of limited interest. “`EnhancedScoreBoard`” features a compact display mode, dims moving boxes. The “`Addscore`” command accepts reentered scores with a warning. “`ChewPair`” command is affected by a new configuration parameter config chew_no_swiss_all = 1, which overrides the default behaviour of switching to Swiss pairing when all unpaired players are contenders (useful if the top players have been left unpaired for more accurate pairings). The “`EXPORTRATINGS`” and “`USERATINGS`” commands support a CSV-style file header specifying field order. The “`LOOK`” command supports CSW2012, no longer supports SOWPODS2003. Added new command “`PROFILE`” to edit persistent configuration options. “`config auto_koth_repeats = 2`” says that any final KOTH rounds forced in Chew pairings will have the specified number of repeats rather than the default unlimited (Llewellin Jegel) The “`PRiZes`” command correctly handles ties in exclusive prizes (Tony Leah). “`config html_index_recent_first = 1`” lists the most recent rounds at the top of the index page, instead of the oldest. “`util/mirror-ftp`” no longer fails if it temporarily loses its Internet connection in the middle of an upload. “`config bracket_prelims = 3`” specifies three rounds of preliminary InitFontes pairings before brackets begin. Added new command “`LowSpread`” to list games with lowest spread. Made substantial cosmetic changes to HTML index appearance. The “`AUPAIR`” command combines multi-division tournaments into one file (Bob Jackman). “`config swiss_order = 'koth'`” changes the ordering of pairings within Swiss win groups to KOTH (Llewellin Jegels). “`Internationalization changes affecting mainly Polish users (Adam Klimont).` “`config round_robin_order`” also applies, with slightly different syntax, to team round robins. (Jason Keller) “`ChewPair`” command works better with Polish-style sum rankings (Adam Klimont). Added “`initrec`” extension field to support tournaments in which a player may arrive with a prior record of wins, losses, spread, capped spread or score sum (Ravee Joradol, Adam Klimont). Added new command “`setESBMeSsaGE`” to display announcements on the scoreboard (Vince Castellano). “`PairQuartiles`” pairing command draws more randomly (Ross Brown). Added new command “`RoundClassRATings`” (Craig Beevers). “`config html_suffix = '.shtml'`” changes default suffix for created HTML files. The “`AUPAIR`” command conforms to Aardvark standards for forfeits and byes (Elie Dangoor). Impossible exagony is detected and reported rather than freezing (Muraguri Peter). “`config swiss_order = ['id','koth']`” is now of type array (Llewellin Jegels). Tweeting is now possible again for the first time since Twitter changed its security system, but with a different configuration command. You'll need to install your own command-line twitter tool (I like ttytter on OS X) and then name it like this “`config twitter_command = 'ttytter -silent -status="%s"'`” (John Chew). Added “`twitter`” extension field for identifying a player's Twitter handle. “`config rating_system = 'aus'`” no longer enables acceleration or feedback points (Vali Muhammad Bhaila). “`EnhancedScoreBoard`” command has new Blink mode, autohides controls, and buttons to move more quickly up and down the ranks. “`config realm = 'pak'`” has a 500-point rating floor (Vali Muhammad Bhaila). Added “`AverageOpponentScores`” command (Brian Bowman). Utility code changes for more robust file saving and mirroring in Windows (Chris Wiegand) “`overseed`” prize type now has a tie-break of final player rank (Pramit Kamath). “`config show_honourable_mention = 1`” configuration option added, shows honourable mentions in prize reports (Vince Castellano). “`config roster_order = 'alpha'`” configuration option added, sorts roster players in alphabetical order “`config roster_order = 'team'`” configuration option added, sorts roster players in team order (Vali Muhammad Bhaila) Added “`config entry_tags = { 'c' => 'csw', 'csw' => 'csw', 't' => 'twl', 'twl' => 'twl'}`” configuration option for tagging games by lexicon (Winter). Added “`config entry = 'tagged'`” entry system for tagged games (Winter). Gibsonization now respects “`config exagony = 1`” configuration option (Lisa Kessler). Enhanced scoreboard works even when reloaded in recent versions of Google Chrome with the XHR caching bug (Lisa Kessler). Enhanced scoreboard handles showing games recorded against inactive opponents without error (Lisa Kessler). “`config initial_schedule`” value may be any positive integer up to a full round robin length. “`config initial_schedule`” value may be any positive integer (Vince Castellano). Using pairing commands to pair players due to go first (or second) with each other will cause an adjustment of firsts/seconds (Vince Castellano). Hooks are no longer reentrant (Vince Castellano). When switching enhanced scoreboard to normal mode, rows are reduced to 10 (formerly 5) if necessary (Vince Castellano). Added “`config esb_geometry{'A'} = [[5,6,0]]`” configuration parameter for specifying enhanced scoreboard geometry (Vince Castellano). Added “`config standings_refresh = 10`” configuration parameter for specifying how often standings files should refresh in browser (Vince Castellano). Added “`config unfair_byes = 1`” configuration parameter for specifying that byes should always be awarded based on standing, not number of byes already awarded (Ravee Joradol). Rating reports now give first/second and location assignments for next rounds if known. “`InitFontes`” now does multiples of round robin lengths too. Better handling of non-Unicode consoles (Ravee Joradol). The “`EditScores`” command no longer exits on garbled input. Added new command “`BUGreport`” to email tournament data and a note to John Chew.
3.310 | 2010 European Open | “`ChewPair`” command works with exagony. Bye assignment works better with exagony. Added experimental new “`begin`” configuration directive for giving commands to run at the beginning of each session. “`EnhancedScoreBoard`” command works better with Kingston Cup. The “`Addscore`” command lets you enter scores that look like byes or forfeits if you are in spread entry mode. The “`LOOK`” command reports how many words were correct if “`config count_good_words = 1`” is in effect. The “`PRiZes`” command can now compute luckystiff prizes (Dave Kulansky). Added support for the new NASPA CSW rating system. “`ChewPair`” command correctly handles the situation where the third-ranked player has clinched a place in the top three and might still make it to second (Rajiv Antao). Added G. Vince Castellano’s TSH QuickStart. Added informal description of Chew pairings (Carla Cree). “`ShowPairings`” command creates tally slips as an experimental side effect (Andy Saunders). Added new command “`ForfeitLOSS`” to simply the process of entering a forfeit loss (Ryan Fischer). Added experimental new command “`FIX`” for graphically editing scorecard. Tweaked the “`TotalTeamStandings`” command. Combined realm-dependent CSS stylesheets into one master stylesheet. “`config exagony = [1,2,3]`” alternate syntax now lists rounds with exagony. “`showWallChart`” displays teams (Vince Castellano). Added experimental new command “`VALET`” for entering game results at table-side. Added “`config no_index_tally_slips = 1`”, suppresses listing of tally slips in event web coverage index (Heinz-Jürgen Michel) “`EnhancedScoreBoard`” command is internationalized for German (Heinz-Jürgen Michel). “`EnhancedScoreBoard`” command can now scroll much more slowly (Andy Saunders). “`EnhancedScoreBoard`” command works with capped spread. “`config spread_cap`” can now be set to a list of values. “`config show_roster_classes = 1`” configuration option displays player classes in tournament rosters. “`ROSTERS`” command shows a lot more information now. Improved “`UpdatePLAYers`” command to better cope with errors in cross-tables.com data (Andy Saunders) The “`NAST`” command features the newer pairings for seven and eight rounds (Steve Pellinen). ‘photos.txt’ may contain blank lines (Heinz-Jürgen Michel) “`STATisticS`” command is internationalized for German users (Heinz-Jürgen Michel). Added “`config locale`” configuration option to control collation order. Added new “`config realm = 'pak'`” (Waseem Khatri). “`UPDATEPIX`” command now only loads photos in database specified by current realm. Added new “`config realm = 'go'`” (Willemien). “`InitFontes`” now does two-round schedules, as well as any odd. “`config flight_cap`” may now be an array, not just a predefined sub. “`config realm = 'nor'`” added (Taral Seierstad). Round robin pairings now have more balanced starts and replies. “`STATisticS`” command now correctly computes median (Taral Seierstad). Corrected “`UPDATERATINGS`” command’s handling of expired NASPA members (Andy Saunders).
3.300 | WSC 2009 | Documentation cleanup, Team Play section added. The “`AUPAIR`” command omits players who did not play any games from its output (Bob Jackman). The “`Addscore`” command no longer lets you enter scores that look like byes or forfeits without pairing the players appropriately (Nigel Richards). “`config realm = 'thai'`” added, uses Thai rating system, rating list, bye spread, etc. The “`AUPAIR`” command correctly handles players who had byes in divisions that had no-shows (Nigel Richards, Bob Jackman). “`config division_name{'A'} = 'Jim Thorpe Division'`” overrides default division naming convention (Matthew Hodges). “`UPDATERATINGS`” and “`USERATINGS`” commands should now work in ABSP realm. The Elo rating code is more numerically stable when newcomer vs. newcomer games predominate (Rich Engelke). “`config realm = 'deu'`” now specifies the newly created “`config rating_system = 'deu'`” rating system, which includes experimental support for capping ratings of newcomers who have not played established opponents (Rich Engelke). “`config realm = 'deu'`” now specifies a separate value for “`config message_file`” in preparation for UI localisation. Internal rating calculation code no longer emits some spurious warning messages (Tapani Lindgren). The “`Addscore`” command input speed scorekeeping does not crash when a game is entered in zero seconds. Cosmetic changes to make regression tests [a-e]* work again. The “`Addscore`” command input speed scorekeeping does not misbehave when run interactively, outside of a regression test (Bryan Pepper). “`config spread_cap = 350`” limits earnable spread per game and is a Thai realm default (Moomin Doramon). Added “`pname`” extension field to allow names to be printed using Unicode characters not available at the console. Changed parsing of extension fields to permit backslashes to escape backslashes or semicolons, and to disregard ‘#’ comments unless at the beginning of the line (modulo white space). “`Addscore`” command now tries to expand just about anything that doesn't look like a score into a name, including Unicode strings (Charlie Reams, Heinz-Jürgen Michel). Experimental “`config windows_console_unicode = 1`” added, permits the use of non-ASCII characters in player names on a Windows console (Heinz-Jürgen Michel) “`AUPAIR`” command corrects some names from NASPA database spellings to WESPA rating spellings (Bob Jackman). Changes to German lexicon (Friedrich Engelke). Code cleanup to fix regression tests. The “`Addscore`” command no longer accepts dots as synonyms for spaces during data entry. If anyone was actually using this feature, let me know and I’ll make it an option. ‘.t’ files are now assumed to be in the ISO Latin-1 encoding. Experimental “`config use_windows_code_page = 1`” added, enables the use of non-ASCII characters on a Windows console (Heinz-Jürgen Michel) The “`PRiZes`” command allows the “`exclusive`” parameter to specify groups of prizes from which a player is eligible to win at most one. Added new “`PairQuartiles`” pairing command (Philip Nelkon). Added new “`EnhancedScoreBoard`” command. “`TeamStandings`” command displays more statistics (Philip Nelkon). Substantial internal changes to improve performance; ratings and ranks after each round are now cached in division data files.
3.290 | Correction to 3.280 | The “`KOTH`” command now accepts an optional “repeats since round” subparameter to (Hubrecht Luyk). Posted documentation for 3.280.
3.280 | 2009 Toronto SCRABBLE Tournament | “`PRiZes`” command handles ties better (Ross Brown). The “`NAST`” command works with all well-defined seven- and eight-round events (Steve Pellinen). “`config oppless_spread = 1`” indicates that spread calculations should ignore opponent scores (and therefore be just the sum of a player’s own scores (Johann-Georg Dengel). “`separator`” prize type no longer uses up a prize number (Ross Brown). “`showWallChart`” displays paired unscored rounds, supports terminology internationalization (Johann-Georg Dengel). Added “`showRankedWallChart`” command (Johann-Georg Dengel). “`config no_boards = 1`” suppresses only boards, not tables (to avoid tables, don’t use “`config tables`”. The “`absp`” realm now uses “`config entry = 'scores'`” as its default (Stewart Holden). Non-ASCII characters in foreign terminology are reduced to ASCII for console output. “`STandings`” command output looks more like “`RATings`” command output (Johann-Georg Dengel). Changed “`UpdatePLAYers`” command to better cope with errors in cross-tables.com data (Ryan Fischer) Updated “`ABSPgrid`” command, which now combines divisions (all, if none are specified) into one grid. (John Grayson, Stewart Holden) “`PRiZes`” command can now read group members from a file. “`PRiZes`” command group members no longer have to all belong to the same division. Updated “`ROTO`” command, which now accepts an optional round number “`util/mirror-ftp`” no longer gives up if it has no Internet connection. “`ShowPairings`” command correctly places players at tables by rank even when School SCRABBLE capped standings are in effect (Joey Krafchick). The “`currency_symbol`” configuration option can now override the default dollar sign in scoreboards. Tweaked “`ChewPair`” command to improve pairings specifically for 12-round events with 14-18 players. The leader/nonleader split now always includes at least 4 leaders where possible, and the faint hope clause now applies in the penultimate round as well as the last. The “`PairMany`” command now accepts player names (Art Moore). The “`EditScores`” command now lets you manually assign board numbers. The “`PRiZes`” command allows the “`winner`” parameter to override a computed winner, which can be useful in events with a separate finals round. The “`RoundHandiCap`” command reports on King's Cup-style handicaps. The “`ScoreBoard`” command works better when displaying a group that isn't at the top of the field. The “`ScoreBoard`” command has specific knowledge of Thai names, and Malaysian/Singaporean names of Chinese origin, and renders them appropriately. The “`THAICASH`” command reports on King's Cup-style winner's bonuses. The “`config force_koth`” configuration parameter will accept greater values than 1, and set up that many final rounds of KOTH. The “`config player_photo_aspect_ratio`” configuration parameter specifies aspect ratio of player photos (Stewart Holden). The “`SUBMIT`” command now sends data to NASPA, not the NSA. The “`config director_id`”, “`config director_password`” and “`config tournament_id`” configuration parameters have been added and are what are now required for automatic ratings submission to NASPA. The “`UPDATERATINGS`” command works with NASPA ratings (Andy Saunders). The “`USERATINGS`” command warns about player NASPA membership status (Andy Saunders). The “`SUBMIT`” command prompts for a password if it does not find one in the configuration file (not yet tested under Windows) (Andy Saunders). The “`PairMany`” command records firsts and seconds if “`config track_firsts = 1`” is in effect (Mauro Pratesi). The “`AUPAIR`” command omits byes/forfeits rather than faking them as ties if “`config no_aupair_bye_ties = 1`” is in effect (Henry Yeo). The “`SUBMIT`” command prompts for a password if it does not find one in the configuration file, even under Windows (Bryan Pepper). The “`SUBMIT`” command generates a complete all.tsh file even if the network connection fails (Carole Denton). The new “`GREEN`” command generates 6-round pairings for 6-8 players as specified by John C. Green (John C. Green). The “`Addscore`” command does not abort as often on incorrect input (Andy Saunders). The “`USERATINGS`” command correctly handles the case where a player has a rating in the data file but not in the rating list. The “`EditScores`” command now lets you assign spread penalties (Andy Saunders). The “`config final_draw = 1`” option specifies that even when firsts and seconds are assigned, players with even records in the last round will be instructed to draw randomly to see who starts (Ian Weinstein). “`config rating_system = 'thai'`” gives a rating system equivalent to NSA 2008 that does not count tie games (Ravee Joradol). The “`Addscore`” command keeps track of input speed. The “`EXPORTRATINGS`” command exports a new rating list, for those using tsh to maintain a rating system (Ravee Joradol). The “`USERATINGS`” command warns about suspended player NASPA membership status (JC Green). Trying to use “`config force_koth`” with automatic pairings gives an error message, may abort tsh in future (Bryan Pepper). The “`SUBMIT`” command works with nonstandard filenames (Dave Johnson). “`RATings`” command now does not show the rating difference column for ABSP users (Stewart Holden). “`ScoreBoard`” command does not include future rounds in counting repeats (John O'Laughlin). Cosmetic improvements to the “`ScoreBoard`” command (Ross Brown). Cosmetic improvements to cross-tables, scorecards and wall charts.
3.270 | Toronto School SCRABBLE Championship | “`util/mirror-ftp`” is easy to configure (Jared Robinson). The “`EditScores`” command now lets you edit byes (Dallas Johnson). The “`NAST`” command works with five-round events (Sherrie Saint John). “`config rating_system = 'elo'`” indicates that Elo ratings should be computed without NSA bugs. Many more NSA rating system bugs are more correctly duplicated. “`config rating_list = 'deu'`” specifies the use of the German ratings list. “`UPSETs`” command displays decimal ratings differences correctly (Stewart Holden). Improved “`ChewPair`” command, applies pairings cap to players within one win of last prize in the last round, effectively extending the KOTH group in the default situation. “`PRiZes`” command can now compute prizes based on results of a selected range of rounds. “`ScoreBoard`” command displays team flags if available, design improvements. new rating systems and rating lists, details to follow. “`config realm = 'deu'`” added, uses German ratings list, rating system and some terminology in common reports (Heinz-Jürgen Michel). “`config rating_system = 'wespa'`” specifies the use of the WESPA rating system. “`config rating_system = 'aus'`” specifies the use of the Australian rating system. “`config rating_system = 'nsa2008'`” specifies the use of the new NSA rating system. “`config gibson = 'strict'`” pairs Gibsons with the highest player out of contention, no matter how many times they have played the Gibson (Jim Hughes). “`util/mirror-ftp`” automatically copies tsh reports to an FTP server whenever they change. “`Addscore`” command correctly reports updated win total on entering a scoreless bye (Stewart Holden). Added new command “`GUELPH`” to support new pairing system (“`config pairing_system = 'guelph'`”) used in Guelph, Ontario, Canada (Andy Saunders). Corrected the calculation of local club ratings that change across multiplier boundaries. Corrected the calculation of ABSP ratings in nonfinal rounds. HTTP clients now try to reconnect 25 times rather than giving up right away. Computed new ratings are saved in .t files (as newr). Ratings for the default 'nsa' realm are now computed using the new logistic rating curve. Fixed bugs in “`UpdatePLAYers`” command (Andy Saunders) Fixed bug in bye-assignment algorithm that could cause a crash if data files were manually edited outside of tsh (Rajiv Antao). “`ScoreBoard`” command correctly displays half-win banners (Ross Brown). “`ScoreBoard`” command respects “`config no_boards = 1`” (Ross Brown). “`config hook_division_update = 'command1;command2;...'`” fires on any update of any division data file (Ross Brown). Corrected “`SUBMIT`” command to handle configuration files that do not end in a newline character (Carla Cree). “`util/mirror-ftp`” can be run from its subdirectory (Stewart Holden). “`HighCombined`” command shows classes for both players (Stewart Holden). “`UpdatePLAYers`” complains and does not try to update data files if cross-tables.com returns an error message (Ryan Fischer). “`util/mirror-ftp.bat`” added for Windows users (Stewart Holden). Negative prize ranks count from the bottom of the field (Ryan Fischer). “`util/mirror-ftp`” syntax changed to permit specifying both username/password and event list on command line (Andy Saunders). Corrected two serious bugs in the “`KOTH`” command that could cause incorrect pairings in divisions with odd numbers of players, and failure to detect Gibsonization (Stewart Holden). “`ChewPair`” command now works better with “`config exagony = 1`” (Ryan Fischer). Added “`config html_index_bottom`” and “`config html_bottom`”, to offer customisation of web report footers (Ryan Fischer). Added “`config custom_stylesheet`” to specify an event-specific CSS stylesheet to override defaults in the standard tsh stylesheet (Ryan Fischer). Corrected a bug in the “`ChewPair`” command that caused rare crashes during Gibsonisation (Ryan Fischer). “`RANDomscores`” generates reasonable scores for ABSP divisions even when the ratings are unreasonable (Ryan Fischer). Cleaned up and documented the “`overseed`” prize type (Ryan Fischer). Added the “`separator`” prize type (Ryan Fischer). “`PRiZes`” outputs a blank prize chart if run at the beginning of the tournament (Ryan Fischer). Added “`BRACKetpair`” command and “`config bracket_order`”, “`config pairing_system = 'bracket'`” and “`config bracket_repeats = 3`” configuration options to support single-elimination pairings (Jason Idalski). Corrected a bug in format of POSTed data in HTTP client code. Added “`password`” extension field in preparation for self-service scoring. Added the “`TWEET`” command and the config twitter_username, config twitter_password, config twitter_prefix and config hook_division_complete{'A'} configuration options. Added the “`TotalTeamStandings`” command to list total standings for a team with members in multiple divisions. Added the “`totalteam`” prize type. “`ScoreBoard`” command displays players out of contention in blue (Ross Brown, implemented by Ross Brown).
3.260 | 2008 Big Apple ST | Added “`config division_rating_system{'A'} = 'none'`” which overrides “`config rating_system`” on a per-division basis (Andy Saunders). Removed “`config max_name_length`”, which is no longer necessary as all tables are dynamically formatted. Removed “`config name_format`”, which is no longer necessary as all tables are dynamically formatted. “`RESETEVERYTHING`” also deletes ‘prizes.doc’ (Brad Mills). “`RoundRATings`” command now uses vulgar fractions, correctly handles empty divisions, correctly handles “`config no_boards = 1`”. “`ShowPairings`” command now correctly handles “`config no_boards = 1`”. Commands triggered by hooks do not change which report “`BrowseLast`” displays. “`config avoid_sr_runs = 1`” is now the default setting in the ABSP realm (Paul Thomson). Added experimental new command “`UpdatePLAYers`”, which uses the new configuration variable “`config cross_tables_id`” to choose and download a player roster from cross-tables.com.
3.250 | 2008 MWMST | The “`EditScores`” command now lets you set a player’s life games total (necessary for accurate computation of NSA ratings) using the “`GAMES`” keyword (Leonora Labog). Added “`BASDSemi`” and “`BASDFinal`” commands, and “`config pairing_system = 'basd'`” configuration option (Ira Freehof). Added “`config round_robin_order`”, which lets you explicitly specify a nonstandard order for the top player’s opponents in a round robin (Ira Freehof). Corrected some serious issues affecting Gibsonization mainly for UK directors (Richard Blakeway). Corrected some less serious issues affecting Gibsonization: tsh could crash if all players in a division were involved in Gibsonization, especially in a small division (Richard Blakeway). Adjusted the threshold at which tsh will refuse to merge contenders and (six or fewer) contenders (who cannot be paired without repeats) from C≤NC to C≤2NC (Ryan Fischer). “`EditScores`” can be invoked on any paired round, not just a scored rond. “`PRiZes`” command now has new “`class`” extra item for designating class prize eligibility. Redesigned the “`ScoreBoard`” command and added the config hook_autopair configuration option. NSA ratings computed while results are being entered are no longer computed incorrectly for players whose results have not yet been entered (Sal Desiato). “`ShowPairings`” used to not show pairings immediately after computing them if everyone was a gibson, a victim or a bye. “`TeamRoundRobin`” command works if one team has one less player than the other (Mike Frentz).
Version | Event | Changes
3.240 | US NSC 2008 | “`showScoreCard`” command indicates repeat pairings (Stewart Holden) Added “`TeamRoundRobin`” command. Corrected “`SUBMIT`” command to handle .t files with missing final newlines (Brett Constantine). Improved “`ChewPair`” command, runs faster for large divisions by doing even fewer unnecessary best-possible-finish computations. “`CheckRoundScores`” command no longer displays inactive players. Added “`config html_index_top`”, which provides an alternate HTML heading to be used for the Event Coverage Index. Added “`config bye_firsts = 'alternate'`”, to support new NSA scheme for assigning firsts and seconds to players who have had byes, is now default for realm 'nsa'. “`Addscore`” command no longer cares if you put extra zeroes in front of player numbers (Jeremy Brooke). “`PRiZes`” command now has a relatively easy configuration syntax and supports several new prizes for the NSC. “`HighRoundLosses`” command replaces earlier “`high-loss-round`” external command (Jeremy Brooke). “`HighRoundWins`” command replaces earlier “`high-win-round`” external command (Jeremy Brooke). Regression testing works better under Windows now. Added “`config mirror_directories = [qw(path1 path2)]`”, to automatically copy ‘.t’ files to other directories. The “`EditScores`” and “`EditScores`” commands no longer display division names with player numbers if there is only one division in the event (Jeremy Brooke). An error is reported at run time if a division has an odd number of active (formerly active or inactive) players (Jeremy Brooke). “`DELETEscore`” command can now be used to delete byes, giving an opponent number of 0 (Jeremy Brooke). “`UnPairRound`” command works correctly with players who have a scored bye in the round being unpaired (Jeremy Brooke). “`UPDATE`” command is now internal, should no longer fail to report its progress for Windows Users (Jeremy Brooke). “`ShowPairings`” alpha pairings indicate firsts and seconds more clearly (Mary Rhoades). “`UPDATEPIX`” command is now internal and has lost its hyphen. “`RoundRATings`” command now accepts a range of rounds to compute (Jeremy Brooke). “`SHOW12`” command is now internal and slightly enhanced (Jeremy Brooke). Pairings commands now correctly detect triple Gibsonization (Bryan Pepper). “`STATisticS`” command reports total number of points scored and games played (Patty Hocker). Added “`UPDATERATINGS`” command (Jeremy Brooke). Added “`USERATINGS`” command (Jeremy Brooke). “`config initial_snaked = 1`” behaviour corrected in case where you are just one player short of the right number (Johann-Georg Dengel).
3.230 | 2008 CNSC, BAT, etc. | “`Addscore`” command largely rewritten, now accepts ‘.’ as equivalent to ‘ ’ (space) to facilitate numeric keypad data entry, reports computed spread when entering scores, also supports new “`config entry = 'both'`” to require the entry of entry of both scores and spread. Fixed a bug that could cause tsh to crash if it tried to pair an empty flight, as could happen if all players were part of a Gibsonisation process (Ryan Fischer). “`config gibson_class = 'A'`” restricts Gibson opponents to the named class (Stewart Holden). The U.K. now has a separate player photo database (Stewart Holden). Added the “`ScoreBoard`” command and the config hook_addscore_flush configuration option that enables its automatic invocation. Corrected recently introduced serious errors in “`ChewPair`” affecting default flight cap pairing in final round, and late rounds with odd numbers of contenders. “`HighWin`” and similar commands now display player classes if available. “`config initial_snaked = 1`” causes “`InitFontes`” to snake players boustrophedonically into groups, rather than assigning them randomly by quartile (Yeo Kien Hung). “`config standings_spread_cap = [100, 150, 250, 250, 250, 250]`” caps allowed spread per round for standings purposes, for the U.S. NSSC. “`config alpha_pair_single_column = 1`” displays alpha pairings in one column (Ben Greenwood). “`ChewPair`” runs a little faster now by not checking Gibsonization below last prize rank. Division names appearing in configuration variables can be in lower case. (Mary Rhoades) The “`ScoreBoard`” command no longer gives spurious error messages if invoked with no arguments (Ryan Fischer). Multiple commands may now be entered on a line, separated by semicolons. Added experimental “`LowerRoundRobins`” command to implement a very poorly thought out pairing system, formerly popular at the U.S. NSC (Kien Hung Yeo, Chris Lennon). Fixed a bug that caused “`ChewPair`” to crash if scores for the previous round were entered before Fontes pairings were generated (Mary Rhoades). Added “`ROSTERS`” command (Mary Rhoades). Altered “`ChewPair`” to raise the threshold from four to six at which a number of noncontenders forced to repeat pairings by being prevented from playing with contenders are allowed to play with them after all (Mary Rhoades). “`ShowPairings`” now mentions repeat pairings (Mary Rhoades). Fixed a bug in “`ChewPair`” that would cause it to hang if the top flight had to include someone who couldn't catch up to the player above them (Mary Rhoades). Corrected “`AUPAIR`” CR LF problem (Yeo Kien Hung). “`config rating_system = 'none'`” indicates that no ratings should be calculated (Karey Heard). Corrected “`STATistics`” command to run correctly when division names are numerical (Karey Heard).
3.220 | 2008 Dallas Open | “`STATisticS`” command now invokes all other statistics commands (Stewart Holden). “`config assign_firsts = 1`”, “`config html_in_event_directory = 1`” “`config track_firsts = 1`” are now default in ABSP realm (Stewart Holden). Corrected “`AUPAIR`” to handle ties correctly (Bob Jackman). Some browsers were not correctly rendering empty cells in tabular reports. (Ricky Purnomo). “`ChewPair`” was incorrectly estimating contention in many cases, resulting in unnecessary late round repeats (Stewart Holden). “`ChewPair`” now checks to see if four non-contenders can't be paired without repeats, not just two (Glenn Dunlop). Added “`config avoid_sr_runs = 1`”, which tries to minimise runs of starts and replies before randomly assigning them to players whose records are equal. Experimental Linux browser support added (Prithwiraj Mukherjee). “`RESETEVERYTHING`” was incorrectly deleting ‘tsh.css’ (Ryan Fischer, issue 86). “`config no_initial_rr = 1`” tells Chew pairings not to start with initial round robins, even if there are enough rounds to do so (Stewart Holden). Rewrote round robin code to use Berger schedule. “`InitFontes`” now accepts any odd number as its first parameter, not just three (Stewart Holden). “`FactorPair`” supports Gibsonization (Carla Cree). Ratings no longer have to be whole numbers (Stewart Holden). “`config random_rr_order = 1`” puts round robin pairings in random order (Ronan Webb). “`STATisticS`” command suppresses meaningless figures depending on “`config assign_firsts`” and “`config track_firsts`”(Stewart Holden). The HTML index will include possibly blank rows for each round if “`config max_rounds`” is set (Stewart Holden). “`ChewPair`” command works much faster now in large divisions by truncating the search for contenders at the flight cap. “`PRiZes`” command calculates upsets automatically. “`STATisticS`” command correctly calculates stronger player winning percentage even when players are numbered alphabetically (Stewart Holden). “`STATisticS`” command hides output from invoked commands. Scorecards displayed on-screen do not include empty rows for rounds not yet played.
3.210 | WSC 2007 | “`config initial_random = 1`” added, specifies one initial round of random pairings when automatic pairings are in effect. “`ShowPairings`” command now displays or suppresses start/reply data depending on configuration settings, no longer relies on user to edit ‘tsh.css’ (Sherrie Saint John). “`ShowPairings`” command no longer tries to make two columns if player photos are being shown. “`CheckRoundScores`” command displays player names. “`config check_by_winner = 1`” added, specifies checking of scores by winner even when starts and replies are being tracked. “`TeamStandings`” command displays more statistics. Added “`RESETEVERYTHING`” command to reset everything (Stewart Holden). Added “`NAST`” command to do NAST pairings. Added “`config pairing_system = 'nast'`” for North American Scrabble Tour events. Added “`config show_last_player_name = 1`” to show last player name and not just ID in ratings reports (Jim Hughes). Added “`config no_boards = 1`” to completely suppress boards (Ricky Purnomo). “`SUBMIT`” command opens browser window to payment screen (Jim Hughes).
3.200 | 2007 Big Apple ST | “`config realm = 'sgp'`” added, suppresses errors about lack of comma in player names in “`AUPAIR`”. Added “`config surname_last = 1`”, is default in ABSP realm (Stewart Holden, issue 8). Added “`config sort_by_first_name = 1`” which sorts alpha pairings by first name, when “`config surname_last = 1`” is in effect. An ActivePerl bug that closed that sometimes standard output filehandle when forking a browser process has been worked around by saving and restoring the handle. (Stewart Holden, issue 68). Added “`DRYrun`” command that simulates one run of a tournament for a division. Added “`config max_div_rounds{'A'} = 5`” which overrides “`config max_rounds`” on a per-division basis (Ricky Purnomo). “`Addscore`”, now accepts player names without commas. (Ricky Purnomo). Added “`config no_ranked_pairings = 1`” to display only alphabetical pairings tables (Stewart Holden, issue 4). Fixed a problem with “`HighLoss`” and similar commands (Stewart Holden, issue 79).
3.190 | September 2007 Toronto 2007 UK NSC Semi-Finals | “`Addscore`”, was complaining too much about scores when “`config entry = 'spread'`”. (Reported by Stewart Holden). Added “`SPITroast`” command for UK-style rotisserie pools (Evan Simpson, issue 6). Added “`STATisticS`” command for generating summary statistics for a tournament. “`MISSing`” now accepts an optional second argument, a division name (Stewart Holden, issue 5). “`RANDomscores`” ABSP-unrated player score distribution bug fixed (Stewart Holden, issue 43). “`KOTH`” and other standard pairings commands honour “`config gibson=1`”(Stewart Holden, issue 33). “`config prize_bands`” defaults to one quarter of division size, not one. Added “`luckySTIFF`” command as opposite for TUFFluck (Stewart Holden). Added “`SPITroast`” command for UK-style rotisserie pools (Evan Simpson, issue 6). ‘tsh.css’ is now copied to the event directory when “`config html_in_event_directory = 1`” is in effect. (Stewart Holden, issue 62). Corrected “`AUPAIR`” to handle byes correctly (Barry Harridge, issue 63). Massive code changes made to support simultaneous (multithreaded) operation of the web server and command-line interface. Regression testing implemented, see ‘util/regression.pl’. “`config alpha_pair_page_break = 10` ” is now the default value in the NSA realm (and 10000 in the ABSP realm), and is used to determine whether or not to switch to two-column printing when no photos are used. (Stewart Holden, issue 65) “`TUFFluck`” is now a built-in command, not an external one, the order of its arguments is reversed, and it generates HTML files (Stewart Holden).
3.180 | 2007 Players Championship | HTML reports are now generated only in the directory (folder) designated by “`config html_directory`”, and no longer in the event directory. This is because reports which included player photos were not able to refer correctly to the location of those photos. If you find this confusing, use “`config html_in_event_directory = 1`”. (Reported by Jennifer Miller). Added “`Browse`” command. “`config bye_spread`” defaults to 50, but can be set to 75 for ABSP use (for Stewart Holden). “`config realm = 'absp'`” sets various configuration variables to ABSP defaults, also chooses alternate default ‘tsh.css’ file which shows starts/replies but suppresses boards. Added “`DOCumentation`” command. Rewrote “`HighLoss`” command, now generates HTML, does not have hyphen in its name. Rewrote “`HighWin`” command, now generates HTML, does not have hyphen in its name. Rewrote “`LowLoss`” command, now generates HTML, does not have hyphen in its name. Rewrote “`LowWin`” command, now generates HTML, does not have hyphen in its name. Added “`AVErages`” command for Stewart Holden. “`RoundRobin`” command takes an initial optional integer argument specifying how many times each player should play his/her opponent consecutively (Stewart Holden). Added “`BrowseLast`” command. Long standing problem with reserved tables finally fixed (Stewart Holden). “`ResultsByRound`” command now also lists number of losses, in case of players missing games completely. Most report-generating commands have been rewritten for code clarity. “`RoundRATings`” and “`RATings`” rewritten for easier maintenance. Next player is shown where available even when ABSP ratings are in effect, but the player name is no longer ever shown (just the ID), to make room for a new column (overridden by “`config no_show_last`”) showing details of the last game, for the sake of player verification. “`showWallChart`” was displaying one too many rounds; it no longer does so (Stewart Holden, issue 34). “`config board_stability`” is ignored at the beginning of a session. (issue 35) “`InitFontes`” interacts correctly with “`config reserved`”. (issue 36). “`config show_divname`” forces division names to be displayed, even when there is only one division. “`Addscore`” command warns if an entered score is less than 100. “`ChewPair`” was overestimating the number of players in contention (issue 37).
3.170 | Toronto LCT | “`config flight_cap`” will let you override the default top-flight cap of 4 * number-of-rounds-remaining in Chew Pairings. Added “`ShowDivisionScoreCards`” command for Stewart Holden. “`config pair_page_break = 15`” will force a page break after every 15 players in regular pairings. Added “`CheckRoundScores`” command for Ben Greenwood. Added “`update-pix`” command for Kath Mullholand. Added “`config player_photos = 1`” option for Kath Mullholand. Changed “`config entry = 'absp'`” option to “`config entry = 'spread'` ”for Stewart Holden. “`config table_method = 'consecutive'`” will assign one board per table, tables numbered beginning at 1 in the alphabetically first division, then continuing consecutively in each subsequent division (Stewart Holden). “`classes A 3`” in the configuration file will declare 3 subdivisions of equal size in Division A, for use in awarding class prizes (Stewart Holden). Configuration errors pause to let you see them, even on old Windows systems (Mauro Pratesi). Added “`TRUNCATEROUNDS`” command for Stewart Holden. Corrected “`DELETEscore`” command to work in a spread-entry environment for Stewart Holden. Added “`TOTalScore`” command for Stewart Holden.
3.160 | 2007 Dallas Open | tsh should complain once and revert to black-and-white rather than crash if something is seriously wrong with its colour environment tourney.pl -C works again TSH/Command modules can be anywhere in @::INC Major internal rewrite to support ongoing web interface development. Please be sure to do a dry run if you are using this release at a tournament. Default pairings will begin with one or more round robins if the number of rounds remaining to pair is greater than the number of players in a division. “`config force_koth`” will force a round of unrestricted KOTH at the end of default pairings. “`config alpha_pair_page_break = 15`” will force a page break after every 15 players. The “`InitFontes`” command will avoid assigning byes to top-rated players, will assign better-quality pairings in odd divisions, and will if you really want to let you use it in a division with only three players. Its board number assignment algorithm has also been substantially improved. Added “`lifeg`” extension field. “`RATings`” command automatically accounts for split ratings “`config split1`” is now deprecated.
3.150 | Toronto Open | Removed spurious error message from “`ShowPairings`”, introduced in 3.140 when player photos are not found. Fixed “`SUBMIT`” command to actually work in non-debug mode. Cross-platform support for “`config backup_directory`”. Fixed “`showWallChart`” command so that it doesn't display cryptic messages when used with track_firsts turned off (Vince Castellano). Added “`ShowManyPairings`” command (Vince Castellano). Cleaned up generation of HTML files and indices. Cleaned up generation of CSCs. Added “`config allow_gaps = 1`” to permit leaving unassigned gaps in a CSC. This necessitated a small change in the .t file format and major changes through tsh. As a side benefit, the “`InitFontes`” command will work around partly paired initial rounds, as long as the number of partly-paired players needing opponents is even in each round. Fixed “`Addscore`” command, now checks correctly for things that don't look like scores. Rewrote contender detection code in“`ChewPair`” yet again. The new version takes into account all available game data, including that from partly scored rounds. Added experimental “`PRiZes`” command, which lists all prizes to be awarded. “`ShowPairings`” command lists all byes ahead of unpaired players. Added “`config board_stability`”, which tries to keep one player from each game at the same board.
3.140 | 2006 MWMST | “`config port = 7777`” enables a multiuser version with graphical user interface in the very early stages of development. The “`part-of-name1,part-of-name2`” syntax introduced in 3.110 works within “`Addscore`” Added hooks to “`ShowPairings`” to support display of player photos when available Use Term::ReadLine where available, so that you can scroll back instead of retyping commands. Fixed a semi-obscure bug in “`ChewPair`” that could affect top pairings at the end of a tournament: the primary criterion for choosing opponents is now whether or not they can catch up to the current leader. Added “`SUBMIT`” command to submit ratings data (currently only for NSA ratings, others added on request)
3.130 | 2006 BMSC | “`RoundRobin`” command balances starts and replies for groups sized 2-26 Corrected bug that might have sometimes led to incorrect assignment of starts and replies
3.120 | 2006 USSO | “`FactorPair`” command no longer does opponent availability optimisation. “`ResultsByRound`” command now also lists contestant ranks prior to start of selected range, to facilitate computing USSO "Best Record Day n by Player In Bottom Half" prizes. “`TUFFluck`” external command works with case-sensitive filesystems.
3.110 | Saxon 2006 | “`config rating_system = 'nsa lct'`” enables LCT ratings multipliers (for Wes Eddings) “`LOOK`” command works within “`Addscore`” “`config entry = 'absp'`” sets data entry to winner-loser-spread mode, generally suppresses display of raw game scores in favour of spread. “`update-dict`” external command fetches dictionary files, which are too big to be included in the regular distribution.
3.100 | July 2006 Toronto | config autopair is slightly less finicky about format (Peter Keller). “`LOOK`” command now uses SOWPODS2003 and TWL2006 lexica. Spurious error messages generated when pairing odd divisions for multiple rounds (InitFontes, RoundRobin) are gone. An error message is displayed if no divisions are defined in the configuration file. tsh is much more tolerant of non-native line breaks in its configuration and data files. Using a configuration file marks it as modified, so that tsh will choose it the next time it is run. If you can't remember a player's number, you can enter it as “`part-of-name1,part-of-name2`”. For example, if “`Chew, John`” is the only person whose family name contains “`CHE`“, he can be referred to as “`che,`”. When division sizes were close to the number of rounds being played, it is easy for bottom-ranked players to clinch positions near the bottom and be relegated to playing each other for several rounds. Chew pairings now check for this condition and do not allow two players who have already played each other to be separated from a flight of contenders.
3.090 | 2006 Toronto LCT | A tournament can use default pairings for some divisions and automatic pairings for others.
3.080 | BAT 2006 | “`config initial_schedule`” specifies number of rounds of InitFontes pairings to use at start of default pairings If “`config html_directory`” does not exist and cannot be created, an error message says so. “`ShowPairings`” command shows table numbers in alpha mode, correctly handles byes in alpha mode. Added “`util/multiroto`” to report on rotisserie pools that span more than one tournament. Fixed a semi-obscure bug in “`ChewPair`”. When using pairings based on the second preceding round, the number of rounds used to compute the contender cap had been too large by one.
3.070 | NSSC 2006 | “`RANDomscores`” command now generates who goes first randomly to improve verisimilitude of reports on simulated runs
3.060 | Toronto vs. Mississauga 2006 | Added “`exagony`” configuration option. Added “`TeamStandings`” command “`RATings`” command correctly accounts for scoreless byes “`STandings`” command correctly accounts for scoreless byes
3.050 | Dallas Open 2006 | If you are using xterm terminal emulation and have specified the “`event_name`” configuration option, tsh will identify itself in your window title bar. “`ShowscoreCard`” formats correctly even when first and seconds are not assigned. Under some circumstances, the downloaded executable files would not be executable for OS/X users. I think I've fixed the problem, and documented how to fix it locally if it recurs. At Kath Mullholand's request, the “`high-win`” external command (and the other three similar ones) now display a header that identifies the division. Quality of pairings is slightly improved by disabling a speed optimization that tries to pair first those players with a smaller number of candidate opponents, when the number of players to be paired in a group is no more than twelve. At Mary Rhoades' request, the “`ShowPairings`” command now also generates alphabetical pairings listings in addition to the old rank-based listings. The “`Addscore`” no longer accepts scores outside the range [-150,1500]. Added “`UPSETs`” command to list top ratings upset games. The `munge-scores.pl` utility, used by several external and utility commands, now reports player numbers, so those external commands will report them too.
3.040 | Oshawa 2006 | Colour prompts for Windows users disabled by default, still optionally selectable. Windows colour is apparently broken in the most recent ActivePerl distribution. If an html_directory needs to be created, lib/tsh.css is copied into it. Fixed an obscure bug in “`ChewPair`” that made it occasionally crash. Utility command “`util/truncate_t`” is tolerant of blank lines. Added top-level script “`get-tsh.pl`”, built using “`update`” external command, to act as a standalone download tool for tsh. That is, you can if you want to download just this one script, run it and it will fetch everything else for you. Useful if you have a mostly complete installation but have somehow managed to wreck either your “tsh.pl” or part of the software update mechanism. The “`update`” external command was saying that some files had been updated even when no files had been updated. That bug is fixed.
3.030 | WSC 2005 | Support for scoreless byes. Fixed a bug that caused starts/replies to be instable. Fixed “`ChewPair`” command and pairing system: Gibson spread threshold now based on some historical data, leaders paired against lower-ranked contenders. “`Addscore`” won't let you switch to a division whose results have all been entered. “`AUPAIR`” command supports byes. Added “`player_number_format`” configuration option. Added “`show_teams`” configuration option. “`RATings`” command shows next opponent if paired. (Suggested by David Acton.) 0-point bye counts as a loss, not a tie. Fixed a bug where pairings display would stop if a table was unoccupied. Fixed a bug in bin/munge-scores that led to games with byes appearing in high/low win/loss lists. “`MISSing`” command lists players in current standing order. Tweaked code for reserved table assignments, think there might still be a problem. For a few versions, you had to specify the max_rounds configuration option to make pairings commands work. This should no longer be necessary, though it is still recommended.
3.020 | Kingston 2005 ("Now... with tint control!") | All remaining commands converted to using newer parsing code. “`LOOK`” command checks for dictionary at runtime. “`UnPairRound`” command does not affect inactive players, minor bugs fixed. “`EditScores`” command deletes future byes when a player is (re)activated. “`RANDomscores`” command sets spread to 50 points for scheduled byes. Fixed a bug where if you asked for pairings too far in advance, inactive player records would still have byes added. Colour prompts for Windows users too. “`MISSing`” command ignores inactive players, displays board numbers when known. “`ShowscoreCard`” shows board numbers. “`UPDATE`” command will delete read-only files (like src/TSH/blib/lib/TSH/Pair.pm) to make way for their replacements. “`Addscore`” prevents entry of Rd. N+1 results when Rd. N is incomplete even when switching divisions. Several commands explicitly report when pairings have failed. Added “`RandomPair`” command. Added “`team`” extension field. Added “`config initial_exagony`” configuration parameter.
3.010 | Kingston 2005 | Added “`ON`” and “`OFF`” subcommands to“`EditScore`” to permit enabling and disabling a player. “`ShowscoreCard`” detects truncated .t files. “`ShowscoreCard`” reports nonstandard spreads for inactive players. Removed a bug that caused multiple byes to be appended each round to inactive players. Removed two bugs introduced in 3.000 that caused odd divisions to severely misbehave. Removed bug introduced in 3.000 that caused round robins to fail sometimes. `UnPairRound` command will delete scored byes if they are the only scores in round. `RANDomscores` command deals more appropriately with partially scored rounds, completing them rather than adding one score to each player regardless of number of scores recorded. Deprecated `PartialSWiss` command finally deleted. First sample folder cleaned up. `RoundRobin` command works with inactive players. In many places, the division name is now not displayed if the tournament has only one division. `PAIR` `PairMany` commands allows either player number to be zero for a bye. `PAIR`, `PairMany` commands un-pairs opponents of repaired players, assigning 50-point byes if necessary. `KOTH`, `Pair1324` commands works with inactive players, uses consecutive repeat avoidance, matching starts and replies, minimizing repeats as secondary criteria. “`FactorPair`” command released.
3.000 | MWMST 2005 | Finished implementing “`ChewPair`” command and pairing system, which is now the default if pairings are asked for and no other system was specified. Added “`HUH`” command for explaining error messages. Rewrote “`HELP`” command to give detailed help about individual commands. Added “`AUPAIR`” command for exporting to that ratings file format. Many commands rewritten to conform to new internal code standards to support faster software updates and smaller runtime memory usage. Fixed a bug in “`ShowPairings`” which had caused it to omit boards where more than two players had erroneously been scheduled to play. Added “`DEBUG`” command for selectively toggling debugging on and off. “`SWiss`” command is now just an alias for “`NewSwiss`”. Added “`config external_path`” to allow user plug-in directories.
2.980 | NSC 2005 | “`ResultsByRound`” command creates printable HTML files. Added very experimental versions of “`FactorPair1`” and “`FactorPair`” commands. Added “`config prize_bands`” to expand support for Chew pairings. Added “`config save_interval`” to auto-save when entering a large number of scores. Added “`config rating_system`” to allow computation of ABSP tournament ratings in “`rat`” command. Added “`maketm`” external command to generate TourneyMan data files. Added “`high-loss-round`” external command to list high losses in each round. Added “`high-win-round`” external command to list high wins in each round. Added “`util/parsetm`” utility to import TourneyMan data files. “`roto`” allows any number of players per team. “`showWallChart`” syntax does not require “-f” before round number anymore. External command “`show12`” shows counts of firsts and seconds for each player. The board at which each game was played is recorded (in “etc board”) and will not change once assigned.
2.975 | ABSP compatibility | Added “`ABSPgrid`” command. Added “`config colour`”. Made external commands work with Windows XP. Reorganized search algorithm for configuration files. It’s now (1) files or directories specified on the command line, (2) the most recently changed among */config.tsh and */tsh.config, or (3) tsh.config. The intent is that users should have one tsh directory with a subdirectory for each event. Added “`update`” external command, which downloads updates to the distribution.
2.960 | Albany NY | Added “`tuffluck`” external command. Partly functional version of “`ChewPair`” command added. ScoreCard command generates HTML version that can be printed as replacement for lost scorecard. WallChart command generates HTML version. Round-by-round HTML files are automatically indexed. New RATING subcommand in EditScores. Contextual help in EditScores. EditScores can be used before any results are entered. Initial .t files may omit trailing semicolon.
2.950 | Toronto LCT | Addscore prevents entry of Rd. N+1 results when Rd. N is incomplete. New external command “`show12`” displays table of firsts/seconds. First/second forecasts/assignments are now more accurate.
2.940 | Stamford CT | Optional specification of configuration file on command line. NewSwiss tries to minimize repeat pairings.
2.930 | CNSC 2005 | Addscore reports how many scores remain unentered. Two-part tournaments are correctly split-rated.
2.920 | Thunder Bay ON 2005 | Added some more three-word names to tourney.pl.
2.910 | BAT 2005 | Added config gibson. Added config max_rounds. The timestamp of the most recent score entered for each player is now recorded. Added ROTO command. Code for reserved table assignments is working again. Forecasts of firsts and seconds are purged before new forecasts are generated, which addresses a potential problem with corrupt stale data when players have systematically misreported firsts and seconds. Added config no_text_files. Added config html_directory. Autopair supports PAIR1324. Fixed a bug that prevented calculation of the ratings of unrated players.
2.900 | BAT 2005 | Some errors now have numbers, which can be looked up in Troubleshooting..
2.850 | NSSC 2005 | Fixed a bug introduced to RoundStanding in 2.800 (?).
2.840 | NSSC 2005 | Fixed a bug introduced in 2.800 (?) where missing pairs were displayed twice.
2.830 | NSSC 2005 | Generated HTML is somewhat more legible and conformant.
2.820 | NSSC 2005 | Corrected determination of firsts and seconds.
2.810 | NSSC 2005 | Added external command (plug-in) interface Partial support for active/inactive players 'off' extension field in '.t' files `MISSING` and `ShowPairings` show "draws" if players must draw config name_format = "%-22s" config max_name_length = 22 config assign_firsts = 0 `showWallChart` and `showScoreCard` adjust column with to widest team name.
2.800 | NSSC 2005 | `EditScore` now displays the current scorecard before each prompt, rather than after changes. You can now enter the word `first` or `second` at the `EditScore` prompt to specify that the player went first or second. `MISSING` and `ShowPairings` display firsts and seconds if known. `config track_firsts = 1` enables tracking of who went first or second in each game. tsh will use NSA rules for determining firsts and seconds, and complain if scores are not entered in order of play if known. Auto-pairing used to be available only when a division was completely unpaired. Now, you can still auto-pair even after entering a few manual pairings. You can now write `config variable = value` instead of `perl $config'variable = value` in tsh.config. Byes are automatically chosen and assigned by the `NS`, `KOTH`and `Pair1324`commands. The `BYE` command is now deprecated. It is no longer documented, and will be deactivated soon. Use the `PAIR` and `Addscore` commands instead. The `ShowPairings` command used to always list everyone and their opponent (if any). Now, if no players are paired, it says so rather than listing everyone as unpaired. The `PAIR` command used to always echo back the names and standings of the players you just (manually) paired. Now it only does so if you changed an existing pairing. The `SWiss`, `PartialSWiss`, `PRESWiss` and `PrePreSWiss` commands are now deprecated. They are no longer documented, and will be deactivated completely soon. Use `NewSwiss` instead. You can now enter 'es' when in `Addscore` mode, to go into `EditScore` on the most recently entered (and presumably mistaken) score. `EditScore` command sometimes didn’t correctly record changes when editing multiple divisions, does so now. `UnPairRound` command used to sometimes give incorrect error messages, but no longer does so. `Pair1324` documentation used to say that below 4th place, pairings were KOTH. This is untrue (they continue 5-7, 6-8, etc.) and the documentation has been corrected. All command parsers rewritten to give consistent response and more specific descriptions of syntax errors. `RoundStandings` used to misreport results in the current round, if not all scores had been entered, now reports correctly. Division name may now be specified in command lines, even when event only has one division. Distribution now in ZIP format. Documentation rewritten. Randomization of player orderings is now much less random, so first-round table assignments stay stable unless roster is changed. Some spurious warning messages deleted. Support added for new generalized .t files. `ShowPairings` now generates HTML. Trailing commas in player names are suppressed.
2.740 | Newsday SSC | `PairMany` debugged.
2.730 | Newsday SSC | `ShowPairings` catches and shows more pairing errors.
2.720 | Newsday SSC | `PairMany` added.
2.710 | Newsday SSC | Player names may include nonterminal numerals.
2.700 | Newsday SSC | HTML output from standings command.
2.600 | Oshawa 2005 | `RoundRobin` command added. `RATings` command added.
2.500 | MWMST 2004 | Trying to autopair a round twice doesn’t crash tsh.pl.
2.400 | Albany 2004 | Fixed `wc -f #`. Autopair works at start of tournament. `MISSING` lists divisions in alphabetical order. 'm' synonym for 'missing' in score entry mode.
2.300 | BAT 2004 | Autopair added. `EditScore` emits updated scorecard.
2.210 | Montreal QC 2004-03 LCT | Suppressed a spurious error message.
2.200 | Cambridge ON 2004 | "Cambridge pairings" added.
2.100 | CNSC 2003 | `Addscore` gives updated cumes as a check.
2.000 | MWMST 2003 | `MISSING` lists missing data in score entry mode. Teed log files have '.doc' extension, no embedded spaces.
1.900 | CWSCQT 2003 | Added `ShowPairings -p` as kludge to work with make-rr.pl.
1.800 | Albany 2003 | `ScoreCard` shows opp ratings. `UnPairRound` reports on problem players. Table numbers can be arbitrary strings . Entering a division name changes divisions in score entry mode. `ShowWallChart -f r` lists beginning with round r only.
1.700 | Boston 2003 | `EditScore` added. `NewSwiss` code added, first manually paired player can be 0 for an unscored bye pairing.
1.600 | Boston 2001 | `InitFontes` works for any number of players, not just 4n and 4n+2.
1.500 | Toronto 2001 | Various changes.
1.400 | Boston 2001 | Various changes.
1.300 | Danbury 2001 | Various changes.
1.200 | 2000 CNSC | Various changes.
1.103 | 1999 MWMST | First production use
1.000 | None | First release

# Known Issues in tsh

tsh bugs and requested features.

Contact John Chew to report bugs or request new features. Bugs will be fixed according to their urgency; features will be added according to urgency, utility and ease of implementation.

## Open Issues

ID | Type | Priority | Difficulty | Submission Date | Scheduled Date | Submitter | Description
--- | --- | --- | --- | --- | --- | --- | ---
1 | new | low | medium | 2007-03-01 | open | John Chew | tsh should understand page sizes and insert page breaks with repeated headings as appropriate.
3 | bug | high | medium | 2007-07-01 | 2007-08-15 | Stewart Holden | “`config exagony`” and “`ChewPair`&rdquo do not always interact well.
7 | new | low | medium | 2007-07-02 | open | John Chew | Request for a command that purges all journalled files after a tournament is over.
10 | new | medium | high | 2007-07-04 | open | John Chew | tsh should warn when delayed Gibsonization is detected when Fontes pairings are in effect.
11 | bug | medium | medium | 2007-07-04 | open | John Chew | Pairings commands should not pair past “`config max_rounds`”.
12 | bug | high | medium | 2007-07-04 | 2007-09-01 | John Chew | A large number of bug reports and new feature requests are embedded in source documentation and should be moved to this file.
13 | new | medium | high | 2007-07-04 | open | John Chew | webupdater should be configurable and documented
14 | new | low | high | 2007-07-04 | open | John Chew | Interactive config.tsh editor.
16 | new | low | high | 2007-07-04 | open | John Chew | It should be possible to request that commands be triggered when all data has been entered (and possibly checked) for a round in a division.
17 | new | low | medium | 2007-07-04 | open | John Chew | Photos on scorecards.
18 | new | low | high | 2007-07-04 | open | John Chew | Virtual scorecards on the web.
19 | new | low | high | 2007-07-04 | open | John Chew | Printing from within tsh.
20 | bug | low | medium | 2007-07-04 | open | John Chew | Add more internal cross-references in the documentation
21 | bug | low | medium | 2007-07-04 | open | John Chew | Proofread documentation for typographic style.
22 | new | low | high | 2007-07-04 | open | John Chew | Load large divisions in separate threads, when the Perl thread model makes this faster.
23 | new | high | medium | 2007-09-01 | open | John Chew | A report that lists the last lines of scorecards for all players, so that players can check their results.
24 | new | medium | medium | 2007-07-04 | open | John Chew | Choose random seed for firsts/seconds in a way that can't be jiggered by a director.
25 | new | low | high | 2007-07-04 | open | John Chew | Correctly rate NSA players who are on high multipliers.
26 | new | low | medium | 2007-07-04 | open | John Chew | Hovering on photos should enlarge them.
27 | new | low | low | 2007-07-04 | open | John Chew | Using the manual PAIR command sometimes leads to more than one game at one board. It should swap boards as necessary.
28 | new | low | high | 2007-07-04 | open | John Chew | Swiss pairings should try to minimize the number of players promoted between groups each round.
29 | new | low | high | 2007-07-04 | open | John Chew | Commands should have alternate syntaxes. For example, the input for Addscore should be parsed as [[keyword(missing)],[keyword(division), division],[player score],[player score player score]].
30 | new | high | medium | 2005-01-01 | open | Graeme Thomas | Swiss pairings should arguably rank players first on sum of opponent scores (SOS), then cume.
31 | new | high | high | 2007-07-04 | 2007-09-01 | John Chew | Should try provisionally assigning the higher-rated player in each game a win in the current round when pairing Fontes.
32 | new | low | high | 2007-07-04 | open | John Chew | Web interface should highlight recently updated information.
39 | new | low | low | 2007-08-16 | open | John Chew | If tsh chooses a sample event, the user should be given the option of interactively creating a new event, as per issue 14.
40 | new | medium | high | 2007-08-16 | open | John Chew | TSH::Config::Export() should be removed once it is no longer necessary.
41 | new | low | medium | 2007-08-16 | open | John Chew | ‘tshxcfg.txt’ should be read in and eval’ed, so that its code can have access to a lexical copy of $tournament.
44 | new | high | high | 2007-08-19 | open | NSA Tech Committee | Connect to NSA ratings database so that player names do not have to be misentered manually, and so that current ratings can optionally be imported (though not for a ME after EB). Also connect to the player database to access/maintain contact information
45 | new | high | low | 2007-08-19 | open | NSA Tech Committee | A command to move players between divisions before the tournament begins.
46 | new | high | high | 2007-08-27 | open | John Chew | A command that automatically assigns players to divisions according to rules set out in the configuration file.
47 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | A command to perform Snake pairings
48 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | event triggers should include a prompt asking user if they want to compute/print pairings and standings
49 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | Byes should not be assigned to unrated players in the first round.
51 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | The “`EditScore`” command should let the user set cumeadj.
52 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | A new command that prints a player address list.
53 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | A new command that prints just player numbers, ratings and names.
54 | new | high | high | 2007-08-19 | open | NSA Tech Committee | Optionally allow portrait/landscape orientation choice in tsh (without using Page Setup), by rendering as a PDF. This would also help give finer layout control, enable direct printing from tsh in OS/X, and would generally be a good thing.
55 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | Explain to specifications authors why it is impossible to prevent some fields in printouts from wrapping under some conditions.
56 | new | high | high | 2007-08-19 | open | NSA Tech Committee | User interface should be intuitive to more people.
57 | new | high | medium | 2007-08-19 | open | NSA Tech Committee | Pairings reports should optionally include brief notes explaining how the pairings were computed.
58 | new | medium | low | 2007-08-28 | open | Stewart Holden | MISSING can be abbreviated to M only when invoked from within Addscore.
59 | new | medium | low | 2007-08-28 | open | Stewart Holden | MISSING should not require its round number unless “`config allow_gaps = 1`” is in effect.
60 | new | medium | high | 2007-08-28 | open | Stewart Holden | It would be nice to be able to specify the order of rounds in a round robin, so that, e.g., players who needed byes in specific rounds could be accommodated.
61 | new | medium | medium | 2007-08-28 | open | Stewart Holden | The order of rounds in a round robin ought to depend on the division name, so as to reduce the likelihood of data entry confusion.
66 | new | medium | medium | 2007-09-17 | open | Stewart Holden | The stats command incorrectly reports a large number of start/reply errors when round robin pairings are used. This problem may be resolved as part of a planned rewrite of the round robin code, or may need to be specifically addressed.
67 | new | high | high | 2007-09-17 | open | John Chew | The following situation might be an example calling for a change to the current Chew pairing algorithm. With a flight cap of 4, there are four contenders with more or less the same record. All pairs have played each other except 1-3 and 1-4. As things stand, because the four require one repeat to be paired, this is accepted as the repeat tolerance, the players are split after second place and paired 1-2, 3-4. Although it would be computationally prohibitive for large flights, it might be worth trying to minimize the total number of repeats for small flights like this to achieve 1-4, 2-3 pairings. Also, when the top two places are Gibson-equivalent, it is imperative that 1-2 not play each other if 3 or 4 are in contention.
69 | new | low | high | 2007-09-29 | open | John Chew | In order to use tsh to look after Scrabble clubs, the following features are required and likely more: the chronological concatenation of sessions (each with its own ‘.t’ file) into seasons, where the output ratings from one session become the input ratings of the next and only one session is active at a time; overall season statistics including performance rating calculations; and something like Washington Go first-available pairings.
75 | new | medium | low | 2007-09-12 | open | Stewart Holden | An extra page break appears after the value of `config html_top`” in the output of “`ShowDivisionScoreCards`”.
76 | new | medium | high | 2007-10-07 | open | John Chew | More basic statistical research is required to determine the distribution of scores as a function of player ratings, start/reply and playing environment.
77 | new | medium | high | 2007-10-07 | open | John Chew | The research of issue 76 needs to be applied to more accurately model possible future outcomes in Chew pairings.
78 | new | medium | medium | 2007-09-12 | open | John Chew | The research of issue 76 needs to be applied to more accurately determine Gibsonization thresholds.
82 | new | medium | low | 2007-12-03 | open | Jim Hughes | “`config repeats{DIV}`” should specify when repeats will be permitted.
83 | new | medium | low | 2007-12-03 | open | Jim Hughes | The manual needs an index.
84 | new | high | medium | 2007-12-05 | open | Jim Hughes | HTTP routines should use LWP where available.
85 | new | medium | medium | 2007-12-05 | open | Jim Hughes | RSS feed for web pages.
87 | new | medium | low | 2008-02-09 | open | Ronan Webb | CSS customisation by including a second stylesheet.
88 | new | medium | medium | 2008-05-15 | open | John Chew | It should not be too difficult to prepare a standalone Windows executable version of tsh, which would be helfpul for newbies but perhaps take up too much disk space for everyone else.
89 | new | high | low | 2008-05-15 | open | Mauro Pratesi | Corrupt configuration file diagnostics may not be visible under Windows.
93 | new | medium | low | 2008-07-27 | open | John Chew | Table reservation data belongs in “.t” files so that it can be edited using “`EditScore`”
94 | new | medium | low | 2008-08-24 | open | John Chew | Trying to enter a bye score as something-0 should cause tsh to prompt you offering to rewrite the game as a forfeit.
95 | new | medium | medium | 2008-11-07 | open | Sherrie Saint John | It would be nice to be able to print result slips with player names.
96 | new | medium | medium | 2009-04-19 | open | Tim Fukawa-Connelly | You shouldn't have to enter bye scores by hand.
97 | new | high | medium | 2009-06-17 | open | Andy Saunders | best possible finishes are overestimated when flight sizes are small.
98 | new | low | medium | 2009-07-20 | open | John Chew | SUBMIT.pm needs to be rewritten along the lines of WebUpdate.pm to use Win32 code for compatibility with older XP systems.
99 | new | low | medium | 2010-06-19 | open | Pakorn Nemitrmansuk | Player photos should show different facial expressions depending on recent W-L history or overall standing.
100 | new | low | medium | 2010-08-09 | open | Ryan Fischer | Sticky players in scoreboard.
101 | new | medium | low | 2010-08-15 | open | John Chew | Board reservations should be made in division data files.
102 | new | low | low | 2010-08-22 | open | Andy Saunders | Player's rnd field should be unique within division.
103 | new | low | medium | 2010-12-01 | open | Vince Castellano | There should be a way to specify exagony only for non-contenders.
104 | new | medium | hard | 2013-12-01 | open | Nigel Richards | The enhanced scoreboard crashes in Safari for iOS 6 when Private Browsing is enabled.

## Closed Issues

ID | Type | Priority | Difficulty | Submission Date | Resolution Date | Submitter | Description
--- | --- | --- | --- | --- | --- | --- | ---
34 | bug | low | low | 2007-07-30 | 2007-07-30 | Stewart Holden | “`showWallChart`” displays one too many rounds.
35 | bug | high | low | 2007-08-01 | 2007-08-01 | John Chew | “`config board_stability`” tries to keep board stable even across session breaks.
36 | bug | high | medium | 2007-08-01 | 2007-08-01 | John Chew | “`InitFontes`” ignores board reservations specified using “`config reserved`”.
37 | bug | high | low | 2007-08-03 | 2007-08-03 | John Chew | “`ChewPair`” overestimates the number of players in contention.
38 | bug | high | low | 2007-08-11 | 2007-08-11 | John Chew | “`Addscore`” does not take into account “`config entry = 'spread'`” when assessing validity of scores.
6 | new | medium | medium | 2007-07-01 | 2007-08-12 | Evan Simpson | Request for a new type of roto command that lets people predict ranks of everyone in a division
5 | new | medium | low | 2007-07-01 | 2007-08-16 | Stewart Holden | “`MISSING`” should accept an optional argument specifying a division.
43 | new | low | low | 2007-04-19 | 2007-08-19 | Stewart Holden | “`RANDomscores`” always assigns 300 points to an ABSP unrated player.
33 | bug | high | medium | 2007-07-28 | 2007-08-21 | Stewart Holden | “`config gibson`” does not work with `KOTH` command.
62 | new | medium | medium | 2007-08-28 | 2007-08-28 | Stewart Holden | ‘tsh.css’ needs to be copied to the event directory when “`config html_in_event_directory = 1`” is in effect.
63 | new | high | low | 2007-09-04 | 2007-09-04 | Barry Harridge | “`AUPAIR`” does not correctly handle byes.
64 | new | low | low | 2007-09-09 | 2007-09-12 | Stewart Holden | “`ABSPgrid`” HTML output does not need to be indexed.
2 | new | low | high | 2007-03-01 | 2007-09-13 | John Chew | tsh should be rewritten as a multithreaded, multiuser system.
65 | new | low | low | 2007-09-13 | 2007-09-14 | Stewart Holden | “`ShowPairings`” should default to not rendering in two columns in the ABSP realm.
8 | new | medium | low | 2007-07-03 | 2007-09-17 | Stewart Holden | Request for a configuration option that specifies rewrites player names with first names first and last names last.
68 | new | high | medium | 2007-09-17 | 2007-09-18 | Stewart Holden | The DOC command apparently suspends all future terminal output under Windows.
4 | new | low | low | 2007-07-01 | 2007-09-30 | Stewart Holden | Request for a configuration option that suppresses ranked pairings files for directors who will always use alpha pairings.
74 | new | high | low | 2007-09-12 | 2008-01-01? | Stewart Holden | Under some circumstances, Gibsonization was failing for non-Chew pairings because the correct code module was not loaded at the right time.
79 | new | high | low | 2007-10-09 | 2008-01-01? | Stewart Holden | “`HighLoss`” and similar commands were giving erroneous results for large divisions.
86 | new | high | low | 2007-12-10 | 2008-01-01? | Ryan Fischer | “`RESETEVERYTHING`” was incorrectly deleting tsh.css
91 | new | low | low | 2007-12-21 | 2008-06-18 | Stewart Holden | “`showScoreCard`” should indicate repeats.
50 | new | high | medium | 2007-08-19 | 2008-05-01 | NSA Tech Committee | During data entry, the most recently entered game's spread should be optionally displayed.
9 | new | medium | medium | 2007-07-04 | 2008-06-01 | John Chew | Request for pairings commands specifically for inter-team matches, such as team vs. team round robin.
42 | new | low | medium | 2007-08-16 | 2007-12-01 | Dan Pratt | ‘util/rr.pl’ should be replaced by an algorithm in ‘RoundRobin.pm’ that uses Clark pairings alternating starts/replies for the side of the table that has player 1, randomly choosing what player 1 does in the first round.
15 | bug | low | high | 2007-07-04 | cancelled 2008-08-01 | John Chew | Supplying one argument to “`PAIR`” should un-pair the identified player. (Cancelled because the “`PAIR n 0 round div`” syntax seems clearer.)
92 | new | low | low | 2008-06-19 | 2008-08-01 | Stewart Holden | Under Windows XP, text starts off unhighlighted, but switches to highlighted after an error.
80 | new | medium | low | 2007-10-21 | 2009-08-01 | John Chew | Ratings data submitted should include configuration settings where possible, to facilitate subsequent analysis.
81 | new | medium | low | 2007-12-03 | 2009-09-01 | Jim Hughes | “`config force_koth`” should accept values greater than 1 to have more than one late round of KOTH pairings.
90 | new | high | low | 2008-06-14 | 2014-05-26 | John Chew | “`LowerRoundRobins`” does not correctly assign board numbers.