How to run the XS4ALL HCC Quiz ------------------------------ This distribution is complete with perl sources, questions with images, and a CGI version to play via the web. You need one controlling PC for the (associate of the) quizmaster, preferably one PC connected to a beamer for the audience to be able to see what's going on, and one PC for each contestant (this script was written with four contestants in mind, but reasonable other numbers should work too. You might need to change the MAXCONTESTANTS in the quizmaster script) Unpack the distribution tar.gz file (you probably already did that). The distribution is needed on all PCs. On the controlling PC, you start "quizmaster". On all the other PCs, start "quiz" (or "quiz -l" to make that PC wait for a server to appear, or "quiz -s servername" to explicitly specify the server if it cannot find it automatically). The questions ------------- The questions are stored in a regular text file, so it can be edited by practically everybody. You can use multiple files or just one file. See the provided sample questions on the format. Always put a line of asterisks **** before a question. Then the question itself, followed by the answers labelled 1) through 4) or a) through d). The the sentence "Het juiste antwoord is: " followed by the label of the right answer (remember, this was developed for a dutch audience! You will find LOTS of dutch sprinkled throughout this entire project). If you use the 1) through 4) labels, the program won't re-order the possible answers. If you use a) through d), the program will randomly shuffle the possible answers every time you select the question. After giving the correct answer, you can put any additional explanation in the file. This explanation is currently only displayed in the CGI version when the answers are evaluated. Every line in the file that starts with "#" will be completely ignored. Start a new round by putting just the round title on a line, immediately followed by a line of asterisks. (if this follows a question, make sure you put a line of asterisks above the title, too!) You can adapt the textfiles and re-read them into the quizmaster application by selecting the appropriate menu button (File -> Reload Vragen. Mixing Dutch and English again...) You don't need the files containing the questions on the machines where you run "quiz". It might even be better to remove them to prevent quiz contestants from viewing them and learning all the answers. This way you only need to control the PC running the quizmaster application. The pictures must be installed on every PC, though. Note that the sample questions included (in dutch!) have been assembled, written, conceived, stolen and organised by the competent staff of XS4ALL Internet. (To be honest, the incompetent part of the staff also contributed a few questions). We were often inspired by the questions of the 1998 O'Reilly Perl Conference Quiz Show by Jon Orwant (thanks, Jon!). We hope that as long as this source of some of the questions is honourably mentioned, this isn't thought of as "plagiarize" but more as "verbosely referring to previous art". Installing the PCs ------------------ You need PCs running a decent OS (It doesn't work on wintendows crap, at least not using a reasonably recent activestate perl, probably due to problems with Tk::fileevent). Your PCs will need a minimum screen resolution of 1024 by 768. You'll need perl version 5.005_03 or better, and the following perl modules that are available on CPAN: Tk 800.015 or better, Storable 0.6 or better, Time::Hires 1.20 or better. Further, it is EXTREMELY important to properly time-synchronise the PCs. I suggest running xntpd. If you loose time synchronisation, the time bars will behave erratic. Finally, since the quiz protocol isn't exactly "safe", you will need to fill in the netblock you're using in the quizmaster application so it will allow the clients to connect. Look for the @allowed_ip initialisation near the top of the quizmaster script. OPERATION --------- This should be straightforward for anyone with the appropriate amount of clue. Especially the "quiz" application is made for a target audience just barely able to browse the web: you see a question, then the answers, there's a timebar counting down, and you can either click the right answer or type "a" through "d" or "1" through "4" to choose an answer. As long as time lasts, you can select another answer if you change your mind. Let the quiz candidates try it out with a test question if you like. A candidate can change his/her name by double clicking on the "Naam" field. The person controlling the "quizmaster" application should have some more clues. First, for each incoming connection, you need to go to the "Client" menu to configure the type of client. For each client, you can choose to "Set Name", "Set Type", or "Kick". The "Kick" option will ask the client to leave (the quiz application running on that client will normally quit). Using "Set Name" you can set the name of the client in case that's useful. The client can set his own name by double clicking on the "Naam" tag, too, but sometimes the client forgets/doesn't know how to operate a mouse/is too lazy/forgets... This is the name that's projected on the projector PC (as soon as you configured that, at least), and that will be visible in the bottom of your quizmaster application in the box containing the users' score and answer given. The "Set Type" menu is most important, and actually too much information has been crammed in there. On the left of the "Set Type" popup window, there's a group of "positie op display" radio buttons. You determine the position on the projector with this, and likewise the position on the display of your quizmaster application. If set to "Niet" (No), nothing about this client is displayed or projected. As a result, this client won't have a popup box with "Naam" and there won't a score visible either. If you select a position for a client, "Naam" and "Score" will appear on the display of this client. The quizmaster application will also display name, score, and given answer for this client, as will the projector. Name will default to a part of the IP address if you haven't set the name yet. Obviously, you cannot put two clients on the same display position, so positions already occupied are greyed out. Move clients temporarily to "Niet" if you want to shuffle them around. On the right in this menu there's "Resultaten en scores weergeven (projector)". If you select this, a bar containing boxes with the names and scores will appear on this client. This is meant to be used with the projector, obviously, but you can enable it for any client if you like. Finally, you can change a clients' score here. Bit of an odd place for a change of score box to be in, but hey, I was being lazy and adding this was easier than adding another menu item. The screen with the questions is reasonably self explaining. If you click on a question, you select that question. You can also use the arrow keys to move the cursor around and use the Enter key to select a question. If you've already used a question, it will be displayed darker than the others (but that doesn't prevent you from using it anyway). Someone familiar with Tk will immediately recognise where this came from. Below the questions are a couple of buttons: "Vraag" (question). This puts the currently selected question on all of quiz applications. Or, if you just completed a question, it will move on to the next question in a specific round, and select and present the next question. "Antwoord" (Answer). This puts the answers on. "Start tijd" (Start time). Starts the timebar. "Antwoord projecteren", checkbox (project answers). Enabling this button puts the answers given by the contestants on the PCs selected for projection. If you do this while the time is still running, contestants can peek at eachothers given answers by looking at the projector screen, but this does make the audience more involved. "Juiste antwoord" (correct answer). This displays the correct answer, and credits the contestants who gave the right answer with 1 point. "Scherm leeg" (clear screen). Remove the question and answers from the screen. Might be useful at the end of a round. In between questions, you can just proceed to the next question. You can't always select all of these buttons, but usually what's available here and what not is quite logical. As soon as you start the time, there's no going back, and you have to complete this question. Finally there are some options under the "File" menu of the quizmaster application. "Reload vragen" (reload questions) rereads the text files making up the questions, allowing you to change the questions while the quizmaster application is running. In case anything goes wrong while parsing the text file, an error message will be displayed in a bold red font at the appropriate place in the questions screen. Just fix the problem and reread the questions again. Note that rereading the questions erases all memory of questions you already used. Using "Reset buttons" activates all of the question-buttons, in case you somehow get yourself into a deadlock there. Then there's "opties" (options). This allows you to change some settings. The "bedenktijd" (thinking time) is 5 seconds by default, but can be changed into anything you like. It's the time the timebar takes to go to zero. You can also automatically start the time once you click "antwoord" (answer). The three radio buttons control the state of the "antwoord projecteren" (project answers) checkbox. You can either leave it as is, or turn this setting on or off by default once you click on "Vraag" (question). CGI --- The cgi version is contained in the "html" subdirectory. It consists of one cgi script, "quiz.cgi", and a script to prepare the data files necessary for the cgi version, "prepare". Run the "prepare" program to convert the questions to the data format needed by the cgi script. The output of the prepare program is a skeleton index.html. Install the generated files, the quiz.cgi application and the all the gif files from the main directory in the same directory as you put the index.html file, create a writable (by the cgi user) quiz.log file and you're ready to go. TODO ---- As the expierence at the HCC Quiz points out, a few things are still missing from this code: Logging! It didn't log anything, so I don't know who answered what question in what way. Rats. (There is logging in the CGI version, though). Major code cleanup. The code isn't properly written, I often choose to cut-n-paste sections, instead of properly modularising them. Also (as is often the case in GUIs), lots of globals make the code even more ugly. It would probably be neat to have an option for "Antwoord weergeven" to turn on automatically when the timebar reaches a specified value (say, 0). To prevent disasters, include code to auto-detect mis-synchronised clocks on the client PCs, and possibly adjust for it automatically. Do something with the explanations in the Tk version. Implement multiple quiz servers in client. Improve QuizRPC code, maybe use Corba? Re-think timeout mechanism. Distribute question pictures to clients instead of requiring the files to be local. Improve layout of quizmaster application. LICENSE ------- This Quiz application and associated files is Copyright (C) 2000, Jan-Pieter Cornet. Although the GPL license doesn't force you to, I urge you to make any modifications you make for your private use of this this script publicly available. I'm also interested in anyone actually using this code, just drop me an Email! This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA