tsh Commands

The basics of how to operate tsh.

Updated Sat Sep 19 12:21:54 EDT 2009 for tsh 3.300.

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:

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.

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.

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.

Testing Commands

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

Miscellaneous Commands

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

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.

Plug-In 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.