NAME

       auto-multiple-choice-annotate - completed answer sheets annotation after marking for AMC
       multiple choice exams.

SYNOPSIS

       auto-multiple-choice annotate --project project-dir --names-file students.csv
                            [annotation options...]

DESCRIPTION

       The auto-multiple-choice annotate command annotates papers scans with scores for all
       questions, global score and mark, resulting in PDF files (one for each student, or one
       single file).

   General options
       --project project-dir
           sets the project name or directory.

       --data project-data-dir
           gives the directory where data files are (default value is project-dir/data).

       --pdf-dir pdf-dir
           sets the project pdf directory, where to output annotated scans (default value is
           project-dir/cr/corrections/pdf).

       --names-file students-list.csv
           sets the students list file name.

       --names-encoding encoding
           selects an encoding for file students-list.csv (default is utf-8).

       --association-key key
           sets the key (column name in the students list file) that is used for association.
           Default value is stored in the database from value actually used for association, so
           this option should not be used.

       --subject subject.pdf
           sets the path to the PDF question file (default is project-dir/DOC-sujet.pdf).

       --compose mode
           use this option if you want to take pages from the subject when there is no boxes to
           be filled on them (for example, question pages before the annotated answer sheet).
           When mode equals 1, the pages are taken from the subject, are filled or not according
           to the student's answers (the same as on the answer sheet), and the same correction
           marks are drawn as on the answer sheet. When mode equals 2, the pages are taken from
           the corrected answer sheet (so the ticked answers are the correct ones), and no
           correction marks are drawn.

       --corrected corrected.pdf
           sets the path to the PDF corrected subject (default is project-dir/DOC-corrected.pdf).
           If not present, this file will be built using values from options --n-copies, --with,
           --filter and --filtered-source).

       --darkness-threshold t
           sets the darkness threshold. Default value is stored in the database from value
           actually used for scoring, so this option should not be used.

       --darkness-threshold-up upper_t
           sets the upper darkness threshold. Default value is stored in the database from value
           actually used for scoring, so this option should not be used.

       --csv-build-name name-model
           sets the model for building students names from the students list file. Default value
           is '(nom|surname) (prenom|name)', so that the name is built using the nom column
           content (or the surname column if the nom column does not exist), followed by the
           content of the prenom column (or the name column), so that the result should be OK for
           French or English simple CSV files.

       --id-file ids.txt
           gives a filename where to find the ids of copies to annotate (one per line, either the
           student number if photocopy mode is off, or student:copy if the photocopy mode is on).
           If no file is given, then all copies will be annotated.

       --debug file.log
           gives a file to fill with debugging information.

   PDF output options
       --single-output
           use this option if you need all annotated copies in a single PDF file. Default
           behavior is to build one PDF file per student.

       --sort s
           sets the sort key (only useful when using --single-output): use

           l
               to keep students in the same order as in the students list file.

           m
               to sort students according to their marks.

           i
               to sort students according to the copy id.

           n
               to sort students according to their names.

       --filename-model model
           sets a file name model for annotated PDFs. In this model, some sequences will be
           substituted:

           (N)
               is replaced by the student's name (see --csv-build-name).

           (ID)
               is replaced by the student number.

           (COL)
               is replaced by the value of column COL in the students list for the current
               student.

           The default value is '(N)-(ID).pdf'.

   Source file options
       These options are used when the --corrected path points to a non-existing file, so that
       this file can be rebuilt.

       --src mcq-source-file --n-copies n --with latex-engine --filter filter-name
       --filtered-source fs.tex
           see auto-multiple-choice-prepare(1).

   Options for embedded scans
       When present, scans are embedded in the annotated PDF file. The following options control
       the quality of the embedded scans, to reduce the annotated file size.

       --embedded-max-size maxsize
           sets the maximal size for scans (in the format widthxheight, in pixels). Default value
           is the empty string, which means there is no maximum size. Scans that are larger will
           be reduced before being included in the annotated file.

       --embedded-format format
           sets the format for scans inclusion: jpeg or png.

       --embedded-jpeg-quality quality
           sets the JPEG quality (from 1 to 100) for jpeg embedded scans.

   Annotation options
       These options controls what kind of annotations are being to be drawn.

       --font-size fs
           sets the font size, in points, for annotations.

       --text-color color
           text color for annotations. Default value is red.

       --verdict header
           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:

           %S
               is replaced by the student total score.

           %M
               is replaced by the maximum total score.

           %s
               is replaced by the student mark.

           %m
               is replaced by the maximum mark.

           %(ID)
               is replaced by the student's name.

           %(COL)
               is replaced by the value of column COL in the students list for the current
               student.

       --position pos
           sets the position where question scores are to be written:

           marge
               the scores will be written in the left margin

           marges
               the scores will be written in the closest margin (left or right).

           case
               the scores will be written near the boxes

           none
               the scores won't be written.

       --verdict-question perl-expression
           sets the text to be printed next to all questions, through a perl expression to be
           evaluated (if you need a simple text, simply quote it with "). Some sequences are
           substituted in it before evaluation:

           %S
               is replaced by the student score for this question.

           %M
               is replaced by the maximum score for this question.

           %s
               is the same as %S, but rounded to nc significant digits (see option --ch-sign).

           %m
               is the same as %M, but rounded to nc significant digits (see option --ch-sign).

           A standard value for this option is "\"%s/%m\"". You can also use tests (with the perl
           syntax ( TEST ? IF-YES : IF-NO )) to write Valid if the score is the maximal score, or
           Failed if not, using

               --verdict-question "(%S==%M ? \"Valid\" : \"Failed\")"

       --verdict-question-cancelled perl-expression
           same as --verdict-question, but applies for cancelled questions (see allowempty
           scoring strategy). The default value is "X".

       --indicatives
           use this option to request boxes annotation for indicative questions (these questions'
           scores won't be taken into account while computing the global score. The correct/wrong
           status is often irrelevant for these questions, so there is no point correcting the
           corresponding boxes).

       --line-width width
           sets the line width (in points) when drawing symbols to correct answers.

       --symbols symbols-definition
           defines how boxes will be annotated. symbols-definition is a comma separated list of
           H-A:shape:color constructs, where H is 0 or 1 depending on whether the box has to be
           checked or not, A is 0 or 1 depending on whether the box is actually checked or not,
           shape is one of none, circle, mark, box and color is a color (name or #RGB, see
           ImageMagick or GraphicsMagick documentation for details).

           Default value is "0-0:none,0-1:circle:red,1-0:mark:red,1-1:mark:blue".

   Lengths
       The following length can be given with a unit (in, ft, pt, cm or mm).

       --dist-to-box d
           sets the distance from the boxes (going left) where to write questions scores when
           using --position case.Defaults to 1cm.

       --dist-margin d
           sets the margin size. Defaults to 5mm.

       --dist-margin-global d
           sets the margin size for the header. Defaults to 3mm.

AUTHORS

       Alexis Bienvenüe <paamc@passoire.fr>
           Main author

       Anirvan Sarkar
           Author and Editor

       Hiroto Kagotani
           Editor

       Frédéric Bréal
           Author and Editor

       Jean Bérard
           Translation from French

       Georges Khaznadar
           Translation from French

COPYRIGHT

       Copyright © 2008-2022 Alexis Bienvenüe

       This document can be used according to the terms of the GNU General Public License,
       version 2 or later.