h1. Do not repeat yourselves or DRY way of working with AMC

Object oriented software design has a main principle, the _do not repeat yourselves_ or DRY principle, that is,

optimize your design in such a way that you do not duplicate (your work on) anything.

Some people could say it is a way of being lazy, which is fine by me, as long as you compensate that with sufficient cleverness.

A way of use AMC in multiple courses is a follows:

Keep all questions in separate files, organised by course and subject.

Preferably also keep them in a version control system. At the moment that is subversion.

h2. Directory structure

Say you teach course LNX, MOD and SEN.

Then for instance my directory structure looks a lot like this.

<pre>

├── lnx

│   └── exam

│       ├── builds

│       │   ├── 20110624

│       │   └── 20120627

│       └── questions

│           ├── chap1

│           ├── chap2

│           ├── chap3

│           ├── chap4

│           ├── chap5

│           ├── chap6

│           └── chap7

├── mod

│   └── exam

│       ├── builds

│       └── questions

└── sen

    └── exam

        ├── builds

        └── questions

</pre>

Keep the question below the questions directory as in @lnx/exam/questions/chap1/cmdline1.tex@, which contain the normal

AMC *question* and *questionmult* environments. Prepare the questions with a normal editor.

h3. Role of files

For each exam that you build from this, create one *exam.tex*, one *questions.tex* and one *students.csv* file in a sub directory specific to the exam instance or exam event.

You could use the convention to use date in short iso8601 format, so 20120627 would be for the exam on 27th of June 2012.

The *exam.tex* file defines all the things that describe the exam and these details are put mostly on the frontpage of each exam.

Think of date, time of the exam, target group, subject title, teachers name and such.

The *questions.tex* file is a more or less simple file with one line specifying the question and the AMC-element group (the element group is what AMC uses to randomize the question order). A *questions.tex* file for a typical exam contains 30 or 40 such lines.

A line looks like this:

<pre>

\element{general}{\inputQ{chap1/cmdline1.tex}}

</pre>

The macro <pre>\inputQ</pre> is no more then an abbrivation of <pre>\input{\QuestionBaseDir/#1}</pre>, of which *\QuestionBaseDir* is explained below.

Keeping the questions separate from the exam file eases the way to create this file, for instance from a spread-sheet or a database query and also eases the comparison with earlier exams, 

so one can easily see if there is not to much overlap in questions for instance for a resit of an exam with (a subset) of the same audience.

The *students.csv* file contains the id's and names (and in my case also the exam language) for the participating students.

h2. Using the AMC gui with the above setup

You can run (and do it for testing purposes of the exams) pdflatex on the *exam.tex* file, but for a real production, use the ~/MC-projects directory and the AMC gui to do all the 

nice things that AMC provides.

To make this work you use a symbolic link *source.tex* pointing to *exam.tex* the tree explained above, for instance in the lnx exam that would be

<pre>

hom@threehundred:~/MC-Projects/lnx_20120629

$ ls -l

source.tex -> ../courses/lnx/exam/builds/20120629/exam.tex

</pre>

but you could point anywhere.

To make sure AMC (or more precisely, pdflatex) can find the files to link and include, you should define a few macros that help latex.

These macros are  

<pre>

\def\CourseDir{/home/hom/fthv/lnx/exam}

\def\QuestionBaseDir{\CourseDir/questions}

\def\ExamInstanceDir{\CourseDir/builds/20120629}

</pre>

It could even be dryer if you keep to conventions like questions and builds always under these names. The you only need to set the coursedir once and the date for a specific exam instance.

*\CourseDir* specifies the course, the *\QuestionsBaseDir* should be obvious as is the *\ExamInstanceDir*.

Note that these specify absolute paths, so that pdflatex can find them, where ever your working directory and latex process directory is.

You can symbolically link the students.csv to the MC-projects subdirectory.

To make this exam known to AMC, start it via the gui and let it create a new *empty* exam with an appropriate name like +lnx_20120629+. Then press edit exam file, which brings up your editor with a new _source.tex_ file. Source.tex is the default file that AMC uses. This is fine.

I save that file and close the editor, cd  (in a terminal window) to the +~/MC-projects/lnx_20120629+ subdirectory and create the symbolic link with 

<pre>

ln -s ../courses/lnx/exam/builds/20120629/exam.tex source.tex

</pre>

This of course removes the auto generated source.tex file and replaces it with a link to the real exam file. You can however still use the edit button with AMC, which will then edit

the newly linked to file. Emacs even recognises the fact that it is a symbolic link to a versioned file and ask if you want to visit the original (pointed to) file. I always say yes.

Back in the AMC guy you can then complete all steps to create the pdf file, check the layouts, print the stuff and after the exam process all.

To make the automatic association and thus producing a personal exam per student, you can use the macros as proposed by Alexis Bienvenüe in ticket #32.

The toyexam.zip attached to this page is a copy of my current collection of test questions, which we can freely use and distribute (unless you teach European topology, 

then you might want to use the questions in a real exam). Anyway, they are the same kind of questions that the maintainers of AMC use to test various features and question type.

Use them freely as a base to clarify questions and answers with respect to this DRY way of working.

h3. Use of the toyexam

Unzip it somewhere conventient.

Create a new exam in the AMC gui e.g., toyexam1 and let the source.tex file point to the *.../toyexam/40_exam/builds/exam1/exam.tex* file.

The names of the directories may differ a bit from the description above, but it is the internal convention we use in our institute.

The subdir *exam2* now contains a complete working example of using a students.csv and auto association.

Link the exam.tex file in the way as described above.