                               TinyQCMl
                     (c) Franois Pessaux - 2014

1) Presentation
   ------------
TinyQCMl is a small multiple-choice questions (MCQ) generator aimed to generate
LaTeX (hence PDF) files from a textual description of the questions and their
related choices.

It generates as many versions of the same MCQ with questions and their answers
randomly shuffled for each generated exemplary. Hence, at the end you get one
LaTeX (PDF) file with several times the same MCQ in various and random
'flavors'.

This is intended to make harder copying answers on the neighbour ^_^

In addition, it is possible to provide several variants for a question
(for instance change variable names, pictures or whatever) and for such
a question, the variant used in each exemplary of the MCQ will be randomly
selected. It is under the responsibility of the user to make variants not
fully different to preserve fairness.


2) Syntax of input files
   ---------------------

MCQ are built from a user text file listing questions and their answers.
The basic syntax is a repetition of

{
  "The question surrounded by double-quotes" ;
  {
    "A first answer surrounded by double-quotes", validity ;
    "A second answer surrounded by double-quotes", validity ;
    "As many as you want", validity ;
  }

   "Optionally a variant of the question, same structure" ;
   {
     "Again answers", validity ;
     "Etc.", validity ;
   }
}

The validity is a flag with 2 values:
  OK meaning the answer is a correct one.
  KO meaning the answer is a wrong one.
You may have as many wrong and correct answers, however, the provided LaTeX
macros file currently only support exactly 1 correct answer.


3) Limitations
   -----------
* The provided LaTeX macros file currently only support exactly 1 correct
  answer per question.
* The provided LaTeX macros file currently only support exactly 4 answers
  per question.


4) Options
   -------
  -d Set the date (a string) to display in the header of the first page.
  -help Print the help
  -l Set the name of the file containing the logo to display in the header of
     the first page. By default, searched in $INSTALL_LIB_DIR/images/logo.png
     which is a 270x200 image.
  -m Set the name of user TeX macros file included as preamble of the document.
     By default, searched in $INSTALL_LIB_DIR/macros.tex.
  -n Set the number of exemplaries of the MCQ. Default is 1.
  -o Set the name of the output LaTeX file.
  -p Run pdflatex once the LaTeX file is written.
  -s Generate the solution of the MCQ instead of the ready-to-fill version.
  -t Set the title to display in the header of the first page. Default is empty.
  -v Print version number then exit.
  --help  Display this list of options

  Invocation Examples:
  mkqcm.x -p -d "31-12-2042" -t "Great Course" ex1.qin
    -> Generate the PDF of the exam, 1 copy, date 31-12-2042, title
       "Great Course".
  mkqcm.x -p -s -n 50 -d "Today" ex1.qin
    -> Generate the PDF of the solution, 50 copies, with date "Today", no
       title.
  mkqcm.x -p -s ex1.qin
    -> Generate the PDF of the solution, 1 copy, no date, no title.
  mkqcm.x -p ex1.qin -n 3 -t "201NI" -o readthis.pdf
    -> Generate the PDF of the exam, 3 copies, no date, title "201NI" in the
       file readthis.pdf.
