readme

Migma intends to help teachers to get several different multiple-choice exams based on the user?s or

Migma 0.1.0  - 2004
by Antonio L Basile ([e-mail])
GNU General Public License (GPL)
Migma comes with ABSOLUTELY NO WARRANTY.


-----
Files 
-----

1) This README
2) migma (bin)
3) migma.pl (source code)
4) exam-Eng.txt (a english sample exam, to test migma)
5) exam-ptBR.txt (a portuguese sample exam, to test migma) 
6) COPYING (migma's license details - GPL)

-------------------
Instalation Process
-------------------

The installation process is as follows:

   1. After downloading your file execute:
   2. gzip -d migma-<your hw>-<your distrib>-x.y.z.tar.gz
   3. tar -xf migma-<your hw>-<your distrib>-x.y.z.tar


If binary doesn't work, you can compile the source code (migma.pl) yourself :

   1.  download and install a recent version of gnu-prolog (from site gnu-prolog.inria.fr)
   2.  open a terminal and look for migma.pl
   3.  type and execute: gplc --min-size migma.pl

obs1: you can also change the local and global stack sizes for migma in
compilation (look in: gplc --help)

obs2: Under windows, you also need to download and install nasm.exe
(http://prdownloads.sourceforge.net/nasm/nasm-0.98.38-djgpp.zip?download)




-----
Usage
-----

Usage: migma [options] <input-file>...
Options:
  -h, --help        print this help and exit
  --hbr             print this help in portuguese and exit
  -a                reorder alternatives (only)
  -q                reorder questions (only)
  --all             reorder alternatives & questions (default)
  -o <file>         place output into file 
  --num <N>         number of (generated) different tests
  --nolatex         output without latex format (default: latex)
  --stats           print statistics
  --audit           create validation file
  --time            print execution time
  --about           display about information and exit
You can use --param or -param (with the same effect) for all the options above.
 
On your text (original):
  begin text (first line) with \inigab <answer sheet> \fimgab
  begin all questions with \que
  begin all alternatives that can be changed with \item
  begin all fixed alternatives with \fixo (only last ones supported)
 
Example:
  \inigab 1c-2a-3c-4b-5e \fimgab   %use this layout (ans-sheet)
  \que  Choose an irrational animal:
  \item the author of this software
  \item a student asking for good marks
  \item prolog
  \item everybody
  \fixo none of the above (nda)
  etc...
 



---------------
Learning to fly
---------------

Some examples to help:


    * The following example creates 10 new versions (p1-AA1, p1-AA2,
etc) from an original exam named p1-AAorig.  They will be generated in
latex format (default) and both - alternatives and questions will be
reordered (default):

./migma    -o   p1-AA   --num  10    p1-AAorig



    * Now let's make a no-latex version of an original exam named
psub-AI-v.txt (with no concern about generated names):

./migma  -nolatex psub-AI-v.txt 
(in this case the generated exams will be: psub-AI-v1.txt, psub-AI-v2.txt, etc)



    * Let's have 3 new exams prepared from the original p2-RNA.txt,
reordering alternatives only (questions remain in the same
position). Let's also have new names like p2-RNAvXX.txt (p2-RNAv1.txt,
p2-RNAv2.txt, etc):

./migma    -a    -o   p2-RNAv.txt    --num   3     p2-RNA.txt



    * Let's have 5 new exams prepared - from the original test.txt,
with audit file, changing the test's name to test-vXX.txt, printing
statistics, without latex format and reordering only the questions:

./migma   --num  5   -audit   -o  test-v.txt   -stats   -nolatex   -q    test.txt
	




VERY IMPORTANT OBSERVATION

If you want a balanced answer sheet, on your original exam:
1) Always use balanced (and random) answer keys on your original exam
(1c 2a 3e 4b etc), ie,
2) Never use something like this : (1a 2a 3a 4a etc)
This procedure helps random process.
A few words:
if you put unbalanced ans-sheet exam, you will get unbalanced ans-sheet exams.




ACKNOWLEDGMENTS

Prof Arnaldo Mandel
Prof Flávio Soares Correa da Silva
Prof Imre Simon
IME-USP
Instituto Presbiteriano Mackenzie 
7K-1sem04-Mackenzie
Christiane Schultz
Juliana Ubhi
Sonia Costa Pereira