The basics of how to operate tsh.
Updated Tue Oct 18 16:03:14 EDT 2005 for tsh 3.010.
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.
The most important commands to remember are
“quit”,
“help”
and
“huh”.
The
“quit”
command makes tsh stop running.
If you’re not sure how to use a command, then try typing
“help the-name-of-the-command”.
Many commands are documented in this way, and soon all of them will be.
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.
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.
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”.
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. |
| 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. 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. |
| MISSING | missing r | List all players whose round r scores have not yet been entered. |
| showScoreCard | sc d p | Show the correct scorecard for player p in division d, for checking. |
The following commands generate reports based on tournament results:
| Command | Example | Description |
|---|---|---|
| ABSPgrid | absp d | Shows a results grid suitable for submission for ABSP ratings. |
| AUPAIR | aupair d | Creates a .TOU file named for the division, containing ratings input information in AUPAIR.EXE format. |
| RATings | rat d | Show current division standings (with ratings estimates) for division d. |
| 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. |
| ROTO | roto r | List rotisserie standings as of round r. |
| RoundStandings | rs r d | Show standings for division d as of round r. |
| ShowPairings | sp r d | Show pairings for round r, division d. |
| STandings | st d | Show current standings for division d. |
| showWallChart | wc d | Show correct wall chart for division d, to check against the physical chart. |
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 |
|---|---|---|
| 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. |
| 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. |
| 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. This command is modal. |
| RandomPair | rp rpt sr d | Add a round of random pairings to a division. |
| RoundRobin | rr d | Add a full round robin to a division. |
| 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. |
And here all the commands which don’t fit into one of the above categories:
| 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. |
| EVAL | eval code | Evaluate arbitary perl code. Use only if you know what you’re doing. |
| 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]. |
| Look | l word | Look up word in dictionary. Optional, not yet part of the main distribution. |
| Quit | q | Quit tsh. |
| 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. |
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 |
|---|---|---|
| high-loss | high-loss div | List top ten high losing scores in a division. |
| high-loss-round | high-loss-round div | List highest losing score in each round in a division. |
| high-win | high-win div | List top ten high winning scores in a division. |
| high-win-round | high-win-round div | List highest winning score in each round in a division. |
| low-loss | low-loss div | List bottom ten low losing scores in a division. |
| low-win | low-win div | List bottom ten low winning scores in a division. |
| maketm | maketm div | Make a TourneyMan data file for a division. |
| nssc | nssc div | List School Championship prizes for a division. |
| show12 | show12 div | List firsts and seconds for all players in a division. |
| tuffluck | tuffluck div | List players according to the total of their six closest losses, for the NSA’s “Tuff Luck” prize. |
| update | update | Update tsh software using a web connection. |
There are also a number of standalone utilities found in the “util/” directory, which are currently provided on an as-is basis.