source: sol/README.rst @ 957

Revision 957, 6.3 KB checked in by lele@…, 21 months ago (diff)

Little tweaks to the README

Scarry On Lin{e|ux}

This project contains some tools that make it easier the organization of a championship of Carrom.

The main component is a Pylons application serving two distinct user interfaces:

  1. A very light, HTML only, read only view of the whole database, where you can actually browse thru the tourneys, seasons and players. You can see it in action on the public SoL instance at http://sol.arstecnica.it/lit/.
  2. A complete ExtJS based desktop-like application, that expose all the functionalities described below in an easy to manage interface, that you can try out visiting http://sol.arstecnica.it/.

Brief history

Scarry was a Delphi application I wrote years ago, with the equivalent goal. It started as a "quick and dirty" solution to the problem, and Delphi was quite good at that. It has served us with good enough reliability for years, but since programming in that environment really boring nowadays, there's no way I could be convinced to enhance it further.

SoL is a complete reimplementation, restarting from scratch: it uses exclusively free software components, so that I won't be embaraced to public the whole source code.

Goals

These are the key points:

  1. Multilingual application

    Scarry spoke only italian, because the i18n mechanism in Delphi (and in general under Windows) sucks. Most of the code was written and commented in italian too, and that makes it very difficult to get foreign contributions

  2. Real database

    Scarry used Paradox tables, but we are in the third millenium, now: SoL uses a real, even if simple and light, SQL database under its skin

  3. Easy to use

    The application is usually driven by computer-illiterated guys, so little to no surprises

  4. Easy to deploy

    Gods know how many hours went in building f*cking installers with BDE goodies

  5. Bring back the fun

    Programming in Python is just that, since the beginning

High level description

The application implements the following features:

  • basic tables editing, like adding a new player, opening a new season, manually tweaking the scores, and so on;
  • handle a single tourney
    1. compose a list of competitors: usually this is just a single player, but there are two people in doubles, or more (teams)
    2. set up the first turn, made up of matches, each coupling two distinct competitors: this is usually done randomly, but the arbiter must be able to manually change the combinations
    3. print the game sheets, where the player will write the scores
    4. possibly show a clock, to alert the end of the game
    5. insert the score of each table
    6. compute the ranking
    7. print the current ranking
    8. possibly offer a way to retire some competitors, or to add a new competitor
    9. compute the next turn
    10. repeat steps c. thru i. usually up to seven turns
    11. possibly offer a way to go back, delete last turn, correct a score and repeat
    12. recompute the ranking, assigning prizes
  • handle a season of tourneys
    • each tourney is associated to one season
    • print the season championship
  • data exchange, to import/export whole tourneys in a portable way

Installation and Setup

  1. Install SoL using easy_install:

    easy_install http://darcs.arstecnica.it/our/sol/dist/SoL-X.Y-py2.6.egg

    where X.Y is the version number, "2.0.1" as I'm writing this

  2. Install ExtJS 2.3.0:

    python -m sol.websetup

  3. Create a standard config file:

    paster make-config SoL config.ini

    and edit it as appropriate

  4. Setup the application:

    paster setup-app config.ini

  5. Optionally load historic data from another instance:

    paster --plugin=SoL restore config.ini http://localhost:6996/

    You may omit the final address: the following will fetch a complete copy of the current database from http://sol.arstecnica.it/:

    paster --plugin=SoL restore config.ini

  6. Run the application server:

    paster serve config.ini

  7. Enjoy!

    firefox http://localhost:6996/

    or, for poor Window$ users or just because using Python makes you happier:

    python -m webbrowser http://localhost:6996/

Documentation

More detailed information about the installation and effective usage of SoL may be found in the distribution (see the Manual entry in the main menu, that basically points to a local copy of manual, available in english or italian).

Development

The complete sources are available in a darcs repository:

darcs get http://darcs.arstecnica.it/our/sol

You can run the test suite with:

python setup.py nosetests

I18N / L10N

Once you install Babel you can update the message catalog (sol/i18n/sol.pot) with:

python setup.py extract_messages

and update the localized messages with:

python setup.py update_catalog

You can start a new language with:

python setup.py init_catalog -l xx

where xx is a two-character code of the language.

Whenever the localized messages get updated, you need to compile them with:

python setup.py compile_catalog

See also http://progetti.arstecnica.it/sol/wiki/LocalizationHowto.

Makefile

Most of the operations usually needed by the development workflow are available also thru make:

$ make help
Please use `make <target>' where <target> is one of
catalog[*]   to compile the i18n catalog
clean[*]     remove regenerable contents and backup files
dist         to prepare for distribution packaging (runs [*] targets)
egg          to create an EGG packaging (runs [*] targets)
install      to install the package
html[*]      to build the HTML documentation
messages     to extract and update the i18n catalog
minimize[*]  to minimize JS and CSS
test         to run the test suites
publish      push changes, egg and manual to the master site
Note: See TracBrowser for help on using the repository browser.