<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/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>

    <date>2018-12-29</date>

    <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
      1.4.0~r:c6041a1).</para>

      <para>You can find the AMC web-site at <ulink
      url="https://www.auto-multiple-choice.net/">https://www.auto-multiple-choice.net/</ulink>,
      and the source code at <ulink
      url="https://gitlab.com/jojo_boulix/auto-multiple-choice/">https://gitlab.com/jojo_boulix/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>

    <author>
      <firstname>Hiroto</firstname>

      <surname>Kagotani</surname>

      <contrib>Editor</contrib>
    </author>

    <author>
      <firstname>Frédéric</firstname>

      <surname>Bréal</surname>

      <contrib>Author and Editor</contrib>
    </author>

    <copyright>
      <year>2008-2018</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 id="license">
    <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 id="prerequis.os">
      <title>Operating system</title>

      <para>The AMC utilities have been written for Linux. They can also be
      installed on MAC OS X using MacPorts.</para>
    </sect2>

    <sect2 id="prerequis.soft">
      <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>image processing libraries ImageMagick and OpenCV</para>
        </listitem>

        <listitem>
          <para>Perl, together with Gtk2-Perl and Glade::XML for the graphical
          user interface</para>
        </listitem>
      </itemizedlist>

      <sect3 id="prerequis.soft.v">
        <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 id="prerequis.latex">
      <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 id="num.limits">
      <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 id="versions">
      <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 id="install">
      <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://www.auto-multiple-choice.net/download">AMC
      web-site</ulink>.</para>

      <para>You can also download the source code archive on the project
      <ulink url="http://download.auto-multiple-choice.net/">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 id="launch">
      <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 id="txt.comments">
      <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 id="txt.opts">
      <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>RandomSeed:</term>

          <listitem>
            <para>One can modify the seed of the random number generator used
            to produce the shuffle, thanks to the option. If the value that is
            assigned ( to be chosen between 1 and 4194303) is modified, then
            the shuffling will differ. Of course, one must not modify this
            value after the test sheets have been printed.</para>

            <note>
              <para>The value is recorded in the xy file (as
              <code>\rngstate{1}{1527384}</code>). The default value is equal
              to 1527384.</para>
            </note>
          </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>Pages:</term>

          <listitem>
            <para>Gives a minimal number of pages for each question sheet. If
            a question has less pages, some white pages will be added. When
            using a separate answer sheet, this option can be written
            <option><replaceable>q</replaceable>+<replaceable>a</replaceable></option>
            (eg. <option>4+2</option>), where <replaceable>q</replaceable>
            will be the minimum number of pages for the question itself, and
            <replaceable>q</replaceable>+<replaceable>a</replaceable> the
            minimum number of pages for the whole sheet.</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>verbatim</code> (see <xref
            linkend="parse_verbatim"/>), <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 id="txt.separate">
        <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 id="txt.questions">
      <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 id="txt.questions.opts">
        <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,id=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 id="txt.questions.scoring">
        <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,id=positive]{haut=1} From the following numbers, which are positive?
- -2
+ 2
+ 10
</programlisting>
      </sect3>

      <sect3 id="txt.questions.open">
        <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 id="txt.multiline">
      <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 id="txt.title">
      <title>Title</title>

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

    <sect2 id="parse_verbatim">
      <title>Verbatim content</title>

      <para>To get a <emphasis>verbatim</emphasis> block (as computer code),
      enclose it between <code>[verbatim]</code> and
      <code>[/verbatim]</code>:</para>

      <programlisting>* What does this program print?
[verbatim]
main( )
{
    printf("hello, world\n");
}
[/verbatim]

+ [| hello, world |]
- [| hello |]
- [| world |]</programlisting>
    </sect2>

    <sect2 id="parse_embf">
      <title>Bold, italic, typewriter, underlined</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>. To get
      <emphasis>typewriter</emphasis> text, enclose it between <code>[|</code>
      and <code>|]</code>. To get <emphasis>underlined</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>

        <varlistentry>
          <term>needspace=<replaceable>dimen</replaceable></term>

          <listitem>
            <para>Gives a height (dimension with unit, such as
            <replaceable>4cm</replaceable>) necessary to begin with the group.
            If the remaining vertical space on the current page is lower than
            this value, the group will begin on the next page.</para>
          </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>

      <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 id="txt.includes">
      <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 id="latex.simple">
      <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}

% \AMCaddpagesto{3} <co id="AMCaddpage" linkends="AMCaddpage.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">
            <para>The <command>namefield</command> command specifies where
            students write their name.</para>
          </callout>

          <callout arearefs="simple.qr" id="simple.qr.exp">
            <para>The environments <command>question</command> and
            <command>choices</command> allow one to build a multiple choice
            question for which there is a single correct answer. A unique
            identifier for the question has to be specified (here:
            <emphasis>prez</emphasis>).</para>
          </callout>

          <callout arearefs="simple.qrmult" id="simple.qrmult.exp">
            <para>The environments <command>questionmult</command> and
            <command>choices</command> allow one to build a multiple choice
            question that may have zero, one or several correct answers.
            Student are asked to check all the boxes corresponding to an
            answer that she/he thinks is correct, or the last box (added
            automatically thanks to the <option>completemulti</option> option
            used in the reference to the package in line 6).</para>
          </callout>

          <callout arearefs="AMCaddpage" id="AMCaddpage.exp">
            <para>Uncomment this line to add enough blank pages to get a
            3-pages copy (see<xref linkend="latex.layout.npages"/>).</para>
          </callout>

          <callout arearefs="simple.fin" id="simple.fin.exp">
            <para>This marks the end of the <command>onecopy</command> command
            (started at line 9).</para>
          </callout>
        </calloutlist></para>
    </sect2>

    <sect2 id="latex.shuffle">
      <title>An example with groups of questions and shuffling</title>

      <para>In this example, we want the order in which questions appear in
      the MCQ test to be different from one realization of the test to the
      other, but still keeping together questions dealing with the same
      subject. To this end, we create two groups of questions, within which
      questions are shuffled at random.</para>

      <para><!--NAME: Groups
DESC: An example (from the documentation) in which questions are shuffled inside two distinct groups.--><programlisting
      id="modeles-groups.tex" linenumbering="numbered">\documentclass[a4paper]{article}

\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[box,completemulti]{automultiplechoice}
\begin{document}

%%% preparation of the groups

\setdefaultgroupmode{withoutreplacement}

\element{geographie}{
  \begin{question}{Paris}
    In which continent is Paris?
    \begin{choices}
      \correctchoice{Europe}
      \wrongchoice{Africa}
      \wrongchoice{Asia}
      \wrongchoice{planet Mars}
    \end{choices}
  \end{question}
}

\element{geographie}{
  \begin{question}{Cameroon}
    Which is the capital city of Cameroon?
    \begin{choices}
      \correctchoice{Yaoundé}
      \wrongchoice{Douala}
      \wrongchoice{Abou-Dabi}
    \end{choices}
  \end{question}
}

\element{histoire}{
  \begin{question}{Marignan}
    In which year did the battle of Marignan take place?
    \begin{choiceshoriz}
      \correctchoice{1515}
      \wrongchoice{1915}
      \wrongchoice{1519}
    \end{choiceshoriz}
  \end{question}
}

\element{histoire}{
  \begin{questionmult}{Nantes}
    What can be said about the \emph{Édit de Nantes}?
    \begin{choices}
      \correctchoice{It was signed in 1598}
      \correctchoice{Il has been revoked by Louis XIV}
      \wrongchoice{It was signed by Henri II}
    \end{choices}
  \end{questionmult}
}

%%% copies

\onecopy{10}{

%%% beginning of the test sheet header:

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
  \centering\large\bf History and geography\\ Examination on Jan. 1st, 2008
\end{minipage}
\namefield{\fbox{\begin{minipage}{.5\linewidth}
Firstname and lastname:

\vspace*{.5cm}\dotfill
\vspace*{1mm}
\end{minipage}}}

%%% end of the header

\begin{center}
  \hrule\vspace{2mm}
  \bf\Large Geography
  \vspace{1mm}\hrule
\end{center}

\insertgroup{geographie}

\begin{center}
  \hrule\vspace{2mm}
  \bf\Large History
  \vspace{2mm}\hrule
\end{center}

\insertgroup{histoire}

}

\end{document}
</programlisting></para>
    </sect2>

    <sect2 id="secensemble">
      <title id="secensemble.title">An example with a separate answer sheet</title>

      <para>In this example, one wants the check-boxes to be put together in a
      separate sheet. This makes cheating more difficult, and, more
      importantly, it is enough to scan a single sheet per student, which
      makes things easier if one has to do a manual scan. In this example, the
      number of questions is limited: they fit into a single page, so that
      such a layout would not be really useful in this particular case. It is
      up to you to modify this example in order to use this layout with a
      large number of questions!</para>

      <para><!--NAME: Separate answers
DESC: An example (from the documentation) where all check-boxes are put together on a separate sheet for each student.--><programlisting
      id="modeles-separate.tex" linenumbering="numbered">\documentclass[a4paper]{article}

\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[box,completemulti,separateanswersheet]{automultiplechoice}    <co
            id="ensemble.opt" linkends="ensemble.opt.exp"/>
\begin{document}

\AMCrandomseed{1237893}

\def\AMCformQuestion#1{{\sc Question #1:}}    <co id="ensemble.fq"
            linkends="ensemble.fq.exp"/>

\setdefaultgroupmode{withoutreplacement}

\element{general}{
  \begin{question}{prez}
    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}
}

\element{general}{
  \begin{questionmult}{pref}
    Among the following cities, which ones are French prefectures?
    \begin{choices}
      \correctchoice{Poitiers}
      \wrongchoice{Sainte-Menehould}
      \correctchoice{Avignon}
    \end{choices}
  \end{questionmult}
}

\element{general}{
  \begin{question}{nb-ue}
    How many different states were members of the European Union in Jan. 2009?
    \begin{choiceshoriz}[o]
      \wrongchoice{15}
      \wrongchoice{21}
      \wrongchoice{25}
      \correctchoice{27}
      \wrongchoice{31}
    \end{choiceshoriz}
  \end{question}
}

\onecopy{5}{

%%% beginning of the test sheet header:

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
  \centering\large\bf Test\\ Examination on Jan. 1st, 2008
\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

\insertgroup{general}

\AMCcleardoublepage    <co id="ensemble.cp" linkends="ensemble.cp.exp"/>

% \AMCaddpagesto{3} <co id="AMCaddpage.separateanswersheet.sujet"
            linkends="AMCaddpage.separateanswersheet.sujet.exp"/>

\AMCformBegin    <co id="debut.form" linkends="debut.form.exp"/>

%%% beginning of the answer sheet header

{\large\bf Answer sheet:}
\hfill \namefield{\fbox{    <co id="ensemble.nom" linkends="ensemble.nom.exp"/>
    \begin{minipage}{.5\linewidth}
      Firstname and lastname:

      \vspace*{.5cm}\dotfill
      \vspace*{1mm}
    \end{minipage}
  }}

\begin{center}
  \bf\em Answers must be given exclusively on this sheet:
  answers given on the other sheets will be ignored.
\end{center}

%%% end of the answer sheet header

\AMCform    <co id="ensemble.formulaire" linkends="ensemble.formulaire.exp"/>

% \AMCaddpagesto{5} <co id="AMCaddpage.separateanswersheet.total"
            linkends="AMCaddpage.separateanswersheet.total.exp"/>

}

\end{document}</programlisting>The following remarks should make the above
      example clearer :<calloutlist>
          <callout arearefs="ensemble.opt" id="ensemble.opt.exp">
            <para>The <option>separateanswersheet</option> option is what
            allows us to do what we wanted.</para>
          </callout>

          <callout arearefs="ensemble.fq" id="ensemble.fq.exp">
            <para>One can re-define in this manner the way the questions are
            identified on the answer sheet (this line is optional).</para>
          </callout>

          <callout arearefs="ensemble.cp" id="ensemble.cp.exp">
            <para>This page break is put before the special page where the
            check-boxes are put together. If one does recto-verso printing, it
            is preferable to use <command>\AMCcleardoublepage</command> so
            that this page is printed apart from the others. In the case of
            recto printing, one can simply use
            <command>\clearpage</command>.</para>
          </callout>

          <callout arearefs="AMCaddpage.separateanswersheet.sujet"
                   id="AMCaddpage.separateanswersheet.sujet.exp">
            <para>Uncomment to get three pages for the question part of each
            copy, see <xref linkend="latex.layout.npages"/>. (Here, the
            command is commented so no effect.)</para>
          </callout>

          <callout arearefs="debut.form" id="debut.form.exp">
            <para>This command marks the beginning of the answer sheet part.
            Its use is necessary for the appropriate treatment of the
            questions which appear only in that part, e.g. those generated by
            <command>\AMCcodeGrid</command>.</para>
          </callout>

          <callout arearefs="ensemble.nom" id="ensemble.nom.exp">
            <para>Students should normally write their name on the answer
            sheet!</para>
          </callout>

          <callout arearefs="ensemble.formulaire" id="ensemble.formulaire.exp">
            <para>The LaTeX command <command>AMCform</command> writes all the
            check-boxes.</para>
          </callout>

          <callout arearefs="AMCaddpage.separateanswersheet.total"
                   id="AMCaddpage.separateanswersheet.total.exp">
            <para>Uncomment to get five pages for the whole copy
            (question+answer sheet), see <xref
            linkend="latex.layout.npages"/>.</para>
          </callout>
        </calloutlist></para>

      <warning>
        <para>When one uses a separate answer sheet, letters (or digits, if
        one uses the option <option>digits</option>, see <xref
        linkend="sec.package.options"/>) are written in the check-boxes. To
        achieve a correct detection of the checked boxes, one has to ask
        students to completely fill the relevant boxes (checking by simply
        drawing a cross would not suffice). One also has to tune the gray
        level threshold (defining the proportion of black dots in a box above
        which that box is considered to be checked) to a value of order
        0.5.</para>
      </warning>
    </sect2>

    <sect2 id="latex.commands">
      <title>Description of the LaTeX commands</title>

      <sect3 id="sec.package.options">
        <title id="sec.package.options.title">Package options</title>

        <para>To use the <package>automultiplechoice</package> package, one
        uses the line <programlisting>\usepackage[...]{automultiplechoice}</programlisting>where
        the dots are replaced by a list of options separated by commas. Here
        are the available options:</para>

        <itemizedlist>
          <listitem>
            <para><option>lang=<replaceable>XX</replaceable></option>: sets
            the subject language to <replaceable>XX</replaceable>. At present,
            only DE (German), ES (Spanish), FR (French), IT (Italian), JA
            (Japanese), NL (Dutch), NO (Norwegian) and PT (Portuguese) are
            available. Several strings added by
            <package>automultiplechoice</package> will be translated, such as
            "None of these answers are correct", see option
            <option>completemulti</option>.</para>
          </listitem>

          <listitem>
            <para><option>pdfform</option>: create a pdf file to fill. </para>

            <note>
              <para>AMC does not automatically manage sending topics.</para>
            </note>
          </listitem>

          <listitem>
            <para><option>box</option>: puts every question in a block, so
            that it cannot be split by a page break.</para>

            <note>
              <para>You may occasionally cancel this option for each question
              with the command <command>\AMCnobloc</command>. <programlisting>{\AMCnobloc%
  \begin{question}{nb-ue}
    How many different states were members of the European Union in Jan. 2009?
    \begin{choiceshoriz}[o]
      \wrongchoice{15}
      \wrongchoice{21}
      \wrongchoice{25}
      \correctchoice{27}
      \wrongchoice{31}
    \end{choiceshoriz}
  \end{question}
}% </programlisting></para>
            </note>
          </listitem>

          <listitem>
            <para><option>asbox</option>: same as <option>box</option>, but
            inside the separate answer sheet.</para>
          </listitem>

          <listitem>
            <para><option>completemulti</option>: automatically adds a "None
            of these answers are correct" choice at the end of each multiple
            question. Thus, for these questions, a distinction can be made
            between no answer and the answer consisting in treating none of
            the listed answers as correct. This behavior can be forced or
            canceled for a particular question using one of the commands
            <command>\AMCcompleteMulti</command> or
            <command>\AMCnoCompleteMulti</command> inside the corresponding
            <command>questionmult</command> environment.</para>
          </listitem>

          <listitem>
            <para><option>noshuffle</option>: stops the automatic shuffling of
            the answers for every question</para>
          </listitem>

          <listitem>
            <para><option>noshufflegroups</option>: stops the automatic
            shuffling of the group for the test (see <xref
            endterm="Groups.questions.title"
            linkend="Groups.questions"/>)</para>
          </listitem>

          <listitem>
            <para><option>answers</option>: produces the corrected version of
            the MCQ test, not the test sheet itself.</para>
          </listitem>

          <listitem>
            <para><option>indivanswers</option> : produces the corrected
            version of each MCQ test.</para>
          </listitem>

          <listitem>
            <para><option>separateanswersheet</option>: requires that all
            check-boxes be put together at the end of the test sheet (usually,
            this option is used when one wants to have only one sheet to scan
            per student - see the example in <xref endterm="secensemble.title"
            linkend="secensemble"/>).</para>
          </listitem>

          <listitem>
            <para><option>digits</option>: if one uses the
            <option>separateanswersheet</option> option, the
            <option>digits</option> option requires the question to be
            identified with digits rather than with letters (which corresponds
            to the default setting).</para>
          </listitem>

          <listitem>
            <para><option>outsidebox</option>: when using
            <option>separateanswersheet</option>, this option asks to print
            letters (or digits) outside the boxes on the answer sheet.</para>
          </listitem>

          <listitem>
            <para><option>init</option> : initializes the random generator
            from time. <emphasis> This option is only for testing: don’t use
            it for a real exam!</emphasis></para>
          </listitem>

          <listitem>
            <para><option>insidebox</option>: when not using
            <option>separateanswersheet</option>, this options asks to print
            letters (or digits) inside the boxes to be filled by the
            students.</para>
          </listitem>

          <listitem>
            <para><option>catalog</option>: use this option to make a catalog
            of your questions to be used to compose future exams. No need to
            use <command>\onecopy</command> with this layout.</para>
          </listitem>

          <listitem>
            <para><option>postcorrect</option>: use this option if you want to
            give the correct answers after scans analysis, from a teacher
            completed answer sheet - see <xref linkend="postcorrect"/> for
            details.</para>
          </listitem>

          <listitem>
            <para><option>fullgroups</option> : cancels the use of the
            optional parameter of <command>\insertgroup</command> and
            <command>\copygroup</command>, so that each group is always fully
            inserted and fully copied. (see <xref
            endterm="Groups.questions.title"
            linkend="Groups.questions"/>)</para>
          </listitem>

          <listitem>
            <para><option>storebox</option> :If you choose to change the
            boxes' shape (square by default, see <xref
            endterm="box.style.title" linkend="box.style"/>) as ovals or
            circles, you may communicate this option to automultiplechoice to
            use <option>\storebox</option> rather than
            <option>\savebox</option> to store the design of the boxes.</para>
          </listitem>

          <listitem>
            <para><option>automarks</option>: in
            <option>separateanswersheet</option> mode, use this option if you
            want to cancel marks printing on the subject pages. They will only
            be print on the answer sheet pages. To change the way pages
            numbers are print on the subject pages, redefine the
            <command>\AMCsubjectPageTag</command> command:</para>

            <programlisting>\renewcommand\AMCsubjectPageTag{%
  \fbox{\texttt{\the\AMCid@etud:\thepage}}%
}</programlisting>

            <warning>
              <para>Only use <option>automarks</option> option if no data are
              to be collected on the subjects pages, as AMC won't be able to
              process these pages.</para>
            </warning>
          </listitem>

          <listitem>
            <para><option>nopage</option>: use this option if you don't need
            margins, corner circles and page identification boxes, that is if
            the document is not intended to be used with AMC (for example to
            produce exercises lists).</para>
          </listitem>
        </itemizedlist>
      </sect3>

      <sect3 id="sec.unecopie">
        <title>Description of a copy</title>

        <para>The LaTeX source code describing the content of the test sheet
        has to be included in a call to the command
        <command>\onecopy</command>, the first argument being the number of
        distinct realizations to be produced, and the second argument being
        the code used to generate a realization.</para>

        <programlisting>\onecopy{50}{ ... }</programlisting>

        <para>An alternative syntax is available, using the
        <command>examcopy</command> environment, where the number of
        realizations is an option (default is 5).</para>

        <programlisting>\begin{examcopy}[50]
...
\end{examcopy}</programlisting>

        <note>
          <para>To use examcopy, you need the <package>environ</package>
          package to be installed, which is not available in the TeX Live 2007
          distribution, still used in Ubuntu distributions up to version 9.10
          (Karmic Koala).</para>
        </note>

        <para>To differentiate between odd and even-numbered copy, use
        <command>\exemplairepair</command> command.</para>

        <para>The command <command>\AMCStudentNumber</command> get the copy
        number.</para>
      </sect3>

      <sect3 id="latex.qr">
        <title id="latex.qr.title">Questions and answers</title>

        <para>For simple questions (a single correct answer), one uses the
        following model: <programlisting linenumbering="unnumbered">\begin{question}{identifier}
  Here is the question...
  \begin{choices}
    \correctchoice{The correct answer}
    \wrongchoice{A wrong answer}
    \wrongchoice{Another wrong answer}
  \end{choices}
\end{question}</programlisting></para>

        <important>
          <para>One must use a different identifier for every question. An
          identifier can be made of digits, letters, and simple characters
          (but do not use e.g. underscores, braces or brackets, that have a
          special meaning in LaTeX files). Don't end your question identifier
          with an integer enclosed in square brackets, as this syntax is
          reserved to codes input.</para>
        </important>

        <note>
          <para>The maximum number of answers for a given question is limited
          to 199.</para>
        </note>

        <important>
          <para>Do not nest a question in a another environment question
          otherwise the notes' export will be incomplete (see <xref
          endterm="sec.export.notes.title"
          linkend="sec.export.notes"/>).</para>
        </important>

        <para>To keep the original order of the answers and prevent shuffling
        for this specific question, one can use the <option>o</option> option
        of the <option>choices</option> environment, replacing line 3 by the
        following:<programlisting>\begin{choices}[o]</programlisting></para>

        <para>To put the answers on two columns, one can use the
        <package>multicol</package> package: load it in the preamble (just
        after the reference to the package
        <package>automultiplechoice</package> for instance) with
        <programlisting>\usepackage{multicol}</programlisting>and include the
        choices environment inside a multicols environment in the following
        manner:<programlisting>\begin{multicols}{2}
  \begin{choices}
    \correctchoice{The correct answer}
    \wrongchoice{A wrong answer}
    \wrongchoice{Another wrong answer}
  \end{choices}
\end{multicols}</programlisting></para>

        <para>For even shorter answers, one can require questions to be
        printed following one another, using the <option>choiceshoriz</option>
        environment instead of <option>choices</option>.</para>

        <para>Multiple questions (those for which no, one, or several answers
        can be correct) use the <option>questionmult</option> environment
        instead of <option>question</option>.</para>

        <para>When the answer to the question is not supposed to be taken into
        account in the grading, one uses the <code>\QuestionIndicative</code>
        command, as in the following example:</para>

        <para><programlisting>\begin{question}{difficulty}\QuestionIndicative
  \scoring{auto=0,v=-1,e=-2}
  Did you find this class easy or difficult? Please answer on a scale from 0 (very difficult) to 5
  (very easy).
  \begin{choiceshoriz}[o]
    \correctchoice{0}
    \correctchoice{1}
    \correctchoice{2}
    \correctchoice{3}
    \correctchoice{4}
    \correctchoice{5}
  \end{choiceshoriz}
\end{question}</programlisting></para>

        <sect4 id="latex.lastchoice">
          <title>Last choice</title>

          <para>You may force AMC to let one or more answers as last choices
          with the command <command>\lastchoices</command>.</para>

          <programlisting>\begin{question}{color}
  Which color?
  \begin{choiceshoriz}
    \wrongchoice{red}
    \wrongchoice{blue}
    \wrongchoice{yellow}
    \lastchoices
    \correctchoice{transparent}
    \wrongchoice{can't say}
  \end{choiceshoriz}
\end{question}

\begin{questionmult}{number}
  How many?
  \begin{choiceshoriz}
    \wrongchoice{none}
    \correctchoice{one}
    \wrongchoice{two}
    \wrongchoice{three}
    \lastchoices
    \correctchoice{not so much}
    \wrongchoice{a lot}
  \end{choiceshoriz}
\end{questionmult}        </programlisting>
        </sect4>

        <sect4>
          <title>Question numbers</title>

          <para>One can modify the number of the next question with the
          <code>\AMCnumero command</code>. At the beginning of each
          realization of the test, a call to</para>

          <para><programlisting>\AMCnumero{1}</programlisting></para>

          <para>is performed, but this command can be used at any
          place.</para>

          <note>
            <para>When you want to hide the number for a particular question
            and do not want to increase the question number, use
            <command>\AMCquestionNumberfalse</command> command as in the
            following example:</para>

            <programlisting>{
  \AMCquestionNumberfalse
  \def\AMCbeginQuestion#1#2{}
  \begin{question}
    ...
  \end{question}
}</programlisting>
          </note>
        </sect4>
      </sect3>

      <sect3 id="latex.explain">
        <title id="latex.explain.title">Explanation for the answers of a
        question</title>

        <para>To provide explanation for the answers of a question, one can
        use the <command>\explain</command> command. The explanations are
        optional and are only displayed in the Solution and Catalog
        file.</para>

        <warning>
          <para>Not displayed in the individual solution</para>
        </warning>

        <para>Here is a simple example:</para>

        <para><programlisting>\begin{question}{explanation}
  Which has the highest elevation among the following?
  \begin{choices}
      \correctchoice{Sagarmatha}
      \wrongchoice{K2}
      \wrongchoice{Mont Blanc}
      \wrongchoice{Aconcagua}
  \end{choices}
  \explain{Sagarmatha which literally means `Head of sky' is the native name of
           Mount Everest, the highest mountain in the world.}
\end{question}</programlisting></para>

        <note>
          <para>The <command>explain</command> command can be used inside
          <option>question</option> like environments only. This includes
          <option>question</option>, <option>questionmult</option> and
          <option>questionmultx</option> environments.</para>
        </note>

        <para>By default this command prints <emphasis>Explanation:
        </emphasis> before each explanations. This behavior can be changed
        using the <command>\AMCtext</command> command (see section <xref
        linkend="AMCtext"/>).</para>

        <para>If you want to change this default behavior only for some
        questions and not for all just use the <command>\AMCtext</command>
        command before the <command>\explain</command> command as in the
        following example:</para>

        <para><programlisting>\begin{question}{elevation}
  Which has the highest elevation among the following?
  \begin{choices}
      \correctchoice{Sagarmatha}
      \wrongchoice{K2}
      \wrongchoice{Mont Blanc}
      \wrongchoice{Aconcagua}
  \end{choices}
  \explain{Sagarmatha which literally means `Head of sky' is the native name of
         Mount Everest, the highest mountain in the world.}
\end{question}

\begin{question}{odd}
  Pick the odd one out.
  \begin{choices}
      \correctchoice{Kilimanjaro}
      \wrongchoice{Himalayas}
      \wrongchoice{Alps}
      \wrongchoice{Andes}
  \end{choices}
  \AMCtext{explain}{\textit{\textbf{Reason: }}}
  \explain{Kilimanjaro is a mountain while the rest are mountain ranges.}
\end{question}

\begin{questionmult}{himalaya}
  Among the following which is in the Himalayas?
  \begin{choices}
      \correctchoice{Mount Everest}
      \correctchoice{K2}
      \wrongchoice{Mont Blanc}
      \wrongchoice{Aconcagua}
  \end{choices}
  \explain{Aconcagua is located in the Andes mountain range while Mont Blanc
                 is located in the Alps.}
\end{questionmult}</programlisting></para>

        <para>This will now print <emphasis>Explanation: </emphasis> before
        the explanations of first and third question but <emphasis>Reason:
        </emphasis> before the explanation of second question.</para>
      </sect3>

      <sect3 id="latex.choices.multicol">
        <title>Putting answers on multiple columns</title>

        <para>To put answers on several columns (and thus save space), one can
        embed the <option>choices</option> environment in a
        <option>multicols</option> environment, using the LaTeX package
        <package>multicol</package>.</para>

        <para>If, moreover, the answers do not fit into a single line, an
        answer might be split over several columns, which might be a little
        puzzling for the reader. The <command>\AMCBoxedAnswers</command>
        command was defined in order to prevent this phenomenon, by embedding
        each answer into a box. Here is an example of use:</para>

        <para><programlisting>\begin{question}{two columns}
  What is a bird ?
  \begin{multicols}{2}\AMCBoxedAnswers
    \begin{choices}
      \correctchoice{It is an animal with wings, laying eggs. There are birds with all sorts of colors.}
      \wrongchoice{It is a large piece of furniture, made of wood, and used most of the time to store
      household linen}
      \wrongchoice{It is a steam machine devised to seal cans at high speed.}
    \end{choices}
  \end{multicols}
\end{question}</programlisting></para>

        <para>Let us note that it is also possible to parameterize the
        vertical space between two answer blocks, thanks to the dimension
        <parameter>AMCinterBrep</parameter>:</para>

        <para><programlisting>\AMCinterBrep=.5ex</programlisting></para>
      </sect3>

      <sect3 id="latex.choices.space">
        <title>Space between answers</title>

        <para>Let us note that it is also possible to parameterize the
        vertical space between many answer blocks, thanks to the dimension
        <parameter>AMCinterIrep</parameter>:</para>

        <para><programlisting>\AMCinterIrep=.75ex</programlisting></para>
      </sect3>

      <sect3 id="marks.display.area">
        <title id="marks.display.area.title">Define the marks' display
        area</title>

        <para>You may add an additional option of marking area (see <xref
        endterm="marks.position.title" linkend="marks.position"/>) with the
        package <package>tikz</package>.</para>

        <programlisting>\usepackage{tikz}</programlisting>

        <sect4 id="latex.zone.std">
          <title>Without the <option>separateanswersheet</option>
          option</title>

          <para>Type this command after <command>\begin{document}</command>
          and before the command <command>\onecopy</command> :</para>

          <programlisting>\AMCsetScoreZone{width=1.5em,height=1.5ex,depth=.5ex,position=margins}</programlisting>

          <para>The variables <parameter>width</parameter>,
          <parameter>height</parameter>, <parameter>depth</parameter> describe
          the dimensions of the box marking and its location on the
          sheet.</para>

          <para>The <parameter>position</parameter> value may be equal to :
          none, question, margin, margins.</para>
        </sect4>

        <sect4 id="latex.zone.separate">
          <title>With the <option>separateanswersheet</option> option</title>

          <para>Type this command after <command>\begin{document}</command>
          and before the command <command>\onecopy</command> :</para>

          <programlisting>\AMCsetScoreZoneAnswerSheet{width=1.5em,height=1.5ex,depth=.5ex,position=question}</programlisting>

          <para>The variables <parameter>width</parameter>,
          <parameter>height</parameter>, <parameter>depth</parameter> describe
          the dimensions of the box marking and its location on the
          sheet.</para>

          <para>The <parameter>position</parameter> value may be equal to :
          none, question, margin, margins.</para>

          <warning>
            <para>The option <option>margins</option> does not work with
            AMC-TXT.</para>

            <para>Don't type one of those commands <emphasis>after</emphasis>
            printing.</para>
          </warning>
        </sect4>
      </sect3>

      <sect3 id="Groups.questions">
        <title id="Groups.questions.title">Groups of questions</title>

        <para>Putting questions into groups allows one to shuffle questions
        inside these groups, in a different way for each realization of the
        test. Every group of questions must have a name formed solely with
        plain letters.</para>

        <para>One can put questions in a group one by one, as in the following
        example.</para>

        <para><programlisting>\element{mygroup}{
  \begin{question}{easy}
    So, how much is one plus one?
    \begin{choiceshoriz}
      \correctchoice{two}
      \wrongchoice{zero}
      \wrongchoice{three}
    \end{choiceshoriz}
  \end{question}
}</programlisting></para>

        <important>
          <para>The formation of the group, using the
          <command>element</command> commands, must be made only once: thus,
          these commands have to be used <emphasis>before</emphasis> the
          <command>onecopy</command> command, which repeats some actions for
          every realization.</para>
        </important>

        <para>Finally, the group content can be output to the test sheet using
        command <command>insertgroup</command>, as in<programlisting>\insertgroup{mygroup}</programlisting></para>

        <para>Group insertion can be controlled by the group mode, that can be
        set by the <command>setgroupmode</command> command (called after group
        creation, once for all, before <command>onecopy</command>):</para>

        <programlisting>\setgroupmode{mygroup}{XXX}</programlisting>

        <para>where <code>XXX</code> can be one of the following:</para>

        <variablelist>
          <varlistentry>
            <term>fixed</term>

            <listitem>
              <para>with this mode, group's elements are taken from the
              beginnig at each insertion.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>cyclic</term>

            <listitem>
              <para>the elements will be taken from the group following the
              last call group’s use, recycling if necessary.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>withreplacement</term>

            <listitem>
              <para>the same as <code>fixed</code>, but the group is shuffled
              before each use.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>withoutreplacement</term>

            <listitem>
              <para>like <code>cyclic</code>, adding some shuffling when
              comming back to the beginning of the group.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Note that a default group mode can be set for all groups that
        will be created next (a group is created at the first
        <command>element</command> call), using the command</para>

        <programlisting>\setdefaultgroupmode{XXX}</programlisting>

        <para>Without any mode definition, the <code>fixed</code> mode is
        used.</para>

        <para>Once a group is formed, it is possible to shuffle questions
        inside this group using the <command>shufflegroup</command> command.
        For instance<programlisting>\shufflegroup{mygroup}</programlisting></para>

        <para>However, the command <command>shufflegroup</command> can always
        be replaced by a proper use of group modes.</para>

        <warning>
          <para>Delete the command <command>\shufflegroup</command> if you
          rerun created tests with a AMC version lower to 1.2.2014.111201 and
          if you change the default mode (<code>fixed</code>).</para>
        </warning>

        <para>Groups of questions can be manipulated more precisely thanks to
        the following commands:</para>

        <itemizedlist>
          <listitem>
            <para><code>\insertgroup[n]{mygroup}</code> (using optional
            parameter <replaceable>n</replaceable>) only inserts the
            <replaceable>n</replaceable> first elements from the group.</para>
          </listitem>

          <listitem>
            <para><code>\insertgroupfrom[n]{groupname}{i}</code> The command
            does the same as <code>\insertgroup[n]{groupname}</code>, starting
            from element at index <replaceable>i</replaceable> (the first
            element has index 0).</para>
          </listitem>

          <listitem>
            <para><code>\cleargroup{mygroup}</code> clears all group
            content.</para>
          </listitem>

          <listitem>
            <para><code>\copygroup{groupA}{groupB}</code> copies all the
            elements from group <replaceable>groupA</replaceable> to the end
            of group <replaceable>groupB</replaceable>. With an optional
            argument <replaceable>n</replaceable>, only the n first elements
            will be copied: <code>\copygroup[n]{groupA}{groupB}</code>.</para>
          </listitem>
        </itemizedlist>

        <para>With these commands, you can for example make a exam taking 4
        questions from group GA at random, 5 questions from group GB at
        random, and all the questions from group GO, shuffling all these
        questions, with the following code (to be used inside the argument of
        the command <command>onecopy</command>, and supposing that the group
        mode of groups <code>GA</code>, <code>GB</code> and <code>all</code>
        is <code>withoutreplacement</code> or
        <code>withreplacement</code>):</para>

        <programlisting>\cleargroup{all}
\copygroup[4]{GA}{all}
\copygroup[5]{GB}{all}
\copygroup{GO}{all}
\insertgroup{all}</programlisting>

        <itemizedlist>
          <listitem>
            <para><code>\copygroupfrom[n]{groupA}{groupB}{i}</code> The
            command does the same as
            <code>\copygroup[n]{groupA}{groupB}</code> starting from element
            at index <replaceable>i</replaceable> (the first element has index
            0).</para>
          </listitem>
        </itemizedlist>
      </sect3>

      <sect3 id="latex.page">
        <title>Page size, margins</title>

        <para>The <command>automultiplechoice</command> LaTeX package uses
        <command>geometry</command> to set the margins and page layout. You
        can overwrite its settings using the <command>\geometry</command>
        command just before the <code>\begin{document}</code> - see the
        geometry package documentation for details. The values initially set
        by AMC are:</para>

        <programlisting>\geometry{hmargin=3cm,headheight=2cm,headsep=.3cm,footskip=1cm,top=3.5cm,bottom=2.5cm}</programlisting>

        <para>When reducing the margins to gain some space, keep in mind
        that:</para>

        <itemizedlist>
          <listitem>
            <para>The four corner marks must be printed entirely (they could
            disappear due to the printer margins).</para>
          </listitem>

          <listitem>
            <para>The four corner marks must be entirely visible on the scans
            (if they are too close from the border and the paper moved a
            little or turned a little during scanning, this could not be the
            case).</para>
          </listitem>
        </itemizedlist>

        <para>It is also possible to set the paper size as an option to add to
        the list given as argument to the <command>\geometry</command>
        command. Available values include <code>a4paper</code>,
        <code>a5paper</code>, <code>a6paper</code>, <code>b4paper</code>,
        <code>b5paper</code>, <code>ansibpaper</code>,
        <code>ansicpaper</code>, <code>ansidpaper</code>,
        <code>letterpaper</code>, <code>executivepaper</code>,
        <code>legalpaper</code>.</para>

        <para>For small paper sizes, it may also be interesting to change the
        position of the human readable sheet IDs (like <code>+1/1/53+</code>)
        in the header. This can be done using the
        <command>\AMCidsPosition</command> command, in the form</para>

        <programlisting>\AMCidsPosition{pos=<replaceable>p</replaceable>,width=<replaceable>w</replaceable>,height=<replaceable>h</replaceable>}</programlisting>

        <para>where <replaceable>p</replaceable> can be <code>none</code>,
        <code>top</code> or <code>side</code>, and the dimensions
        <replaceable>w</replaceable> and <replaceable>h</replaceable> refers
        to the (invisible) box containing the ID. The default values
        are</para>

        <programlisting>\AMCidsPosition{pos=side,width=4cm,height=3ex}</programlisting>

        <para>Let us end with an example for A5 paper sheets:</para>

        <programlisting>\geometry{a5paper,hmargin=1.6cm,top=2.5cm}
\AMCidsPosition{pos=top}</programlisting>

        <warning>
          <para>Do not load package <command>pgfpages</command> or any other
          layout applications</para>
        </warning>
      </sect3>

      <sect3 id="box.style">
        <title id="box.style.title">Check-box presentation style</title>

        <para>The <command>\AMCboxStyle</command> (new name for the
        <command>\AMCboxDimensions</command> command which still compatible
        with the options) allows one to modify one or several dimensions of
        the check-boxes.</para>

        <para>Default values are :</para>

        <programlisting>\AMCboxStyle{shape=square,size=2.5ex,down=.4ex,rule=.5pt,outsidesep=.1em,color=black}</programlisting>

        <itemizedlist>
          <listitem>
            <para><option>shape</option> is the shape of the boxes. Use the
            value <replaceable>square</replaceable> to get squares or
            rectangles, and <replaceable>oval</replaceable> to get circles or
            ovals. Note that the LaTeX package tikz must be loaded for
            <replaceable>oval</replaceable> to work.</para>
          </listitem>

          <listitem>
            <para><option>width</option> is the width of the box;</para>
          </listitem>

          <listitem>
            <para><option>height</option> is the height of the box;</para>
          </listitem>

          <listitem>
            <para><option>size</option> is the size (<option>width</option>
            and <option>height</option>) of the box;</para>
          </listitem>

          <listitem>
            <para><option>rule</option> is the thickness of the boundary of
            the box;</para>
          </listitem>

          <listitem>
            <para><option>down</option> controls by how much boxes are pushed
            down.</para>
          </listitem>

          <listitem>
            <para><option>outsidesep</option> for the distance between the box
            and the letter when printed outside the box when the
            <option>outsidebox</option> option is choosen (see <xref
            endterm="sec.package.options.title"
            linkend="sec.package.options"/>).</para>
          </listitem>

          <listitem>
            <para><option>cross=true</option> only displayed on the answer
            sheet, shows the good answer with a cross instead of filling in
            black the box</para>
          </listitem>

          <listitem>
            <para><option>crossrule=1.5pt</option> only displayed on the
            answer sheet, is the thickness of the cross.</para>
          </listitem>

          <listitem>
            <para><option>color=<replaceable>col</replaceable></option> gives
            the color to be used to draw boxes. The color
            <replaceable>col</replaceable> must be compatible with the
            <command>xcolor</command> package. For example, some names such as
            <replaceable>red</replaceable> can be used. You can also define
            your proper color, as in</para>

            <programlisting>\definecolor{mylightgreen}{rgb}{0.67,0.88,0.5}
\AMCboxStyle{color=mylightgreen}</programlisting>
          </listitem>
        </itemizedlist>

        <para>To obtain smaller boxes, one can e.g. use the command</para>

        <programlisting>\AMCboxStyle{size=1.7ex,down=.2ex}</programlisting>

        <para>When using <option>separateanswersheet</option> package option,
        you can also customize the boxes labeling. The default behavior is to
        use uppercase alphabetical labeling, or arabic numbering if the
        <option>digits</option> package option is used. To use your own
        labeling, one has to redefine the <command>\AMCchoiceLabel</command>
        command which takes as argument the name of the counter used to number
        the choices. For example, the following code will ask for lowercase
        letters to label the boxes:</para>

        <programlisting>\def\AMCchoiceLabel#1{\alph{#1}}</programlisting>

        <para>As an other example, when using <package>arabxetex</package>
        package, the following code may be useful:</para>

        <programlisting>\def\AMCchoiceLabel#1{\textLR{\Alph{#1}}}</programlisting>

        <para>One can also change the style of the boxes labels redefining the
        <command>\AMCchoiceLabelFormat</command> command, as in the following
        example (here we need bold labels):</para>

        <programlisting>\def\AMCchoiceLabelFormat#1{\textbf{#1}}</programlisting>

        <para>One can also change the style of the outside labels redefining
        the <command>\AMCoutsideLabelFormat</command> command, as in the
        following example (here we need bold labels):</para>

        <programlisting>\def\AMCoutsideLabelFormat#1{\textbf{#1}}</programlisting>

        <note>
          <para>The switch used to tick or not correct answers is
          <command>\AMC@correctrue</command>. You can define a command to set
          it to true, just after the \begin{document}.</para>

          <programlisting>\makeatletter
\def\AMCforcecorrect{\AMC@correctrue}
\makeatother</programlisting>

          <para>and then use it for a particular question (enclose in braces
          to limit its effect to one question):</para>

          <programlisting>{\AMCforcecorrect\begin{questionmult}{test}\QuestionIndicative
   .....
 \end{questionmult}
}
        </programlisting>

          <para>You should tell AMC not to count points for this question
          (with a 0-point scoring, or using
          <command>\QuestionIndicative</command>).</para>
        </note>
      </sect3>

      <sect3 id="latex.style">
        <title>Questions presentation style</title>

        <para>The way each question is presented can be modified by redefining
        the LaTeX command <command>AMCbeginQuestion</command>, whose default
        definition is the following:</para>

        <para><programlisting>\def\AMCbeginQuestion#1#2{\par\noindent{\bf Question #1} #2\hspace*{1em}}</programlisting></para>

        <para>The first parameter transmitted to this command is the number of
        the question to be displayed. The second parameter contains
        <code>\multiSymbole</code> in the case of a multiple question, and is
        void in all other cases. The <code>\multiSymbole</code> command too
        can be modified: its goal is to distinguish multiple questions from
        the others. By default, it displays a club.</para>

        <para><programlisting>\def\multiSymbole{$\clubsuit$}</programlisting></para>

        <warning>
          <para>With nominative sheets (see <xref
          endterm="Nominative.sheets.title" linkend="Nominative.sheets"/>),
          set up it with a new command in the preamble.</para>

          <informalexample>
            <programlisting>\def\Iswitch{\def\AMCbeginQuestion##1##2{}\AMCquestionNumberfalse}</programlisting>
          </informalexample>

          <para>and use it when you need it. (Do not forget to type inside
          brackets to limit the effect) :</para>

          <programlisting>{\Iswitch
 \begin{question}{Number}
   Choose the greater.
   \begin{choiceshoriz}[o]
     \wrongchoice{200}\wrongchoice{2}\wrongchoice{20}\wrongchoice{200}\correctchoice{600}
   \end{choiceshoriz}
 \end{question}
}
      </programlisting>
        </warning>

        <para>The display of answers can be modified in the same fashion, if
        one uses the <option>choicescustom</option> environment instead of
        <option>choices</option> or <option>choiceshoriz</option>, redefining
        the three following LaTeX macros:</para>

        <programlisting>\def\AMCbeginAnswer{}
\def\AMCendAnswer{}
\def\AMCanswer#1#2{#1 #2}
</programlisting>

        <important>
          <para>Inside the commande <command>\onecopy</command>, double the
          <code>#</code>.</para>

          <programlisting>\def\AMCanswer##1##2{##1  ##2}
\def\AMCbeginQuestion##1##2{}</programlisting>
        </important>

        <para>One can also change spacing redefining the following dimensions
        (here are the default values):</para>

        <programlisting>\AMCinterIrep=0pt
\AMCinterBrep=.5ex
\AMCinterIquest=0pt
\AMCinterBquest=3ex
\AMCpostOquest=7mm
\setlength{\AMChorizAnswerSep}{3em plus 4em}
\setlength{\AMChorizBoxSep}{1em}
</programlisting>

        <para>These dimensions are the vertical space between questions
        (<code>quest</code>) or answers (<code>rep</code>), in boxed mode
        (<code>B</code>, with <command>\AMCBoxedAnswers</command> or
        <option>box</option> package option) or standard mode (<code>I</code>)
        and the space left after an open question. The two last lengths are used
        in environment: <option>choicescustom</option></para>
      </sect3>

      <sect3 id="latex.layout">
        <title>Layout</title>

        <sect4 id="latex.layout.margins">
          <title>Margins</title>

          <para>Margins were chosen so that the document prints correctly on
          most printers. If your printer reduces, you can use the command
          <command>geometry</command> from laTex package
          <package>geometry</package>. For example, In order to narrow the top
          margin's copies, we can use <code>\geometry{top=3cm}</code> instead
          the default value 3.5cm, just before
          <code>\begin{document}</code>.</para>
        </sect4>

        <sect4 id="latex.layout.npages">
          <title>Number of pages</title>

          <para>AMC automatically handles the number of pages for each
          subject. You can choose to fix a identical number of pages for each
          subject with the command <command>\AMCaddpagesto{integer}</command>
          to be called at a place you need to reach this number of pages
          (usually at the end of the copy description or between the question
          and the answer sheet).</para>
        </sect4>
      </sect3>

      <sect3 id="latex.style.separate">
        <title>Separate answer sheet presentation style</title>

        <para>It is also possible to modify the layout of the separate answer
        sheet produced with the <option>separateanswersheet</option> option
        (see  <xref endterm="secensemble.title" linkend="secensemble"/>).</para>

        <orderedlist>
          <listitem>
            <para>If one only wants to modify the horizontal spacing between
            two check-boxes or the vertical spacing between two questions, one
            just has to redefine the following dimensions:</para>

            <programlisting>\AMCformHSpace=.3em
\AMCformVSpace=1.2ex
</programlisting>
          </listitem>

          <listitem>
            <para>For a deeper modification of the display settings, one can
            also redefine the commands that are used at the beginning of each
            question and for each answer:</para>

            <programlisting>\def\AMCformBeforeQuestion{\vspace{\AMCformVSpace}\par}
\def\AMCformQuestion#1{\textbf{Question #1:}}
\def\AMCformAnswer#1{\hspace{\AMCformHSpace} #1}
</programlisting>

        <para>These definitions have to be inserted just after
        <code>\begin{document}</code> in the LaTeX file.</para>
          </listitem>

          <listitem>
          <para>
         You can force AMC not to respect the arrangement of the questions and to store the open
         questions in order to restore them together. This can be useful when you use package
          <package>multicols</package >, the answers to open questions needing more space
          when hand written.
          </para>

        <para >The command <command>\AMCformFilter {!\AMCifcategory {open}}</command>
        displays all questions except the open questions then the command
        <command>\AMCformFilter {\AMCifcategory {open}}</command >
        displays only the open questions. Both commands must be used <emphasis> together</emphasis >.</para >

         <programlisting>
%On two columns, the answers boxes are displayed
%except the open questions.
\begin{multicols}{2}
\AMCformFilter{!\AMCifcategory{open}}
\end{multicols}

%All the open questions are displayed.
\AMCformFilter{\AMCifcategory{open}}
         </programlisting>

         <note><para>The ascending numbering is always respected.</para></note>
          </listitem>
        </orderedlist>
      </sect3>

      <sect3 id="latex.codes">
        <title>Code acquisition</title>

        <para>Code acquisition can be easily performed thanks to the LaTeX
        command
        <command>\AMCcodeGridInt[<replaceable>options</replaceable>]{<replaceable>key</replaceable>}{<replaceable>n</replaceable>}</command>,
        for instance to allow each student to enter her/his student number by
        herself/himself on the answer sheet. The two arguments of this command
        are a code/question key (identifier), and the number
        <replaceable>n</replaceable> of digits to be used by the code. One can
        e.g. use the following header</para>

        <para><programlisting>{\setlength{\parindent}{0pt}\hspace*{\fill}\AMCcodeGridInt{etu}{8}\hspace*{\fill}
\begin{minipage}[b]{6.5cm}
$\longleftarrow{}$\hspace{0pt plus 1cm} please encode your student number below,
and write your first and last names below.

\vspace{3ex}

\hfill\namefield{\fbox{
    \begin{minipage}{.9\linewidth}
      Firstname and lastname:

      \vspace*{.5cm}\dotfill

      \vspace*{.5cm}\dotfill
      \vspace*{1mm}
    \end{minipage}
  }}\hfill\vspace{5ex}\end{minipage}\hspace*{\fill}

}
</programlisting></para>

        <para>If the <option>separateanswersheet</option> option is used, the
        <command>\AMCcodeGridInt</command> command has to be placed after the
        <command>\AMCformBegin</command> command.</para>

        <para>Note that the codes rendering can be adapted modifying the
        lengths <command>\AMCcodeHspace</command>,
        <command>\AMCcodeVspace</command> representing the horizontal and
        vertical amount of space between boxes. Default values are set with
        the following commands:</para>

        <programlisting>\AMCcodeHspace=.5em
\AMCcodeVspace=.5em
</programlisting>

        <para>The command
        <command>\AMCcodeGrid[<replaceable>options</replaceable>]{<replaceable>key</replaceable>}{<replaceable>description</replaceable>}</command>
        can be used to handle more complex codes, as codes including letters.
        Here, <replaceable>description</replaceable> is a coma-separated list
        of character pools to offer. As an example, a client code formed with
        a lettre from A to E followed by three digits can be handled with
        <command>\AMCcodeGrid{client}{ABCDE,0123456789,0123456789,0123456789}</command>.</para>

        <para>The two commands \AMCcodeGrid and \AMCcodeGridInt accept the
        following options (coma-separated into the optional
        <replaceable>options</replaceable> argument):</para>

        <variablelist>
          <varlistentry>
            <term>vertical=<replaceable>bool</replaceable></term>

            <listitem>
              <para>where <replaceable>bool</replaceable> is <code>true</code>
              or <code>false</code>, to indicate the direction to be used (the
              default value is <code>true</code>);</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>v</term>

            <listitem>
              <para>is an alias for <code>vertical=true</code>;</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>h</term>

            <listitem>
              <para>is an alias for <code>vertical=false</code>;</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>top</term>

            <listitem>
              <para>allows to get top-aligned columns in vertical
              direction.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="openquestions">
        <title>Open questions</title>

        <para>One can sometimes require some open questions to be added to the
        subject. One way to do so is to reserve boxes use to the teacher for
        these questions. After the exam, the teacher reads the completed
        answer sheets and tick the boxes according to the answers written by
        the students for open questions. He will then scan the sheets and let
        AMC correct the multiple choice questions and integrate the open
        questions scores into the marks.<programlisting>\begin{question}{open}
  Define \emph{inflation}.
  \AMCOpen{lines=5}{\wrongchoice[W]{w}\scoring{0}\wrongchoice[P]{p}\scoring{1}\correctchoice[C]{c}\scoring{2}}
\end{question}
</programlisting></para>

        <para>In this example, the teacher will get three boxes. If the first
        (labeled W for wrong) is ticked, the student will get 0 points. If the
        second (labeled P for partial) is ticked, the student will get 1
        point. If the third (labeled C for correct) is ticked, the student
        will get 2 points.</para>

        <para>The first argument to <command>\AMCOpen</command> is a comma
        separated list of options. The available options are:</para>

        <variablelist>
          <varlistentry>
            <term>lineup=<replaceable>bool</replaceable></term>

            <listitem>
              <para>if <code>true</code>, the answering area and the scoring
              boxes will be on the same line. If <code>false</code> (this is
              default), the answering area is enclosed in a frame and placed
              below the scoring boxes.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>lineuptext=<replaceable>text</replaceable></term>

            <listitem>
              <para>if <code>lineup=true</code>, the text and ansewering area
              will be on the same line.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>lines=<replaceable>num</replaceable></term>

            <listitem>
              <para>sets the number of lines for the answer. Default value is
              <code>1</code>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>lineheight=<replaceable>dim</replaceable></term>

            <listitem>
              <para>sets the height of each line. Default value is
              <code>1cm</code>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>dots=<replaceable>bool</replaceable></term>

            <listitem>
              <para>if <code>true</code> (Default), each line will be realized
              by a line of dots.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>contentcommand=<replaceable>cmdname</replaceable></term>

            <listitem>
              <para>Use this option if you want to customize the content of
              the answer area. You will have to define a
              <command>\<replaceable>cmdname</replaceable></command> command
              that has to produce the content.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>hspace=<replaceable>dim</replaceable></term>

            <listitem>
              <para>sets the space between boxes in the marking area.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>backgroundcol=<replaceable>color</replaceable></term>

            <listitem>
              <para>sets the background color of the marking area.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>foregroundcol=<replaceable>color</replaceable></term>

            <listitem>
              <para>sets the foreground color of the marking area.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>scan=<replaceable>bool</replaceable></term>

            <listitem>
              <para>if <code>false</code>, the boxes are not scanned (this can
              be useful if you plan to use manual data capture only to mark
              this question, and don't want to take into account the students
              drawings on the boxes). Defaults to <code>true</code>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>annotate=<replaceable>bool</replaceable></term>

            <listitem>
              <para>if <code>false</code> (default value), the boxes from this
              question won't be annotated when annotating the answer sheets
              (only the score will be written).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>question=<replaceable>text</replaceable></term>

            <listitem>
              <para>sets a short text that helps the examiner to identify the
              question. This text will be written before the scoring boxes,
              only if a separate answer sheet is used.</para>

              <para>The question's identifier will be displayed if you type
              question in the options list.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>answer=<replaceable>text</replaceable></term>

            <listitem>
              <para>sets a short text that will be written in the answering
              area for corrected answer sheets.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <tip>
          <para>Use the command <command>\savebox</command>, <emphasis>outside
          the onecopy command</emphasis>, to display a longer text with
          linebreaks.</para>

          <programlisting>
       \newsavebox{\correcbox}
        \savebox{\correcbox}{\parbox{5cm}{\color{red}{Here a linebreak\\or\\here...}}}
       </programlisting>

          <para>Call out the boxe's contents:</para>

          <programlisting>
        \AMCOpen{lines=4,lineheight=0.15cm, answer= \usebox{\correcbox}}{Question}
       </programlisting>
        </tip>

        <variablelist>
          <varlistentry>
            <term>width=<replaceable>dim</replaceable></term>

            <listitem>
              <para>sets the width of the frame enclosing the answering area
              when <code>lineup=false</code>. Default value is
              <code>.95\linewidth</code>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>framerule=<replaceable>dim</replaceable></term>

            <listitem>
              <para>sets the line width for the frame enclosing the answering
              area.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>framerulecol=<replaceable>color</replaceable></term>

            <listitem>
              <para>sets the frame color for the answering area.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>boxmargin=<replaceable>dim</replaceable></term>

            <listitem>
              <para>sets the margin around the scoring boxes.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>boxframerule=<replaceable>dim</replaceable></term>

            <listitem>
              <para>sets the line width for the frame around the scoring
              boxes.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>boxframerulecol=<replaceable>color</replaceable></term>

            <listitem>
              <para>sets the color of the frame around the scoring
              boxes.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>You can set other default values (for the whole exam) for all
        these parameters using the command <command>\AMCopenOpts</command>,
        like</para>

        <programlisting>\AMCopenOpts{boxframerule=2pt,boxframerulecol=red}</programlisting>

        <para>Moreover, a little text can be written in the marking area to
        tell the students not to tick these boxes, redefining the
        <command>\AMCotextReserved</command> command, as:</para>

        <programlisting>\def\AMCotextReserved{\emph{Reserved}}</programlisting>

        <para>When using separate answer sheets, the text added to each open
        question can also be defined, as:</para>

        <programlisting>\def\AMCotextGoto{\par{\bf\emph{Please write the answer on the separate answer sheet.}}}</programlisting>

        <tip>
          <para>if the number of boxes is significant, use this tip
          (<command>\parbox</command>) to force a linebreak.</para>

          <programlisting>\AMCOpen{lines=6}{
          \hbox{\parbox{8.5cm}{
			    \correctchoice[1]{1}\scoring{b=1}
			    \correctchoice[2]{2}\scoring{b=2}
			    \correctchoice[3]{3}\scoring{b=3}
			    \correctchoice[4]{4}\scoring{b=4}
			    \correctchoice[5]{5}\scoring{b=5}
			    \correctchoice[6]{6}\scoring{b=6}
			    \correctchoice[7]{7}\scoring{b=7}
			    \correctchoice[8]{8}\scoring{b=8}
			    \correctchoice[9]{9}\scoring{b=9}
			    \correctchoice[10]{10}\scoring{b=10}
			    \wrongchoice[F]{F}\scoring{b=0}
                    }}
            }
	      </programlisting>
        </tip>
      </sect3>

      <sect3 id="latex.oneletter">
        <title>One-letter answers</title>

        <para>Sometimes this is not necessary to write some long text to
        describe answers, and one letter or symbol is enough. When using a
        separate answer sheet, it is quite annoying to print the boxes both on
        the question and on the answer sheet. In such cases, use
        <command>\AMCBoxOnly</command> instead of the <code>choices</code>
        environment:</para>

        <programlisting>\begin{question}{arm}
  Which letter shows the \textit{arm} on the diagram?
  \AMCBoxOnly{ordered=true}{\wrongchoice[A]{}\correctchoice[B]{}%
    \wrongchoice[C]{}\wrongchoice[D]{}}
\end{question}</programlisting>

        <para>The first argument to <command>\AMCBoxOnly</command> is a comma
        separated list of options. The available options are:</para>

        <variablelist>
          <varlistentry>
            <term>help=<replaceable>text</replaceable></term>

            <listitem>
              <para>prints some reminder text before the boxes on the separate
              answer sheet.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>ordered=<replaceable>bool</replaceable></term>

            <listitem>
              <para>if <code>true</code> (the default value is
              <code>false</code>), the answers won't be shuffled.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="latex.seed">
        <title>Choice of shuffling parameters</title>

        <para>One can modify the seed of the random number generator used to
        produce the shuffle, thanks to the following command (to be used just
        at the beginning of the document, and in any case outside the
        <command>onecopy</command> command):</para>

        <para><programlisting>\AMCrandomseed{1527384}</programlisting></para>

        <para>If the value that is assigned (to be chosen between 1 and
        4194303) is modified, then the shuffling will differ. Of course, one
        must not modify this value after the test sheets have been
        printed.</para>

        <note>
          <para>The value is recorded in the xy file (as
          <code>\rngstate{1}{1515}</code>). The default value is 1515.</para>
        </note>
      </sect3>

      <sect3 id="latex.separate.sect">
        <title>Using sectioning and separate answer sheet</title>

        <para>For sectioning to be also visible in the separate answer sheet
        (if any), use <command>\AMCsection</command> and
        <command>\AMCsubsection</command> instead of
        <command>\section</command> and <command>\subsection</command>
        (<command>\AMCsection*</command> and
        <command>\AMCsubsection*</command> are also defined, for unnumbered
        sectionning)</para>
      </sect3>

      <sect3 id="latex.refs">
        <title>Using references inside the test sheets</title>

        <para>Using LaTeX commands <command>\label</command>,
        <command>\ref</command> and <command>\pageref</command> within
        questions or answers is problematic since they will be called with the
        same arguments for every realization of the test, which will alter the
        numbering of references. To solve this problem, one should use instead
        the commands <command>\AMClabel</command>, <command>\AMCref</command>
        and <command>\AMCpageref</command>: they add the realization number to
        their argument before transmitting it to <command>\label</command>,
        <command>\ref</command> and <command>\pageref</command>.</para>

        <note>
          <para>Since the version 1.2.2015.102901, you don't have to use the
          command <command>\AMCqlabel</command> to label a question but type
          <command>\AMClabel</command>. The old command remain compatible with
          your previous tex files/exams.</para>
        </note>

        <para>One also has to reset counters to zero at the beginning of each
        realization. For instance, if one wants to include references to
        pictures that are put together in a separate page, one might write
        something like</para>

        <programlisting>\element{animals}{
  \begin{figure}[p]
    \centering
    \includegraphics[width=.6\linewidth]{tiger}
    \caption{An animal}
    \AMClabel{tiger}
  \end{figure}

  \begin{question}{tiger}
    Which is the animal on figure~\AMCref{tiger} page~\AMCpageref{tiger}?
    \begin{choices}
      \correctchoice{A tiger}
      \wrongchoice{A giraffe}
      \wrongchoice{An elephant}
      \wrongchoice{A cat}
    \end{choices}
  \end{question}
}</programlisting>

        <para>and it is then important to add, just after the command
        <command>\onecopy</command> the line</para>

        <programlisting>\setcounter{figure}{0}</programlisting>

        <para>so that the numbering of figures starts at 1 for every
        realization. Without that last command, the numbering of figures would
        go on from one realization to the next one, which is clearly not
        desirable.</para>

        <sect4 id="cleveref">
          <title>Using the package cleveref</title>

          <para>This package sort in an ascending order the questions'
          numbers, the questions' pages or the labels' pages (the
          documentation <ulink
          url="http://mirrors.ctan.org/macros/latex/contrib/cleveref/cleveref.pdf">http://mirrors.ctan.org/macros/latex/contrib/cleveref/cleveref.pdf</ulink>).</para>

          <warning>
            <para>This package must be loaded <emphasis>after</emphasis> the
            package <package>automultiplechoice</package>.</para>
          </warning>

          <para>To use this package, a new command was created:
          <command>\AMCstudentlabel</command>. <programlisting>\cref{\AMCstudentlabel{led},\AMCstudentlabel{lamp},\AMCstudentlabel{motor}}</programlisting>
          <emphasis>led</emphasis>, <emphasis>lamp</emphasis>,
          <emphasis>motor</emphasis> are the created labels to reference the
          questions with the command \AMClabel{}.</para>
        </sect4>
      </sect3>

      <sect3 id="AMCtext">
        <title>Customizing some texts inserted by AMC</title>

        <para>Use <command>\AMCtext</command> for the following
        customizations:</para>

        <itemizedlist>
          <listitem>
            <para><code>\AMCtext{none}{<replaceable>sentence</replaceable>}</code>
            replaces « None of these answers are correct. » (the English
            default text) with the given <replaceable>sentence</replaceable>
            when using option <option>completemulti</option>.</para>
          </listitem>

          <listitem>
            <para><code>\AMCtext{corrected}{<replaceable>title</replaceable>}</code>
            replaces « Corrected » (the English default text) with the given
            <replaceable>title</replaceable> on the corrected answer
            sheet.</para>
          </listitem>

          <listitem>
            <para><code>\AMCtext{catalog}{<replaceable>title</replaceable>}</code>
            replaces « Catalog » (the English default text) with the given
            <replaceable>title</replaceable> on the questions catalog produced
            thanks to option <option>catalog</option>.</para>
          </listitem>

          <listitem>
            <para><code>\AMCtext{explain}{<replaceable>title</replaceable>}</code>
            replaces « <emphasis>Explanation</emphasis> » (the English default
            text) with the given <replaceable>title</replaceable> before the
            explanations produced due to the <command>explain</command>
            command.</para>

            <para>The default option for this command is:</para>

            <programlisting>\AMCtext{explain}{\textit{\textbf{Explanation: }}}</programlisting>
          </listitem>

          <listitem>
            <para>You can also consider using commands like the following ones
            (here the second argument is set to the default English
            value):</para>

            <programlisting>\AMCtext{draft}{DRAFT}
\AMCtext{message}{For your examination, preferably print documents
                  compiled from auto-multiple-choice.}</programlisting>
          </listitem>

          <listitem>
            <para><code>\AMCsetFoot{<replaceable>text</replaceable>}</code>
            sets the footer. Use for example
            <code>\AMCsetFoot{\thepage}</code> to write the page
            number.</para>
          </listitem>
        </itemizedlist>
      </sect3>

      <sect3 id="binary.code">
        <title id="binary.code.title">Binary code</title>

        <para>AMC identifies each test and the page number of test with the
        binary code.</para>

        <itemizedlist>
          <listitem>
            <para>First row : 12 boxes (default value) : maximum number of
            tests = 2^12-1 = 4 095.</para>
          </listitem>

          <listitem>
            <para>Second row : 6 first boxes (default value) : maximum number
            of pages per tests = 2^6-1 = 63.</para>
          </listitem>

          <listitem>
            <para>Second row : 6 last boxes (default value) : check
            code.</para>
          </listitem>
        </itemizedlist>

        <para>To raise the number of tests and/or pages per test modify the
        commands' default values <command>\AMC@NCBetud</command>,
        <command>\AMC@NCBpage</command> et
        <command>\AMC@NCBcheck</command>.</para>

        <para>Load those commands below in the preambule (here with the
        default values).</para>

        <programlisting>\makeatletter
\def\AMC@NCBetud{12}
\def\AMC@NCBpage{6}
\def\AMC@NCBcheck{6}
\makeatother          </programlisting>
      </sect3>
    </sect2>

    <sect2 id="latex.amcopts">
      <title>Options for AMC</title>

      <para>You can add in the source file header (the first lines that begin
      with a '%') some options to be passed to AMC:</para>

      <variablelist>
        <varlistentry>
          <term><code>%%AMC:preprocess_command=<replaceable>commandname</replaceable></code></term>

          <listitem>
            <para>tells AMC to run the <replaceable>commandname</replaceable>
            command before calling LaTeX to process the source file. This
            command will be run inside the project directory, and the name of
            a source file copy will be passed as an argument. There is no
            problem for <replaceable>commandname</replaceable> to change this
            file content, because this is only a copy.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><code>%%AMC:latex_engine=<replaceable>engine</replaceable></code></term>

          <listitem>
            <para>tells AMC to set the LaTeX engine to use for this file,
            regardless to the one entered as a preference by the user.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="latex.numerical">
      <title>Mathematical questions with randomized statements</title>

      <sect3 id="latex.numerical.fp">
        <title>Using package fp</title>

        <para>Thanks to the LaTeX package <package>fp</package>, whose
        documentation is available at <ulink
        url="http://mirrors.ctan.org/macros/latex/contrib/fp/README">http://mirrors.ctan.org/macros/latex/contrib/fp/README</ulink>,
        and which can be downloaded with the command <programlisting>\usepackage{fp}</programlisting>added
        before that corresponding to <package>automultiplechoice</package>,
        one can create exercises with randomized numerical data. Let us start
        with a simple example.</para>

        <para><programlisting>\begin{question}{addition}
  \FPeval\VQa{trunc(1+random*8,0)}  <co id="alea.random"
              linkends="alea.random.exp"/>
  \FPeval\VQb{trunc(4+random*5,0)}
  \FPeval\VQsomme{clip(VQa+VQb)}  <co id="alea.result"
              linkends="alea.result.exp"/>
  \FPeval\VQnonA{clip(VQa+VQb-1)}  <co id="alea.fausse"
              linkends="alea.fausse.exp"/>
  \FPeval\VQnonB{clip(VQa*VQb)}
  \FPeval\VQnonC{clip(VQa-VQb)}

  What is the sum of \VQa{} and \VQb{} ?
  \begin{choiceshoriz}
    \correctchoice{\VQsomme}
    \wrongchoice{\VQnonA}
    \wrongchoice{\VQnonB}
    \wrongchoice{\VQnonC}
  \end{choiceshoriz}
\end{question}</programlisting></para>

        <para>The <command>\FPeval</command> command is used to perform
        computations:</para>

        <para><calloutlist>
            <callout arearefs="alea.random" id="alea.random.exp">
              <para>Since <command>random</command> returns a real number in
              the interval [0,1], this command sets VQa to a random integer
              value between 1 and 8. The next line sets VQb to a random
              integer value between 4 and 8.</para>
            </callout>

            <callout arearefs="alea.result" id="alea.result.exp">
              <para>Putting the correct answer in the variable VQsomme.</para>
            </callout>

            <callout arearefs="alea.fausse" id="alea.fausse.exp">
              <para>Putting wrong answers in variables VQnonA, VQnonB and
              VQnonC...</para>
            </callout>
          </calloutlist>Variable names beginning with VQ have been chosen so
        as to avoid interference with other LaTeX commands.</para>

        <note>
          <para>You can set the random seed with</para>

          <para><programlisting>\FPseed=<replaceable>integer</replaceable></programlisting></para>

          <para><replaceable>integer</replaceable> must be fixed, and not
          computed from date/time values.</para>
        </note>

        <sect4 id="latex.intervals">
          <title>Choosing an interval</title>

          <para>The <command>automultiplechoice</command> package moreover
          defines a <command>\AMCIntervals</command> command which makes this
          kind of construction simpler, as illustrated in the next
          example:<programlisting>\begin{question}{inf-expo-indep}
  \FPeval\VQa{trunc(2 + random * 4,0)}
  \FPeval\VQb{trunc(6 + random * 5,0)}
  \FPeval\VQr{VQa/(VQa+VQb)}

  Let $X$ and $Y$ be two independent random variables, following the exponential distribution with
respective parameters \VQa{} and \VQb{}.
  To which interval does the probability $\mathbb{P}[X&lt;Y]$ belong ?

  \begin{multicols}{5}
    \begin{choices}[o]
      \AMCIntervals{\VQr}{0}{1}{0.1}  <co id="choix.intervalles"
                linkends="choix.intervalles.exp"/>
    \end{choices}
  \end{multicols}
\end{question}</programlisting></para>

          <calloutlist>
            <callout arearefs="choix.intervalles" id="choix.intervalles.exp">
              <para>This lines inserts ten answers corresponding to the
              intervals [0,0.1[ [0.1,0.2[ ... [0.9,1[, while indicating that
              the correct interval is the one containing VQr. The arguments of
              the <command>\AMCIntervals</command> command are the
              following:</para>

              <orderedlist>
                <listitem>
                  <para>The correct answer,</para>
                </listitem>

                <listitem>
                  <para>The left point of the first interval,</para>
                </listitem>

                <listitem>
                  <para>The right point of the last interval,</para>
                </listitem>

                <listitem>
                  <para>The length of each interval.</para>
                </listitem>
              </orderedlist>
            </callout>
          </calloutlist>

          <para>Note that the interval formatting can be changed redefining
          the <command>\AMCintervalFormat</command> command, which is
          originally defined as</para>

          <programlisting>\def\AMCIntervalFormat#1#2{[#1,\,#2[}</programlisting>

          <para>to follow local conventions (writing [a,b) instead of [a,b[ is
          for example a common usage).</para>
        </sect4>

        <sect4 id="latex.numeric">
          <title>Coding the result</title>

          <para>The students can also be asked to code the numerical answer,
          using the <command>\AMCnumericChoices</command> command, as in the
          following example:</para>

          <programlisting>\begin{questionmultx}{sqrt}
  \FPeval\VQa{trunc(5+random*15,0)}
  \FPeval\VQs{VQa^0.5}
  Compute $\sqrt{\VQa}$ and round it with two digits after period.

  \AMCnumericChoices{\VQs}{digits=3,decimals=2,sign=true,
                 borderwidth=0pt,backgroundcol=lightgray,approx=5}
\end{questionmultx}
</programlisting>

          <para>Note the use of <code>questionmultx</code> environment: we
          need this question to be multiple as several boxes has to be ticked,
          but we can’t say that several answers are correct, so we don’t show
          the symbol for multiple questions.</para>

          <para>Available options that can be used in the second argument of
          the <command>\AMCnumericChoices</command> command are the following
          (<replaceable>bool</replaceable> can be <code>true</code> or
          <code>false</code>, and <replaceable>color</replaceable> must be a
          color known by the <command>xcolor</command> package):</para>

          <variablelist>
            <varlistentry>
              <term>digits=<replaceable>num</replaceable></term>

              <listitem>
                <para>gives the number of digits to request (defaults to
                3).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>decimals=<replaceable>num</replaceable></term>

              <listitem>
                <para>gives the number of digits after period to request
                (defaults to 0). Note that when <replaceable>num</replaceable>
                is positive, the LaTeX package <command>fp</command> must be
                loaded.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>base=<replaceable>num</replaceable></term>

              <listitem>
                <para>gives the base for <code>digits</code> and
                <code>decimals</code> (defaults to 10).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>significant=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if <code>true</code>, the numbers to code are the first
                significant digits from the first argument of
                <command>\AMCnumericChoices</command>. For example, the right
                answer to
                <code>\AMCnumericChoices{56945.23}{digits=2,significant=true}</code>
                is 57.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>exponent=<replaceable>num</replaceable></term>

              <listitem>
                <para>switch to scientific notation mode, with
                <replaceable>num</replaceable> digits for the exponent.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>nozero=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if true, the choice 0 is removed for all digits. May be
                useful when using <command>\AMCnumericChoices</command> to
                enter small (&lt;10) positive values.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sign=<replaceable>bool</replaceable></term>

              <listitem>
                <para>requests (or not) a signed value (defaults to
                true).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>exposign=<replaceable>bool</replaceable></term>

              <listitem>
                <para>same for the exponent sign.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>strict=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if <code>true</code>, a box has to be ticked for every
                digit (even null digits) and for the sign. If
                <code>false</code>, if some digits has no ticked box, they
                will be set to zero. Defaults to <code>false</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>vertical=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if true, each digit is represented on one raw. If false
                (default), each digit is represented on one line.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>expovertical=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if <code>true</code>, the mantissa is
                <emphasis>above</emphasis> the exponent. If <code>false</code>
                (default), the mantissa is <emphasis>beside</emphasis> the
                exponent.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>reverse=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if true, place higher values of the digits on the top in
                <code>vertical</code> mode (defaults to true).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>vhead=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if true, in <code>vertical</code> mode, a header is
                placed over all digits rows, made using the command
                <command>\AMCntextVHead</command> that is originally defined
                as</para>

                <programlisting>\def\AMCntextVHead#1{\emph{b#1}}</programlisting>

                <para>This default value is useful to number the binary
                digits.</para>

                <para>Default value is <code>false</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>hspace=<replaceable>space</replaceable></term>

              <listitem>
                <para>sets the horizontal space between boxes (defaults to
                <code>.5em</code>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>vspace=<replaceable>space</replaceable></term>

              <listitem>
                <para>sets the vertical space between boxes (defaults to
                <code>1ex</code>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>borderwidth=<replaceable>space</replaceable></term>

              <listitem>
                <para>sets the width of the frame border around all the boxes
                (defaults to <code>1mm</code>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>bordercol=<replaceable>color</replaceable></term>

              <listitem>
                <para>sets the color of the frame (defaults to
                <code>lightgray</code>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>backgroundcol=<replaceable>color</replaceable></term>

              <listitem>
                <para>sets the background color (defaults to
                <code>white</code>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Tsign=<replaceable>text</replaceable></term>

              <listitem>
                <para>sets the text to print at the top of the boxes to set
                the sign (Can also be redefined by
                <code>\def\AMCntextSign{<replaceable>text</replaceable>}</code>,
                and defaults to be empty).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Tpoint=<replaceable>text</replaceable></term>

              <listitem>
                <para>sets the text for the period. Can also be redefined by
                <code>\def\AMCdecimalPoint{<replaceable>text</replaceable>}</code>,
                and defaults to <code>\raisebox{1ex}{\bf .}</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Texponent=<replaceable>text</replaceable></term>

              <listitem>
                <para>sets the text that separates mantissa and exponent. Can
                also be redefined by
                <code>\def\AMCexponent{<replaceable>text</replaceable>}</code>,
                and defaults to
                <code>$\times10$\textasciicircum</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>scoring=<replaceable>bool</replaceable></term>

              <listitem>
                <para>if <code>true</code>, a scoring strategy is given to AMC
                for this question. Defaults to <code>true</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>scoreexact=<replaceable>num</replaceable></term>

              <listitem>
                <para>gives the score for an exact answer (defaults to
                2).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>exact=<replaceable>num</replaceable></term>

              <listitem>
                <para>sets the maximal distance to the correct integer value
                (value without the decimal point) for an answer to be said
                <emphasis>exact</emphasis> and be rewarded to
                <code>scoreexact</code> points (defaults to 0).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>scoreapprox=<replaceable>num</replaceable></term>

              <listitem>
                <para>gives the score for an
                <emphasis>approximative</emphasis> answer (defaults to
                1).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>approx=<replaceable>num</replaceable></term>

              <listitem>
                <para>sets the maximal distance to the correct integer value
                (value without the decimal point) for an answer to be said
                <emphasis>approximative</emphasis> and be rewarded to
                <code>scoreapprox</code> points (defaults to 0).</para>

                <warning>
                  <para>AMC converts all numbers (decimals included) to
                  integers (simply removing the decimal point) before
                  subtracting them and comparing with <code>approx</code>. As
                  an example, with <code>decimals=2</code>, if the correct
                  answer is 3.14 and the given answer is 3.2, then the integer
                  difference is 320-314=6, so that the student gets
                  <code>scoreapprox</code> points only if <code>approx</code>
                  is 6 or greater.</para>
                </warning>
              </listitem>
            </varlistentry>

              <varlistentry>
              <term>scorewrong=<replaceable>num</replaceable></term>
                <listitem>
                <para>gives the score for an wrong answer (defaults to
                0).</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>You can set other default values (for the whole exam) for all
          these parameters using the command
          <command>\AMCnumericOpts</command>, like</para>

          <programlisting>\AMCnumericOpts{scoreexact=3,borderwidth=2pt}</programlisting>

          <para>Moreover, the text added at the end of the questions using
          <command>\AMCnumericChoices</command> when not in the separate
          answer sheet (and when a separate answer sheet is requested by the
          <code>separateanswersheet</code> package option) can also be set
          redefining the <command>\AMCntextGoto</command> command, as:</para>

          <programlisting>\def\AMCntextGoto{\par{\bf\emph{Please code the answer on
                           the separate answer sheet.}}}</programlisting>
        </sect4>
      </sect3>

      <sect3 id="latex.numerical.pgf">
        <title>Using package pgf/tikz</title>

        <para>This package must be declared <emphasis>after</emphasis> the
        package <package>automultiplechoice</package>.</para>

        <para>LaTeX package <package>pgf/tikz</package> (see <ulink
        url="http://www.ctan.org/tex-archive/graphics/pgf/base">http://www.ctan.org/tex-archive/graphics/pgf/base</ulink>)
        provides mathematical functions that can be loaded with
        <programlisting>\usepackage{tikz}</programlisting></para>

        <para>First of all, you must set the random seed to be sure to get the
        same result each time latex is run to compile the subject:</para>

        <para><programlisting>\pgfmathsetseed{2056}</programlisting></para>

        <sect4 id="latex.numerical.pgf.simple">
          <title>A simple computation</title>

          <para>Here is an example with a simple computation:</para>

          <para><programlisting>\begin{question}{inverse}
  \pgfmathrandominteger{\x}{1}{50}

  How much is the reciprocal of $x=\x$?

  \begin{choices}
    \correctchoice{\pgfmathparse{1/\x}\pgfmathresult }
    \wrongchoice{\pgfmathparse{1/(\x +1))}\pgfmathresult}
    \wrongchoice{\pgfmathparse{cos(\x)} \pgfmathresult}
    \wrongchoice{\pgfmathparse{\x^(-0.5)}\pgfmathresult}
  \end{choices}
\end{question}
</programlisting></para>

          <para>Here, the command <command>\pgfmathparse</command> makes the
          computation, and <command>\pgfmathresult</command> outputs the
          result.</para>

          <para>Output formatting is also available with the command
          <command>\pgfmathprintnumber</command>, as in the following example
          (three digits after decimal point, and use of the comma as a decimal
          point).</para>

          <para><programlisting>\begin{question}{inverse3}
  \pgfmathrandominteger{\x}{1}{50}
  \pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=3,use comma}
  How much is the reciprocal of $x=\pgfmathprintnumber{\x}$?

  \begin{choices}
    \correctchoice{\pgfmathparse{1/\x}\pgfmathprintnumber{\pgfmathresult}}
    \wrongchoice{\pgfmathparse{1/(\x +1))} \pgfmathprintnumber{\pgfmathresult}}
    \wrongchoice{\pgfmathparse{cos(\x)} \pgfmathprintnumber{\pgfmathresult}}
    \wrongchoice{\pgfmathparse{\x^(-0.5)} \pgfmathprintnumber{\pgfmathresult}}
  \end{choices}
\end{question}
</programlisting><note>
              <para>You can also use the <command>\AMCIntervals</command> and
              <command>\AMCnumericChoices</command> commands (see <xref
              linkend="latex.intervals"/> and <xref
              linkend="latex.numeric"/>)</para>
            </note></para>
        </sect4>

        <sect4 id="latex.numerical.pgf.graphs">
          <title>Graphics</title>

          <para>The tikz package also allows to make (random or not)
          graphs.</para>

          <para><programlisting>\begin{questionmult}{graph}
  Let us consider the three functions which graphs are plotted below:
  \pgfmathrandominteger{\a}{2}{4}
  \begin{center}
    \begin{tikzpicture}[domain=0:4]
      \draw[very thin,color=gray] (-0.1,-4.1) grid (3.9,3.9);
      \draw[-&gt;] (-0.2,0) -- (4.2,0) node[right] {$x$};
      \draw[-&gt;] (0,-4.2) -- (0,4.2) node[above] {$f(x)$};
      \draw[color=red] plot (\x,{(1+\a/4)*\x-\a}) node[right] {$f_{1} (x)$};
      \draw[color=blue] plot (\x,{\a*sin(\x r)}) node[right] {$f_{2}(x)$};
      \draw[color=orange] plot (\x,{\a*cos(\x r)}) node[right] {$f_{3}(x)$};
    \end{tikzpicture}
  \end{center}
  Then:
  \begin{choices}
    \pgfmathrandominteger{\x0}{2}{4}
    \correctchoice{$f_{2}(\x0)$=\pgfmathparse{\a*sin(\x0 r)} \pgfmathprintnumber{\pgfmathresult}.}
    \correctchoice{$f_{3}(\x0)$=\pgfmathparse{\a*cos(\x0 r)} \pgfmathprintnumber{\pgfmathresult}.}
    \wrongchoice{La fonction $f_{1}(x)$ est une fonction linéaire.}
  \end{choices}
\end{questionmult}
</programlisting></para>

          <para>To make pretty graphs, package <package>pgfplots</package> can
          also be useful.</para>

          <para>With pgfmath, precision is limited, so that a "Arithmetic
          overflow" error can be encountered. Packages <package>tikz</package>
          and <package>pgfplots</package> allows to overcome this problem,
          using <command>gnuplot</command> as a backend. You need to install
          <command>gnuplot</command> on your system, and use LaTeX option
          <option>--shell-escape</option>. To this purpose, go to AMC
          preferences window, and set the LaTeX engine for your project to
          "<option>pdflatex --shell-escape</option>" (without the
          quotes).</para>
        </sect4>
      </sect3>

      <sect3 id="latex.numerical.lualatex">
        <title>Using LuaLaTeX</title>

        <para>LUA language can be used inside LaTeX documents thanks to the
        <command>lualatex</command> command. If you uses it, your document
        needs to be UTF-8 encoded, and you must not load the
        <package>inputenc</package> package. See <ulink
        url="http://www.luatex.org/documentation.html">http://www.luatex.org/documentation.html</ulink>
        for some information.</para>

        <para>LUA commands are to be given as a <command>\directlua</command>
        argument. The most useful LUA function is
        <command>tex.print</command>, which will output results back to
        LaTeX.</para>

        <para>Once again, if you use random numbers, always fix the random
        seed to get the same results across different compilations:</para>

        <programlisting>\directlua{math.randomseed (2048)}</programlisting>

        <para>Here is a very simple sample source file:</para>

        <programlisting>\documentclass[a4paper]{article}
%\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[box,completemulti]{automultiplechoice}
\begin{document}

\onecopy{10}{

%%% head

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
  \centering\large\bf LuaLaTeX sample exam
\end{minipage}
\namefield{\fbox{\begin{minipage}{.5\linewidth}
Name :

\vspace*{.5cm}\dotfill
\vspace*{1mm}
\end{minipage}}}

%%%

\directlua{math.randomseed (2048)}
\directlua{a=math.random()}

\begin{question}{square-root}
  How much is the square root of \directlua{tex.print(a)}?

  \begin{choices}
    \correctchoice{\directlua{tex.print(math.sqrt(a))}}
    \wrongchoice{\directlua{tex.print(math.sqrt(2*a))}}
    \wrongchoice{\directlua{tex.print(math.sqrt(a*1.001))}}
  \end{choices}
\end{question}

}

\end{document}      </programlisting>

        <para>Output formatting can be obtained using lua functions, or with
        the <package>siunitx</package> package.</para>

        <note>
          <para>You can also use the <command>\AMCIntervals</command> and
          <command>\AMCnumericChoices</command> commands (see <xref
          linkend="latex.intervals"/> and <xref
          linkend="latex.numeric"/>)</para>
        </note>
      </sect3>

      <sect3 id="latex.pstricks">
        <title>Use PSTricks</title>

        <para>Load this package <emphasis>after</emphasis>
        <package>automultiplechoice</package>.</para>

        <para>To use <command>PSTricks</command>, you have to configure AMC :
        <menuchoice>
            <guimenu>Edit</guimenu>

            <guimenuitem>Preferences</guimenuitem>

            <guimenuitem>Main</guimenuitem>

            <guimenuitem>Default LaTex engine</guimenuitem>

            <guimenuitem>latex+dvipdf</guimenuitem>
          </menuchoice></para>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="graphical-interface">
    <title>Usage - Graphical interface</title>

    <para>We shall describe here a usage example with the graphic interface
    from the conception of the multiple-choice test until the edition of
    students' scores.</para>

    <sect2 id="gui.new">
      <title>Creating a new project and subject</title>

      <para>Let's open the graphic interface. This can be done ordinarily by
      selecting <menuchoice>
          <guimenu>Applications</guimenu>

          <guisubmenu>Education</guisubmenu>

          <guimenuitem>Auto Multiple Choice</guimenuitem>
        </menuchoice> in the general menu of Gnome (or its equivalent in KDE
      or other), but the command <userinput>auto-multiple-choice</userinput>
      can be used directly.</para>

      <para>Let's now create a new project, thanks to <menuchoice>
          <guimenu>Project</guimenu>

          <guimenuitem>New</guimenuitem>
        </menuchoice>. A window opens and allows us to see existing project
      names (if any) and choose a name for our new project (made with simple
      characters; « test » will be OK for our short test), which we write in
      the field <guilabel>Project name</guilabel>. Then we push the
      <guibutton>New project</guibutton> button.</para>

      <para>Now we must choose a LaTeX file as a source for the
      multiple-choice. Several possibilities are shown:</para>

      <itemizedlist>
        <listitem>
          <para><guilabel>model</guilabel>: this choice allows to choose from
          models shipped with AMC an exam to customize later.</para>
        </listitem>

        <listitem>
          <para><guilabel>file</guilabel>: this choice allows to choose a
          LaTeX file already prepared for this exam. Somebody may have
          prepared the exam for you, or you can have prepared the exam outside
          AMC, using your favorite LaTeX editor.</para>
        </listitem>

        <listitem>
          <para><guilabel>empty</guilabel>: using this choice, an empty LaTeX
          file will be created. You have to edit it to compose the exam from
          zero.</para>
        </listitem>

        <listitem>
          <para><guilabel>archive</guilabel>: use this choice if you have a
          zip or tgz archive containing the exam definition (LaTeX source
          file, along with image files, parameters file for example). This
          archive can be made by an external software. It can also be a backup
          of one of your AMC projects.</para>
        </listitem>
      </itemizedlist>

      <para>For our test, let us choose <guilabel>model</guilabel>. The next
      window presents the models: choose for example <guilabel>Simple
      example</guilabel> from <guilabel>[EN] Documentation group</guilabel>.
      Now we can edit it to modify the shape of the document or the questions,
      thanks to the <guibutton>Edit LaTeX file</guibutton> button which
      launches the default editor.</para>
    </sect2>

    <sect2 id="gui.prepare">
      <title>Preparing the subject</title>

      <para>Preparing a project is done in two steps. First we must make the
      reference documents from the LaTeX source file. This can be done by
      clicking the <guibutton>Update documents</guibutton> or <keycode>Alt+U</keycode>. The following
      documents are produced:</para>

      <itemizedlist>
        <listitem>
          <para>The <emphasis>question</emphasis>. This file can be printed to
          distribute its pages to students (see below).</para>
        </listitem>

        <listitem>
          <para>The <emphasis>solution</emphasis>. We can check that the
          chosen responses there are the good ones. It is also made to be
          distributed to students.</para>
        </listitem>
      </itemizedlist>

      <para>When produced, those documents can be viewed (and possibly
      printed) from the corresponding buttons.</para>

      <para>Now we can begin the last step of the preparation: analyzing the
      layout. It can be launched with the button <guibutton>Layout
      detection</guibutton>. This analysis detects, in every page of the
      subject, the exact position of every element which must be analyzed in
      the students' copies.</para>

      <para>To check whether the layouts have been correctly detected, we can
      use the button <guibutton>Check layouts</guibutton>. A short insight
      allows to check that red checkboxes are correctly located over the boxes
      of the subject.</para>
    </sect2>

    <sect2 id="printing">
      <title id="printing.title">Printing and exam</title>

      <para>Two alternative workflows can be considered:</para>

      <itemizedlist>
        <listitem>
          <para>For the most robust, create as many exam sheets as necessary
          for all your students, with different sheets numbers, and print them
          all. Each page can be identified by its numbers and boxes at the
          top, so that you can scan several times the same completed answer
          sheet page carefree.</para>
        </listitem>

        <listitem>
          <para>Secondly, you can print a few subjects (or only one if you
          want), and photocopy them to get one subject for all students.
          Questions shuffling will be less efficient, and if you give several
          times a scan of the same page, AMC won't be able to know about it
          and will create an unwanted duplicate.</para>
        </listitem>
      </itemizedlist>

      <warning>
        <para>To use this second workflow using photocopies, there must be
        only one page for students to write on (using a separate answer sheet
        can help you for this). If not, you won't be able to continue with
        AMC! Indeed, it would be impossible for AMC to make the link between
        two pages from the same student.</para>
      </warning>

      <para>When the preparation is over, we can print the subject, and
      distribute it to the students... In simple cases, we can directly print
      from the viewer (after clicking the line <guilabel>Subject</guilabel> in
      the list of work documents). When it is better to print the copies
      separately (for example if copies contain multiple pages and when the
      printer allows to staple them together), we shall rather use the button
      <guibutton>Print copies</guibutton> after calculating the layout.</para>
    </sect2>

    <sect2 id="gui.test">
      <title>Test</title>

      <para>Let the students pass the exam.</para>

      <important>
        <para>When the subject is printed and distributed, we may no more
        modify the <emphasis>work documents</emphasis> because they must
        remain identical to distributed copies.</para>
      </important>

      <para>It is preferable that students use a black or blue pen or B or HB
      pencil.</para>

      <para>Depending on the situation, you can ask the students to
      <emphasis>tick</emphasis> or <emphasis>fill</emphasis> the boxes.</para>

      <sect3 id="gui.advice">
        <title>Tick the boxes</title>

        <para>If you ask the students to tick the correct boxes, they can
        correct a ticked box ereasing their mark with a eraser or white-out
        fluid. However, <emphasis>they must not try to draw the boxes
        back</emphasis>. Trying to do so, they could draw lines inside the
        boxes, that could then be considered as ticked boxes.</para>

        <para>You can also let the students correct ticked boxes filling them
        completely. If you choose this option, you have to set the
        <guilabel>upper darkness threshold</guilabel> (from
        <guimenu>Preferences</guimenu> menu, <guilabel>Project</guilabel> tab)
        to some value less than 1 (but not too low). If the darkness ratio of
        a box is between the <guilabel>darkness threshold</guilabel> and the
        <guilabel>upper darkness threshold</guilabel>, the box is considered
        as been ticked. If the darkness ratio is greater than the
        <guilabel>upper darkness ratio</guilabel>, the box is considered as
        not ticked.</para>
      </sect3>

      <sect3 id="gui.correct">
        <title>Fill the boxes</title>

        <para>When the letters (or numbers) referencing the answers are drawn
        inside the boxes, you must tell the students to fill the correct
        boxes, as AMC can't make the difference between a box with a letter
        and ticked box.</para>

        <para>The stiudents can correct a ticked box ereasing their mark with
        a eraser or white-out fluid, but they don't have any other solution to
        correct a ticked box. You must set the <guilabel>upper darkness
        threshold</guilabel> to 1.<guilabel/></para>
      </sect3>
    </sect2>

    <sect2 id="gui.capture">
      <title>Reading the copies</title>

      <para>Now we shall describe the input from students' copies, which can
      be done automatically and/or manually.</para>

      <para>Let's move to the <guilabel>Data capture</guilabel> tab of the
      graphical interface.</para>

      <sect3 id="gui.capture.auto">
        <title>Automated input</title>

        <para>For automatic recognition of the checked boxes in the students'
        pages, they must be previously digitalized. I use a copier/scanner
        which does it automatically (all the pages in a bundle without
        interaction with me), with the following settings: 300 dpi, OCR mode
        (for the characters' recognition, black and white without grayscale -
        but the scanner does not process any character recognition), each scan
        delivered as a single TIFF file per page.</para>

        <note>
          <para>To analyze the scans, we must have them in one or several
          image files (TIFF, JPG, PNG, etc.). Vector graphics formats (PDF, PS
          or EPS) are also suitable: scans will then be converted into PNG by
          AMC before analysis.</para>
        </note>

        <note>
          <para>When giving scans for automated data capture the first time,
          you will have tell AMC which method you used: either different
          papers printed, or photocopied papers (see <xref
          endterm="printing.title" linkend="printing"/>).</para>
        </note>

        <para>Then we select this set of scan files in the dialog opened by
        the button <guibutton>Automated</guibutton> of the section
        <guilabel>Data capture after examination</guilabel>, then we validate
        with the <guibutton>OK</guibutton> button. AMC begins with Optical
        Mark Recognition to detect the position of the four circle corner
        marks on the scans, position the boxes, and detects the amount of
        black pixels in each box.</para>

        <para>The result of the analysis of each page is indicated in the
        lists of the section <guilabel>Diagnosis</guilabel>:</para>

        <itemizedlist>

        <listitem>
          <para>The value<option>update</option> displays the date
          the date the page was last modified. Hided by default. Click on the button
          <guimenuitem>columns</guimenuitem> to show it.</para>
        </listitem>

          <listitem>
            <para>The value <emphasis>MSD</emphasis> (mean square deviation)
            is an indication of the good framing of the marks (the four black
            dots surrounding each copy). When it is too great, the framing
            must be checked (right click on the page's line then choose
            <guimenuitem>page</guimenuitem> to view the scanned page and the
            boxes as they were detected).</para>
          </listitem>

          <listitem>
            <para>The value <emphasis>sensitivity</emphasis> is an indicator
            of proximity of the filling of the boxes with the threshold. If it
            is too great (from 8 to its max value 10), we must check whether
            the boxes recognized as checked are the good ones (a right click
            on the page's line the choose <guimenuitem>zoom</guimenuitem> to
            view the set of boxes in the copy, verify whether the detection
            worked correctly, and correct it if needed drag-and-dropping the
            boxes images).</para>
          </listitem>

        <listitem>
          <para>The value <emphasis>scan files</emphasis> displays the name of
          the handled page.  Hided by default. Click on the button
          <guimenuitem>columns</guimenuitem> to show it.</para>
        </listitem>

        </itemizedlist>
      </sect3>

      <sect3 id="gui.capture.manual">
        <title>Manual input</title>

        <para>If we cannot use easily the scanner, or if, for a few copies,
        the automated input did not work as expected, we can manage the input
        manually. To do so, let's open the right window thanks to the button
        <guibutton>Manual</guibutton> of the section <guilabel>Input of the
        copies after exam</guilabel>. In that window, we can input the boxes
        which have been checked ourselves (by clicking them) on the wanted
        pages.</para>

        <warning>
          <para>Every manual input will overwrite results eventually coming
          from a previous or posterior automated input for the same
          page.</para>
        </warning>

        <sect4 id="gui.capture.manual.color">
	  <title>Viewing empty or inavlid questions</title>
	  <para>By clicking on the page numbers, AMC wrap the boxes answers
	  with a colored square :
	  <itemizedlist>
            <listitem><para>cyan for empty answers,</para></listitem>
            <listitem><para>yellow for invalid answers.</para></listitem>
	  </itemizedlist>
	  </para>

	  <para>You may change this colors in the menu tab:
	  <menuchoice>
            <guimenu>Preferences</guimenu>
            <guisubmenu>Display</guisubmenu>
            <guimenuitem>Scan</guimenuitem>
          </menuchoice></para>

          <para>It is possible to search a specific question
          (see <xref endterm="gui.capture.manual.focus.title" linkend="gui.capture.manual.focus"/>)</para>
        </sect4>

        <sect4 id="gui.capture.manual.focus">
         <title id="gui.capture.manual.focus.title">Select a specific question</title>
         <para>This option make it possible to manually mark on-screen a specific question.
          This save your having to search on each page the question if they are shuffled.</para>

         <sect5 id="gui.capture.manual.open.question.focus">
           <title>Mark an open question on-screen</title>
           <itemizedlist>
           <listitem><para>open the manual input tab and select  "scan" as background,</para></listitem>
           <listitem><para>select the question to mark
           (drop-down menu above the list of pages) .</para></listitem>
           </itemizedlist>

           <para>The open question's check-boxes are on the top of the window, and when you click
           <guibutton>next</guibutton> you move forward to the following student, always for the same question.</para>

           <note><para>All questions can be checked like this.</para></note>
          </sect5>

          <sect5 id="gui.capture.manual.empty.invalid.question.focus">
           <title>Check on-screen pages with invalid or empty questions</title>
           <itemizedlist>
           <listitem> <para>The marking must be ended before use
           (see <xref endterm="gui.marks.proc.title" linkend="gui.marks.proc"/>
           section <xref endterm="gui.marks.title" linkend="gui.marks"/>),</para></listitem>
           <listitem><para> open the manual input tab and select  "scan" as background,</para>
           </listitem>
           <listitem><para>choose if you want to navigate through all pages, through pages
           with invalid answers (inv), or through pages with invalid or empty answers (i &amp; e).
           </para></listitem>
           </itemizedlist>
            </sect5>
         </sect4>

      </sect3>
    </sect2>

    <sect2 id="gui.marks">
      <title id="gui.marks.title">Correction</title>

      <para>In the <guilabel>Marking</guilabel> tab of the graphic interface,
      the part <guilabel>Marking</guilabel> allows us to deduce the scores of
      the students from the inputs, but also to read the codes written by the
      students (see <xref linkend="latex.codes"/>).</para>

      <sect3 id="gui.marks.proc">
        <title id="gui.marks.proc.title">Process</title>

        <para>The computation of the scores is launched with the button
        <guibutton>Mark</guibutton>, but we must previously make the following
        choice:</para>

        <itemizedlist>
          <listitem>
            <para>If we check the box <guilabel>Update marking
            scale</guilabel>, the scoring strategy will be first extracted
            from the LaTeX source file. This allows to try many strategies at
            the end of the correction process. This action also updates which
            answers are specified as correct or as wrong. Hence, potential
            mistakes in the answers can be easily fixed after the exam. The
            method to specify the strategy in the LaTeX file will be explained
            in the section <xref endterm="bareme.title" linkend="bareme"/> (a
            default scoring strategy is used when no indication is
            given).</para>
          </listitem>
        </itemizedlist>

        <para>When we click the button <guibutton>Mark</guibutton>, the
        correction is made (this can take some time if we also asked for the
        reading of the scale).</para>
      </sect3>

      <sect3 id="bareme">
        <title id="bareme.title">Scoring strategy</title>

        <para>The strategy used to score the copies is indicated in the LaTeX
        source file, with the command <command>scoring</command>. It can be
        used in an environment <command>question</command> or
        <command>questionmult</command>, to set it for every response, but
        also in the environment <command>choices</command>, to give scaling
        indications about a single response. The argument of the LaTeX command
        scoring is made of indications like
        <code><replaceable>parameter</replaceable>=<replaceable>value</replaceable></code>,
        separated by comas. The usable parameters are the following (the table
        shows also in which context those parameters can be used):</para>

        <informaltable>
          <tgroup cols="6">
            <colspec align="center" colname="param" colwidth="3pc"/>

            <colspec align="center" colname="q" colwidth="1pc"/>

            <colspec align="center" colname="r" colwidth="1pc"/>

            <colspec align="center" colname="qm" colwidth="1pc"/>

            <colspec align="center" colname="rm" colwidth="1pc"/>

            <colspec align="left" colname="valeur"/>

            <spanspec nameend="r" namest="q" spanname="simple"/>

            <spanspec nameend="rm" namest="qm" spanname="multiple"/>

            <tbody>
              <row>
                <entry morerows="1">parameter</entry>

                <entry spanname="simple">simple</entry>

                <entry spanname="multiple">multiple</entry>

                <entry morerows="1">value</entry>
              </row>

              <row>
                <entry>Q</entry>

                <entry>A</entry>

                <entry>Q</entry>

                <entry>A</entry>
              </row>

              <row>
                <entry>e</entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>The score given when responses are incoherent: many
                boxes checked for a simple question, or, for a multiple
                question, the box "none of the responses are correct" checked
                while another box is also checked.</entry>
              </row>

              <row>
                <entry>v</entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>The score given in case of no response (no box is
                checked).</entry>
              </row>

              <row>
                <entry>d</entry>

                <entry/>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>An offset, i.e. a value added to every score not
                relevant of parameters e and v.</entry>
              </row>

              <row>
                <entry>p</entry>

                <entry/>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>The bottom score. If the calculation of the score in
                that question yields a value below the bottom value, the sore
                is set to the bottom value.</entry>
              </row>

              <row>
                <entry>b</entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry>●</entry>

                <entry>Score for a good response to a question.</entry>
              </row>

              <row>
                <entry>m</entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry>●</entry>

                <entry>Score for a bad response to a question.</entry>
              </row>

              <row>
                <entry/>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry/>

                <entry>Without parameter name (syntax:
                <code>\scoring{2}</code>), this indicates the score to give if
                the student has checked <emphasis>this</emphasis>
                response.</entry>
              </row>

              <row>
                <entry>auto</entry>

                <entry>●</entry>

                <entry/>

                <entry/>

                <entry/>

                <entry>With this parameter, the value of the response numbered
                <replaceable>i</replaceable> will be
                <replaceable>auto</replaceable>+<replaceable>i</replaceable>-1.
                This option is mainly used with
                <code>\QuestionIndicative</code> (see section <xref
                endterm="latex.qr.title" linkend="latex.qr"/>).</entry>
              </row>

              <row>
                <entry>mz</entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>This parameter is used for a "maximum or zero" scoring:
                if all the answers are correct, the score is
                <replaceable>mz</replaceable>. If not, the score is
                zero.</entry>
              </row>

              <row>
                <entry>haut</entry>

                <entry/>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>When you give this parameter a value
                <replaceable>n</replaceable>, the score given for a perfect
                response will be <replaceable>n</replaceable>, and one point
                will be withdrawn for each error.</entry>
              </row>

              <row>
                <entry>MAX</entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>Gives the maximal value given for the question (for a
                "question scored 5", one can write MAX=5). To be used only
                when it is not the same value as when one replies every good
                response.</entry>
              </row>

              <row>
                <entry>formula</entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>Gives the score to be given for the question, often
                using a formula that uses some variables (see <xref
                linkend="scoring.global"/>), without taking <code>b</code> and
                <code>m</code> values into account.</entry>
              </row>

              <row>
                <entry>set.<replaceable>XXX</replaceable></entry>

                <entry>●</entry>

                <entry>●</entry>

                <entry>●</entry>

                <entry>●</entry>

                <entry>Gives a particular value to the variable named
                <replaceable>XXX</replaceable>, that will be available in a
                <code>formula</code>. In an answer context, the value is
                associated to the variable only if the box is ticked. As a
                particular case, give a non-null value to the variable
                <varname>INVALID</varname> to declare the responses incoherent
                (so that the score will be given by the variable
                <code>e</code>).</entry>
              </row>

              <row>
                <entry>setglobal.<replaceable>XXX</replaceable></entry>

                <entry>●</entry>

                <entry>●</entry>

                <entry>●</entry>

                <entry>●</entry>

                <entry>Gives a value to the variable
                <replaceable>XXX</replaceable> for all following questions
                (relative to the lexicographic order of IDs)</entry>
              </row>

              <row>
                <entry>default.<replaceable>XXX</replaceable></entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>Gives a value to the variable
                <replaceable>XXX</replaceable> in the case when no ticked
                boxes gave a value to <replaceable>XXX</replaceable>.</entry>
              </row>

              <row>
                <entry>requires.<replaceable>XXX</replaceable></entry>

                <entry>●</entry>

                <entry/>

                <entry>●</entry>

                <entry/>

                <entry>Tells that the variable <replaceable>XXX</replaceable>
                has to be defined, unless the data is told
                <emphasis>incoherent</emphasis> and the question scored with
                the value of <code>e</code>.</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>

        <note>
          <para>haut=x has been written as d=x-N, p=0</para>
        </note>

        <important>
          <para>If you use the parameter <code>default</code>, you have to
          type the variable's value <replaceable>XXX</replaceable> inside the
          scoring of the question, see below.</para>
        </important>

        <programlisting>\begin{questionmult}{03}\scoring{default.COMP=10,default.PROP=11,formula=(COMP==PROP ? 1 : 0),MAX=1}
  Name an important gas in the air and its percentage.
  \begin{multicols}{4}
    \begin{choices}
      \wrongchoice{steam}
      \wrongchoice{gas}
      \correctchoice{nitrogen}\scoring{set.COMP=1}
      \correctchoice{oxygen}\scoring{set.COMP=2}
      \wrongchoice{carbon dioxide}
      \correctchoice{20\%}\scoringset.PROP=2}
      \wrongchoice{40\%}
      \wrongchoice{60\%}
      \correctchoice{80\%}\scoring{set.PROP=1}
    \end{choices}
  \end{multicols}
\end{questionmult}</programlisting>

        <note>
          <para>If you specify <code>MAX = 3</code> to a matter that report 4
          points, a student will have a score of 4/3 in this question</para>
        </note>

        <para>The default scale for a simple question is
        <code>e=0,v=0,b=1,m=0</code>, which gives one point for a good
        response and no point in the other cases. The default scaling for a
        multiple question is <code>e=0,v=0,b=1,m=0,p=-100,d=0</code>, which
        gives a point for every checked box, either good or not (good box
        checked or wrong box not checked).</para>

        <note>
          <para>You may assign the value <code>set.XXX</code> to the variables
          b and m.</para>
        </note>

        <para>The LaTeX command <command>\scoring</command> can also be used
        outside question definitions, for whole examination parameters:</para>

        <itemizedlist>
          <listitem>
            <para><code>SUF=</code><replaceable>x</replaceable> gives a total
            number of points sufficient to get the maximal mark. For example,
            with 10 for the maximal mark and parameter <code>SUF=8</code>, a
            student getting a total of 6 points will get mark 6/8*10=7.5,
            whatever the value of the total number of points for a perfect
            answer sheet.</para>
          </listitem>

          <listitem>
            <para><code>allowempty=<replaceable>x</replaceable></code> allows
            the student to leave <replaceable>x</replaceable> questions
            unanswered. When summing up questions scores,
            <replaceable>x</replaceable> unanswered questions will be
            canceled.</para>
          </listitem>
        </itemizedlist>

        <para>Using all of these parameters in combination allows to define
        many kinds of scoring strategies, as in the following example:</para>

        <para><!--NAME: Scoring strategy
DESC: Example (from the documentation) with different scoring strategies.--><programlisting
        id="modeles-scoring.tex" linenumbering="numbered">\documentclass{article}

\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[box,completemulti]{automultiplechoice}

\begin{document}

\element{qqs}{
\begin{question}{good choice}
  How many points would you like for this question?
  \begin{choices}
    \correctchoice{Maximum: 10}\scoring{10}
    \wrongchoice{Only 5}\scoring{5}
    \wrongchoice{Two will be enough}\scoring{2}
    \wrongchoice{None, thanks}\scoring{0}
  \end{choices}
\end{question}
}

\element{qqs}{
\begin{questionmult}{added}
  Get free points checking the following boxes:
  \begin{choices}
    \correctchoice{2 points}\scoring{b=2}
    \wrongchoice{One negative point!}\scoring{b=0,m=-1}
    \correctchoice{3 points}\scoring{b=3}
    \correctchoice{1 point}
    \correctchoice{Half point}\scoring{b=0.5}
  \end{choices}
\end{questionmult}
}

\element{qqs}{
\begin{questionmult}{3 or zero}\scoring{mz=3}
  Only a perfect response will be scored 3 points - otherwise, null score.
  \begin{choices}
    \wrongchoice{Wrong}
    \wrongchoice{Wrong}
    \correctchoice{Right}
    \correctchoice{Right}
  \end{choices}
\end{questionmult}
}

\element{qqs}{
\begin{questionmult}{all for 2}\scoring{haut=2}
  Perfect response scored 2 points, and give back one point for any error...
  \begin{choices}
    \correctchoice{Right}
    \correctchoice{This one is OK}
    \correctchoice{Yes!}
    \wrongchoice{False!}
    \wrongchoice{Don't check!}
  \end{choices}
\end{questionmult}
}

\element{qqs}{
\begin{question}{attention}\scoring{b=2}
  Some very bad answer yields here to a negative score (-2), but the correct answer is rewarded 2 points.
  \begin{choices}
    \correctchoice{Good!}
    \wrongchoice{Not correct}
    \wrongchoice{Not correct}
    \wrongchoice{Not correct}
    \wrongchoice{Very bad answer!}\scoring{-2}
  \end{choices}
\end{question}
}

\element{qqs}{
\begin{questionmult}{as you like}
  Choose how much points you need:
  \begin{choices}
    \correctchoice{You take two points here}\scoring{b=2}
    \wrongchoice{Check to give 3 points}\scoring{b=0,m=3}
    \correctchoice{Get one if checked, but give one if not}\scoring{m=-1}
  \end{choices}
\end{questionmult}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\onecopy{20}{

\noindent{\bf QCM  \hfill Scoring strategy test}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
\centering\large\bf Test\\ Jan. 2008\end{minipage}
\namefield{\fbox{\begin{minipage}{.5\linewidth}
Name:

\vspace*{.5cm}\dotfill
\vspace*{1mm}
\end{minipage}}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\shufflegroup{qqs}

\insertgroup{qqs}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

}

\end{document}</programlisting></para>
      </sect3>

      <sect3 id="scoring.global">
        <title>Global scoring strategy</title>

        <para>To use a strategy globally for a set of questions, one can
        define it in a LaTeX command, as in the following example:</para>

        <programlisting>\def\barQmult{haut=3,p=-1}

\begin{questionmult}\scoring{\barQmult}
  [...]
\end{questionmult}</programlisting>

        <para>Another possibility comes with the LaTeX commands
        <command>\scoringDefaultS</command> and
        <command>\scoringDefaultM</command>, to be used in the begin of the
        document (outside the command <command>\onecopy</command>), which
        allow to give default values for the scoring strategy of simple and
        multiple questions:</para>

        <programlisting>\scoringDefaultM{haut=3,p=-1}</programlisting>

        <para>If you use <command>formula</command> with
        <command>\scoringDefautM</command> or
        <command>\scoringDefautS</command>, you must cancel it to score
        different questions with a specific scoring.</para>

        <programlisting>\begin{questionmult}\scoring{b=1,m=-0.5,formula=}
  [...]
\end{questionmult}</programlisting>

        <para>In some cases, defining a global strategy can be interesting
        <emphasis>depending of the number of proposed responses</emphasis>. To
        do so, just input the value <varname>N</varname>. For example, to get
        a scale yielding 4 as the maximal score and such as the mean expected
        score of a student checking randomly the boxes is 1, one can use the
        scale <code>d=4,b=0,m=-(4-1)*2/N</code> (which give the score -2 if
        every response is false, i.e. the wrong boxes have been checked and
        the right boxes are not). Operations allowed in those formulas are the
        four simple operations (<code>+</code> <code>-</code> <code>*</code>
        <code>/</code>), test operator <code>( ? : )</code>, parenthesis and
        all perl operators.</para>

        <note>
          <para>The test operator is written<programlisting>( test ? if true: if false)</programlisting></para>

          <para>The test part can use operators like <code>&gt;</code>
          (greater), <code>&gt;=</code> (greater or equal), <code>&lt;</code>
          (lesser), <code>&lt;=</code> (lesser or equal), <code>==</code>
          (equal), <code>!=</code> (different), <code>||</code> (or),
          <code>&amp;&amp;</code> (and).</para>
        </note>

        <para>Other variables can also be used:</para>

        <itemizedlist>
          <listitem>
            <para><varname>N</varname> is the number of proposed responses,
            without counting the response eventually added by the option
            <option>completemulti</option>.</para>
          </listitem>

          <listitem>
            <para><varname>NB</varname> is the number of correct responses to
            the question (without taking in account checked or non-checked
            boxes).</para>
          </listitem>

          <listitem>
            <para><varname>NBC</varname> is the count of correct responses
            which have been checked.</para>
          </listitem>

          <listitem>
            <para><varname>NM</varname> is the number of wrong responses to
            the question (without taking in account checked or non-checked
            boxes).</para>
          </listitem>

          <listitem>
            <para><varname>NMC</varname> is the count of wrong responses which
            have been checked.</para>
          </listitem>

          <listitem>
            <para><varname>IS</varname> is set to 1 if the question is simple
            and 0 if not.</para>
          </listitem>

          <listitem>
            <para><varname>IMULT</varname> is set to 1 if the question is
            multiple and 0 if not.</para>
          </listitem>
        </itemizedlist>
      </sect3>

      <sect3 id="scoring-result">
        <title>From scoring strategy to students marks</title>

        <para>Here is how students' marks are computed: for every
        student,</para>

        <orderedlist>
          <listitem>
            <para>The scoring strategy is applied for each question in turn,
            to get the <emphasis>questions scores</emphasis>.</para>
          </listitem>

          <listitem>
            <para>All questions (except indicative ones) scores are added to
            get the student <emphasis>total score</emphasis>.</para>
          </listitem>

          <listitem>
            <para>If a positive <emphasis>maximal mark</emphasis> is given as
            a parameter (in the <guilabel>Project</guilabel> tab of the
            <menuchoice>
                <guimenu>Edit</guimenu>

                <guimenuitem>Preferences</guimenuitem>
              </menuchoice> window), the total score of the student is divided
            by the <emphasis>maximum total score</emphasis> (which is the
            total score for a perfect copy), and multiplied by the difference
            (<emphasis>maximal mark</emphasis> - <emphasis>minimal
            mark</emphasis>), then added to the <emphasis>minimal
            mark</emphasis> to get the student's <emphasis>mark</emphasis>.
            This way, if the student answered perfectly to all questions, his
            mark will be the maximum mark, and a student with null score will
            get the <emphasis>minimal mark</emphasis>. If you set the
            <emphasis>maximal mark</emphasis> to 100 and the <emphasis>minimal
            mark</emphasis> to 0, the student's mark can be seen as a
            percentage of good answers.</para>
          </listitem>

          <listitem>
            <para>This mark is rounded using the following settings from
            <menuchoice>
                <guimenu>Edit</guimenu>

                <guisubmenu>Preferences</guisubmenu>

                <guimenuitem>Project</guimenuitem>
              </menuchoice>:</para>

            <itemizedlist>
              <listitem>
                <para>Grain: set it to 1 if you need an integer value, set it
                to 0.25 if you need to round up to a quarter, etc. Set it to 0
                if you want to cancel rounding.</para>
              </listitem>

              <listitem>
                <para>Rounding type: lower, normal, greater</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </orderedlist>
      </sect3>

      <sect3 id="correc.test">
        <title>Correct the scoring errors</title>

        <para>You may, even after the test, change the scoring. However, you
        must not <emphasis>never</emphasis> update the document. It is better
        to open the file with a text editor to make changes and save
        it.</para>

        <para>You may :</para>

        <itemizedlist>
          <listitem>
            <para>turn correct answer into wrong answers.</para>
          </listitem>

          <listitem>
            <para>turn wrong answer into correct answers.</para>
          </listitem>

          <listitem>
            <para>Modify the scoring scale for one or several question or the
            default scoring.</para>
          </listitem>
        </itemizedlist>

        <para>You can not :</para>

        <itemizedlist>
          <listitem>
            <para>Turn a simple question into a multiple choices
            question.</para>
          </listitem>

          <listitem>
            <para>Turn a multiple choices question into a simple
            question.</para>
          </listitem>

          <listitem>
            <para>Add questions, answers.</para>
          </listitem>

          <listitem>
            <para>Remove questions, answers.</para>
          </listitem>

          <listitem>
            <para>Modify the order of the questions and/or answers.</para>
          </listitem>
        </itemizedlist>

        <note>
          <para>If you want to cancel a question use this strategy
          <command>\scoring{b=0,m=0,e=0,v=0}</command> or this one
          <command>\QuestionIndicative</command>.</para>
        </note>
      </sect3>
    </sect2>

    <sect2 id="sec.students.id">
      <title>Identification of the students</title>

      <para>This stage is not mandatory. It deals with associating each copy
      with a student. The name of the student is not read in an automated
      fashion, but two reasonable possibilities are proposed:</para>

      <orderedlist>
        <listitem>
          <para>It is possible to ask students to identify themselves on their
          copy with their student number, which will be written by checking
          one box per digit. A LaTeX command is designed to use this method on
          the copy (see the part <xref linkend="latex.codes"/>). After the
          exam, copies will be identified automatically taking into account a
          list matching the students' numbers and their names.</para>
        </listitem>

        <listitem>
          <para>With no input of the students' numbers, or in the case when
          the automated identification has not succeeded perfectly (for
          example when a student made a wrong input), the graphical interface
          allows an assisted manual association.</para>
        </listitem>
      </orderedlist>

      <para>Let's first move to the <guilabel>Marking</guilabel> tab of the
      graphical interface.</para>

      <sect3 id="liste.etudiants">
        <title id="liste.etudiants.title">List of the students</title>

        <para>We must previously supply a list of students. This list can
        obviously be used for many multiple-choices tests. This list is a CSV
        file with optional comments lines at the beginning with prefix
        `<code>#</code>', as in the following example:<programlisting># STUDENTS / 1ST YEAR
surname:name:id:email
Bienvenüe:Alexis:001:paamc@passoire.fr
Boulix:Jojo:002:jojo.boulix@rien.xx
Noël:Père:003:pere.noel@pole-nord.xx</programlisting></para>

        <para>The first lines of the file which begin with the character
        `<code>#'</code> are comments. The first of the other lines contains
        (separated by the character <code>`:'</code>) the column titles. Then,
        with one line per student, we write the corresponding information.
        There must be at least one column named <code>name</code> or
        <code>surname</code>.</para>

        <note>
          <para>One can replace the separator <code>`:'</code> by a comma, a
          semicolon or a tabulation. However the same separator must be used
          everywhere in the file which contains the list of students. The used
          separator is detected by taking the character (out of the four
          possible characters) which appears most frequently in the first line
          which is not a comment.</para>

          <para>Any CSV file should be suitable.</para>
        </note>

        <warning>
          <para>Type carefully the CSV file to send the same test to multiple
          recipients.</para>

          <itemizedlist>
            <listitem>
              <para>A semi-colon or colon or tabulation to separate the
              headers and a comma to separate the email adresses.</para>
            </listitem>

            <listitem>
              <para>A comma to separate the headers and email adresses between
              inverted comma/quotation marks.</para>
            </listitem>
          </itemizedlist>

          <programlisting>name,forenama,email
Boulix,Jojo,"jojo@boulix.fr,parents@boulix.com"       </programlisting>
        </warning>

        <para>The prepared list of students will then be selected with the
        button <guibutton>Set file</guibutton> in the <guilabel>Students
        identification</guilabel> section. We must also choose one of the
        columns as a unique key which will identify the students (generally,
        one chooses the column containing the student's number). Last, to
        prepare an automated association, we must choose the name of the
        relevant code used in the LaTeX command <command>\AMCcode</command>
        (if used).</para>
      </sect3>

      <sect3 id="gui.assoc">
        <title>Association</title>

        <sect4 id="gui.assoc.auto">
          <title>Automated association</title>

          <para>When we push the button <guibutton>Automatic</guibutton> in
          the part <guilabel>Students identification</guilabel>, matching of
          the codes given by the students begins. We can watch or improve the
          result later with a (partial) manual association.</para>

          <warning>
            <para>To make an automated association, at least one command
            <command>AMCcode</command> is required (see <xref
            linkend="latex.codes"/>) in the LaTeX source file, as well as a
            list of students with a column containing a reference (generally a
            number of student) which will be identical to the input given in
            the boxes produced by the command
            <command>AMCcode</command>.</para>
          </warning>
        </sect4>

        <sect4 id="gui.assoc.manual">
          <title>Manual association</title>

          <para>To open the window allowing recognition of the students'
          names, let's click on <guibutton>Manual</guibutton> button in the
          <guilabel>Students identification</guilabel> section. This window is
          made of an upper part which presents in sequence images of the names
          written by the students, a lower part containing a button for each
          student from the list we supplied, and a right part allowing to
          browse easily the copies to be identified. Let's click the button
          matching the name written in the upper part for each presented page
          (by default, only the copies not or badly identified are presented -
          this can be changed by checking the box
          <guilabel>associated</guilabel>). When every page is read, a blue
          background appears instead of the names, and we just need to click
          the <guibutton>Save</guibutton> button to end with
          association.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2 id="sec.export.notes">
      <title id="sec.export.notes.title">Exporting the scores list</title>

      <para>At this stage, we can get the list of scores under various formats
      (currently CSV and OpenOffice), with the button
      <guibutton>Export</guibutton>. This export will be followed by the
      opening of the produced file by the appropriate software (if
      available).</para>

      <sect3 id="gui.export.ods">
        <title>Export to ODS (OpenOffice, LibreOffice)</title>

        <para>In the exported file, the following colors are used:</para>

        <variablelist>
          <varlistentry>
            <term>gray</term>

            <listitem>
              <para>is used for <emphasis>non applicable</emphasis>. This may
              be for example scores for absentees, or scores corresponding to
              a question that was not shown to the corresponding
              student.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>yellow</term>

            <listitem>
              <para>is used for questions that has not been answered by the
              student.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>red</term>

            <listitem>
              <para>is used for questions with an <emphasis>invalid</emphasis>
              answer: the student ticked several boxes in a simple question,
              or he ticked some boxes <emphasis>and</emphasis> the box
              <emphasis>None of these answers are correct</emphasis>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>purple</term>

            <listitem>
              <para>used for indicative questions.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>
    </sect2>

    <sect2 id="gui.annotate">
      <title>Annotation</title>

      <para>When we push the button <guibutton>Annotate papers</guibutton>,
      copies annotation will begin: on every scan, the following annotations
      will be made (these are the default annotations, they can be
      configured):</para>

      <itemizedlist>
        <listitem>
          <para>The boxes wrongly checked by the student will be circled in
          red;</para>
        </listitem>

        <listitem>
          <para>the non-checked boxes which should have been are checked in
          red;</para>
        </listitem>

        <listitem>
          <para>the checked boxes which had to be checked are checked in
          blue;</para>
        </listitem>

        <listitem>
          <para>for each question, obtained and maximal scores are
          indicated;</para>
        </listitem>

        <listitem>
          <para>the global score of the copy is indicated on the first page of
          the copy.</para>
        </listitem>
      </itemizedlist>

      <para>The text written on the first page of the copies can be configured
      (<menuchoice>
          <guimenu>Edit</guimenu>

          <guimenuitem>Preferences</guimenuitem>

          <guimenuitem>Annotation</guimenuitem>

          <guimenuitem>Header</guimenuitem>
        </menuchoice> or <menuchoice>
          <guimenu>Edit</guimenu>

          <guimenuitem>Preferences</guimenuitem>

          <guimenuitem>Project</guimenuitem>

          <guimenuitem>Papers annotation</guimenuitem>

          <guimenuitem>Header text</guimenuitem>
        </menuchoice>). Substitutions will be made within the provided text
      (please have a look at <xref linkend="scoring-result"/> for some details
      on the meaning of those values):</para>

      <variablelist>
        <varlistentry>
          <term><literal>%S</literal></term>

          <listitem>
            <para>is replaced by the student's <emphasis>total
            score</emphasis>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>%M</literal></term>

          <listitem>
            <para>is replaced by the <emphasis>maximum total
            score</emphasis>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>%s</literal></term>

          <listitem>
            <para>is replaced by the student's
            <emphasis>mark</emphasis>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>%m</literal></term>

          <listitem>
            <para>is replaced by the <emphasis>maximum mark</emphasis>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>%(ID)</literal></term>

          <listitem>
            <para>is replaced by the student's name.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>%(<replaceable>COL</replaceable>)</literal></term>

          <listitem>
            <para>is replaced by the value of column
            <replaceable>COL</replaceable> in the students list for the
            current student.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>This operation is made for each page, giving as a result PDF
      annotated papers. The name of the PDF file which will contain the
      corrected copy of a student is based on the template indicated in the
      field <guilabel>File name model</guilabel>. In that template, every
      substring as « (<replaceable>col</replaceable>) » is replaced by the
      contents of the column named <code><replaceable>col</replaceable></code>
      in the file containing the list of students (see section <xref
      endterm="liste.etudiants.title" linkend="liste.etudiants"/>). If we let
      this field empty, a default value is built up based on the student's
      name and student number.</para>

      <sect3 id="Options.annotation.separateanswersheet">
        <title id="Options.annotation.separateanswersheet.title">Options with
        the option <option>separateanswersheet</option></title>

        <itemizedlist>
          <listitem>
            <para><command>Only pages with answers</command> : the answer
            sheets will be annoted.</para>
          </listitem>
        </itemizedlist>

        <itemizedlist>
          <listitem>
            <para><command>Question pages from subject</command> : the answer
            sheets will be annoted and the subject will be inclued to the pdf
            file.</para>
          </listitem>
        </itemizedlist>

        <itemizedlist>
          <listitem>
            <para><command>Question pages from correction</command> : the
            answer sheets will be annoted and the corrected will be inclued to
            the pdf fil.</para>
          </listitem>
        </itemizedlist>
      </sect3>

      <sect3 id="marks.position">
        <title id="marks.position.title">Marks' position</title>

        <para>You may choose marks's position with the menu <menuchoice>
            <guimenu>Edit</guimenu>

            <guimenuitem>Preference</guimenuitem>

            <guimenuitem>Project</guimenuitem>

            <guimenuitem>Marks position</guimenuitem>
          </menuchoice></para>

        <para>Default choices</para>

        <itemizedlist>
          <listitem>
            <para>(none)</para>
          </listitem>

          <listitem>
            <para>In the margin.</para>
          </listitem>

          <listitem>
            <para>In the both margins</para>
          </listitem>

          <listitem>
            <para>Beside the boxes.</para>
          </listitem>

          <listitem>
            <para>Where defined in the source (see <xref
            endterm="marks.display.area.title" linkend="marks.display.area"/>
            ).</para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>

    <sect2 id="preferences.defaut">
      <title id="preferences.defaut.title">Default values edit menu</title>

      <para><menuchoice>
          <guimenuitem>Edit</guimenuitem>

          <guimenuitem>Preferences</guimenuitem>

          <guimenuitem>Scan</guimenuitem>
        </menuchoice></para>

      <para><command>Scans conversion</command></para>

      <itemizedlist>
        <listitem>
          <para>Vector formats density (DPI) : 250</para>
        </listitem>

        <listitem>
          <para>Black &amp; white conversion threshold : 0.60</para>
        </listitem>

        <listitem>
          <para>Erase red from scans : unticked</para>
        </listitem>

        <listitem>
          <para>Force conversion: unticked</para>
        </listitem>
      </itemizedlist>

      <para><command>Detection parameters</command></para>

      <itemizedlist>
        <listitem>
          <para>Marks size max increase: 0.20</para>
        </listitem>

        <listitem>
          <para>Marks size max decrease : 0.20</para>
        </listitem>

        <listitem>
          <para>Default darkness threshold : 0.15</para>
        </listitem>

        <listitem>
          <para>Default upper darkness threshold : 1</para>
        </listitem>

        <listitem>
          <para>Measured box proportion: 0.80</para>
        </listitem>

        <listitem>
          <para>Process scans with 3 corner marks : unticked</para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="alt">
    <title>Alternative usages</title>

    <sect2 id="alt.photocopy">
      <title>Photocopied subject</title>

      <para>As explained in <xref endterm="printing.title"
      linkend="printing"/>, it is not always possible to photocopy one answer
      sheet to give to several students. However, when using a separate answer
      sheet and when questions and answers are not to be shuffled, you can
      photocopy the subject, and print all the answer sheets separately. We
      detail here the proper way to follow.</para>

      <itemizedlist>
        <listitem>
          <para>Use <option>separateanswersheet</option> package option (see
          <xref endterm="sec.package.options.title"
          linkend="sec.package.options"/>).</para>
        </listitem>

        <listitem>
          <para>Write the subject before calling <command>onecopy</command>
          command or outside <command>examcopy</command> environment.</para>
        </listitem>

        <listitem>
          <para>Use <command>\AMCformS</command> to output answer boxes in
          each answer sheet, inside
          <command>onecopy</command>/<command>examcopy</command>.</para>
        </listitem>
      </itemizedlist>

      <para>Here is a minimal example:</para>

      <programlisting>\documentclass[a4paper]{article}
\usepackage[separateanswersheet]{automultiplechoice}
\begin{document}

\noindent{\bf Subject}

\begin{question}{sum}
  How much are one plus one?
  \begin{choices}
    \wrongchoice{1}
    \correctchoice{2}
    \wrongchoice{3}
  \end{choices}
\end{question}

\begin{question}{k2}
  How high is the K2?
  \begin{choices}
    \wrongchoice{around 8000m}
    \correctchoice{around 8600m}
    \wrongchoice{around 9000m}
  \end{choices}
\end{question}

\AMCcleardoublepage

\onecopy{5}{

\AMCformBegin

{\large\bf Answer sheet:}
\hfill \namefield{\fbox{
    \begin{minipage}{.5\linewidth}
      Name:

      \vspace*{.5cm}\dotfill
      \vspace*{1mm}
    \end{minipage}
  }}

\AMCformS

}

\end{document}
</programlisting>

      <para>You will get from this LaTeX file one subject (sheet numbered 0)
      to print and photocopy to all students, and several answer sheets to
      print (one for each student).</para>
    </sect2>

    <sect2 id="postcorrect">
      <title>Post correcting</title>

      <para>Suppose you want to use a single generic answer sheet for all your
      exams. You simply print answer boxes on it (say 5 for each questions,
      and 40 questions), and give the students a subject that you wrote
      somewhere else. The point here is that the correct choices are not
      pointed out in the LaTeX file, so that AMC does not know about them. The
      solution is to give one answer sheet to the teacher to fill correct
      choices. Then, after scanning and AMC analysis, you simply have to tell
      AMC which is the teacher completed answer sheet.</para>

      <para>To implement this idea, follow these rules:</para>

      <itemizedlist>
        <listitem>
          <para>Use <option>postcorrect</option>, <option>insidebox</option>
          and <option>noshuffle</option> package options (see <xref
          endterm="sec.package.options.title"
          linkend="sec.package.options"/>).</para>
        </listitem>

        <listitem>
          <para>Only use <command>\wrongchoice</command> for all your choices
          (never <command>\correctchoice</command>).</para>
        </listitem>
      </itemizedlist>

      <para>Here is a minimal example:</para>

      <programlisting>\documentclass[a4paper]{article}
\usepackage{multicol}
\usepackage[insidebox,noshuffle,postcorrect]{automultiplechoice}

\begin{document}

\onecopy{5}{

\noindent
\begin{tabular}{|l|l|l|}
\hline
student number &amp; class &amp; subject\\
\hline
 \vspace{-0.25cm}
 &amp; &amp;\\
\AMCcode{StudentNum}{10}&amp;
\AMCcode{class}{2}&amp;
\AMCcode{subject}{3}
\\
\hline
\end{tabular}
\hfill\namefield{\fbox{
    \begin{minipage}{.25\linewidth}
      Name:

      \vspace*{.5cm}\dotfill

      \vspace*{.5cm}\dotfill
      \vspace*{1mm}
    \end{minipage}
  }}\hfill


\vspace{.5cm}
\noindent\hrulefill

\begin{multicols}{2}\columnseprule=.4pt

\begin{question}{01}
\begin{choicescustom}
\wrongchoice{}%
\wrongchoice{}%
\wrongchoice{}%
\wrongchoice{}%
\wrongchoice{}%
\end{choicescustom}
\end{question}

\begin{question}{02}
\begin{choicescustom}
\wrongchoice{}%
\wrongchoice{}%
\wrongchoice{}%
\wrongchoice{}%
\wrongchoice{}%
\end{choicescustom}
\end{question}

% continue here to get as many questions as needed...

\end{multicols}

}

\end{document}
</programlisting>

      <para>You can then process the LaTeX file in AMC, print the sheets, scan
      them after the exam, and start AMC automatic data capture (including the
      teacher sheet). When you click on <guibutton>Mark</guibutton> in the
      <guilabel>Marking</guilabel> tab, letting <guilabel>Update marking
      scale</guilabel> ticked, you will be prompted for the teacher answer
      sheet number. You can then continue as usual.</para>

      <note>
        <para>You can also write the letters outside the boxes: replace the
        <option>insidebox</option> option with <option>outsidebox</option>,
        and write your questions in the following way:</para>

        <programlisting>\begin{question}{01}
  \begin{choicescustom}
    \wrongchoice{A }%
    \wrongchoice{B }%
    \wrongchoice{C }%
    \wrongchoice{D }%
    \wrongchoice{E }%
  \end{choicescustom}
\end{question}</programlisting>
      </note>

      <note>
        <para>To use this option only for the questions answers (and not for
        the student number), type, just after <code>\begin{document}</code>
        <programlisting>\makeatletter
\def\setoutsidebox{\AMC@outside@boxtrue}
\makeatother</programlisting></para>

        <para>Then, use this command locally (inside braces) in the form
        :</para>

        <programlisting>{\setoutsidebox\AMCform}</programlisting>
      </note>
    </sect2>

    <sect2 id="Nominative.sheets">
      <title id="Nominative.sheets.title">Nominative sheets</title>

      <para>In some situations, it can be useful to prepare nominative sheets
      for all students, from a list of students. Let us see how this can be
      done.</para>

      <itemizedlist>
        <listitem>
          <para>The students list has to be a CSV list. Suppose in the
          following that the file students.csv, in the project directory, is
          UTF8 encoded and that its content is like the following:</para>

          <programlisting>name,forename,id
Boulix,Jojo,001
Golin,André,002
Moniuszko,Stanisław,003</programlisting>

          <warning>
            <para>Do not use _ (underscore) with the student's name or
            forename. A compilation error will be displayed.</para>
          </warning>
        </listitem>

        <listitem>
          <para>The LaTeX source file has to load csvsimple package,
          with:</para>

          <programlisting>\usepackage{csvsimple}</programlisting>
        </listitem>

        <listitem>
          <para>In the LaTeX source file, define the subject as a command that
          produce a single subject. This command will be called once for each
          student by <command>\csvreader</command> (suppose here that the
          questions has already be defined and included in a group named
          <code>general</code>):</para>

          <programlisting>\newcommand{\subject}{
  \onecopy{1}{

    \noindent{\bf AutoMultipleChoice  \hfill TEST}

    \vspace*{.5cm}

    \begin{center}\em
      Pre-filled test.
    \end{center}

    \hfill \namefield{\fbox{
        \begin{minipage}{.5\linewidth}
          Name:

          \Large\bf \name{} \surname{}

          \vspace*{1mm}
        \end{minipage}
      }}

    \noindent\hrulefill

    \vspace{1ex}

    \shufflegroup{general}
    \insertgroup{general}

    \AMCassociation{\id}
  }
}

\csvreader[head to column names]{students.csv}{}{\subject}<co
              id="separator.comma" linkends="separator.comma.exp"/>
%\csvreader[head to column names,separator=semicolon]{liste.csv}{}{\subject}<co
              id="separator.semicolon" linkends="separator.semicolon.exp"/>

</programlisting>

          <para>The head to column names option for
          <command>\csvreader</command> defines commands
          <command>\name</command>, <command>\surname</command> and
          <command>\id</command> (named from the CSV headers), that can be
          used inside <command>\subject</command>. The
          <command>\AMCassociation</command> call tells AMC to associate the
          current sheet to student with id <command>\id</command>.</para>

          <para><calloutlist>
              <callout arearefs="separator.comma" id="separator.comma.exp">
                <para>Use this command if the CSV file contains only one email
                address per student.</para>
              </callout>

              <callout arearefs="separator.semicolon"
                       id="separator.semicolon.exp">
                <para>Use this command if the CSV file contains multiple email
                addresses per student.</para>
              </callout>
            </calloutlist></para>
        </listitem>

        <listitem>
          <para>After printing, scanning, data capture and marking, when
          associating copies with students, choose value
          "<emphasis>pre-association</emphasis>" for field "code-name for
          automatic association", and "<emphasis>id</emphasis>" for field
          "Primary key".</para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="commands">
    <title>Commands manual</title>

    <para>You may skip this part if you want to use only the graphical user
    interface (and that should usually be the case). However, every action
    carried out with the graphical interface can also be performed using the
    various commands whose syntax is described here.</para>

    <refentry id="auto-multiple-choice">
      <refmeta>
        <refentrytitle>auto-multiple-choice</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>auto-multiple-choice</refname>

        <refpurpose>Automated treatment of MCQs</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain"><replaceable>action</replaceable></arg>

          <arg rep="repeat">arguments</arg>
        </cmdsynopsis>

        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg>project</arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>auto-multiple-choice</command> command transmits
        its arguments to the
        <command>AMC-<replaceable>action</replaceable>.pl</command>
        command.</para>

        <para>The second form, which does not mention any action, calls the
        graphical interface <command>AMC-gui.pl</command>, possibly with the
        name of a project to be opened.</para>
      </refsect1>

      <refsect1>
        <title>See also</title>

        <para>Different AMC actions: <citerefentry>
            <refentrytitle>AMC-prepare</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>, <citerefentry>
            <refentrytitle>AMC-imprime</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>, <citerefentry>
            <refentrytitle>AMC-analyse</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>, <citerefentry>
            <refentrytitle>AMC-note</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>, <citerefentry>
            <refentrytitle>AMC-association-auto</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>, <citerefentry>
            <refentrytitle>AMC-export</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>, <citerefentry>
            <refentrytitle>AMC-annotate</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>, <citerefentry>
            <refentrytitle>AMC-regroupe</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>.</para>
      </refsect1>
    </refentry>

    <refentry id="AMC-prepare">
      <refmeta>
        <refentrytitle>AMC-prepare</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-prepare</refname>

        <refpurpose>prepares working documents from LaTeX source
        file</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">prepare</arg>

          <arg choice="plain">--mode s</arg>

          <arg choice="plain">--prefix
          <replaceable>project-dir</replaceable></arg>

          <arg choice="plain"><replaceable>mcq-source-file</replaceable></arg>
        </cmdsynopsis>

        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">prepare</arg>

          <arg choice="plain">--mode b</arg>

          <arg choice="plain">--data
          <replaceable>project-data-dir</replaceable></arg>

          <arg choice="plain"><replaceable>mcq-source-file</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-prepare.pl</command> command extracts working
        documents from the source file describing the multiple choice
        questionnaire. Information to be extracted depends on the
        <option>--mode</option> argument value. In any mode, the source
        filename must be given as an argument.</para>

        <itemizedlist>
          <listitem>
            <para>with "<option>--mode s</option>",
            <command>AMC-prepare.pl</command> makes the subject file (answer
            sheet to be printed and given to the students), the correction
            (single corrected answer sheet) and the positions file (file
            containing information about the positions of the boxes on the
            pages). The following arguments can be used:</para>

            <variablelist>
              <varlistentry>
                <term><option>--out-sujet
                <replaceable>subject.pdf</replaceable></option></term>

                <listitem>
                  <para>sets the subject file to build.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>--out-corrige
                <replaceable>corrected.pdf</replaceable></option></term>

                <listitem>
                  <para>sets the correction to build.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>--out-calage
                <replaceable>calage.xy</replaceable></option></term>

                <listitem>
                  <para>sets the positions file to build.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>--prefix
                <replaceable>directory</replaceable></option></term>

                <listitem>
                  <para>this directory is only necessary if one or more of the
                  three previous options are not used: default values are then
                  <filename><replaceable>directory</replaceable>/sujet.pdf</filename>,
                  <filename><replaceable>directory</replaceable>/corrige.pdf</filename>
                  and
                  <filename><replaceable>directory</replaceable>/calage.xy</filename>.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>

          <listitem>
            <para>with "<option>--mode b</option>",
            <command>AMC-prepare.pl</command> extracts scoring data from the
            source file. In this mode, the <option>--data</option> argument
            must be used (see below).</para>
          </listitem>
        </itemizedlist>

        <para>The following optional arguments can be used in any mode:</para>

        <variablelist>
          <varlistentry>
            <term><option>--with
            <replaceable>latex-engine</replaceable></option></term>

            <listitem>
              <para>gives the LaTeX engine (command) to be used.
              <replaceable>latex-engine</replaceable> can be
              <command>pdflatex</command> or <command>xelatex</command> for
              example.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--filter
            <replaceable>filter</replaceable></option></term>

            <listitem>
              <para>sets the filter name to transform the MCQ source file into
              a LaTeX file. Native filters are <code>latex</code> (no change
              at all) and <code>plain</code> (source is an AMC-TXT
              file).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--filtered-source
            <replaceable>mcq-latex-file</replaceable></option></term>

            <listitem>
              <para>gives the LaTeX file to make from the source file using
              specified filter. If omitted, a filename derived from
              <replaceable>mcq-source-file</replaceable> adding
              <filename>_filtered.tex</filename> is used.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--n-copies
            <replaceable>n</replaceable></option></term>

            <listitem>
              <para>sets the number of copies to produce, overriding the
              number given in the LaTeX source file (first argument of the
              <command>\onecopy</command> command).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--debug
            <replaceable>file.log</replaceable></option></term>

            <listitem>
              <para>gives a file to fill with debugging information.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--epoch
            <replaceable>EPOCH</replaceable></option></term>

            <listitem>
              <para>gives an epoch (number of seconds since january 1, 1970)
              to get a reproducible pdf output.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--data
            <replaceable>project-data-dir</replaceable></option></term>

            <listitem>
              <para>sets the directory where the project's SQLite data files
              are.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
    </refentry>

    <refentry>
      <refmeta>
        <refentrytitle>AMC-meptex</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo>Auto Multiple Choice</refmiscinfo>

        <refmiscinfo>1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-meptex</refname>

        <refpurpose>gets the layout information from the working document to
        the layout database</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">meptex</arg>

          <arg choice="plain">--src <replaceable>calage.xy</replaceable></arg>

          <arg choice="plain">--data
          <replaceable>directory</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-meptex.pl</command> command extracts the layout
        information (exact positions of the boxes, the marks, the name field
        on all the pages) from a working document
        <replaceable>calage.xy</replaceable> and fills the layout database (a
        SQLite file) in the data directory
        <replaceable>directory</replaceable>.</para>
      </refsect1>
    </refentry>

    <refentry id="AMC-imprime">
      <refmeta>
        <refentrytitle>AMC-imprime</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-imprime</refname>

        <refpurpose>prints AMC multiple choice answer sheets to be distributed
        to the students</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">imprime</arg>

          <arg choice="plain">--sujet
          <replaceable>subject.pdf</replaceable></arg>

          <arg choice="plain">--fich-nums
          <replaceable>numbers-file.txt</replaceable></arg>

          <arg choice="plain">--data <replaceable>data-dir</replaceable></arg>

          <arg choice="plain">--methode
          <replaceable>method</replaceable></arg>

          <arg rep="repeat">where-to-print-arguments</arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-imprime.pl</command> command prints selected
        copies from a AMC multiple choice answer sheet.</para>

        <refsect2>
          <title>What to print</title>

          <para>The following arguments describe what to print:</para>

          <variablelist>
            <varlistentry>
              <term><option>--sujet
              <replaceable>subject.pdf</replaceable></option></term>

              <listitem>
                <para>sets the subject file (prepared by <citerefentry>
                    <refentrytitle>AMC-prepare</refentrytitle>

                    <manvolnum>1</manvolnum>
                  </citerefentry>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--fich-nums
              <replaceable>numbers-file.txt</replaceable></option></term>

              <listitem>
                <para>gives a file where the numbers of the copies to be
                printed are written (one number per line). If this argument is
                not given, all the copies will be printed.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--data
              <replaceable>data-dir</replaceable></option></term>

              <listitem>
                <para>gives the directory where data files are (see for
                example <citerefentry>
                    <refentrytitle>AMC-meptex</refentrytitle>

                    <manvolnum>1</manvolnum>
                  </citerefentry>). The layout database in the data directory
                is used to know at which page of the subject file each copy
                begins and ends.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--split</option></term>

              <listitem>
                <para>asks to print separate answer sheets separately.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--answer-first</option></term>

              <listitem>
                <para>asks to reorder the pages of each copy to get the
                separate answer sheet first.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>Where to print</title>

          <para>Several printing methods are currently defined:</para>

          <itemizedlist>
            <listitem>
              <para>with "<option>--methode CUPS</option>",
              <command>AMC-imprime.pl</command> prints to a CUPS printer. One
              print job is sent for each copy, allowing for example to use
              stapling. Use the following options with this method:</para>

              <variablelist>
                <varlistentry>
                  <term><option>--imprimante
                  <replaceable>printer</replaceable></option></term>

                  <listitem>
                    <para>sets the CUPS printer name to print to.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><option>--options
                  <replaceable>cups-options</replaceable></option></term>

                  <listitem>
                    <para>gives CUPS options, in the
                    <option>opt1=value1,opt2=value2,...</option>
                    format.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>

            <listitem>
              <para>with "<option>--methode file</option>",
              <command>AMC-imprime.pl</command> outputs the answer sheets to
              files (one for each copy).</para>

              <variablelist>
                <varlistentry>
                  <term><option>--output
                  <replaceable>filename</replaceable></option></term>

                  <listitem>
                    <para>sets the filename for outputs. The
                    '<literal>%e</literal>' sequence will be replaced by a
                    4-digits copy number. If
                    <replaceable>filename</replaceable> does not contain
                    '<literal>%e</literal>', the string
                    '<literal>-%e.pdf</literal>' will be added at its
                    end.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>

            <listitem>
              <para>with "<option>--methode command</option>",
              <command>AMC-imprime.pl</command> will use a provided command
              for each copy.</para>

              <variablelist>
                <varlistentry>
                  <term><option>--print-command
                  <replaceable>command</replaceable></option></term>

                  <listitem>
                    <para>gives the command to be used for printing. The
                    <replaceable>command</replaceable> string will be split at
                    each space character (even when using quotes...). The
                    sequence '<literal>%f</literal>' will be replaced by a PDF
                    filename (containing the copy to print), and
                    '<literal>%e</literal>' will be replaced by the copy
                    number.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </itemizedlist>
        </refsect2>

        <refsect2>
          <title>Other options</title>

          <para>Other available options:</para>

          <variablelist>
            <varlistentry>
              <term>--extract-with <replaceable>command</replaceable></term>

              <listitem>
                <para>gives the command to use to extract pages from the PDF
                subject. Currently, <command>pdftk</command>, <command>gs</command>
                and <command>qpdf</command> are available.
                The default value is <command>pdftk</command>,
                but <command>qpdf</command> and then <command>gs</command>
                will be used if the <command>pdftk</command> command is not
                installed.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>
      </refsect1>
    </refentry>

    <refentry>
      <refmeta>
        <refentrytitle>AMC-getimages</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-getimages</refname>

        <refpurpose>prepares scan images before sending them to <citerefentry>
            <refentrytitle>AMC-analyse</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry> for analysis</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">getimages</arg>

          <arg choice="opt">--copy-to
          <replaceable>project-scans-dir</replaceable></arg>

          <arg>--vector-density <replaceable>density</replaceable></arg>

          <arg choice="plain">--list
          <replaceable>list-file</replaceable></arg>

          <group>
            <arg choice="plain"
            rep="repeat"><replaceable>scan-files</replaceable></arg>
          </group>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-getimages.pl</command> command prepares scan
        files before sending them to <citerefentry>
            <refentrytitle>AMC-analyse</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>:</para>

        <itemizedlist>
          <listitem>
            <para>multipage image files are split to get one file per
            page.</para>
          </listitem>

          <listitem>
            <para>vector images (such as PDF, EPS) are converted to bitmap
            images.</para>
          </listitem>
        </itemizedlist>

        <para>The input images can be given either as arguments to
        AMC-getimages.pl, either as the name of a file which contains all the
        paths of the scan files.</para>

        <variablelist>
          <varlistentry>
            <term><option>--list
            <replaceable>list-file</replaceable></option></term>

            <listitem>
              <para>gives the name of the file that optionally contains (one
              per line) the paths of the scan files. This file will be cleared
              and filled with the paths of the scan files after processing, so
              that the same path can be passed to
              <command>AMC-analyse.pl</command> as the
              <option>--list-fichiers</option> option value.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--copy-to
            <replaceable>project-scans-dir</replaceable></option></term>

            <listitem>
              <para>gives a directory where to copy all the scans
              files.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--vector-density
            <replaceable>density</replaceable></option></term>

            <listitem>
              <para>sets the density used to convert vector graphics scans to
              bitmap files. Defaults to 300.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
    </refentry>

    <refentry id="AMC-analyse">
      <refmeta>
        <refentrytitle>AMC-analyse</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-analyse</refname>

        <refpurpose>automatic data capture from scans for AMC multiple choice
        exams.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">analyse</arg>

          <arg choice="plain">--projet
          <replaceable>project-dir</replaceable></arg>

          <arg>--seuil-coche <replaceable>threshold</replaceable></arg>

          <arg>--tol-marque <replaceable>tol</replaceable></arg>

          <group>
            <arg choice="plain">--list-fichiers
            <replaceable>files-list.txt</replaceable></arg>

            <arg choice="plain"
            rep="repeat"><replaceable>scan-files</replaceable></arg>
          </group>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-analyse.pl</command> command performs automatic
        data capture from scans of completed answer sheets of an AMC multiple
        choice questionnaire. Before calling
        <command>AMC-analyse.pl</command>, <citerefentry>
            <refentrytitle>AMC-prepare</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry> should have been called to make working documents
        (<option>--mode s</option>) and the layout should have been processed
        with <citerefentry>
            <refentrytitle>AMC-meptex</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>.</para>

        <variablelist>
          <varlistentry>
            <term><option>--data
            <replaceable>data-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where data files are (see for example
              <citerefentry>
                  <refentrytitle>AMC-meptex</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>). Defaults to
              <filename><replaceable>project-dir</replaceable>/data</filename>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--cr
            <replaceable>project-cr-dir</replaceable></option></term>

            <listitem>
              <para>gives a directory where to create image reports of the
              data capture (zooms on the boxes in a <filename>zooms</filename>
              sub-directory, name filed extraction as a
              <filename>name-*.jpg</filename> file, and layout report as a
              <filename>page-*.jpg</filename> file).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--projet
            <replaceable>project-dir</replaceable></option></term>

            <listitem>
              <para>When using this option, if <option>--cr</option> is not
              used, <replaceable>project-cr-dir</replaceable> will be set to
              <filename><replaceable>project-dir</replaceable>/cr</filename>.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Giving the names of the scan files to process can be done in two
        ways:</para>

        <itemizedlist>
          <listitem>
            <para>these names can be given as arguments,</para>
          </listitem>

          <listitem>
            <para>these names can be written to a plain file (one filename per
            line), using the <option>--list-fichiers
            <replaceable>files-list.txt</replaceable></option> to give the
            name of this file.</para>
          </listitem>
        </itemizedlist>

        <para>Some parameters for data capture may be set using the following
        options:</para>

        <variablelist>
          <varlistentry>
            <term><option>--prop
            <replaceable>proportion</replaceable></option></term>

            <listitem>
              <para>sets the proportion of each box that will be measured to
              decide if the box is ticked or not. Default value is 0.8.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--bw-threshold
            <replaceable>threshold</replaceable></option></term>

            <listitem>
              <para>This parameter is used when converting the grayscale scan
              file to black and white. To get more black pixels, use a greater
              value. To get more white pixels, use a smaller value. The
              threshold must be between 0 and 1. The default value is
              0.6.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--ignore-red</option></term>

            <listitem>
              <para>With this option, only red channel will be used from color
              scans. This way, all that is written in red will be ignored in
              the scan. This can be useful when the boxes are printed in
              red.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--tol-marque
            <replaceable>tol</replaceable></option></term>

            <listitem>
              <para>defines the tolerance when detecting the four marks in the
              scans corners. These marks are detected looking for black
              connected components which dimensions are
              <emphasis>closed</emphasis> to the target dimension
              <replaceable>target</replaceable> (exact dimensions of the marks
              if printing/scanning process where perfectly accurate). If
              <replaceable>tol</replaceable> is a real number, accepted
              dimensions are those between
              (1-<replaceable>tol</replaceable>)*<replaceable>target</replaceable>
              and
              (1+<replaceable>tol</replaceable>)*<replaceable>target</replaceable>.
              If <replaceable>tol</replaceable> is
              "<replaceable>tinf</replaceable>,<replaceable>tsup</replaceable>"
              (where <replaceable>tinf</replaceable> and
              <replaceable>tsup</replaceable> are real numbers), accepted
              dimensions are those between
              (1-<replaceable>tinf</replaceable>)*<replaceable>target</replaceable>
              and
              (1+<replaceable>tsup</replaceable>)*<replaceable>target</replaceable>.
              A standard value is 0.2.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--multiple</option></term>

            <listitem>
              <para>This option is to be used when the scans are photocopies
              from some subjects (different students can have the same
              subject). In this case, <emphasis>copy</emphasis> numbers are
              allocated to students so that their answer sheets, with the same
              subject number, can be differentiated.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--pre-allocate
            <replaceable>copy_id</replaceable></option></term>

            <listitem>
              <para>This option can be used in conjunction with
              <option>--multiple</option>. The copy numbers used for the scans
              will start from <replaceable>copy_id</replaceable>, in the same
              order than the scans given as arguments.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--try-three | --no-try-three</term>

            <listitem>
              <para>Use one of these options to tell if you allow processing
              of scans where only three corner marks are present.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--debug
            <replaceable>file.log</replaceable></option></term>

            <listitem>
              <para>gives a file to fill with debugging information.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
    </refentry>

    <refentry id="AMC-note">
      <refmeta>
        <refentrytitle>AMC-note</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-note</refname>

        <refpurpose>computes marks after scans data capture for AMC multiple
        choice exams.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">note</arg>

          <arg choice="plain">--data
          <replaceable>project-data-dir</replaceable></arg>

          <arg>--seuil <replaceable>threshold</replaceable></arg>

          <arg>--grain <replaceable>granularity</replaceable></arg>

          <arg>--arrondi <replaceable>rounding</replaceable></arg>

          <arg>--notemin <replaceable>min</replaceable></arg>

          <arg>--notemax <replaceable>max</replaceable></arg>

          <group>
            <arg choice="plain">--no-plafond</arg>

            <arg choice="plain">--plafond</arg>
          </group>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-note.pl</command> command computes marks for
        all students from the scoring strategy extracted from the LaTeX source
        file by <citerefentry>
            <refentrytitle>AMC-prepare</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry> and from the data capture reports made by
        <citerefentry>
            <refentrytitle>AMC-analyse</refentrytitle>

            <manvolnum>1</manvolnum>
          </citerefentry>.</para>

        <variablelist>
          <varlistentry>
            <term><option>--data
            <replaceable>project-data-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where data files are (see for example
              <citerefentry>
                  <refentrytitle>AMC-meptex</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--seuil
            <replaceable>threshold</replaceable></option></term>

            <listitem>
              <para>gives the black ratio threshold for deciding whether a box
              is ticked or not. When deciding whether a box is checked or not,
              <command>AMC-note.pl</command> compares the black ratio (number
              of black pixels over total number of pixels) to
              <replaceable>threshold</replaceable>. If the black ratio is
              greater then <replaceable>threshold</replaceable>, the box is
              declared to be checked. Standard values can be 0.15 in the
              standard layout, or 0.5 for separate answer sheet layout (in
              this last case, letters are drawn in the boxes, and the students
              are told to fill the boxes entirely).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--seuil-up
            <replaceable>upper_threshold</replaceable></option></term>

            <listitem>
              <para>gives the black ratio threshold over which a box is
              considered as not being ticked. You can set this value to (for
              example) 0.6 to allow students to cancel a ticked box filling it
              completely: if the black ratio is between
              <replaceable>threshold</replaceable> and
              <replaceable>upper_threshold</replaceable>, the box is
              considered as being ticked, but if the black ratio is greater
              than <replaceable>upper_threshold</replaceable> (for example
              when the box is filled), the box is considered as not being
              ticked. The default value is 1.0, so that this feature is
              disabled.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--grain <replaceable>granularity</replaceable>
            --arrondi <replaceable>rounding</replaceable></option></term>

            <listitem>
              <para>ask marks to be rounded to a multiple of
              <replaceable>granularity</replaceable>. If
              <replaceable>rounding</replaceable> is '<literal>i</literal>',
              rounding is done from below (as with <citerefentry>
                  <refentrytitle>floor</refentrytitle>

                  <manvolnum>3</manvolnum>
                </citerefentry>). If <replaceable>rounding</replaceable> is
              '<literal>n</literal>', rounding is done to the nearest multiple
              of <replaceable>granularity</replaceable>. If
              <replaceable>rounding</replaceable> is '<literal>s</literal>',
              rounding is done from above (as with <citerefentry>
                  <refentrytitle>ceil</refentrytitle>

                  <manvolnum>3</manvolnum>
                </citerefentry>). For example, with options "<option>--grain
              0.25 --arrondi s</option>", mark 6.285 is rounded to 6.5.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--notemin
            <replaceable>min</replaceable></option></term>

            <listitem>
              <para>with this option, all marks below
              <replaceable>min</replaceable> will be replaced by
              <replaceable>min</replaceable>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--notemax
            <replaceable>max</replaceable></option></term>

            <listitem>
              <para>gives the mark to associate to a sheet where all answers
              are correct. If not used, marks are not scaled.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--plafond</option></term>

            <listitem>
              <para>with this option, all marks above
              <replaceable>max</replaceable> will be replaced by
              <replaceable>max</replaceable>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--debug
            <replaceable>file.log</replaceable></option></term>

            <listitem>
              <para>gives a file to fill with debugging information.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--postcorrect-student <replaceable>s</replaceable>
            --postcorrect-copy <replaceable>c</replaceable></option></term>

            <listitem>
              <para>requests port-correction from the completed answer sheet
              identified by student and copy numbers. In post-correction mode,
              correct answers are not extracted from the LaTeX source file,
              but taken from the answers given on this sheet.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
    </refentry>

    <refentry id="AMC-association-auto">
      <refmeta>
        <refentrytitle>AMC-association-auto</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-association-auto</refname>

        <refpurpose>automatic association between students and answer sheets
        for AMC multiple choice exams.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">association-auto</arg>

          <arg choice="plain">--data
          <replaceable>project-data-dir</replaceable></arg>

          <arg choice="plain">--notes-id <replaceable>id</replaceable></arg>

          <arg choice="plain">--liste
          <replaceable>students-list.csv</replaceable></arg>

          <arg>--encodage-liste <replaceable>list-encoding</replaceable></arg>

          <arg choice="plain">--liste-key <replaceable>key</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-association-auto.pl</command> command
        associates students with their answer sheet (when there are no errors
        from students when coding their student number and no error during
        data capture). See <xref linkend="sec.students.id"/> from English user
        documentation for details.</para>

        <variablelist>
          <varlistentry>
            <term><option>--data
            <replaceable>project-data-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where data files are (see for example
              <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--notes-id
            <replaceable>id</replaceable></option></term>

            <listitem>
              <para>gives the identification string of the code provided for
              student numbers (command <command>\AMCcode</command> in the
              LaTeX source file).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--pre-association</option></term>

            <listitem>
              <para>if used, the <option>--notes-id</option> option is ignored
              and the automatic association is made from the pre-association
              data (command <command>\AMCassociation</command> in the LaTeX
              source file).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--liste
            <replaceable>students-list.csv</replaceable></option></term>

            <listitem>
              <para>gives the students list.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--encodage-liste
            <replaceable>list-encoding</replaceable></option></term>

            <listitem>
              <para>gives the students list file encoding (default is
              utf-8).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--liste-key
            <replaceable>key</replaceable></option></term>

            <listitem>
              <para>gives the column name where to find the student number in
              the students list.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--debug
            <replaceable>file.log</replaceable></option></term>

            <listitem>
              <para>gives a file to fill with debugging information.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
    </refentry>

    <refentry id="AMC-association">
      <refmeta>
        <refentrytitle>AMC-association</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-association</refname>

        <refpurpose>manual association between students and answer sheets for
        AMC multiple choice exams.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">association</arg>

          <arg choice="plain">--data
          <replaceable>project-data-dir</replaceable></arg>

          <arg choice="plain">--list</arg>
        </cmdsynopsis>

        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">association</arg>

          <arg choice="plain">--data
          <replaceable>project-data-dir</replaceable></arg>

          <arg choice="plain">--set</arg>

          <arg choice="plain">--student
          <replaceable>student-sheet-number</replaceable></arg>

          <arg>--copy <replaceable>copy-number</replaceable></arg>

          <arg choice="plain">--id <replaceable>student-id</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-association.pl</command> command handles
        association data between students and their answer sheet.</para>

        <variablelist>
          <varlistentry>
            <term><option>--data
            <replaceable>project-data-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where data files are (see for example
              <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>).</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>With option <option>--list</option>, all association data is
        output.</para>

        <para>With option <option>--set</option>, a manual association is
        updated.</para>
      </refsect1>
    </refentry>

    <refentry id="AMC-export">
      <refmeta>
        <refentrytitle>AMC-export</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-export</refname>

        <refpurpose>exports marks for AMC multiple choice exams.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">export</arg>

          <arg choice="plain">--data
          <replaceable>project-data-dir</replaceable></arg>

          <arg choice="plain">--module <replaceable>module</replaceable></arg>

          <arg choice="plain">--fich-noms
          <replaceable>students-list.csv</replaceable></arg>

          <arg>--noms-encodage <replaceable>list-encoding</replaceable></arg>

          <arg choice="plain">--o <replaceable>output-file</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-export.pl</command> command exports marks from
        an Auto Multiple Choice exam.</para>

        <variablelist>
          <varlistentry>
            <term><option>--data
            <replaceable>project-data-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where data files are (see for example
              <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--module
            <replaceable>module</replaceable></option></term>

            <listitem>
              <para>selects a module for export. See below for the modules
              included in the AMC standard distribution.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--fich-noms
            <replaceable>students-list.csv</replaceable></option></term>

            <listitem>
              <para>sets the students list file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--noms-encodage
            <replaceable>list-encoding</replaceable></option></term>

            <listitem>
              <para>selects an encoding for file
              <replaceable>students-list.csv</replaceable> (default is
              utf-8).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--o
            <replaceable>output-file</replaceable></option></term>

            <listitem>
              <para>gives the output file name.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--option-out
            <replaceable>options</replaceable></option></term>

            <listitem>
              <para>gives an option for selected module, in the form
              <literal>key=value</literal> (see below for possible options for
              each module). To specify multiple options, use
              <option>--option</option> several times.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--sort
            <replaceable>sort-type</replaceable></option></term>

            <listitem>
              <para>sort the students names, depending on
              <replaceable>sort-type</replaceable>. If
              <replaceable>sort-type</replaceable> is <literal>l</literal>,
              use line number from students list file to sort. If
              <replaceable>sort-type</replaceable> is <literal>m</literal>,
              use mark (and name if marks are equal) to sort. If
              <replaceable>sort-type</replaceable> is <literal>i</literal>,
              use student number to sort. If
              <replaceable>sort-type</replaceable> is <literal>n</literal>,
              use name to sort (or line from students list if equal).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--useall
            <replaceable>all</replaceable></option></term>

            <listitem>
              <para>if <replaceable>all</replaceable> is <literal>0</literal>
              or empty, only students with a scanned answer sheet appears in
              the output. If <replaceable>all</replaceable> is
              <literal>1</literal>, all students in the students list appears
              in the output.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>

      <refsect1>
        <title>Modules</title>

        <refsect2>
          <title>OpenDocument</title>

          <para>With "<option>--module ods</option>", an OpenDocument (for use
          by OpenOffice or LibreOffice for example) is produced. The following
          options are recognized:</para>

          <variablelist>
            <varlistentry>
              <term>nom</term>

              <listitem>
                <para>gives a name for the exam, to be written on the
                beginning of the sheet.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>code</term>

              <listitem>
                <para>gives an short name for the exam, to be used as a tab
                name.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>columns</term>

              <listitem>
                <para>sets the list of columns that are to be added to each
                student. Default value is
                <code>student.key,student.name</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>stats</term>

              <listitem>
                <para>with a true value, a table will be added with statistics
                for all questions.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>statsindic</term>

              <listitem>
                <para>with a true value, a table will be added with statistics
                for all indicative questions.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>CSV</title>

          <para>With "<option>--module CSV</option>", a CSV file is produced.
          The following options are recognized:</para>

          <variablelist>
            <varlistentry>
              <term>columns</term>

              <listitem>
                <para>sets the list of columns that are to be added to each
                student. Default value is
                <code>student.copy,student.key,student.name</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>decimal</term>

              <listitem>
                <para>sets the decimal point (default is a dot).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>encodage</term>

              <listitem>
                <para>sets the encoding to use for output (default is
                utf-8).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>separateur</term>

              <listitem>
                <para>sets the character used between columns (default is a
                comma).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>entoure</term>

              <listitem>
                <para>sets the character used to enclose strings (default is a
                double quote).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>ticked</term>

              <listitem>
                <para>if not empty, additional columns (with
                "<literal>CHECKED:</literal>" prefix) are included to give all
                the checked boxes on all the sheets. This can be used by an
                external program to retrieve all the checked boxes when marks
                are not sufficient. Use value <literal>01</literal> to get
                0;0;1;1;0 if boxes 3 and 4 are checked, and value
                <literal>AB</literal> to get CD if boxes 3 and 4 are
                checked.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>List</title>

          <para>With "<option>--module List</option>", a PDF file is produced
          with a list of marks for all students. The following options are
          recognized:</para>

          <variablelist>
            <varlistentry>
              <term>pagesize</term>

              <listitem>
                <para>The page size. Default value is <code>a4</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>nom</term>

              <listitem>
                <para>gives the name of the exam, to be printed at the top of
                the page.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>ncols</term>

              <listitem>
                <para>The number of columns. Default value is 2.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>decimal</term>

              <listitem>
                <para>sets the decimal point (default is a dot).</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>
      </refsect1>
    </refentry>

    <refentry id="AMC-annote">
      <refmeta>
        <refentrytitle>AMC-annotate</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-annotate</refname>

        <refpurpose>completed answer sheets annotation after marking for AMC
        multiple choice exams.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">annotate</arg>

          <arg choice="plain">--project
          <replaceable>project-dir</replaceable></arg>

          <arg choice="plain">--names-file
          <replaceable>students.csv</replaceable></arg>

          <arg rep="repeat">annotation options</arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-annotate.pl</command> command annotates papers
        scans with scores for all questions, global score and mark, resulting
        in PDF files (one for each student, or one single file).</para>

        <refsect2>
          <title>General options</title>

          <variablelist>
            <varlistentry>
              <term><option>--project
              <replaceable>project-dir</replaceable></option></term>

              <listitem>
                <para>sets the project name or directory.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--data
              <replaceable>project-data-dir</replaceable></option></term>

              <listitem>
                <para>gives the directory where data files are (default value
                is
                <filename><replaceable>project-dir</replaceable>/data</filename>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--pdf-dir
              <replaceable>pdf-dir</replaceable></option></term>

              <listitem>
                <para>sets the project pdf directory, where to output
                annotated scans (default value is
                <filename><replaceable>project-dir</replaceable>/cr/corrections/pdf</filename>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--names-file
              <replaceable>students-list.csv</replaceable></option></term>

              <listitem>
                <para>sets the students list file name.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--names-encoding
              <replaceable>encoding</replaceable></option></term>

              <listitem>
                <para>selects an encoding for file
                <replaceable>students-list.csv</replaceable> (default is
                utf-8).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--association-key
              <replaceable>key</replaceable></option></term>

              <listitem>
                <para>sets the key (column name in the students list file)
                that is used for association. Default value is stored in the
                database from value actually used for association, so this
                option should not be used.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--subject
              <replaceable>subject.pdf</replaceable></option></term>

              <listitem>
                <para>sets the path to the PDF question file (default is
                <filename><replaceable>project-dir</replaceable>/DOC-sujet.pdf</filename>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--compose
              <replaceable>mode</replaceable></option></term>

              <listitem>
                <para>use this option if you want to take pages from the
                subject when there is no boxes to be filled on them (for
                example, question pages before the annotated answer sheet).
                When <replaceable>mode</replaceable> equals 1, the pages are
                taken from the subject, are filled or not according to the
                student's answers (the same as on the answer sheet), and the
                same correction marks are drawn as on the answer sheet. When
                mode equals 2, the pages are taken from the corrected answer
                sheet (so the ticked answers are the correct ones), and no
                correction marks are drawn.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--corrected
              <replaceable>corrected.pdf</replaceable></option></term>

              <listitem>
                <para>sets the path to the PDF corrected subject (default is
                <filename><replaceable>project-dir</replaceable>/DOC-corrected.pdf</filename>).
                If not present, this file will be built using values from
                options <option>--n-copies</option>, <option>--with</option>,
                <option>--filter</option> and
                <option>--filtered-source</option>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--darkness-threshold
              <replaceable>t</replaceable></option></term>

              <listitem>
                <para>sets the darkness threshold. Default value is stored in
                the database from value actually used for scoring, so this
                option should not be used.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--darkness-threshold-up
              <replaceable>upper_t</replaceable></option></term>

              <listitem>
                <para>sets the upper darkness threshold. Default value is
                stored in the database from value actually used for scoring,
                so this option should not be used.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--csv-build-name
              <replaceable>name-model</replaceable></option></term>

              <listitem>
                <para>sets the model for building students names from the
                students list file. Default value is '<code>(nom|surname)
                (prenom|name)</code>', so that the name is built using the
                <code>nom</code> column content (or the <code>surname</code>
                column if the <code>nom</code> column does not exist),
                followed by the content of the <code>prenom</code> column (or
                the <code>name</code> column), so that the result should be OK
                for French or English simple CSV files.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--id-file
              <replaceable>ids.txt</replaceable></option></term>

              <listitem>
                <para>gives a filename where to find the ids of copies to
                annotate (one per line, either the student number if photocopy
                mode is off, or
                <code><replaceable>student</replaceable>:<replaceable>copy</replaceable></code>
                if the photocopy mode is on). If no file is given, then all
                copies will be annotated.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--debug
              <replaceable>file.log</replaceable></option></term>

              <listitem>
                <para>gives a file to fill with debugging information.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>PDF output options</title>

          <variablelist>
            <varlistentry>
              <term><option>--single-output</option></term>

              <listitem>
                <para>use this option if you need all annotated copies in a
                single PDF file. Default behavior is to build one PDF file per
                student.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--sort
              <replaceable>s</replaceable></option></term>

              <listitem>
                <para>sets the sort key (only useful when using
                <option>--single-output</option>): use</para>

                <variablelist>
                  <varlistentry>
                    <term>l</term>

                    <listitem>
                      <para>to keep students in the same order as in the
                      students list file.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>m</term>

                    <listitem>
                      <para>to sort students according to their marks.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>i</term>

                    <listitem>
                      <para>to sort students according to the copy id.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>n</term>

                    <listitem>
                      <para>to sort students according to their names.</para>
                    </listitem>
                  </varlistentry>
                </variablelist>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--filename-model
              <replaceable>model</replaceable></option></term>

              <listitem>
                <para>sets a file name model for annotated PDFs. In this
                model, some sequences will be substituted:</para>

                <variablelist>
                  <varlistentry>
                    <term><literal>(N)</literal></term>

                    <listitem>
                      <para>is replaced by the student's name (see
                      <option>--csv-build-name</option>).</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>(ID)</literal></term>

                    <listitem>
                      <para>is replaced by the student number.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>(<replaceable>COL</replaceable>)</literal></term>

                    <listitem>
                      <para>is replaced by the value of column
                      <replaceable>COL</replaceable> in the students list for
                      the current student.</para>
                    </listitem>
                  </varlistentry>
                </variablelist>

                <para>The default value is
                '<literal>(N)-(ID).pdf</literal>'.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>Source file options</title>

          <para>These options are used when the <option>--corrected</option>
          path points to a non-existing file, so that this file can be
          rebuilt.</para>

          <variablelist>
            <varlistentry>
              <term><option>--src <replaceable>mcq-source-file</replaceable>
              --n-copies <replaceable>n</replaceable> --with
              <replaceable>latex-engine</replaceable> --filter
              <replaceable>filter-name</replaceable> --filtered-source
              <replaceable>fs.tex</replaceable></option></term>

              <listitem>
                <para>see <citerefentry>
                    <refentrytitle>AMC-prepare</refentrytitle>

                    <manvolnum>1</manvolnum>
                  </citerefentry>.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>Options for embedded scans</title>

          <para>When present, scans are embedded in the annotated PDF file.
          The following options control the quality of the embedded scans, to
          reduce the annotated file size.</para>

          <variablelist>
            <varlistentry>
              <term><option>--embedded-max-size
              <replaceable>maxsize</replaceable></option></term>

              <listitem>
                <para>sets the maximal size for scans (in the format
                <literal><replaceable>width</replaceable>x<replaceable>height</replaceable></literal>,
                in pixels). Default value is the empty string, which means
                there is no maximum size. Scans that are larger will be
                reduced before being included in the annotated file.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--embedded-format
              <replaceable>format</replaceable></option></term>

              <listitem>
                <para>sets the format for scans inclusion:
                <replaceable>jpeg</replaceable> or
                <replaceable>png</replaceable>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--embedded-jpeg-quality
              <replaceable>quality</replaceable></option></term>

              <listitem>
                <para>sets the JPEG quality (from 1 to 100) for jpeg embedded
                scans.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>Annotation options</title>

          <para>These options controls what kind of annotations are being to
          be drawn.</para>

          <variablelist>
            <varlistentry>
              <term><option>--font-size
              <replaceable>fs</replaceable></option></term>

              <listitem>
                <para>sets the font size, in points, for annotations.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--text-color
              <replaceable>color</replaceable></option></term>

              <listitem>
                <para>text color for annotations. Default value is
                <replaceable>red</replaceable>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--verdict
              <replaceable>header</replaceable></option></term>

              <listitem>
                <para>sets the text header to be printed on each first page of
                the students copies. This text may contain CR characters for
                multi-line headers. Some sequences are substituted in
                it:</para>

                <variablelist>
                  <varlistentry>
                    <term><literal>%S</literal></term>

                    <listitem>
                      <para>is replaced by the student total score.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%M</literal></term>

                    <listitem>
                      <para>is replaced by the maximum total score.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%s</literal></term>

                    <listitem>
                      <para>is replaced by the student mark.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%m</literal></term>

                    <listitem>
                      <para>is replaced by the maximum mark.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%(ID)</literal></term>

                    <listitem>
                      <para>is replaced by the student's name.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%(<replaceable>COL</replaceable>)</literal></term>

                    <listitem>
                      <para>is replaced by the value of column
                      <replaceable>COL</replaceable> in the students list for
                      the current student.</para>
                    </listitem>
                  </varlistentry>
                </variablelist>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--position
              <replaceable>pos</replaceable></option></term>

              <listitem>
                <para>sets the position where question scores are to be
                written:</para>

                <variablelist>
                  <varlistentry>
                    <term>marge</term>

                    <listitem>
                      <para>the scores will be written in the left
                      margin</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>marges</term>

                    <listitem>
                      <para>the scores will be written in the closest margin
                      (left or right).</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>case</term>

                    <listitem>
                      <para>the scores will be written near the boxes</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>none</term>

                    <listitem>
                      <para>the scores won't be written.</para>
                    </listitem>
                  </varlistentry>
                </variablelist>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>--verdict-question
              <replaceable>perl-expression</replaceable></term>

              <listitem>
                <para>sets the text to be printed next to all questions,
                through a perl expression to be evaluated (if you need a
                simple text, simply quote it with <code>"</code>). Some
                sequences are substituted in it before evaluation:</para>

                <variablelist>
                  <varlistentry>
                    <term><literal>%S</literal></term>

                    <listitem>
                      <para>is replaced by the student score for this
                      question.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%M</literal></term>

                    <listitem>
                      <para>is replaced by the maximum score for this
                      question.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%s</literal></term>

                    <listitem>
                      <para>is the same as <code>%S</code>, but rounded to
                      <replaceable>nc</replaceable> significant digits (see
                      option <option>--ch-sign</option>).</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><literal>%m</literal></term>

                    <listitem>
                      <para>is the same as <code>%M</code>, but rounded to
                      <replaceable>nc</replaceable> significant digits (see
                      option <option>--ch-sign</option>).</para>
                    </listitem>
                  </varlistentry>
                </variablelist>

                <para>A standard value for this option is
                <code>"\"%s/%m\""</code>. You can also use tests (with the
                perl syntax <code>( TEST ? IF-YES : IF-NO )</code>) to write
                <emphasis>Valid</emphasis> if the score is the maximal score,
                or <emphasis>Failed</emphasis> if not, using</para>

                <programlisting>--verdict-question "(%S==%M ? \"Valid\" : \"Failed\")"</programlisting>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>--verdict-question-cancelled
              <replaceable>perl-expression</replaceable></term>

              <listitem>
                <para>same as <option>--verdict-question</option>, but applies
                for cancelled questions (see <code>allowempty</code> scoring
                strategy). The default value is <code>"X"</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--indicatives</option></term>

              <listitem>
                <para>use this option to request boxes annotation for
                indicative questions (these questions' scores won't be taken
                into account while computing the global score. The
                correct/wrong status is often irrelevant for these questions,
                so there is no point correcting the corresponding
                boxes).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--line-width
              <replaceable>width</replaceable></option></term>

              <listitem>
                <para>sets the line width (in points) when drawing symbols to
                correct answers.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--symbols
              <replaceable>symbols-definition</replaceable></option></term>

              <listitem>
                <para>defines how boxes will be annotated. symbols-definition
                is a comma separated list of
                <literal><replaceable>H</replaceable>-<replaceable>A</replaceable>:<replaceable>shape</replaceable>:<replaceable>color</replaceable></literal>
                constructs, where <replaceable>H</replaceable> is
                <literal>0</literal> or <literal>1</literal> depending on
                whether the box has to be checked or not,
                <replaceable>A</replaceable> is <literal>0</literal> or
                <literal>1</literal> depending on whether the box is actually
                checked or not, <replaceable>shape</replaceable> is one of
                <literal>none</literal>, <literal>circle</literal>,
                <literal>mark</literal>, <literal>box</literal> and
                <replaceable>color</replaceable> is a color (name or #RGB, see
                ImageMagick or GraphicsMagick documentation for details).
                Default value is
                "<code>0-0:none,0-1:circle:red,1-0:mark:red,1-1:mark:blue</code>".</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>Lengths</title>

          <para>The following length can be given with a unit
          (<code>in</code>, <code>ft</code>, <code>pt</code>, <code>cm</code>
          or <code>mm</code>).</para>

          <variablelist>
            <varlistentry>
              <term><option>--dist-to-box
              <replaceable>d</replaceable></option></term>

              <listitem>
                <para>sets the distance from the boxes (going left) where to
                write questions scores when using <option>--position
                case</option>.Defaults to <code>1cm</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--dist-margin
              <replaceable>d</replaceable></option></term>

              <listitem>
                <para>sets the margin size. Defaults to
                <code>5mm</code>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--dist-margin-global
              <replaceable>d</replaceable></option></term>

              <listitem>
                <para>sets the margin size for the header. Defaults to
                <code>3mm</code>.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>
      </refsect1>
    </refentry>

    <refentry>
      <refmeta>
        <refentrytitle>AMC-mailing</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">1.4.0</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-mailing</refname>

        <refpurpose>mail PDF annotated completed answer sheets to
        students</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">mailing</arg>

          <arg>--xmlargs <replaceable>args.xml</replaceable></arg>

          <arg choice="plain">--project
          <replaceable>project-dir</replaceable></arg>

          <arg choice="plain">--students-list
          <replaceable>students-list.csv</replaceable></arg>

          <arg>--list-encoding <replaceable>encoding</replaceable></arg>

          <arg choice="plain">--email-column
          <replaceable>col</replaceable></arg>

          <arg choice="plain">--sender
          <replaceable>sender-email</replaceable></arg>

          <arg choice="plain">--subject
          <replaceable>subject</replaceable></arg>

          <arg choice="plain">--text
          <replaceable>email-body</replaceable></arg>

          <arg>--text-content-type
          <replaceable>content-type</replaceable></arg>

          <arg>--debug <replaceable>file.log</replaceable></arg>

          <arg rep="repeat"><replaceable>transport
          arguments</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The command <command>AMC-mailing.pl</command> sends by email the
        PDF annotated completed answer sheets to the students. Email addresses
        are taken from the students list file.</para>

        <variablelist>
          <varlistentry>
            <term><option>--project
            <replaceable>project-dir</replaceable></option></term>

            <listitem>
              <para>Gives the project directory.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--students-list
            <replaceable>students-list.csv</replaceable></option></term>

            <listitem>
              <para>sets the students list file name.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--list-encoding
            <replaceable>encoding</replaceable></option></term>

            <listitem>
              <para>selects an encoding for file
              <replaceable>students-list.csv</replaceable> (default is
              utf-8).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--email-column
            <replaceable>col</replaceable></option></term>

            <listitem>
              <para>sets the name of the column containing the email addresses
              of the students in the students list file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--sender
            <replaceable>sender-email</replaceable></option></term>

            <listitem>
              <para>sets the sender email.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--cc
            <replaceable>cc-email-address</replaceable></option></term>

            <listitem>
              <para>sets the carbon copy email address.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--bcc
            <replaceable>bcc-email-address</replaceable></option></term>

            <listitem>
              <para>sets the blind carbon copy email address.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--subject
            <replaceable>subject</replaceable></option></term>

            <listitem>
              <para>sets the subject of the emails to send.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--text
            <replaceable>email-body</replaceable></option></term>

            <listitem>
              <para>sets the body text of the emails to send.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--text-content-type
            <replaceable>content-type</replaceable></option></term>

            <listitem>
              <para>sets the content-type of email text.
              <replaceable>content-type</replaceable> may be
              <constant>text/plain</constant> or
              <constant>text/html</constant>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--attach
            <replaceable>filename</replaceable></option></term>

            <listitem>
              <para>adds file <replaceable>filename</replaceable> as an
              attachment to all emails sent. Use this option several times to
              attach multiple files.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--transport
            <replaceable>transport</replaceable></option></term>

            <listitem>
              <para>sets the transport to use.
              <replaceable>transport</replaceable> may be
              <constant>sendmail</constant> or
              <constant>SMTP</constant>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--debug
            <replaceable>file.log</replaceable></option></term>

            <listitem>
              <para>gives a file to fill with debugging information.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--delay
            <replaceable>time</replaceable></option></term>

            <listitem>
              <para>sets a delay of <replaceable>time</replaceable> seconds
              between each sending.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>

      <refsect1>
        <title>Transport arguments</title>

        <para>Depending on the value used for argument
        <replaceable>transport</replaceable>, the following arguments can be
        added:</para>

        <refsect2>
          <title>Transport sendmail</title>

          <variablelist>
            <varlistentry>
              <term><option>--sendmail-path
              <replaceable>path</replaceable></option></term>

              <listitem>
                <para>sets the path to the <command>sendmail</command> command
                (defaults to <filename>/usr/sbin/sendmail</filename>).</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>

        <refsect2>
          <title>Transport SMTP</title>

          <variablelist>
            <varlistentry>
              <term><option>--smtp-host
              <replaceable>host</replaceable></option></term>

              <listitem>
                <para>sets the SMTP hostname (defaults to
                <constant>smtp</constant>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--smtp-port
              <replaceable>port</replaceable></option></term>

              <listitem>
                <para>sets the port to use (default value is 25).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--smtp-ssl
              <replaceable>mode</replaceable></option></term>

              <listitem>
                <para>sets the security mode for the SMTP connection. The
                option <replaceable>mode</replaceable> can be
                <code>ssl</code>, <code>starttls</code>, or <code>0</code>
                (unsecured).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--smtp-user
              <replaceable>user</replaceable></option></term>

              <listitem>
                <para>sets the username for authenticated SMTP.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--smtp-passwd-file
              <replaceable>file</replaceable></option></term>

              <listitem>
                <para>gives the path of a file containing the password (as the
                first line of the file) for authenticated SMTP.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>
      </refsect1>

      <refsect1>
        <title>Arguments in a XML file</title>

        <para>To avoid encoding problems, one can place some arguments in a
        XML file and use the <option>--xmlargs
        <replaceable>file.xml</replaceable></option> argument as the first
        command argument. Here is an example of such a file:</para>

        <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;arguments&gt;
  &lt;arg&gt;--sender&lt;/arg&gt;&lt;arg&gt;Bienvenüe &amp;lt;paamc@passoire.fr&amp;gt;&lt;/arg&gt;
  &lt;arg&gt;--text&lt;/arg&gt;&lt;arg&gt;Voilà votre copie corrigée&lt;/arg&gt;
  &lt;arg&gt;--subject&lt;/arg&gt;&lt;arg&gt;QCM&lt;/arg&gt;
&lt;/arguments&gt;</programlisting>
      </refsect1>
    </refentry>
  </sect1>

  <sect1>
  <title>miscellaneous</title>

  <sect2 id="divers.gmail">
      <title>Configure AMC to use GMAIL</title>

      <para>Login to your gmail account then enable the option :
      Allowing less secure apps to access your account.</para>

      <sect3>
        <title>Linux users (Ubuntu,Xubuntu,Lubuntu etc.)</title>

         <para>Type in a terminal : </para>

         <programlisting>sudo apt-get install msmtp</programlisting>
         <programlisting>sudo gedit /etc/msmtprc</programlisting>

         <para>add the following content to msmtprc file and save it. </para>

 <programlisting>
account gmail
host smtp.gmail.com
tls on
tls_certcheck off
port 587
auth login
from <emphasis>your_user_name@gmail.com</emphasis>
user <emphasis>your_user_name@gmail.com</emphasis>
password <emphasis>your_password</emphasis>
</programlisting>

          <para>
          Set up AMC : <menuchoice>
          <guimenu>Edit</guimenu>

          <guisubmenu>Preferences</guisubmenu>

          <guisubmenu>Email</guisubmenu>

          <guimenuitem>Mail delivery method</guimenuitem>
          </menuchoice>,  select <guibutton>sendmail</guibutton> and type
         the path : <programlisting>/usr/bin/msmtp</programlisting>
          </para>
        </sect3>

        <sect3>
         <title>Macintosh users</title>

          <para>Type in a terminal : </para>

           <programlisting>sudo port install msmtp</programlisting>
          <programlisting>sudo pico ~/.msmtprc</programlisting>

           <para>add the following content to msmtprc file and save it. </para>

 <programlisting>
account gmail
host smtp.gmail.com
tls on
tls_certcheck off
port 587
auth login
from <emphasis>your_user_name@gmail.com</emphasis>
user <emphasis>your_user_name@gmail.com</emphasis>
password <emphasis>your_password</emphasis>
</programlisting>

        <para>
          Set up AMC : <menuchoice>
          <guimenu>Edit</guimenu>

          <guisubmenu>Preferences</guisubmenu>

          <guisubmenu>Email</guisubmenu>

          <guimenuitem>Mail delivery method</guimenuitem>
          </menuchoice>,  select <guibutton>sendmail</guibutton> and type
         the path : <programlisting>/opt/local/bin/msmtp</programlisting>
          </para>
        </sect3>
    </sect2>
  </sect1>
</article>
