quizz CGI script by Thomas Linden.
Version 1.1.4



Install
---------------------------------

  1. Edit the Makefile.

  2. Type 'make install' (possibly as root)

     or

  1. Copy the whole stuff into a new directory.

  2. Make sure the apache daemon has write permissions
     to the data/ directory.


  3. Configure the apache daemon. Add "Options ExecCGI"
     to the virtual host or directory block where the
     script resides.

  4. Configure the templates. You may use any html editor.
     Be sure to preserve the special tags (inside []) and
     the <!--perl* comments!



Configuration
---------------------------------

  Change to the config/ directory and edit the file quizz.cfg,
  this is the master configuration file.

  The most important thing to do for you is to add an additional
  config file. You can have many additionaly configs, one for
  each questionaire.


  Edit the questionaire config file, see the example file
  pc.quizz for an example. The name of this file does not
  matter - btw.
  

  The questionaire config file should at least have the following
  stuff configured:

    quiz_name         - the quiz name
    quiz_description  - a description
    key               - a random string, used as directory for
                        data storage

    The <config>..</config> block contains several important
    values which influences the behavior of the script:

       max_best       - how many users should be displayed in the
                        best of list

       you can either use counter_time or counter_points as the
       timeout counter, set the appropriate one to 1.

       The variable 'cookie' can be set to one of the following
       values:
          none   - no cookies will be used at all
	  user   - allow one quizz entry per user
	  ip     - allow one quizz entry per source-ip
	  both   - allow one quizz entry per user and source-ip

       The variable 'cookie_expire' sets the expiration of the
       cookie, the default is one week (+1M), see the CGI.pm
       manpage for a description of the format. It has no effect if
       cookie is set to 'none'.

  The questions are configured in <question N>..</question> blocks
  N is the numer of the question, this must be an integer.

    The following variables must exist:

      time   - max seconds the question takes
      points - max points for max time, e.g. if time is 20 and points 40
               then the user gets 40 points if he needs 0 seconds.
               points must be tilable by time!
      type   - question type. possible values:
                 M (multiple choice)
                 S (single choice)
                 R (regular expression)
      question - the question you want to ask, some string.

     For single and multiple choice questions you have to define
     a <choice>..</choice> block, which contains the possible
     choices. Inside such a block are one or more questions defined.
     Eg:
         <choice>
	   A = God.
	   B = Himself.
	   C = His murder.
	   D = The gun.
	 </choice>

     The variable 'result' defines which answers are the correct ones.
     For single choice questions just add the letter or number.
     For multiple choice questions add the letter(s) separated by
     comma.
     For regex questions just add the perl regex on which the answer
     must match.

     If you are using O as 'type' (optional-multiple choice) then you
     may define a number of possible correct answers and in an
     additional variable 'required' the number of minimum required
     correct answers. This makes it possible to have e.g. 3 correct
     answers but 2 correct answers are enough to achieve the points.
     If 'required' is undefined or 0, then any choice will be true
     even if the user chooses none answer. Beware!



Maintenance
---------------------------------

 This CGI script stores some informations in GDBM files (result.db and
 stats.db) in the data/ directory. If you want to manage those files,
 I suggest you to use dbtool (http://www.daemon.de/dbtool/). dbtool
 allows you to remove or to modify entries and much more.



License
---------------------------------

  Licensed under the terms of the artistic license.



Copyright
---------------------------------

  2003 (c) Thomas Linden <tom@daemon.de>



    