tengine.sh - README				Kevin Waldron 2006
===================				==================

Introduction
------------

tengine.sh is a simple quiz engine, primarily designed to be used
as a login shell, so that prospective UNIX/Linux System Administrators
can sit a technical quiz as part of their interview process.

This README assumes that you'll be running tengine.sh as an interactive
quiz, not via a login shell. If you want to set it up to run as a login
shell for an interviewee, just add make the /usr/local/tengine/bin/tengine.sh
script their login shell, and ensure that the interviewee's login account
has read access to the entire tengine tree, and write access to the 
/usr/local/tengine/var/tmp directory, where the results files are stored.

Functionality currently exists within tengine.sh for two types of
questions - multiple choice, and fill-in-the-blank.

Installation
------------

All steps to be performed as root:

# pwd
/usr/local
# ls
tengine.tar.gz
# gzip -dc ./tengine.tar.gz | tar xf -
# rm tengine.tar.gz
# ls
tengine

Beneath the tengine directory, you'll find the following directory
structure

tengine
  |------ bin		# contains the tengine.sh script
  |------ data		# contains the question data
  |        |------ 0001 # sample question directory
  |        |------ 0002 # sample question directory
  |------ var
           |------ tmp  # directory for temporary files and RESULTS 

Because this script was primarily designed for use as a login shell,
results are not given directly to the script user, but rather 
deposited in a file under /usr/local/tengine/var/tmp.

Question Files
--------------

Beneath each question directory, you'll find four files. For example,
in the 0001 directory, there are the following four files:

0001.h
0001.q
0001.a
0001.c

The extensions for these files denote the following:

h - header
q - question
a - answers
c - correct answer

The header file is a four-line file formatted thusly:

QUESTIONID
TYPE
DIFFICULTY
CATEGORY

QUESTIONID can be anything you like, but I like to keep it the same as
the question number directory. 

TYPE can be either MULTI for multiple choice, or BLANK for a "fill-in-
the-blank" type question.

DIFFICULTY is not currently used, and is for future development.

CATEGORY is used to display the question category to the user.

For example, 0001.h may contain:
0001
BLANK
EASY
System Configuration

The question file contains the actual question that will be asked, such as:
In which file is the default runlevel of the system defined?

The answers file contains the possible answers, and is only relevant for
multiple-choice questions.

The correct answer file contains the correct answer, against which the 
users input is compared, for example, 0001.c should contain
/etc/inittab

For a MULTI question, the answers file may be something like:
a - ext2
b - hsfs
c - pcfs
d - ufs

and the correct answer file would contain the appropriate multiple choice
response, such as a simple:
a

Take a look at the sample questions in the /usr/local/tengine/data
directory tree for examples of this.

Notes
-----

If you want to use the script as a login shell, uncomment the NUM_TO_ASK
value and set it to a value less than or equal to the number of questions
currently under the data directory tree. If this variable is commented out,
the user will be prompted for the number of questions that they wish to
attempt.

Results Files
-------------

When the user invokes tengine.sh, they'll be prompted for their Full Name. 
This is used when the results files are generated.

An example results file, found under /usr/local/tengine/var/tmp could be
something along the lines of:
a - a
/etc/inittab - /I/Dont/Know
Kevin_Waldron: 1 answer correct out of 2 - 50%

The format for question lines is 
correct_answer - answer_given

The last line in the results file is a summary of the test.

Performance
-----------

The way that questions are asked "randomly" will work a lot faster if there
is a large pool of questions to choose from.

Questions?
----------

This is a very brief, terse, README. I just put it together so that I could
distribute tengine.sh incase anybody finds it useful. If I receive enough
feedback I will develop tengine.sh and the documentation further, but for now,
any questions and comments, please email me.

kevin@zazzybob.com

Cheers
Kevin