readme

A Perl-based statistics management system designed for academic competition tournaments. These tourn

Livestat 1.2
released June 14, 2002
by Jason Weill
[e-mail]
http://livestat.org

WELCOME

Thank you for choosing Livestat, the newest choice in academic competition 
statistics collection.  This document explains how to get set up and running 
with your first Livestat enabled tournament.

WHAT IS LIVESTAT?

Livestat is a collection of Perl scripts which are used to track individual and
team statistics for academic competition (also known as quiz bowl, College 
Bowl, and various related names).  

WHAT CAN LIVESTAT DO?

Livestat handles most standard tournaments in the academic competition world.
It can handle timed and untimed tournaments, mid-round substitutions, power 
marks, and statistics by team, individual, and round.

WHAT CAN'T LIVESTAT DO?

Bracketing, bonus conversion, advanced statistics at various levels, detailed 
statistics per player, and enabling or disabling ties.  More feature requests 
should be submitted to [e-mail]

Livestat does not run on demand; it generates static pages when so requested, 
and publishes them for static serving.  As such, no CGI, ASP, PHP, or other 
dynamic web content is currently used.

WHAT IS PERL?

Perl is a scripting language created by Larry Wall, and has been ported to 
many platforms.  Most Linux and Mac OS X systems will have Perl pre-installed.
On other operating systems, such as Windows 95, NT, and Mac OS Classic, you can
download Perl runtime later.  For Windows, I recommend ActivePerl 
(http://www.activestate.com/ActivePerl/).  For Mac OS Classic, you can use 
MacPerl (http://www.macperl.com).  Please note that Livestat has been tested on
Red Hat Linux, Mac OS X, and Windows NT systems only.  Although it contains no
OS-specific calls, please note that at this phase extensive testing has not 
been completed.

Current Perl users will need the modules Net::FTP, File::stat, and File::Find.
Most installations include these.

GETTING STARTED

If you're still with me, congratulations -- it's now time to get down to 
business with Livestat.  The first thing to do is examine all those .pl files
that came with the distribution.  These are Perl scripts.  If you are on a 
Unix system, you will need to make them executable (chmod +x *.pl).  
Optionally, you can start each script by typing "perl" followed by the filename
of the script (perl publish.pl, for example).

SCRIPT          DESCRIPTION
new-tourney.pl  Creates a new tournament (parameter: tournament directory).
set-active.pl   Sets the active tournament (parameter: tournament directory).
game.pl         Enters a game for the tournament into the system.
standings.pl    Generates a standings table based on overall results.
indiv.pl        Generates individual statistics for all players in one table.
rounds.pl       Generates round-by-round statistics.
teams.pl        Generates a page of statistics for each team.
finalize.pl     Modifies statistics pages to stop them from automatically 
                refreshing, and changes their titles to reflect the tournament 
                being finished.  Older files are backed up in the same 
                directory.
publish.pl      Publishes files by FTP.  (You will need to modify this script.)

To set up a new tournament, run 'new-tourney.pl' with the directory name that
you would like to use to store output and data files.  If no such directory 
exists, it will be created.  Enter only a relative path, such as "mytournament"
instead of "/home/ju33/mytournament".  It is strongly recommended that you use 
a different directory for each event.

Livestat 1.2 adds the ability to customize the header and footer for HTML 
files generated.  The page's header covers the start of the HTML file and 
everything up to but not including the body's header.  Likewise, the footer 
should include everything to be rendered after the dynamically created page.
The header and footer are stored in the files common.head and common.foot, 
respectively.  The text "TITLEHERE" will be automatically replaced with the 
appropriate page title.  It is not necessary to type the name of the tournament
into either of these files, but you can include other navigation elements and 
style sheets.

The sample style sheet "layout.css" includes several mappings for special 
styles used by the tables and other elements in generated tables.

If you wish to maintain multiple tournaments concurrently, use 'set-active.pl' 
to switch the active tournament.  The currently active tournament is stored 
in the file "activetourney".  If this file is modified or damaged, 
set-active.pl will restore it.  set-active.pl takes one argument, the directory
name where information is stored.  For example, if you're running a tournament
called 'alpha' and wish to switch to 'beta', run 'set-active.pl beta'.

Once a tournament has been created, run 'game.pl' to assign team and player 
scores.  If a player was substituted in the half, you may state that he/she 
only heard 0.5 of the game (untimed tournaments) or a certain number of tossups
(timed tournaments).  These figures are used when computing statistics such as
points per game.  game.pl does not allow you to backtrack; if you make a 
mistake, see "Fixing Data Entry Mistakes" in the next section.

Once a game has been recorded, you may generate a standings table 
('standings.pl'), individual results ('indiv.pl'), round-by-round statistics 
('rounds.pl'), and team-by-team statistics ('teams.pl').  None of these 
functions take any parameters.  Once generated, the HTML files will be in the
tournament directory, ready for upload to your FTP server.  You will need to 
edit publish.pl to put your own FTP server information in the spaces provided.
Please note that storing your FTP password this way is insecure, so use 
publish.pl at your own risk!

A bash script 'gen' has been provided that generates and uploads all HTML files
based on current data.  Feel free to modify it as you see fit.

FIXING DATA ENTRY MISTAKES

It happens.  You hit '0' at the wrong time, and now your data file is horribly
disfigured.  It's okay -- you can change the files at any time.  Before 
modifying any data file, please back it up!  Save files in text format only 
-- never in a binary format such as Microsoft Word.

All files are located in the tournament's directory.  [yn] means that the 
option can be y (yes) or n (no) only.

global.cfg
name=Full Name of Tournament
power=[yn] (Does this tournament use power toss-ups?)
timed=[yn] (Is this a timed tournament?)

# BEGIN TEAMS (do not delete or edit this line)
teamtag=Name of Team
anotherteam=Some Other Team
...
finalteam=The Last Team
# END TEAMS (do not delete or edit this line)


scores
This file is a comma-separated value file.  Each line takes the format
	round_number,team_a,team_b,score_a,score_b
where 'team_a' and 'team_b' are tags as defined in global.cfg.  Many 
spreadsheet programs, including Microsoft Excel, can export and import CSV 
files such as this one.


indstats
This file is a comma-separated value file.  Each line takes the format
	round_number,team_a,team_b,PlayerName,heard,pheard,power,tossup,neg5
where the parameters are as follows:
	round_number - the round of the match
	team_a, team_b - team tags as defined in global.cfg
	PlayerName - the player's name, which is case-sensitive.  All 
	             characters excluding the comma are allowed.
	heard - the number of toss-ups read in the entire match
	        (or '1' in an untimed tournament)
	pheard - the number of toss-ups heard by this player in this match
	         (or, in an untimed tournament, the portion of this round
	         heard by this player.  If a player left at halftime, this
	         would be 0.5, for example.)
	power - the number of power toss-ups by this player in this match.
	        If power toss-ups are disabled in global.cfg, this will always
	        be set to 0.
	tossup - the number of standard 10-point toss-ups by this player in 
	         this match.
	neg5 - the number of (-5)-point interrupts by this player in this 
	       match.

WEB DESIGN FEATURES

You may modify the .pl files which generate HTML.  By default, Livestat 
depends on a file 'layout.css' which is one directory higher than the 
statistics files.  You should upload this file separately to your web space
in the main directory specified in publish.pl.  Livestat is designed to take 
advantage of Cascading Style Sheets, but please note that not all web browsers
fully and correctly support the CSS1 standard.  More information on CSS is 
available from the World Wide Web Consortium (http://www.w3.org/Style/CSS/).

By default, all Livestat pages have a meta refresh of 90 seconds.  Since 
you will likely want to remove this refresh after the tournament has finished,
run finalize.pl to modify all output files.  Please remember to republish the 
files afterwards.

EXTENDING LIVESTAT

This program is released under the GNU General Public License (GPL).  The 
entire text of the GNU GPL is provided in the enclosed file 'COPYING' for your
convenience.  In short, if you make any modifications or enhancements to 
Livestat, you are obligated to make your derivative works available under the 
GNU GPL as well.

COPYRIGHT AND LEGAL INFORMATION

Livestat is Copyright (C) 2001-02 Jason Weill.  Inquiries about Livestat 
should be directed to [e-mail], or via snail mail to:
	Jason Weill
	SMC 4949
	P.O. Box 3015
	Pittsburgh, PA  15230-3015

Livestat is in no way affiliated with Jupiter Media Metrix Site Measurement, 
which formerly was known as Livestat.  Jupiter Media Metrix Site Measurement
is a service which meters traffic on Internet sites.

Thank you for using Livestat!