The basics of how to operate tsh.
Updated 2018-10-09T12:05:00+05 for tsh 3.340.
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 to remember are
command makes tsh stop running.
If you’re not sure how to use a command, then try typing
Here’s an example, showing what one version of tsh
shows when you enter “
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
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.
If you’re not sure what a message means, and it has a code in
[square brackets] after it, enter
Again, messages are documented in this way, and soon all of them will be.
If you enter
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
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 “
command, which displays standings in a division as of a specified
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 “
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
The comma is optional if you include at least two letters from one of the
As of the current release, this is not consistently implemented in
modal commands such as the
where the comma is not optional.
The following commands are used for entering tournament results, as well as checking and correcting them:
|Addscore||a r d||Begin entering new game scores for round |
|CheckRoundScores||crs r d||List all entered scores for round |
|DELETEscore||delete p1 s1 p2 s2 r d||Delete the previously entered scores |
|EditScore||es d p r||Begin editing previously entered game scores, starting with player |
|FIX||fix d p||(Experimental) Begin graphically editing previously entered game scores for player |
|ForfeitLOSS||floss d pn r spr||Delete any previous pairings for player |
|MISSING||missing r div||List all players in division |
|showScoreCard||sc d p||Show the correct scorecard for player |
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.
opens your web browser to the most recent report that you requested,
so that you can easily print it.
|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||aos 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 |
|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 |
|ResultsByRound||rbr r1-r2 d||Rank players in division |
|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 |
|RoundHandiCap||rhc r1-r2 d||Show Thai handicaps in rounds |
|RoundRATings||rrat r1-r2 d [r]||Show standings with ratings estimates for division A round may be specified to indicate pairing bars should apply to a round other than the latest for which pairings exist.|
|RoundStandings||rs r d||Show standings for division |
|saveJSON||json d||Used internally to store the state of a division on a web server, in a form usable by the “|
|ScoreBoard||sb d rk1 rkn size cols secs||Create an HTML-only scoreboard showing what is going on in division |
|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 |
|ShowManyPairings||smp r1-r2 d||Show pairings for rounds |
|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||sp r d||Show pairings for round |
|STandings||st d [r]||Show current standings for division A round may be specified to indicate pairing bars should apply to a round other than the latest for which pairings exist.|
|showRankedWallChart||rwc d||Show ranked wall chart for division |
|showWallChart||wc d||Show correct wall chart for division |
|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 |
|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 |
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.
|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 “|
|BASDFinal||basdf r d||Add Round |
|BASDSemi||basds d||Add three rounds of BASD semifinal pairings to division |
|BRACKetpair||brack n d||Set up pairings for single-elimination with |
|CAMbridgePair||camp d||Set up seven-round pairings as used in Cambridge ON for division |
|ChewPair||cp sr d||Set up Chew Pairings in division |
|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 |
|GUELPH||guelph d||Set up pairings as used in Guelph ON CAN for division |
|InitFontes||if nr d||Set up fixed pairings for |
|KOTH||koth rpt sr d||Add king-of-the-hill pairings allowing |
|LowerRoundRobins||lrr rk rds d||Add |
|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 |
|Pair1324||p1324 rpt sr d||Pair 1–3, 2–4, 5–7, 6–8, and so on, i.e., factored pairings with factor two. Some people call it QOTH or Queen-of-the-Hill pairings. See KOTH above for descriptions of arguments.|
|PairMany||pm r d||Begin manually pairing a large number of players in round |
|PairMany12||pm12 r d||Begin manually pairing a large number of players in round |
|PairQuartiles||pq q rpt r d||Pair the top quartile at random against quartile |
|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 |
|TeamMultipleRoundRobin||tmrr rpt n d||Divide each team in division |
|UnPairRound||upr r d||Delete all round |
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
which produces much better quality Swiss pairings.
|BYE||bye p s r d||Deprecated: use |
|PrePreSwiss||ppsw rpt p1 p2 d||Deprecated: use |
|PRESWiss||ppsw rpt p1 p2 d||Deprecated: use |
|SWiss||sw rpt sr d||Deprecated: use |
The following commands are used mostly for testing your tsh configuration before your tournament begins.
|DEBUG||debug code level||Turns debugging for sections labelled with |
|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 |
|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.|
And here all the commands which don’t fit into one of the above categories:
|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 “|
|EXPORTRATINGS||exportratings||Creates a copy of the ratings database used by the “|
|HELP||help topic||Displays builtin documentation. |
|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 “|
|LOOK||l word||Look up |
|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.|
|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 |
|UPDATE||update||Update tsh software using a web connection.|
|UPDATEPIX||updatepix||Update the local photo database used by the “|
|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||useratings||Update all player ratings using the ratings database most recently updated by the “|
|VALET||valet d p r||(Experimental) Open a browser window for data entry.|
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.
|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.|
|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.|
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.
|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 email@example.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 “
This script needs to know five things to run. They can be specified in various ways.
“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 ‘