- Authorship & Datestamp
- How-To for Running Tsh
  - Prerequisites
  - Download Locations
  - Update The Installation
  - Initial Setup
  - Typographical Conventions
  - Preparing For Your Event
  - Entering Scores
  - Amending Pairings Due to a Bye
  - Check Standings Against Wall Chart
  - Finding And Correcting a Data Entry Error
- Command Review
  - Generate/Display Pairings
  - Add Scores
  - Show Standings
  - WallChart
  - Correct a Game's Score
  - Find Whose Scores are Missing
  - Account for a Dropout/in
  - To-Do

# Authorship & Datestamp

This version was created 2010-02-03 by G. Vincent Castellano, and last revised 2012-10-21. May be distributed freely without alteration. Contact the author with any comments or corrections.

This document is compatible with `tsh` installation version 3.320 and later (but not too much later).

# How-To for Running Tsh

## Prerequisites

Tsh requires fluency with command-line tools. In the dark ages before everything was done with a GUI and a mouse, command-line interfaces were the norm. You type a command, hit 'enter', and get a response back. If you're overly intimidated by this prospect you should stop now.

## Download Locations

1. If you are running Windows, download and install the most recent version of ActiveState Perl installer from http://www.activestate.com/activeperl/downloads .

2. Visit http://www.poslarchive.com/math/software/tsh/doc/install.html for instructions on downloading tsh itself. You can skip the section on “Perl”--the previous step takes care of that.

## Update The Installation

If you are returning to use a tsh installation you had established previously, enter the UPDATE command to download the current version. You will of course need a working Internet connection to do this.

## Initial Setup

Make a clean tournament sub-directory with a descriptive name: I recommend the date concatenated with a location, e.g., `2006-07-15-CCCC`.

If you use Seth Lipkin’s www.cross-tables.com website to host your pretournament player roster, do this: | If not, do this:
In that subdirectory, create a configuration file called `config.tsh` which will look something like:
    division a a.t
    division b b.t
    division c c.t

    config max_rounds = 7
    config cross_tables_id = 12345
where the 7 should be replaced with the number of rounds that players will play in your tournament, and the 12345 should be replaced with the number that you see at the end of the website address of your player roster. | In that subdirectory, create a configuration file called `config.tsh` which will look something like:
    division a a.t
    division b b.t
    division c c.t

    config max_rounds = 7
where the 7 should be replaced with the number of rounds that players will play in your tournament.
The first three lines tell TSH where to find the data for each division. Here the division names are 'a', 'b', 'c', and their data will be found respectively in `a.t`, `b.t` and `c.t`. (You will want to keep these division names simple and easy to type, don't get cute and use names of breakfast cereals.) Division names are case-insensitive. The contents of each division file (before pairings are set) are lines like:
    Vince Castellano           1717
The above line would indicate that there is a player named Vince Castellano whose pre-tournament rating is 1717.
The first time you run tsh, enter the command `U` `pdate` `PLAY` `ers` at the `tsh>` prompt to download your roster from Cross-Tables. If you subsequently have any roster changes before your event starts, you can either edit them on Cross-Tables and `UPLAY` again; or follow the instructions on the right to edit your division data files manually. | Use a text editor (Notebook, Notepad, Vim, TextEdit, but not Word) to edit the division (.t) and config.tsh files. Don't use tabs anywhere. Don't use numbers in people's names. For unrated players, use an initial rating of 0.

Next, you may wish to enhance these files with the pairing information: who plays whom. There are many ways to tell TSH want kind of pairings you want (manual, automatic, default), and many different kinds of pairing systems that TSH can compute (round robin, king-of-the-hill, Swiss, Chew, etc.). If you have no idea, and don't have an experienced director you can ask, then TSH will do its best to choose a sensible default. For example, if you tell it that you have 6 players who want to play 5 rounds, it will set up a round robin.

When pairings have been added, the division data lines will look like this.

    Vince Castellano       1717 11      9       7       5       3 ;

where the rating is followed by a list of space-delimited opponent numbers. You can enter or edit the opponent numbers manually, but the chances are that TSH already supports any pairing system that you want to use; and if not, you can request a new pairing system on a few weeks' notice. Note that when editing a division data file, you must make sure that TSH is not running, or else your changes may be ignored or deleted.

Run tsh.pl in the TSH directory, with the event sub-directory as the argument, using one of the following commands:

DOS or Windows | Unix or OS/X
    perl tsh.pl 2006-07-15-CCCC
    ./tsh.pl 2006-07-15-CCCC

If you get a tsh> prompt then no errors were found in the config file or divisions. Capital letters in the full names of commands are the short forms of the commands; and commands are case-insensitive. E.g., the command `R` `ound` `R` `obin` is abbreviated `rr`.

## Typographical Conventions

Text shown exactly as it is to be entered within tsh is shown in fixed-width.

Generic text intended to be replaced with specific values within tsh is shown in fixed-width italic. (E.g., r for a particular round number, or d for a particular division name.)

Within this document, the short form of a command is shown as the bolded letters of the full command name.

## Preparing For Your Event

This document is intended to be merely a road map for using `tsh`. If you are completely new to `tsh` you should plan on spending several hours with the program over a period of at least two weeks to become sufficiently acquainted.

(If you are conscientious enough to take this advice to heart, you will also what to review John Chew's Checklist For Organizing Scrabble® Tournaments.)

After setting up the divisions, you can use the following commands to simulate an event and validate your expectations of how the pairings and reporting functions work:

- DRY run: `dry` `r d`

  - Simulates an entire tournament for a division using random data.

- RAND omscores: `rand` `d`

  - Give each player in division d a random score, to help simulate a tournament’s pairing system.

- RESETEVERYTHING: `reseteverything`

  - Delete scores and pairings data—rewinds the event to the beginning. Use only to undo the effect of the above two commands, after the tournament actually starts this command should not be used.

Further information on the above and all `tsh` commands is available at http://www.poslarchive.com/math/software/tsh/doc/commands.html, from whence the above descriptions were derived.

## Entering Scores

Start adding scores for a division with the A ddscore command which takes the round and division as arguments.

For example, at the tsh> prompt, enter:

    tsh> a 1 a
         ^ ^ ^
         | | +-- For Division A
         | +---- For Round 1
         +------ Add scores

You will see a prompt like:

    [A1]:pn1 ps1 pn2 ps2 (12 scores left)?

Meaning for Div A round 1, enter (separated by spaces)

      Player1Num Player1Score Player2Num Player2Score

Depending on your configuration options, you may also be required to enter the game spread, or you might not be required to enter the scores.

followed by Enter. Player 1 is the player who went first, player 2 went second. TSH will read scores until you hit Enter without entering anything.

Example:

    tsh> a 1 a
    [A1]:pn1 ps1 pn2 ps2 (12 scores left)? 12 384 2 467
    #12 Ronnie Thomas 384 (0.0 -83) - #2 Florence Spanfelner 467 (1.0 +83).
    [A1]:pn1 ps1 pn2 ps2 (10 scores left)? 3 453 9 435
    #3 Joanne Cohen 453 (1.0 +18) - #9 George Spanfelner 435 (0.0 -18).
    [A1]:pn1 ps1 pn2 ps2 (8 scores left)? 10 298 4 312
    #10 Rose Noel 298 (0.0 -14) - #4 Dave Engelhardt 312 (1.0 +14).
    [A1]:pn1 ps1 pn2 ps2 (6 scores left)? 5 352 7 407
    #5 Diana Grosman 352 (0.0 -55) - #7 Carole Denton 407 (1.0 +55).
    [A1]:pn1 ps1 pn2 ps2 (4 scores left)? 6 439 8 370
    #6 Dan Milton 439 (1.0 +69) - #8 Brian Bailey 370 (0.0 -69).
    [A1]:pn1 ps1 pn2 ps2 (2 scores left)?
    Updating Division A.
    updating a.t

### Notes

1. There was a bye this round due to a late player. See below.

2. The file "a.t" is updated with scores. You can view this file to see how it is updated.

3. If you do not know a player’s number, you can enter either `m` to see all missing players remaining in this round, or enter an unambiguous part of their name (e.g. `Joanne` instead of their number).

4. You can change divisions by entering just the name of the division on its own line.

## Amending Pairings Due to a Bye

Now we will deal with the first-round bye (between player 1 and player 11), where Player 11 arrived late and forfeited her game. Use the `F` `orfeit` `LOSS` command:

    tsh> floss 11 1
    Vince Castellano (A1) used to be paired to Lorraine Burton (A11). [iprwasp]
    Updating a.t

## Check Standings Against Wall Chart

Now that you have entered round 1 data, you may wish to check standings against the wall chart. Do this with the `W` `all` `C` `hart` command (follow "wc" with the division name):

    tsh> wc a
    Division A Wallchart

    Player                 Rd 01
    Vince Castellano         1.0
                             +50
    Florence Spanfelner      1.0
                             +83
    Joanne Cohen             1.0
                             +18
    Dave Engelhardt          1.0
                             +14
    Diana Grosman            0.0
                             -55
    Dan Milton               1.0
                             +69
    Carole Denton            1.0
                             +55
    Brian Bailey             0.0
                             -69
    George Spanfelner        0.0
                             -18
    Rose Noel                0.0
                             -14
    Lorraine Burton          0.0
                             -50
    Ronnie Thomas            0.0
                             -83

Repeat for each round and each division.

## Finding And Correcting a Data Entry Error

Now before doing the final KOTH, check the wall chart. We have a discrepancy, with Carole Denton 4-1 +118, where the wall chart shows 3-2 -70. There is probably another player with a win count error, and the matchup between these two was done wrong. tsh shows George Spanfelner at 1-4 -105 and the wall chart has him 2-3 +84.

Use the S core C ard command to show a contestant score card for Carole (Player 7). It shows that the scores for these players were swapped and will have to be re-entered.

Then use the E nter S core command to edit scores for Div A Player 7 Round 5:

    tsh> es a 7 5
    Player Scorecard: Carole Denton (A7) (1497)
    - Last score was entered 19 minutes ago.
    Rnd Brd Opp Rtng Opponent Name           Won-Lost For Agn Sprd Cumul
      1       5 1533 Diana Grosman           1.0- 0.0 407 352  +55   +55
      2      11 1307 Lorraine Burton         2.0- 0.0 356 324  +32   +87
      3       1 1717 Vince Castellano        2.0- 1.0 287 357  -70   +17
      4       3 1618 Joanne Cohen            3.0- 1.0 335 328   +7   +24
      5       9 1338 George Spanfelner       4.0- 1.0 423 329  +94  +118
      6       2 1670 Florence Spanfelner

The tsh view of the contestant scorecard is printed, and then you are prompted. Enter the scores for that round, separated by a space, with the player's being edited first:

    Carole Denton (A7) R5 [423 329 vs. George Spanfelner (A9)] (? for help) 329 423

The scorecard is reprinted. At this point is probably prudent to also print the opponent's scorecard.

# Command Review

## Generate/Display Pairings

`smp` `First-Last Div```

Example:

    smp 1-3 a

S how M ultiple P airings for rounds 1-3 in division A. Produces output in HTML directory. Even if you only want to show pairings for a single round, you may like the formatting provided by this command.

Example:

    smp 3 a

## Add Scores

`a` `Round Div```

Example:

    a 3 a

A ddscores for round 3 in division A. Enter data for one or more rounds in the form:

`Player1Num Player1Score Player2Num Player2Score```

Hit `Enter``` with no data to return to the command prompt.

## Show Standings

`st` `Div`

Example:

    st a

ST andings for division A, to the extent data has been entered. Produces output in HTML directory. If possible, don't post standings until all the scores have been entered. The exception to this will be near the end of an event when you are waiting for out-of-contention players to turn in their slips.

## WallChart

`wc` `Div```

Example:

    wc a

W all C hart for division A, to the extent data has been entered. Produces output in HTML directory. Most useful for finding errors in data entry relative to a player's scorecard. (The S core C ard command is also useful for this.)

## Correct a Game's Score

`es` `Div Player Round```

Example:

    es a 17 3

E dit S core for Player 17, division A, Round 3. You will then be prompted to enter this player's score and their opponent's score. Both players' records will then be updated.

## Find Whose Scores are Missing

`missing` `Round Div```

Example:

    missing 3 a

Shows who you have to go chase for tally slips.

## Account for a Dropout/in

If you know that a player is going to be absent in future rounds, then you should mark them as inactive for pairings until they return, using the `E` `dit` `S` `cores` command. When the command shows you its prompt, enter either `off -50` to assign an inactive player a forfeit loss with -50 spread each round, or `on` to reactivate a returning player.

## To-Do

- smp commands for init

- util/mirror-ftp