<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

"/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">

<article lang="en">

  <title>Auto Multiple Choice</title>

  <articleinfo>

    <title>Auto Multiple Choice</title>

    <subtitle>Design of MCQ tests with automated correction and

    grading</subtitle>

    <abstract>

      <para>AMC is a set of utilities allowing the use of MCQ written in plain

      text or LaTeX, and their automated correction and grading from scans of

      the answer sheets using Optical Mark Recognition (OMR). This document

      describes its use (for the version

      @/PACKAGE_V_DEB/@~@/PACKAGE_V_VC/@).</para>

      <para>The AMC project is hosted by <ulink

      url="http://gna.org/">Gna !</ulink> : you can find the AMC web-site

      there <ulink

      url="http://home.gna.org/auto-qcm/">http://home.gna.org/auto-qcm/</ulink>,

      and the web-page where the project is hosted there <ulink

      url="https://bitbucket.org/auto-multiple-choice/auto-multiple-choice">https://bitbucket.org/auto-multiple-choice/auto-multiple-choice</ulink>.</para>

    </abstract>

    <author>

      <firstname>Alexis</firstname>

      <affiliation>

        <address><email>paamc@passoire.fr</email></address>

      </affiliation>

      <surname>Bienvenüe</surname>

      <contrib>Main author</contrib>

    </author>

    <author>

      <firstname>Anirvan</firstname>

      <surname>Sarkar</surname>

      <contrib>Author and Editor</contrib>

    </author>

    <editor>

      <firstname>Hiroto</firstname>

      <surname>Kagotani</surname>

      <contrib>Editor</contrib>

    </editor>

    <copyright>

      <year>2008-2013</year>

      <holder>Alexis Bienvenüe</holder>

    </copyright>

    <othercredit class="translator">

      <surname>Bérard</surname>

      <firstname>Jean</firstname>

      <contrib>Translation from French</contrib>

    </othercredit>

    <othercredit class="translator">

      <surname>Khaznadar</surname>

      <firstname>Georges</firstname>

      <contrib>Translation from French</contrib>

    </othercredit>

    <legalnotice>

      <para>This document can be used according to the terms of the GNU

      General Public License, version 2 or later.</para>

    </legalnotice>

  </articleinfo>

  <sect1>

    <title>License</title>

    <para>Auto Multiple Choice is free software: you can redistribute it

    and/or modify it under the terms of the GNU General Public License as

    published by the Free Software Foundation, either version 2 of the

    License, or (at your option) any later version.</para>

    <para>This program is distributed in the hope that it will be useful, but

    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY

    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License

    for more details. You should have received a copy of the GNU General

    Public License along with this program. If not, see <ulink

    url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>.</para>

  </sect1>

  <sect1 id="prerequis">

    <title>Prerequisites</title>

    <sect2>

      <title>Operating system</title>

      <para>The AMC utilities have been written for Linux. They might be

      adapted to MAC OS X or Windows without too many difficulties, but I

      won't do that in the near future. Please contact me if you are

      interested to do it : I can help you a little, and I will include

      changes in AMC if necessary.</para>

    </sect2>

    <sect2>

      <title>Software</title>

      <note>

        <para>If you install AMC with deb or RPM package (on debian, Ubuntu

        and derivatives, Mandriva, openSUSE, Fedora), every software used by

        AMC will be automatically installed.</para>

      </note>

      <para>The main packages/software that are required for the use of AMC

      are the following:</para>

      <itemizedlist>

        <listitem>

          <para>LaTeX</para>

        </listitem>

        <listitem>

          <para>ImageMagick</para>

        </listitem>

        <listitem>

          <para>Perl, together with Gtk2-Perl and Glade::XML for the graphical

          user interface</para>

        </listitem>

      </itemizedlist>

      <sect3>

        <title>Recommended versions for software used by AMC</title>

        <para>A few bugs in old versions of software used by AMC are

        particularly detrimental to its operating normally:</para>

        <itemizedlist>

          <listitem>

            <para>With old versions of <package>Net::CUPS</package> (debian

            package <package>libnet-cups-perl</package>), the command for

            printing the test sheets leads to a premature exit from the AMC

            graphical user interface. This bug is fixed in versions 0.61 and

            later of <package>Net::CUPS</package>.</para>

          </listitem>

          <listitem>

            <para>With old versions of ImageMagick, the merging of corrected

            answer sheets into a single PDF file per student does not work

            when answer sheets comprise more than one page. This bug is fixed

            in versions 6.5.5 ad later of ImageMagick.</para>

          </listitem>

        </itemizedlist>

      </sect3>

    </sect2>

    <sect2>

      <title>LaTeX</title>

      <para>From version 1.1 of AMC, it is not mandatory anymore to write your

      questionnaires using LaTeX language (see <xref linkend="AMC-TXT"/> for a

      plain text alternative syntax). However, LaTeX is still the native AMC

      language for questionnaires descriptions, and allows the user to design

      his questionnaires with tremendous freedom. The templates that are

      provided should allow those who are not deterred by LaTeX format to

      quickly start writing their own MCQs.</para>

    </sect2>

  </sect1>

  <sect1 id="usagenotes">

    <title>Usage notes</title>

    <sect2>

      <title>Numerical limitations</title>

      <para>In the present version (starting with version 0.156), the maximum

      number of students per test is limited to 4 095, and the maximum number

      of pages per test is limited to 63 ( Modifiable default values, see

      <xref endterm="binary.code.title" linkend="binary.code"/>).</para>

      <para>The maximum number of answers for a given question is limited to

      199 (Unmodifiable default value).</para>

      <para>LaTeX's own limitations may make compilation impossible, producing

      e.g. a « <errortext>No room for a new \toks</errortext> » error. In that

      case, try again using the package <package>etex</package>, thanks to the

      <code>\usepackage{etex}</code> command.</para>

    </sect2>

    <sect2>

      <title>Versions</title>

      <para>Even though it should not have too many consequences, it is

      recommended not to change the program version while working with a given

      project (between the time when the test sheets are printed and the time

      when tests are corrected and graded). There are a few modifications

      which may interfere with AMC operating normally if you apply them while

      working with a given project:</para>

      <itemizedlist>

        <listitem>

          <para>If you have compiled and printed with a version of AMC earlier

          than 0.155, and then handle the project with version 0.156 or later,

          add the option <option>versionA</option> in the reference to the

          package <package>automultiplechoice</package> in the LaTeX file.

          Example:</para>

          <programlisting>\usepackage[box,completemulti,versionA]{automultiplechoice}</programlisting>

        </listitem>

        <listitem>

          <para>From version 0.262 on, the drawing of the checkboxes changed

          to be slightly larger, which may alter the layout of the test

          sheets.</para>

        </listitem>

        <listitem>

          <para>From version 0.267, if you want to produce A4 format test

          sheets, you have to state it explicitly in the LaTeX file:</para>

          <programlisting>\documentclass[a4paper]{article} </programlisting>

        </listitem>

        <listitem>

          <para>From version 0.394, if your LaTeX code needs package

          <package>graphicx</package>, you have to load it explicitly (earlier

          versions of AMC loaded it).</para>

        </listitem>

        <listitem>

          <para>The LaTeX command <command>\AMCcode</command> was rewritten in

          version 0.518. It is now more robust and configurable, but you will

          have to adapt the LaTeX sources you wrote for older versions to keep

          the same layout.</para>

        </listitem>

        <listitem>

          <para>From version 1.1.0, all AMC data is stored in SQLite databases

          instead of lots of XML files. The first time you open a project, old

          XML files will be converted to the new format.</para>

        </listitem>

      </itemizedlist>

    </sect2>

    <sect2>

      <title>Installation</title>

      <para>With debian, Ubuntu, or a derived operating system, you can use

      the debian official repository and ubuntu AMC repositories. On Mandriva,

      openSUSE or Fedora, you can use prebuilt RPM packages. The installation

      procedure is described on the <ulink

      url="http://home.gna.org/auto-qcm/download">AMC web-site</ulink>.</para>

      <para>You can also download the source code archive on the project

      <ulink url="http://download.gna.org/auto-qcm/">download space</ulink>,

      then use the following commands in a terminal:</para>

      <screen>tar xvzf auto-multiple-choice_xxxx_precomp.tar.gz

cd auto-multiple-choice-xxx

make

sudo make install</screen>

    </sect2>

    <sect2>

      <title>Access</title>

      <para>Once the installation is made, the graphical user interface can be

      launched by choosing <menuchoice>

          <guimenu>Applications</guimenu>

          <guisubmenu>Education</guisubmenu>

          <guimenuitem>Auto Multiple Choice</guimenuitem>

        </menuchoice> in the Gnome general menu (or its KDE or other analog),

      but one can also use the <userinput>auto-multiple-choice</userinput>

      command.</para>

    </sect2>

  </sect1>

  <sect1 id="AMC-TXT">

    <title>AMC-TXT syntax</title>

    <para>For users who are not ready to learn LaTeX (if not already familiar

    with this language), AMC includes a filter to process simple plain text

    files in a particular format, named AMC-TXT. This section is devoted to

    detail the syntax of AMC-TXT files. If you prefer use LaTeX to gain a

    fine-control over your questionnaires, skip to next section.</para>

    <para>Let us begin with a simple example:</para>

    <!--NAME: AMC-TXT format simple example

DESC: A very simple example (from the documentation) using the AMC-TXT format. This is a very simple plain text format to write your questionnaires without any LaTeX knowledge.-->

    <programlisting id="modeles-simple-txt.txt"># AMC-TXT source file

Title: My first AMC questionnaire

Presentation: Please answer the following questions

the best you can.

* What is the capital city of Cameroon?

+ Yaounde

- Douala

- Kribi

** From the following numbers, which are positive?

- -2

+ 2

+ 10</programlisting>

    <important>

      <para>The file that contains your questionnaire must be a plain text

      file, UTF-8 encoded. This is the default encoding of several text

      editors, like <command>gedit</command>. Don't use a text editor that can

      format your text with bold, images, and so on, like

      OpenOffice/LibreOffice, or equivalent: these save your text with a lot

      of other data, and AMC won't be able to read it.</para>

    </important>

    <note>

      <para>The default font that will be used is <ulink

      url="http://www.linuxlibertine.org/">libertine</ulink>, an open source

      font that contains characters for a lot of languages. You have to

      install this font or choose another one (see options below). If you

      install AMC with a debian/ubuntu package, this font will be install

      together as a recommended package.</para>

    </note>

    <para>You already understand AMC-TXT structure: some general options

    first, and then questions.</para>

    <sect2>

      <title>Comments</title>

      <para>You can write some comments inside your AMC-TXT source file in

      lines <emphasis>beginning</emphasis> with a `<code>#</code>'. These

      lines won't be considered by AMC.</para>

    </sect2>

    <sect2>

      <title>General options</title>

      <para>Here are the options you can use (in any order):</para>

      <variablelist>

        <varlistentry>

          <term>Lang:</term>

          <listitem>

            <para>use it to specify a language the questionnaire is written

            in. At present, only DE (German), ES (Spanish), FR (French), IT

            (Italian), NL (Dutch), NO (Norwegian), PT (portuguese), JA

            (Japanese, see <xref linkend="txt-japanese"/>) and AR (Arabic, see

            <xref linkend="txt-arabic"/>) are supported. Without this option,

            English will be selected. You can also define the localized string

            used for another language (see the <option>L-xxx</option>

            options).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>PaperSize:</term>

          <listitem>

            <para>Sets the paper size. Possible values are <code>A3</code>,

            <code>A4</code>, <code>A5</code>, <code>A6</code>,

            <code>B3</code>, <code>B4</code>, <code>B5</code>,

            <code>B6</code>, <code>letter</code>, <code>legal</code>,

            <code>ANSIA</code>, <code>ANSIB</code>, <code>ANSIC</code>,

            <code>ANSID</code>, <code>ANSIE</code>.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>Title:</term>

          <listitem>

            <para>The exam title, written on top of the sheet.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>Presentation:</term>

          <listitem>

            <para>A text that presents the exam (length, rules...).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>ShuffleQuestions:</term>

          <listitem>

            <para>If 1 (default), questions will be shuffled so that their

            order is different from one sheet to the other. If 0, the

            questions will always show with the same order as in your

            file.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>Code:</term>

          <listitem>

            <para>Give a positive integer value <replaceable>n</replaceable>

            to add boxes so that students will be able to code their student

            number on their sheets, with <replaceable>n</replaceable>

            digits.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>CodeDigitsDirection:</term>

          <listitem>

            <para>Sets the direction for code's digits boxes (either

            <code>vertical</code> or <code>horizontal</code>). If unset, AMC

            will choose the direction from the number of digits (horizontal

            for small number of digits, and vertical for high number of

            digits).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>Columns:</term>

          <listitem>

            <para>Give a positive integer value <replaceable>n</replaceable>

            to get a subject with <replaceable>n</replaceable> columns.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>CompleteMulti:</term>

          <listitem>

            <para>If 1 (default), for multiple questions (those for which

            zero, one or several answers are correct), an answer "None of

            these answers are correct" will be added. Without it, it should be

            impossible to make a difference between "the student didn't answer

            for this question" and "the student thinks no answer is correct

            for this question". If you don't want this answer to be added, set

            this option to 0.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>L-None:</term>

          <listitem>

            <para>Give a string to replace <emphasis>None of these answers are

            correct</emphasis> (see previous option).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>QuestionBlocks:</term>

          <listitem>

            <para>If 1 (default), all questions will be enclosed in a

            invisible frame that prevents it to be split across several

            columns or pages. If 0, questions are allowed to be split if

            necessary: that can save pages at the cost of readability.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>L-Question:</term>

          <listitem>

            <para>Give a translation of <emphasis>Question</emphasis> in your

            questionnaire, if you need.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>L-Name:</term>

          <listitem>

            <para>Give a translation of <emphasis>Name and surname</emphasis>,

            a text written in the box where students are to write their

            identity.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>L-Student:</term>

          <listitem>

            <para>Small text that asks students to code their student numbers

            and write their name, when <option>Code</option> option is

            used.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>TitleWidth:</term>

          <listitem>

            <para>Width of the title zone, when <option>Code:</option> is not

            used. Default value is <code>.47\linewidth</code>.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NameFieldWidth:</term>

          <listitem>

            <para>Width of the name field part. Usual LaTeX dimensions can be

            used. The default value is <code>5.8cm</code> when

            <option>Code:</option> is used, and <code>.47\linewidth</code>

            without <option>Code:</option>.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NameFieldLines:</term>

          <listitem>

            <para>Number of lines in the name field box. Default is

            <code>2</code> when <option>Code:</option> is used, and

            <code>1</code> otherwise.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NameFieldLinespace:</term>

          <listitem>

            <para>Line space in the name field box. Defaut value is

            <code>.5em</code>.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>ManualDuplex:</term>

          <listitem>

            <para>If 1 (this is not the default value), each subject will

            consist of an even number of pages, so that the user can manually

            print the PDF subject for all students in one go in duplex

            mode.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>SingleSided:</term>

          <listitem>

            <para>If 1 (this is not the default value), no blank page will be

            added between the question and the separate answer sheet, even if

            the question has an odd number of pages. This mode can be useful

            when the subjects are printed single-sided, or when it is not

            necessary to separate question and answer sheet.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>BoxColor:</term>

          <listitem>

            <para>Color of the boxes to be filled by the students. This allows

            to print the boxes with some color that won't disturb too much the

            data capture (for example <emphasis>red</emphasis>, but some light

            gray can also be considered). The color has to be given as a valid

            <command>xcolor</command> color (see <command>xcolor</command>

            LaTeX package documentation for details), such as

            <emphasis>red</emphasis>, <emphasis>magenta</emphasis>,

            <emphasis>pink</emphasis>, <emphasis>lightgray</emphasis>,

            <emphasis>cyan</emphasis>, or in the form <code>#RRGGBB</code>,

            like <code>#FFBEC8</code> for some light red.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DefaultScoringS:</term>

          <listitem>

            <para>Default scoring strategy for simple questions (questions for

            which one and only one answer is correct). See <xref

            linkend="bareme"/> for details. The default value gives one point

            for the right answer, and zero for others.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DefaultScoringM:</term>

          <listitem>

            <para>Default scoring strategy for multiple questions (questions

            for which there can be zero, one or several correct answers). See

            <xref linkend="bareme"/> for details. The default value is

            <code>haut=2</code>, so that a perfect answer gives 2 points, and

            each error (ticking a box that should not be ticked, or leaving a

            box that should be ticked unticked) takes one point off (keeping

            the score non-negative).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>LaTeX:</term>

          <listitem>

            <para>Set this option to 1 if you want to use LaTeX commands in

            your texts. This allows for example to insert mathematical

            formulas, like <code>$\sqrt{a+b}$</code>. If 0 (default), all your

            texts will be written unmodified.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>LaTeX-Preambule:</term>

          <listitem>

            <para>Give commands you want to be added to the LaTeX preambule

            (for example <command>\usepackage</command> commands).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>LaTeX-BeginDocument:</term>

          <listitem>

            <para>Give commands to be inserted at the beginning of the LaTeX

            <command>document</command> environment (for example macro

            definitions).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>Disable:</term>

          <listitem>

            <para>Gives a comma-separated list of features to disable. Current

            implemented features are <code>images</code> (see <xref

            linkend="parse_images"/>), <code>embf</code> (see <xref

            linkend="parse_embf"/>) and <code>local_latex</code> (see <xref

            linkend="parse_local_latex"/>).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>PackageOptions:</term>

          <listitem>

            <para>Gives some more options to pass to the automultiplechoice

            LaTeX package (see <xref linkend="sec.package.options"/>.</para>

          </listitem>

        </varlistentry>

      </variablelist>

      <sect3>

        <title>Separate answer sheet</title>

        <para>To use separate answer sheets for your questionnaire, consider

        the following options:</para>

        <variablelist>

          <varlistentry>

            <term>SeparateAnswerSheet:</term>

            <listitem>

              <para>If 1, a separate answer sheet will be added.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>AnswerSheetTitle:</term>

            <listitem>

              <para>Title of the answer sheet.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>AnswerSheetPresentation:</term>

            <listitem>

              <para>Presentation of the answer sheet. For example, remind the

              students that the answers are to be given on this sheet

              <emphasis>only</emphasis>.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>AnswerSheetColumns:</term>

            <listitem>

              <para>Number of columns for the answer sheet.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>AutoMarks:</term>

            <listitem>

              <para>If 1, uses <option>automarks</option> option (see <xref

              linkend="sec.package.options"/>).</para>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect3>

    </sect2>

    <sect2>

      <title>Questions</title>

      <para>Simple questions (questions for which one and only one answer is

      correct) begin with a <code>*</code> at the beginning of the line, and

      multiple questions (questions for which there can be zero, one or

      several correct answers) begin with a <code>**</code>. Insert then the

      question itself, and the choices, introduced with a <code>+</code> for

      correct ones and with a <code>-</code> for wrong ones.</para>

      <sect3>

        <title>Questions options</title>

        <para>Some options are available for questions. They must be separated

        by commas and enclosed by square brackets just after the leading

        <code>*</code>'s, as in the following example:</para>

        <programlisting>*[ordered,horiz,name=sum] How much are

one plus one?

- 0

- 1

+ 2</programlisting>

        <para>Available options for questions:</para>

        <variablelist>

          <varlistentry>

            <term>horiz</term>

            <listitem>

              <para>present choices horizontally, not on separated

              lines.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>columns=<replaceable>n</replaceable></term>

            <listitem>

              <para>make <replaceable>n</replaceable> columns for the

              choices.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>ordered</term>

            <listitem>

              <para>don't shuffle the choices, keep the same order as in the

              description file.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>id=<replaceable>xxxx</replaceable></term>

            <listitem>

              <para>Give a name to the question, so as to locate the

              corresponding results easily in the exported spreadsheets. This

              name must contain only simple characters, without accents and

              LaTeX special characters such as <code>_</code>, <code>^</code>,

              <code>%</code>...</para>

              <para><option>name</option> can also be used instead of

              <option>id</option> for compatibility with old versions, but you

              should prefer using <option>id</option>.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>indicative</term>

            <listitem>

              <para>don't use this question score to compute the global

              student's score.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>next</term>

            <listitem>

              <para>Use this option if you want the question to stay next to

              the previous one, even when using questions shuffling with

              <option>ShuffleQuestions</option> general option.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>first</term>

            <listitem>

              <para>Use this option to place the question always at the

              beginning of the group (see <xref

              linkend="sec.txt-groups"/>).</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>last</term>

            <listitem>

              <para>Use this option to place the question always at the end of

              the group (see <xref linkend="sec.txt-groups"/>).</para>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect3>

      <sect3>

        <title>Scoring strategy</title>

        <para>You can set the scoring strategy for a particular question or

        choice enclosing it with braces just after the leading characters

        (<code>*</code>, <code>**</code>, <code>+</code> or <code>-</code>)

        and the possible options, as in the following example. See <xref

        linkend="bareme"/> for details about the scoring strategy

        syntax.</para>

        <programlisting>*{b=2,m=-1} What is the capital city of France?

+ Paris

- Lille

- Marseille

- Ouagadougou

-{-2} New York

**[ordered,horiz,name=positive]{haut=1} From the following numbers, which are positive?

- -2

+ 2

+ 10

</programlisting>

      </sect3>

      <sect3>

        <title>Open questions</title>

        <para>You can define open question giving options (see <xref

        linkend="openquestions"/>) enclosed with <code>&lt;</code> and

        <code>&gt;</code>, as in the following example:</para>

        <programlisting>*&lt;lines=4&gt; Describe the moon.

-[O]{0} O

-[P]{1} P

+[V]{2} V</programlisting>

        <para>You should also consider using the following global

        options:</para>

        <variablelist>

          <varlistentry>

            <term>L-OpenText:</term>

            <listitem>

              <para>Text used to tell the student to write the answer on the

              separate answer sheet (if relevant).</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>L-OpenReserved:</term>

            <listitem>

              <para>Text to be written along the open questions boxes to tell

              the student not to consider these boxes.</para>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect3>

    </sect2>

    <sect2>

      <title>Multi-line</title>

      <para>You can always continue some text on the next lines (even if some

      of them are empty), provided that these following lines cannot be

      considered as the beginning of an option definition, of a question or of

      a choice. As an example, consider the following question:</para>

      <programlisting>* How much are 2

  + 2?

- 0

+ 4

- 10</programlisting>

      <para>This is a correct AMC-TXT question. However, it won't be treated

      as you'd like to, because here the second line is not considered as

      being the following of the first one, but form the first choice of the

      question!</para>

      <para>A similar problem arises from the following AMC-TXT question,

      where `<code>Gershwin:</code>' is considered as a general option

      definition...</para>

      <programlisting>* You all know Georges

  Gershwin: he is a composer.

  When was he born?

+ in 1898

- in 1892

- in 1902</programlisting>

      <para>This is a correct way to write it:</para>

      <programlisting>* You all know Georges Gershwin:

  he is a composer.

  When was he born?

+ in 1898

- in 1892

- in 1902</programlisting>

      <para>Note that line breaks can be inserted leaving an empty line,

      as:</para>

      <programlisting>Presentation: Title

Description of the exam.

** Difficult question.

How many stars in the sky?

- one

- two

- ten millions</programlisting>

    </sect2>

    <sect2>

      <title>Title</title>

      <para>To get a title, enclose it between <code>[==</code> and

      <code>==]</code>.</para>

    </sect2>

    <sect2 id="parse_embf">

      <title>Bold, italic</title>

      <para>To get <emphasis>bold</emphasis> text, enclose it between

      <code>[*</code> and <code>*]</code>. To get <emphasis>italic</emphasis>

      text, enclose it between <code>[_</code> and <code>_]</code>.</para>

      <programlisting>* What is the [*capital city*] of [_France_]?

+ Paris

- Lille

- Marseille</programlisting>

    </sect2>

    <sect2 id="parse_images">

      <title>Images</title>

      <para>You can add images in your document using the following

      syntax:</para>

      <programlisting>![height=2cm]images/bird.png!</programlisting>

      <para>Here, the image <filename>images/bird.png</filename> that is

      located in the project directory will be appended with 2cm height.

      Options that can be used inside the square brackets are those from the

      <command>\includegraphics</command> LaTeX command

      (<parameter>width=3cm</parameter> or

      <parameter>keepaspectratio</parameter> for example). To get a centered

      image that is three quarters of the line width, use</para>

      <programlisting>!{center}[width=.75\linewidth]images/map.pdf!</programlisting>

    </sect2>

    <sect2 id="parse_local_latex">

      <title>Pieces of LaTeX code</title>

      <para>You can include some small parts of LaTeX code in your document,

      including it in double square brackets, as in:</para>

      <programlisting>Questions with a [[\multiSymbole{}]] may have zero, one or more right answers.</programlisting>

    </sect2>

    <sect2 id="sec.txt-groups">

      <title>Questions groups</title>

      <para>You can group some question so that they stay together even when

      shuffling, with the following syntax:</para>

      <programlisting>*( Questions about Martin Luther King.

* When was he born?

- in 1901

+ in 1929

- in 1968

* When did he die?

- in 1945

- in 1515

+ in 1968

- in 1999

* Where was he born?

+ Atlanta

- Memphis

- New York

*) End of questions on Martin Luther King. </programlisting>

      <para>You can specify some options on groups, like:</para>

      <programlisting>*([shuffle=false,columns=2] Questions about Martin Luther King.</programlisting>

      <para>The following options are available:</para>

      <variablelist>

        <varlistentry>

          <term>shuffle=<replaceable>xxx</replaceable></term>

          <listitem>

            <para>Give <replaceable>true</replaceable> or

            <replaceable>false</replaceable> to tell if you want to shuffle

            the questions inside the group. The default value if the global

            one, from the <option>ShuffleQuestions</option> option.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>columns=<replaceable>n</replaceable></term>

          <listitem>

            <para>Number of columns for the group's questions.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>group=<replaceable>nom</replaceable></term>

          <listitem>

            <para>Give a name for the group (for internal matter).</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>numquestions=<replaceable>n</replaceable></term>

          <listitem>

            <para>With this option, only the first

            <replaceable>n</replaceable> questions of the group will be used.

            If the questions are shuffled, this allows to get

            <replaceable>n</replaceable> questions chosen at random from the

            group.</para>

            <note>

              <para>Question with option <option>first</option> or

              <option>last</option> are not affected (they are always

              inserted). Moreover, questions stuck together with option

              <option>next</option> count as one single question.</para>

            </note>

          </listitem>

        </varlistentry>

      </variablelist>

    </sect2>

    <sect2 id="txt-arabic">

      <title>Arabic language</title>

      <para>Writing a questionnaire in Arabic is a little special. Use of

      course option</para>

      <programlisting>Lang: AR</programlisting>

      <para>You can also consider the following global options:</para>

      <variablelist>

        <varlistentry>

          <term>ArabicFont:</term>

          <listitem>

            <para>This is the font used for Arabic text. Default value is

            <emphasis>Rasheeq</emphasis>, a font from the project <ulink

            url="http://arabeyes.org/">ArabEyes</ulink> (you can find it on

            debian/ubuntu in the ttf-arabeyes package).</para>

          </listitem>

        </varlistentry>

      </variablelist>

      <warning>

        <para>For better working and portability, give an explicit value for

        <option>L-Name</option> and <option>L-Student</option> options.</para>

      </warning>

      <note>

        <para>To insert texts with non-Arabic characters, you must turn on

        <option>LaTeX</option> option and enclose these texts as a

        <command>\textLR</command> LaTeX command argument, as in

        <code>\textLR{xelatex command}</code>.</para>

      </note>

    </sect2>

    <sect2 id="txt-japanese">

      <title>Japanese language</title>

      <para>Japanese language questionnaires can be produced with

      option</para>

      <programlisting>Lang: JA</programlisting>

      <para>AMC will make some adjustments on the produced LaTeX source to

      allow Japanese characters to be included.</para>

      <warning>

        <para>In this case, AMC will use <command>pTex</command> to process

        the LaTeX file made from your AMC-TXT source file. AMC needs a

        <emphasis>recent</emphasis> version of <command>pTex</command> to

        work. Versions of pTex from texlive 2009, that can be found on old

        versions of some linux distributions, are <emphasis>not</emphasis>

        compatible.</para>

      </warning>

    </sect2>

    <sect2>

      <title>Including other files</title>

      <para>You can include other files with:</para>

      <programlisting>IncludeFile: <replaceable>file-to-include.txt</replaceable></programlisting>

      <warning>

        <para>Be very careful when including a single file from different

        projects! Suppose for example that

        <filename>/home/alexis/questions-a.txt</filename> is included from

        projects A and B. You already processed project A, and you are

        currently working on project B. You update the scoring strategy of a

        question in <filename>/home/alexis/questions-a.txt</filename>, and

        also add another question. If you need to update the marks in project

        A with this new scoring strategy, AMC will also see a new question for

        which no data capture has been made, and this will spoil all your

        marks in A...</para>

      </warning>

    </sect2>

  </sect1>

  <sect1 id="latex">

    <title>LaTeX source file</title>

    <para>This section describes the LaTeX commands that allows you to design

    your exam answer sheets from a LaTeX source file. If you chose another

    format for your source file, you can skip this section. The MCQ can be

    described as a LaTeX file using the <package>automultiplechoice</package>

    package. You can check the LaTeX file you are designing at any moment by

    compiling it with the <command>latex</command> command, then visualizing

    the resulting dvi file.</para>

    <para>We start with a few examples giving quick illustrations of how to

    build LaTeX files for MCQs; the corresponding tex file are available as

    templates, so that one can create a new MCQ project starting with one of

    these templates.</para>

    <sect2>

      <title>A simple example</title>

      <para><!--NAME: Simple example

DESC: A simple example (from the documentation) with one simple question and one multiple question.--><programlisting

      id="modeles-simple.tex" linenumbering="numbered">\documentclass[a4paper]{article}

\usepackage[utf8x]{inputenc}    <co id="simple.latin1"

            linkends="simple.latin1.exp"/>

\usepackage[T1]{fontenc}

\usepackage[box,completemulti]{automultiplechoice}    <co id="simple.amc"

            linkends="simple.amc.exp"/>

\begin{document}

\onecopy{10}{    <co id="simple.exemplaire" linkends="simple.exemplaire.exp"/>

%%% beginning of the test sheet header:    <co id="simple.entete"

            linkends="simple.entete.exp"/>

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}

\begin{minipage}{.4\linewidth}

\centering\large\bf Test\\ Examination on Jan., 1st, 2008\end{minipage}

\namefield{\fbox{    <co id="simple.champnom" linkends="simple.champnom.exp"/>

                \begin{minipage}{.5\linewidth}

                  Firstname and lastname:

                  \vspace*{.5cm}\dotfill

                  \vspace*{1mm}

                \end{minipage}

         }}

\begin{center}\em

Duration : 10 minutes.

  No documents allowed. The use of electronic calculators is forbidden.

  Questions using the sign \multiSymbole{} may have

  zero, one or several correct answers.  Other questions have a single correct answer.

  Negative points may be attributed to \emph{very

    bad} answers.

\end{center}

\vspace{1ex}

%%% end of the header

\begin{question}{prez}    <co id="simple.qr" linkends="simple.qr.exp"/>

  Among the following persons, which one has ever been a President of the French Republic?

  \begin{choices}

    \correctchoice{René Coty}

    \wrongchoice{Alain Prost}

    \wrongchoice{Marcel Proust}

    \wrongchoice{Claude Monet}

  \end{choices}

\end{question}

\begin{questionmult}{pref}    <co id="simple.qrmult"

            linkends="simple.qrmult.exp"/>

  Among the following cities, which ones are French prefectures?

  \begin{choices}

    \correctchoice{Poitiers}

    \wrongchoice{Sainte-Menehould}

    \correctchoice{Avignon}

  \end{choices}

\end{questionmult}

\clearpage    <co id="simple.clear" linkends="simple.clear.exp"/>

}   <co id="simple.fin" linkends="simple.fin.exp"/>

\end{document}

</programlisting></para>

      <para>A few extra details on this example:</para>

      <para><calloutlist>

          <callout arearefs="simple.latin1" id="simple.latin1.exp">

            <para>The packages <package>inputenc</package> and

            <package>fontenc</package> allow one to use the UTF-8 encoding.

            You can of course modify them depending on the encoding you want

            to use.</para>

          </callout>

          <callout arearefs="simple.amc" id="simple.amc.exp">

            <para>The options used here for the <package>automultiplechoice

            </package>LaTeX package prevent questions from being split between

            two pages (<option>box</option>) and to automatically complete any

            multiple choice question by a standard answer allowing the student

            to mention that, in her/his opinion, none of the listed answers is

            correct (<option>completemulti</option>).</para>

          </callout>

          <callout arearefs="simple.exemplaire" id="simple.exemplaire.exp">

            <para>The <command>onecopy</command> command produces as many

            (distinct) realizations of the MCQ test as desired (here 10).

            See <xref linkend="sec.unecopie"/> for an alternative syntax using

            an environment.</para>

          </callout>

          <callout arearefs="simple.entete" id="simple.entete.exp">

            <para>Lines that start here describe the header of the

            test-sheet.</para>

          </callout>

          <callout arearefs="simple.champnom" id="simple.champnom.exp">