<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
<article lang="en">
  <title>Auto Multiple Choice</title>

  <articleinfo>
    <title>Auto Multiple Choice</title>

    <subtitle>Design of MCQ tests with automated correction and
    grading</subtitle>

    <abstract>
      <para>AMC is a set of utilities allowing the use of MCQ written in
      LaTeX, and their automated correction and grading from scans of the
      answer sheets. This document describes its use (for the version
      @/PACKAGE_V_DEB/@~svn @/PACKAGE_V_SVN/@).</para>

      <para>The AMC project is hosted by <ulink
      url="http://gna.org/">Gna !</ulink> : you can find the AMC web-site
      there <ulink
      url="http://home.gna.org/auto-qcm/">http://home.gna.org/auto-qcm/</ulink>,
      and the web-page where the project is hosted there <ulink
      url="https://gna.org/projects/auto-qcm/">https://gna.org/projects/auto-qcm/</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>

    <copyright>
      <year>2008-2011</year>

      <holder>Alexis Bienvenüe</holder>
    </copyright>

    <othercredit class="translator">
      <surname>Bérard</surname>

      <firstname>Jean</firstname>

      <contrib>Translation from French</contrib>
    </othercredit>

    <othercredit class="translator">
      <surname>Khaznadar</surname>

      <firstname>Georges</firstname>

      <contrib>Translation from French</contrib>
    </othercredit>

    <legalnotice>
      <para>This document can be used according to the terms of the GNU
      General Public License, version 2 or later.</para>
    </legalnotice>
  </articleinfo>

  <sect1>
    <title>License</title>

    <para>Auto Multiple Choice is free software: you can redistribute it
    and/or modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation, either version 2 of the
    License, or (at your option) any later version.</para>

    <para>This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
    for more details. You should have received a copy of the GNU General
    Public License along with this program. If not, see <ulink
    url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>.</para>
  </sect1>

  <sect1 id="prerequis">
    <title>Prerequisites</title>

    <sect2>
      <title>Operating system</title>

      <para>The AMC utilities have been written for Linux. They might be
      adapted to MAC OS X or Windows without too many difficulties, but I won
      do that in the near future. Please contact me if you are interested to
      do it : I can help you a little, and I will include changes in AMC if
      necessary.</para>
    </sect2>

    <sect2>
      <title>Software</title>

      <note>
        <para>If you install AMC with deb or RPM package (on debian, Ubuntu
        and derivatives, Mandriva, openSUSE, Fedora), every software used by
        AMC will be automatically installed.</para>
      </note>

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

      <itemizedlist>
        <listitem>
          <para>LaTeX</para>
        </listitem>

        <listitem>
          <para>ImageMagick</para>
        </listitem>

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

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

        <para>A few bugs in old versions of software used by AMC are
        particularly detrimental to its operating normally:</para>

        <itemizedlist>
          <listitem>
            <para>With old versions of <package>Net::CUPS</package> (debian
            package <package>libnet-cups-perl</package>), the command for
            printing the test sheets leads to a premature exit from the AMC
            graphical user interface. This bug is fixed in versions 0.61 and
            later of <package>Net::CUPS</package>.</para>
          </listitem>

          <listitem>
            <para>With old versions of ImageMagick, the merging of corrected
            answer sheets into a single PDF file per student does not work
            when answer sheets comprise more than one page. This bug is fixed
            in versions 6.5.5 ad later of ImageMagick.</para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>

    <sect2>
      <title>LaTeX</title>

      <para>Some knowledge of LaTeX is useful for the design of MCQs. However,
      the templates that are provided should allow those who are not deterred
      by LaTeX/XML/HTML formats to quickly start writing their own
      MCQs.</para>
    </sect2>
  </sect1>

  <sect1 id="usagenotes">
    <title>Usage notes</title>

    <sect2>
      <title>Numerical limitations</title>

      <para>In the present version (starting with version 0.156), the maximum
      number of students per test is limited to 4095, and the maximum number
      of pages per test is limited to 63.</para>

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

      <para>LaTeX's own limitations may make compilation impossible, producing
      e.g. a « <errortext>No room for a new \toks</errortext> » error. In that
      case, try again using the package <package>etex</package>, thanks to the
      <code>\usepackage{etex}</code> command.</para>
    </sect2>

    <sect2>
      <title>Versions</title>

      <para>Even though it should not have too many consequences, it is
      recommended not to change the program version while working with a given
      project (between the time when the test sheets are printed and the time
      when tests are corrected and graded). There are a few modifications
      which may interfere with AMC operating normally if you apply them while
      working with a given project:</para>

      <itemizedlist>
        <listitem>
          <para>If you have compiled and printed with a version of AMC earlier
          than 0.155, and then handle the project with version 0.156 or later,
          add the option <option>versionA</option> in the reference to the
          package <package>automultiplechoice</package> in the LaTeX file.
          Example:</para>

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

        <listitem>
          <para>From version 0.262 on, the drawing of the checkboxes changed
          to be slightly larger, which may alter the layout of the test
          sheets.</para>
        </listitem>

        <listitem>
          <para>From version 0.267, if you want to produce A4 format test
          sheets, you have to state it explicitly in the LaTeX file:</para>

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

        <listitem>
          <para>From version 0.394, if your LaTeX code needs package
          <package>graphicx</package>, you have to load it explicitly (earlier
          versions of AMC loaded it).</para>
        </listitem>

        <listitem>
          <para>The LaTeX command <command>\AMCcode</command> was rewritten in
          version 0.518. It is now more robust and configurable, but you will
          have to adapt the LaTeX sources you wrote for older versions to keep
          the same layout.</para>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Installation</title>

      <para>With debian, Ubuntu, or a derived operating system, you can use
      the debian official repository and ubuntu AMC repositories. On Mandriva,
      openSUSE or Fedora, you can use prebuilt RPM packages. The installation
      procedure is described on the <ulink
      url="http://home.gna.org/auto-qcm/download">AMC web-site</ulink>.</para>

      <para>You can also download the source code archive on the project
      <ulink url="http://download.gna.org/auto-qcm/">download space</ulink>,
      then use the following commands in a terminal:</para>

      <screen>tar xvzf auto-multiple-choice_xxxx_precomp.tar.gz
cd auto-multiple-choice-xxx
make
sudo make install</screen>
    </sect2>

    <sect2>
      <title>Access</title>

      <para>Once the installation is made, the graphical user interface can be
      launched by choosing <menuchoice>
          <guimenu>Applications</guimenu>

          <guisubmenu>Education</guisubmenu>

          <guimenuitem>Auto Multiple Choice</guimenuitem>
        </menuchoice> in the Gnome general menu (or its KDE or other analog),
      but one can also use the <userinput>auto-multiple-choice</userinput>
      command.</para>
    </sect2>
  </sect1>

  <sect1 id="latex">
    <title>Preparation of the LaTeX file</title>

    <para>First of all, the MCQ has to be described as a LaTeX file using the
    <package>automultiplechoice</package> package. This chapter describes the
    relevant LaTeX commands. You can check the LaTeX file you are designing at
    any moment by compiling it with the <command>latex</command> command, then
    visualizing the resulting dvi file.</para>

    <para>We start with a few examples giving quick illustrations of how to
    build LaTeX files for MCQs; the corresponding tex file are available as
    templates, so that one can create a new MCQ project starting with one of
    these templates.</para>

    <sect2>
      <title>A simple example</title>

      <para><!--NAME: Simple example
DESC: A simple example (from the documentation) with one simple question and one multiple question.--><programlisting
      id="modeles-simple.tex" linenumbering="numbered">\documentclass[a4paper]{article}

\usepackage[utf8x]{inputenc}    <co id="simple.latin1"
            linkends="simple.latin1.exp" />
\usepackage[T1]{fontenc}

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

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

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

\noindent{\bf QCM  \hfill TEST}

\vspace*{.5cm}
\begin{minipage}{.4\linewidth}
\centering\large\bf Test\\ Examination on Jan., 1st, 2008\end{minipage}
\namefield{\fbox{    <co id="simple.champnom" linkends="simple.champnom.exp" />
                \begin{minipage}{.5\linewidth}
                  Firstname and lastname:

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

\begin{center}\em
Duration : 10 minutes.

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


  Questions using the sign \multiSymbole{} may have
  zero, one or several correct answers.  Other questions have a single correct answer.

  Negative points may be attributed to \emph{very
    bad} answers.
\end{center}
\vspace{1ex}

%%% end of the header

\begin{question}{prez}    <co id="simple.qr" linkends="simple.qr.exp" />
  Among the following persons, which one has ever been a President of the French Republic?
  \begin{choices}
    \correctchoice{René Coty}
    \wrongchoice{Alain Prost}
    \wrongchoice{Marcel Proust}
    \wrongchoice{Claude Monet}
  \end{choices}
\end{question}

\begin{questionmult}{pref}    <co id="simple.qrmult"
            linkends="simple.qrmult.exp" />
  Among the following cities, which ones are french prefectures?
  \begin{choices}
    \correctchoice{Poitiers}
    \wrongchoice{Sainte-Menehould}
    \correctchoice{Avignon}
  \end{choices}
\end{questionmult}

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

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

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

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

      <para><calloutlist>
          <callout arearefs="simple.latin1" id="simple.latin1.exp">
            <para>The packages <package>inputenc</package> and
            <package>fontenc</package> allow one to use the ISO-8859-1
            (latin1) 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="simple.clear" id="simple.clear.exp">
            <para>The <command>clearpage</command> is used to start the next
            realization of the MCQ test on a new double page.</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>
      <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

\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}

\shufflegroup{geographie}
\insertgroup{geographie}

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

\shufflegroup{histoire}
\insertgroup{histoire}

\clearpage

}

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

    <sect2 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{\vspace{\AMCformVSpace}\par {\sc Question #1:} }    <co
            id="ensemble.fq" linkends="ensemble.fq.exp" />

\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
Durée : 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

\shufflegroup{general}
\insertgroup{general}

\AMCcleardoublepage    <co id="ensemble.cp" linkends="ensemble.cp.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" />

\clearpage    

}  

\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="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>AMCcode</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>
        </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 grey
        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>
      <title>Description of the LaTeX commands</title>

      <sect3 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>box</option>: puts every question in a block, so
            that it cannot be split by a page break.</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.</para>
          </listitem>

          <listitem>
            <para><option>noshuffle</option>: stops the automatic shuffling of
            the answers for every question</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>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 section <xref
            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). With this option, one has to take care
            that the number of answers does not exceed 9.</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>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>
        </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>If you have downloaded the LaTeX package
        <package>environ</package> <emphasis>before</emphasis>
        <package>automultiplechoice</package>, 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>The <package>environ</package> package is not available in the
          TeX Live 2007 distribution, which is still used in Ubuntu
          distributions up to version 9.10 (Karmic Koala).</para>
        </note>
      </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}{identifiant}
  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. braces or brackets). Don't end your question
          identifier with a dot followed by digits, 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>

        <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 by putting in the preamble (just
        after the reference to the package
        <package>automultiplechoice</package> for instance) the following
        <programlisting>\usepackage{multicol}</programlisting>and by including
        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></para>

        <para>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>
      </sect3>

      <sect3>
        <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 parametrize the vertical
        space between two answer blocks, thanks to the dimension
        <parameter>AMCinterBrep</parameter>:</para>

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

      <sect3>
        <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>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>Finally, the group content can be output to the test sheet using
        command <command>insertgroup</command>, as in<programlisting>\insertgroup{mygroup}</programlisting></para>

        <note>
          <para>These last two commands (<command>shufflegroup</command> and
          <command>insertgroup</command>) are to be used inside the argument
          of the command <command>onecopy</command>, so that shuffling is
          performed before each realization.</para>
        </note>

        <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
            parameterl <replaceable>n</replaceable>) only inserts the
            <replaceable>n</replaceable> first elements from the group.</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 exemple 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>):</para>

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

      <sect3>
        <title>Check-box presentation style</title>

        <para>The <command>\AMCboxDimensions</command> command allows one to
        modify one or several dimensions of the check-boxes.</para>

        <itemizedlist>
          <listitem>
            <para><option>size</option> is the size 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>
        </itemizedlist>

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

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

        <para>When using <option>separateanswersheet</option> package option,
        you can also customize the boxes labelling. The default behaviour is
        to use uppercase alphabetical labelling, or arabic numbering if the
        <option>digits</option> package option is used. To use your own
        labelling, 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>
      </sect3>

      <sect3>
        <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>

        <para>Finally, 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>

        <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>

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

      <sect3>
        <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 section <xref 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 (here follows the default
            definitions):</para>

            <programlisting>\def\AMCformQuestion#1{\vspace{\AMCformVSpace}\par{\bf Question #1:}}
\def\AMCformAnswer#1{\hspace{\AMCformHSpace} #1}
</programlisting>
          </listitem>
        </orderedlist>

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

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

        <para>Code acquisition can be easily performed thanks to the LaTeX
        command <command>AMCcode</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
        identifier, and the number of digits to be used by the code. One can
        e.g. use the following header</para>

        <para><programlisting>\noindent\AMCcode{studentid}{8}\hspace*{\fill}
\begin{minipage}{.5\linewidth}
$\longleftarrow{}$ please encode your student number below,
and write your first and last names below.

\vspace{3ex}

\namefield{\fbox{    
    \begin{minipage}{.9\linewidth}
      Firstname and lastname:
      
      \vspace*{.5cm}\dotfill
      \vspace*{1mm}
    \end{minipage}
  }}
\end{minipage}
</programlisting></para>

        <para>If the <option>separateanswersheet</option> option is used, the
        <command>AMCcode</command> command has to be placed after the
        <command>AMCdebutFormulaire</command> command.</para>

        <para>Note that the codes rendering from <command>\AMCcode</command>
        can be adapted modifying the lenghts
        <command>\AMCcodeHspace</command>, <command>\AMCcodeVspace</command>
        and <command>\AMCcodeBoxSep</command>, representing the horizontal and
        vertical amount of space between boxes, and the amount of space
        between boxes and labels (when the labels are written outside the
        boxes). Defaut values are set with the following commands:</para>

        <programlisting>\AMCcodeHspace=.5em
\AMCcodeVspace=.5em
\AMCcodeBoxSep=.1em</programlisting>
      </sect3>

      <sect3>
        <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>
      </sect3>

      <sect3>
        <title>Using references inside the test sheets</title>

        <para>Using LaTeX commands <command>\label</command> and
        <command>\ref</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> and <command>\AMCref</command>:
        they add the realization number to their argument before transmitting
        it to <command>\label</command> et <command>\ref</command>.</para>

        <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}?
    \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>
      </sect3>

      <sect3>
        <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>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>
        </itemizedlist>
      </sect3>
    </sect2>

    <sect2>
      <title>Mathematical questions with randomized statements</title>

      <para>Thanks to the LaTeX package <package>fp</package>, whose
      documentation is available at <ulink
      url="http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=fp">http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=fp</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{} et \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 et 8. The next line sets VQb to a random integer value
            between 4 et 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 et
            VQnonC...</para>
          </callout>
        </calloutlist>Variable names beginning with VQ have been chosen so as
      to avoid interference with other LaTeX commands.</para>

      <para>The automultiplechoice package moreover defines a
      <command>\choixIntervalle</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{} et \VQb{}.
  To which interval does the probability $\mathbb{P}[X&lt;Y]$ belong ?

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

      <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>\choixIntervalle</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>
    </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>
      <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>
      <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>. 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>

        <listitem>
          <para>The <emphasis>adjustment</emphasis> document. It contains
          information to locate framing marks, checkboxes, and also the area
          where students write their names are drawn on all the pages.</para>
        </listitem>
      </itemizedlist>

      <para>When produced, those documents can be viewed (and possibly
      printed) with a double-click on their names.</para>

      <para>Now we can begin the last step of the preparation: analyzing the
      layout document. It can be launched with the button
      <guibutton>Calculate</guibutton> in the section <guilabel>Layout
      detection</guilabel>. This analysis detects, in every page of the
      subject, the exact position of every element which must be analyzed in
      the students' copies. This analysis can be a bit long (mainly when there
      are many pages in the subject). We can see the result in the right-side
      list, which displays for each page its number, its identificator (a code
      containing the student's number), the page number for this student, and
      a code to verify the identification), and also the date of the last
      update of the layout.</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>
      <title>Printing and exam</title>

      <warning>
        <para>You must create as many exam sheets as necessary for all your
        students, with different sheets numbers, and print them all. If you
        print one or several sheets and photocopy them to have enough for all
        the students, you won't be able to continue with AMC!</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>

      <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>
    </sect2>

    <sect2>
      <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>
        <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 greyscale -
        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>

        <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 button <guibutton>Use</guibutton> of this dialog. It's now
        time to drink a coffee because the analysis of copies can be very long
        (and can be done quietly because it requires no interaction).</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 <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>
        </itemizedlist>
      </sect3>

      <sect3>
        <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>

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

    <sect2>
      <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>
        <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 allow to try many strategies at
            the end of the correction process. 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></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></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>

                <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>

                <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>

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

              <row>
                <entry>m</entry>

                <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></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>

                <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></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>

                <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></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>
            </tbody>
          </tgroup>
        </informaltable>

        <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>

        <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>
        </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: Exemple (from the documentation) with different scoring strategies.--><programlisting
        id="modeles-scoring.tex" linenumbering="numbered">\documentclass{article}

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

\usepackage[bloc,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}

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

\clearpage

}

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

      <sect3>
        <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>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>), cases operator <code>( ? : )</code> and
        parenthesis.</para>

        <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>
    </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 text
        file containing one student per line. We may also append a few
        complementary informations in the file, as in the following example
        (in the example above, email will not be used at all by
        AMC):<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 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 informations.
        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>
        </note>

        <para>The prepared list of students (either a simple list or with more
        informations) will then be selected with the button <guilabel>List of
        the students</guilabel>. 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>
        <title>Association</title>

        <sect4>
          <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>
          <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
          part <guilabel>Students identification</guilabel>. 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>
      <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>
    </sect2>

    <sect2>
      <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:</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 curent
            student.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>This operation is made for each page, giving as a result JPG
      format annotated pages.</para>

      <para>If we wish to distribute the annotated/corrected copies to
      students in electronic format, it is useful to make a PDF file for each
      student, from his/her JPG annotated pages. This is made by pushing the
      button <guibutton>Group</guibutton>. 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>
    </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 usualy 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">@/PACKAGE_V_DEB/@</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-annote</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">@/PACKAGE_V_DEB/@</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.tex</replaceable></arg>
        </cmdsynopsis>

        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">prepare</arg>

          <arg choice="plain">--mode m</arg>

          <arg choice="plain">--mep-dir
          <replaceable>project-mep-dir</replaceable></arg>

          <arg choice="plain">--calage
          <replaceable>calage.xy</replaceable></arg>

          <arg choice="plain"><replaceable>mcq.tex</replaceable></arg>
        </cmdsynopsis>

        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">prepare</arg>

          <arg choice="plain">--mode b</arg>

          <arg choice="plain">--bareme
          <replaceable>scoring.xml</replaceable></arg>

          <arg choice="plain"><replaceable>mcq.tex</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-prepare.pl</command> command extracts working
        documents from the source LaTeX file describing the multiple choice
        questionnaire. Informations to be extracted depends on the
        <option>--mode</option> argument value. In any mode, the LaTeX 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 informations 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 m</option>",
            <command>AMC-prepare.pl</command> makes the MEP files (XML files
            with exact positions of the boxes, the marks, the name field on
            all the pages). In this mode, the following arguments must be
            used:</para>

            <variablelist>
              <varlistentry>
                <term><option>--calage
                <replaceable>calage.xy</replaceable></option></term>

                <listitem>
                  <para>sets the positions file to be used.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>--mep
                <replaceable>project-mep-dir</replaceable></option></term>

                <listitem>
                  <para>sets the directory to store MEP files into.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>

          <listitem>
            <para>with "<option>--mode b</option>",
            <command>AMC-prepare.pl</command> makes the scoring file
            extracting the scoring strategy defined in the source LaTeX file.
            In this mode, the following arguments must be used:</para>

            <variablelist>
              <varlistentry>
                <term><option>--bareme
                <replaceable>scoring.xml</replaceable></option></term>

                <listitem>
                  <para>sets the scoring file to create.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </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
              exemple.</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>
        </variablelist>
      </refsect1>
    </refentry>

    <refentry id="AMC-imprime">
      <refmeta>
        <refentrytitle>AMC-imprime</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">@/PACKAGE_V_DEB/@</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">--mep
          <replaceable>project-mep-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>--mep
              <replaceable>project-mep-dir</replaceable></option></term>

              <listitem>
                <para>gives the directory where MEP files are (see
                <citerefentry>
                    <refentrytitle>AMC-prepare</refentrytitle>

                    <manvolnum>1</manvolnum>
                  </citerefentry>). The MEP files are used to know at which
                page of the subject file each copy begins and ends.</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 exemple 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>
      </refsect1>
    </refentry>

    <refentry id="AMC-analyse">
      <refmeta>
        <refentrytitle>AMC-analyse</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">@/PACKAGE_V_DEB/@</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 then MEP files (<option>--mode
        m</option>).</para>

        <variablelist>
          <varlistentry>
            <term><option>--mep
            <replaceable>project-mep-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where MEP files (prepared by
              <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>) can be found.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--cr
            <replaceable>project-cr-dir</replaceable></option></term>

            <listitem>
              <para>gives a directory where to create reports of the data
              capture.</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>,
              and if <option>--mep</option> is not used,
              <replaceable>project-mep-dir</replaceable> will be set to
              <filename><replaceable>project-dir</replaceable>/mep</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>--seuil-coche
            <replaceable>threshold</replaceable></option></term>

            <listitem>
              <para>When deciding whether a box is checked or not,
              <command>AMC-analyse.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). The black ratio is written
              in the data capture reports, so that this threshold value can be
              refined later without calling <command>AMC-analyse.pl</command>
              again.</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 acurate). 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>--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">@/PACKAGE_V_DEB/@</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">--cr
          <replaceable>project-cr-dir</replaceable></arg>

          <arg choice="plain">--bareme
          <replaceable>scoring.xml</replaceable></arg>

          <arg choice="plain">-o <replaceable>marks.xml</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>--cr
            <replaceable>project-cr-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where to find data capture reports
              (see <citerefentry>
                  <refentrytitle>AMC-analyse</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--bareme
            <replaceable>scoring.xml</replaceable></option></term>

            <listitem>
              <para>gives the scoring strategy file (see <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--o
            <replaceable>marks.xml</replaceable></option></term>

            <listitem>
              <para>gives the name of the file to create and fill with
              students' marks.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--seuil
            <replaceable>threshold</replaceable></option></term>

            <listitem>
              <para>gives the black ratio threshold (see <citerefentry>
                  <refentrytitle>AMC-analyse</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>) for deciding whether a box is ticked or
              not.</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>
        </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">@/PACKAGE_V_DEB/@</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">--notes
          <replaceable>marks.xml</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>

          <arg choice="plain">--assoc
          <replaceable>assoc.xml</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-association-auto.pl</command> command reads
        report from to associate 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>--notes
            <replaceable>marks.xml</replaceable></option></term>

            <listitem>
              <para>gives the name of the marks file (also containing read
              codes as student id numbers) produced by <citerefentry>
                  <refentrytitle>AMC-note</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>--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>--assoc
            <replaceable>assoc.xml</replaceable></option></term>

            <listitem>
              <para>gives the name of the file to create and fill with
              association report.</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-export">
      <refmeta>
        <refentrytitle>AMC-export</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">@/PACKAGE_V_DEB/@</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">--module <replaceable>module</replaceable></arg>

          <arg choice="plain">--fich-notes
          <replaceable>marks.xml</replaceable></arg>

          <arg choice="plain">--fich-assoc
          <replaceable>assoc.xml</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>--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-notes
            <replaceable>marks.xml</replaceable></option></term>

            <listitem>
              <para>sets the marks file, generated by <citerefentry>
                  <refentrytitle>AMC-note</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--fich-assoc
            <replaceable>assoc.xml</replaceable></option></term>

            <listitem>
              <para>sets the association file, generated by <citerefentry>
                  <refentrytitle>AMC-association-auto</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry> and maybe modified for manual
              association.</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 scaned 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>
          </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>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 colums (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>cochees</term>

              <listitem>
                <para>if true (value <literal>1</literal> for example),
                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.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect2>
      </refsect1>
    </refentry>

    <refentry id="AMC-annote">
      <refmeta>
        <refentrytitle>AMC-annote</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">@/PACKAGE_V_DEB/@</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-annote</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">annote</arg>

          <arg choice="plain">--projet
          <replaceable>project-dir</replaceable></arg>

          <arg choice="plain">--notes
          <replaceable>marks.xml</replaceable></arg>

          <arg choice="plain">--bareme
          <replaceable>scoring.xml</replaceable></arg>

          <arg choice="plain">--fich-assoc
          <replaceable>assoc.xml</replaceable></arg>

          <arg rep="repeat">annotation options</arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The <command>AMC-annote.pl</command> command annotates papers
        scans with scores for all questions, global score and mark, resulting
        in JPEG files (one for each page).</para>

        <variablelist>
          <varlistentry>
            <term><option>--projet
            <replaceable>project-dir</replaceable></option></term>

            <listitem>
              <para>sets the project directory.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--cr
            <replaceable>project-cr-dir</replaceable></option></term>

            <listitem>
              <para>sets the project reports directory, where to find data
              capture reports prepared by <citerefentry>
                  <refentrytitle>AMC-analyse</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>, and where to output annotated scans. Default
              value is
              <filename><replaceable>project-dir</replaceable>/cr</filename>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--notes
            <replaceable>marks.xml</replaceable></option></term>

            <listitem>
              <para>sets the marks file, prepared by <citerefentry>
                  <refentrytitle>AMC-note</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--bareme
            <replaceable>scoring.xml</replaceable></option></term>

            <listitem>
              <para>sets the scoring file, prepared by <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--fich-assoc
            <replaceable>assoc.xml</replaceable></option></term>

            <listitem>
              <para>sets the association file, prepared by <citerefentry>
                  <refentrytitle>AMC-association-auto</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry> and/or modified for manual association.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--fich-noms
            <replaceable>students-list.csv</replaceable></option></term>

            <listitem>
              <para>sets the students list file name.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--noms-encodage
            <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>--qualite
            <replaceable>qual</replaceable></option></term>

            <listitem>
              <para>sets JPEG quality for output files. Default value is
              65.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--taille-max
            <replaceable>maxsize</replaceable></option></term>

            <listitem>
              <para>sets the maximal size for output files (in the format
              <literal><replaceable>width</replaceable>x<replaceable>height</replaceable></literal>,
              in pixels). Default value is
              <literal>1000x1500</literal>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--pointsize-nl
            <replaceable>lines</replaceable></option></term>

            <listitem>
              <para>sets the size of texts requiring that with this size, the
              number of text lines that fits on the page height must be
              <replaceable>lines</replaceable>. Default value is
              <literal>60</literal>.</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 curent student.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--ch-sign
            <replaceable>nc</replaceable></option></term>

            <listitem>
              <para>Sets the number <replaceable>nc</replaceable> of
              significant digits to use when printing global mark.</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>colour</replaceable></literal>
              constructs, where <replaceable>H</replaceable> is
              <literal>0</literal> or <literal>1</literal> depending on wether
              the box has to be checked or not, <replaceable>A</replaceable>
              is <literal>0</literal> or <literal>1</literal> depending on
              wether 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>coulour</replaceable> is a colour (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>

          <varlistentry>
            <term><option>--position
            <replaceable>pos</replaceable></option></term>

            <listitem>
              <para>sets the position of individual questions scores.
              <replaceable>pos</replaceable> may be '<literal>none</literal>'
              (do dot write individual scores), '<literal>marge</literal>'
              (write scores in the margin) or '<literal>case</literal>' (write
              scores at the left of the left-most box for the question.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--ecart
            <replaceable>dx</replaceable></option></term>

            <listitem>
              <para>sets the horizontal space to let between individual
              question score and the leftmost box when <option>--position
              case</option> is used.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--ecart-marge
            <replaceable>x</replaceable></option></term>

            <listitem>
              <para>sets the x position for individual questions scores when
              written in the margin (in <emphasis>em</emphasis> units).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--line-width
            <replaceable>lw</replaceable></option></term>

            <listitem>
              <para>sets the line width for symbols drwan on the scans (in
              pixels). Default value is 2.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--indicatives
            <replaceable>bool</replaceable></option></term>

            <listitem>
              <para>say if indicative questions are to be annotated (use 1 for
              a true value; default is false).</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-regroupe">
      <refmeta>
        <refentrytitle>AMC-regroupe</refentrytitle>

        <manvolnum>1</manvolnum>

        <refmiscinfo class="source">Auto Multiple Choice</refmiscinfo>

        <refmiscinfo class="version">@/PACKAGE_V_DEB/@</refmiscinfo>
      </refmeta>

      <refnamediv>
        <refname>AMC-regroupe</refname>

        <refpurpose>merge JPEG annotated AMC multiple choice answer sheets to
        get a PDF file per student.</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>auto-multiple-choice</command>

          <arg choice="plain">regroupe</arg>

          <arg choice="plain">--projet
          <replaceable>project-dir</replaceable></arg>

          <arg choice="plain">--sujet
          <replaceable>subject.pdf</replaceable></arg>

          <arg choice="plain">--modele
          <replaceable>file-name-model</replaceable></arg>

          <arg choice="plain">--fich-assoc
          <replaceable>assoc.xml</replaceable></arg>

          <arg choice="plain">--fich-noms
          <replaceable>students-list.csv</replaceable></arg>

          <arg>--noms-encodage <replaceable>encoding</replaceable></arg>

          <arg>--compose</arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>

        <para>The command <command>AMC-regroupe.pl</command> merges annotated
        AMC multiple choice answer sheets (there is one per page) to get a
        single PDF file per student.</para>

        <variablelist>
          <varlistentry>
            <term><option>--mep
            <replaceable>project-mep-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where MEP files (prepared by
              <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>) can be found.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--cr
            <replaceable>project-cr-dir</replaceable></option></term>

            <listitem>
              <para>gives the directory where to find individual annotated
              JPEG files prepared by <citerefentry>
                  <refentrytitle>AMC-annote</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry> and where to write annotated students
              PDFs.</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>,
              and if <option>--mep</option> is not used,
              <replaceable>project-mep-dir</replaceable> will be set to
              <filename><replaceable>project-dir</replaceable>/mep</filename>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--sujet
            <replaceable>subject.pdf</replaceable></option></term>

            <listitem>
              <para>gives the subject file (as prepared by <citerefentry>
                  <refentrytitle>AMC-prepare</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry>). This helps in getting the page size for the
              subject to make annotated PDF fit this size.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--fich-assoc
            <replaceable>assoc.xml</replaceable></option></term>

            <listitem>
              <para>sets the association file, prepared by <citerefentry>
                  <refentrytitle>AMC-association-auto</refentrytitle>

                  <manvolnum>1</manvolnum>
                </citerefentry> and/or modified for manual association.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--fich-noms
            <replaceable>students-list.csv</replaceable></option></term>

            <listitem>
              <para>sets the students list file name.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--noms-encodage
            <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>--modele
            <replaceable>file-name-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.</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 curent student.</para>
                  </listitem>
                </varlistentry>
              </variablelist>

              <para>The default value is
              '<literal>(N)-(ID).pdf</literal>'.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--compose</option></term>

            <listitem>
              <para>When using this option, pages for which there is no scan
              will be replaced by the corresponding page from the corrected
              answer sheet. This option is for example usefull when using the
              separate answer sheet layout: in this case, the annotated answer
              sheet will not be readable without the pages with the
              questions.</para>

              <para>When using the <option>--compose</option> option, one must
              also use the <option>--tex-src</option> (and optionnaly
              <option>--with</option>) option.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--tex-src
            <replaceable>mcq.tex</replaceable></option></term>

            <listitem>
              <para>gives the LaTeX source file for the subject.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--with
            <replaceable>latex-engine</replaceable></option></term>

            <listitem>
              <para>gives the LaTeX engine (command) to be used to process
              <replaceable>mcq.tex</replaceable>.
              <replaceable>latex-engine</replaceable> can be
              <command>pdflatex</command> or <command>xelatex</command> for
              exemple.</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>
  </sect1>
</article>
