quizz CGI script by Thomas Linden.
Version 1.2.3



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 variable 'latency_limit' configures how many seconds
       a user may take to achive the full points for a question.
       If defined within the <config> block this setting will be
       global. You can define it per question too.

  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)
		 C (cloze expresion)
      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!

     The type "C" (cloze expression) question type means that the user
     has to fill the holes within a freetext. All expressions must be
     correct to succeed, therefore is no 'result' variable required.
     The values are defined with the well-known <choice> block. The
     positions inside the question which have to be filled must be
     marked with <LETTER> where LETTER is one of the letters inside
     the <choice> block, eg:

       question = I <A> <B>.
       <choice>
         A = love
	 B = you
       </choice>
    
     The correct answer will be: I "love" "you".

     For each question you can add an explanation which will be displayed
     in the result page if the user finished the quiz. Example:

       explanation = <<EOF
         Some descriptive text.
       EOF


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-2005 (c) Thomas Linden <tom@daemon.de>



    
