updated documentation for version 1.5.0

1 files changed, 212 insertions, 69 deletions

diff --git a/boca-1.5.0/doc/ADMIN.txt b/boca-1.5.0/doc/ADMIN.txt
index ed76a16..7dc83ad 100644
--- a/boca-1.5.0/doc/ADMIN.txt
+++ b/boca-1.5.0/doc/ADMIN.txt
@@ -1,13 +1,18 @@
 How to create a contest
 -----------------------
-(Last updated: 10/Oct/2011 by cassio@ime.usp.br)
+(Last updated: 24/aug/2012 by cassio@ime.usp.br)
 
-1) Log in as "system", empty password.
+(This file also explains details about problem packages, multi-site
+contests, and other relevant topics to run a contest. Please read it
+in full.)
+
+1) Log in as "system", empty password (or the password that is set in
+the file src/private/conf.php under name "basepass").
 
 2) Click on "Options" and change the password of
 the user "system" to something secret and safe.
 
-3a) (Most likely you don't) 
+3a) (Most likely you don't want to do this item) 
 If you have an import file, click on "Import",
 choose the file, click to Send it and go to step 4.
 Note that many follow steps will be already complete.
@@ -51,12 +56,14 @@ IF RUNNING MULTIPLE SITES, BE SURE TO USE THE CORRECT
 NUMBERS HERE ASSIGNED BY WHOEVER IS COORDINATING
 THE MULTI-SITE CONTEST!!
 
-5) Log in as "admin", empty password.
+5) Log in as "admin", empty password (or the password that is set in
+the file src/private/conf.php under name "basepass").
 
 6) Click on "Options" and change the password of
 the user "admin" to something secret and SAFE!!
 
-7) (This can be probably skipped if they are already included)
+7) (This can be probably skipped if they are already included, which
+is the case in the newest BOCA versions)
 Include any answers for submissions that you might
 like to have in addition to the standard ones.
 Click on "Answers" and use the two fields to input
@@ -81,15 +88,19 @@ unless you really know what you are doing. The updates
 cascade on the database, removing or updating everywhere
 needed.
 
-8) Include the contest languages. Use the "Languages"
+8) (This can be probably skipped if they are already included, which
+is the case in the newest BOCA versions)
+Include the contest languages. Use the "Languages"
 item for it. Each language is defined by a number,
-a name and two scripts: one for compiling and running
-the submitted codes and one for verifying if the
-output generated is equilavent to the judge's output.
+a name and the extension of the source files in such language.
+(*** Note that BOCA versions prior to 1.5 had also the scripts for
+compiling and running the submitted codes, and one for verifying 
+if the output generated is equilavent to the judge's output. Ignore
+this comments if you are running BOCA 1.5 or later.
 The scripts should be any executable file permitted
 in the computer that will run the autojudging
 environment (pay attetion on CRs or CRLFs for EOLs.
-This causes problems in some systems). 
+This causes problems in some systems).
 It's also possible to import the language
 information from a file. 
 The scripts are available together with BOCA in the
@@ -104,8 +115,13 @@ Take some minutes to look into those script files, because
 they have path specifications for some executables, such as gcc,
 g++, javac, etc. These paths must be fixed (if needed) before
 uploading the file to BOCA. Usually the default values work
-just fine. If you find any trouble with the scripts, let me
-know.  
+just fine. This ends the part about BOCA prior to 1.5 **)
+
+For BOCA >= 1.5, all scripts to run the submission are inside the
+problem package. Please take a look into the examples in the directory
+doc/problemexamples/ and use them as basis for specifying new
+problems. Later on we discuss further how problems are specified.
+
 If you make some mistake, you can re-insert the language
 even without deleting it. Just fill up the fields again,
 repeating the language number (first field). In this case
@@ -121,34 +137,24 @@ necessary.
 use the form available there. The fields are:
 * Number: number of the problem. Start with 1.
 * Name: nickname of the problem. Good choices are
-problem letters: A, B, C, D, etc.
-Problem fullname: the complete name of the problem.
-Problem basename: the name of the sourcecode file
-expected, without the extension. This is essential
-for Java programmers, who must use this name as the
-main class name.
-* Descfile: a file containing the description of the
-problem. It can be a html file, pdf file, etc. It
-will become available to the teams during the contest.
-You may leave this field empty.
-* Inputfile: file with the input to be used when
-judging the submission of this problem
-(it's possible to have troubles with CRs and CRLFs 
-for EOLs when using multiple OSes).
-* Solfile: file with the correct output for this problem
-when executed with the inputfile. This is the file
-that will be compared with the output generated by
-the team's code (again, it's possible to have problems
-with CRs and CRLFs for EOLs when using multiple OSes).
-* Time-limit: maximum number of seconds the code should
-spend trying to solve this problem.
+problem letters: A, B, C, D, etc. A good practice is to
+create the warm-up problems e.g. using letters plus a dot,
+like A., B., and then the contest problem with A, B, C, D...
+Then, to run the warm-up, one might delete all the contest
+problems, which later can be undeleted for the real contest,
+while the warm-up problem deleted.
+
+* Problem package (ZIP): a zip file (encrypted or not) containing
+all information about the problem. See below for a description
+of how this ZIP must be organized.
 * Color name: name of the color for this problem. It will
 be used if the balloon figure cannot be displayed.
 * Color (RGB): enter the rgb value, in the standard HTML
 format for colors, for this problem. E.g. 000000 is black,
 FFFFFF is white, FF0000 is red, 00FF00 is green and so on.
 Colors are interesting because BOCA presents the balloons
-with the problem colors. Nevertheless, they are not essential.
+with the problem colors. Nevertheless, they are not essential
+and can be left empty.
 
 If you make some mistake, you can re-insert the problem
 even without deleting it. Just fill up the fields again,
@@ -160,61 +166,174 @@ unless you really know what you are doing. The updates
 cascade on the database, removing or updating everywhere
 needed.
 
+===== ATTENTION: READ THIS CAREFULLY IF YOU ARE GOING
+===== TO CREATE YOUR OWN PROBLEM PACKAGE FILES. IF YOU
+===== ARE RUNNING A CONTEST THAT HAS THESE FILES ALREADY
+===== PREPARED FOR YOU, THEN THIS IS NOT SO IMPORTANT...
+PROBLEM PACKAGE: since BOCA 1.5, the problems are
+specified by a ZIP file, which shall have the following folders
+inside it:
+compare/
+compile/
+description/
+input/
+limits/
+output/
+run/
+tests/
+
+Inside compare/, compile/, limits/, runs/, there should be an
+executable (usually a shell script) with the name of each language
+extension that is configured in BOCA (within tab languages). The
+common files are c, cpp and java.
+Inside description/, there must exist a text file named problem.info,
+with the following lines:
+basename=shortfilename
+fullname=This is the problem full name
+descfile=desc.txt
+
+The left-side of this equalities are tags and must not be changed. The
+right-hand side are the values that must be specified.
+shortfilename is the name of the java class that must contain the main() 
+function. This is the name that appears in the booklet of problems 
+that is distributed to the teams. This is a mandatory field. 
+"This is the problem full name" is to be replaced by the full name of
+the problem, as it appears in the booklet of problems. This is also a 
+mandatory field. The line of descfile must contain the name of a file
+that will be made available for the teams in the BOCA interface. It is
+the description of the problem, and can have any format. Usual formats
+are .txt and .pdf files. This field is not mandatory, and this line
+can be removed if one does not want to make the problem description
+available inside BOCA.
+
+Inside input/ and output/ there must have files in a one-to-one
+correspondence and with the same filenames. Each file in input will be
+given as standard input to the code that has been submitted, and later
+the generated output will be compared to the file with same name that
+is in the output/ folder.
+
+The folder tests/ may contain any executable files that are meant to
+test the autojudge system in the first time it is run. To clarify all
+the steps, the workflow of the BOCA autojudge system, which dictates how
+the problem must be specified, is as follows:
+
+When a submission arrives for the first time for a given problem, the
+corresponding problem package is downloaded by the autojudge from the
+server. Then the autojudge reads the description/problem.info to
+obtain the basename of the problem, runs the scripts in the directory
+tests/ to check if everything is ok (the person who specified the
+problem package can include any desired code to be tested in such
+directory, and this code will be run and should return zero on success
+and non-zero otherwise), runs the scripts inside limits/ for each language
+to obtain the time-limits of the problem, and then proceeds to run the
+submission itself. If the problem had already been run by the
+autojudge, then these steps are not performed, but are cached and the
+information is reused later.
+
+To test a submission, the autojudge runs the script in the compile/
+folder corresponding to the language of the submission, which obtains
+an executable version of the code. Then the script of run/ for the
+given language is executed for each file in the input/ directory, and
+finally the script in compare/ is performed (again for the given
+language and every file in the output/ directory), checking if the
+results are correct.
+
+Take a look in the doc/problemexamples/.
+There is a script named gen_examples.sh with some command-lines
+to generated encrypted problem zip files. The main code for that is
+the script createproblemzip.php. If it is not to encrypt the problem
+file, then it is enough to zip the directory with the problem data as
+described, e.g. by doing:
+
+# cd doc/problemexamples
+# zip -r bits.zip bits/
+
+and the file bits.zip is to be included in the problem form of BOCA.
+
 
 10) Include the users. There are five types of users
 that can be used: admin, team, judge, staff and score.
-admin: manage the contest. He(she) has access to every
+* admin: manage the contest. He(she) has access to every
 clarification, run, logs, tasks, etc of the contest.
 It is him(her) that starts and ends the competition
 (although it can be done automaticly by the system).
-You don't need to have more than one or two admin accounts.
-judge: responsible for judging the submission and
+You don't need to have more than one or two admin accounts. It is
+usually useful to have two admin accounts just in case you have any
+problem with one of them.
+* judge: responsible for judging the submission and
 answering the clarification. It's used to have from
 three to eight judges. Note that admins, judges and
-staff must have well formed passwords.
-staff: responsible for printing files, delivery
+staff must have well formed complicated passwords.
+There is one judge, which is appointed by the admin using the tab
+"Site", which is designated as chief judge, and has some additional
+tasks such as fixing submission answers that are not in agreement
+among different judges.
+* staff: responsible for printing files, delivery
 balloons, helping teams with hardware problems, etc.
 Normally one staff account (for the chief staff person)
 is enough.
-score: account with the scoreboard. It has no other
+* score: account with the scoreboard. It has no other
 privilegies. This account is good for making the coachs
 informed about the results and for making the results
-available to remote people. A few score accounts are
+available to remote people. Usually a single score account is
 enough.
-team: here is where the contest happens. These accounts
-are for the teams. The passwords are not so important
-if we restrict the access of each team by IP addresses.
-The same thing may be done for the other users too
+* team: here is where the contest happens. These accounts
+are for the teams. It is safest to restrict the access of each team by
+IP addresses. The same thing may be done for the other users too
 (and it's a good practice to improve security).
+* site: the user of type site is only used as the means of
+communication between the main server and the local servers in a
+multi-site contest. On local sites, this user can be set up with
+standard data (and strong password). The details on how to step up a
+user of type site are usually given by the admin of the main site. The
+users of type "site" on the main server have an important
+characteristic: they are not allowed to directly log in to the main
+site, but connections are established from the local sites. On the
+main site, the ICPC ID (see below) of the user of type "site" must be
+a number corresponding to the site from which the connection will
+come. THIS IS AN IMPORTANT INFORMATION FOR MULTI-SITE CONTESTS ONLY.
+
 The users can be imported by a text file too. See
 IMPORT.txt for details.
 The fields presented in the "Users" item are:
-* User site number: number of the site of the user. Usually 1.
+* User site number: number of the site of the user. Usually 1 in a
+single site contest. or the corresponding site number in a multi-site
+contest. PAY ATTENTION TO USE THE PROPER SITE NUMBER.
 * User number: number of the user (used internally
-by the system). Usually equals the team number.
+by the system). Usually equals the team number, but doesn't have
+to. It only has to be a unique number among users.
 * Username: nickname of the user. Used to be
 team1, team2, team30, judge1, judge2, admin1, staff1, etc.
 It's possible to have the same usernumber and username
 in different sites. In a single site contest, all user numbers
 and usernames must be distinct.
-* ICPC ID: ID Number of team in the ICPC System.
-* Type: type of the user (team, judge, staff, admin, score)
+* ICPC ID: ID Number of team in the ICPC System. In case of users of
+type "site" for a multi-site contest, this field tells the site number
+of the user when connecting to the main server.
+* Type: type of the user (team, judge, staff, admin, score, site)
 * Enabled: is the user enabled? 
 * Multilogins: can the user make more than one connection
 at the same time? It's not a problem to allow that if
 the users are restricted by IP numbers.
 * User full name: complete name of the user. In case of teams,
-it's convinient to put the institution name plus the team
-nickname here.
-* User description: some detail about the user, like students names.
-This field is optional.
+it's convinient to put a short name for the team between [ ] and then
+the full name of the team. This does not include the institution
+name. E.g.
+"[Best Ever] Best team name ever created in history"
+
+* User description: some detail about the user, like institution name
+and students names. The rule of thumb is to have a short institution
+name between [ ], then the full institution name between another pair [ ],
+then any additional description that you may want to include. E.g.
+"[IME-USP][Institute of Maths and Statistics] Person1, Person2, Person3"
+
 * User IP: if set, it restricts from where the user can log in
 the system. It is recommended to restrict the logins by IP numbers.
-If using Maratona Linux, the IP number is 10.0.99.X for the
-team numbered X.
-* Password: password of the user. You may leave it blank for the
-team users as each team user is restricted by IP. Choose good
-password for admins, judges and staff.
+Check the IP numbers of the computers where the teams are supposed to
+be. If using ICPC linux, do not check the IP inside the virtual
+machine, but the IP of the actual computer where the virtual machine
+is run.
+* Password: choose strong passwords!
 
 If you make some mistake, you can alter the user fields.
 Click on the user number in the table and proceed to its
@@ -232,10 +351,10 @@ THE CONTEST.
 11) Configure the site data in the "Site" item. The fields
 are:
 * Site number: number of the site, with a "new" item to create
-new sites. This is not necessary for single contests.
+new sites. This is not necessary for single-site contests. In
+multi-site contest, be sure to have your site number correctly
+assigned to you by whoever is running the main site.
 * Name: name of the site
-* Public IP: internet IP address of this site for communicating
-with the others. Not needed for single contests.
 * Start date, End date, stop answering, stop score: equivalent
 to admin's contest page. Usually the default values are enough.
 * Runs/clars that will be judged here: for multi-site contest,
@@ -245,14 +364,18 @@ site contest, just leave the site number here.
 * Tasks that will be treated here: same meaning of the
 previous field. For single contests or multi-site contest
 it's used to have each site treating its tasks. So leave here
-* the number of the site.
+the number of the local site.
 * Active: is the site active? I hope yes.
 * Autoend: should the contest ends automaticly at the defined
 * time? Usually yes.
-* Globalscore: should the scoreboard be propagated to all sites?
-Not needed for single contests.
-* Autojudge: do not use this option for a contest. It is under 
-development/test.
+* Globalscore: site numbers of the teams that should be included in
+the scoreboard. Not needed for single-site contests. For multi-site,
+this defines which information to include in the local scoreboard.
+* Autojudge: do not use this option for a contest unless you tested
+it and are fine with the results. It basically tell the autojudge to
+take final decisions about the submissions. In a real contest, it is
+ideal that a human judge check each of the submissions before sending
+the result to the teams.
 * Scorelevel: detail level of information on the scoreboard.
 0 means no details while 4 means maximum detail. 2 is a good
 choice, although, for single contests, 3 and 4 are also ok and 
@@ -279,10 +402,11 @@ The "delete all" fields (delete all clars, delete all runs and
 delete all tasks, delete all bkps) are useful (AND IMPORTANT!) 
 for cleaning everything up just after finished the warmup. 
 Between the warmup and the real contest, you
-do not need to create another BOCA contest. Just erase all warmup
+do not need to create another BOCA contest. Just delete all warmup
 problems, all clars, all tasks and all runs (keeping the languages,
-users and answers). Now, reenter the contest information (start
-date and duration, insert the real contest problems and you are
+users and answers). Then undelete the problems of the real contest (if
+you have already included them), or enter them for the first time,
+reenter the contest information (start date and duration), and you are
 ready.
 
 12) It's all done.
@@ -296,6 +420,25 @@ will delete all clarifications and runs related to that
 problem. This way, it's not recommended to remove any of these 
 things during the contest.
 
+
+===
+=== IMPORTANT INFORMATION FOR MULTI-SITE CONTESTS ===
+===
+If you are participating in a multi-site contest as a local site, you
+may simply wait for the main site to set up languages and problems for
+you. If you connect to the main site (by logging in with the user of
+type site you have created) and the problems are already defined
+there in the main site, then they will be downloaded to your site
+automatically. Other information, such as time of contest, inclusion
+of users, languages, etc, can all be downloaded from the main site if
+this has already been specified there. So the natural procedure is to
+create a user type "site" and log in with it, then enter the
+credentials to the main site (it will be asked after the log in) and
+see what information is already downloaded from the main site, before
+spending time included everything by yourself.
+===
+===
+
 Contacts and Copyrights
 -----------------------
 BOCA Copyright (c) 2003- Cassio Polpo de Campos (cassio@ime.usp.br)