'\" t
.\"     Title: auto-multiple-choice-annotate
.\"    Author: Alexis Bienven\(:ue <paamc@passoire.fr>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2023-02-06
.\"    Manual: Auto Multiple Choice
.\"    Source: Auto Multiple Choice 1.6.0
.\"  Language: English
.\"
.TH "AUTO\-MULTIPLE\-CHOI" "1" "2023-02-06" "Auto Multiple Choice 1\&.6\&.0" "Auto Multiple Choice"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
auto-multiple-choice-annotate \- completed answer sheets annotation after marking for AMC multiple choice exams\&.
.SH "SYNOPSIS"
.HP \w'\fBauto\-multiple\-choice\fR\ 'u
\fBauto\-multiple\-choice\fR annotate \-\-project\ \fIproject\-dir\fR \-\-names\-file\ \fIstudents\&.csv\fR [annotation\ options...]
.SH "DESCRIPTION"
.PP
The
\fBauto\-multiple\-choice annotate\fR
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)\&.
.SS "General options"
.PP
\fB\-\-project \fR\fB\fIproject\-dir\fR\fR
.RS 4
sets the project name or directory\&.
.RE
.PP
\fB\-\-data \fR\fB\fIproject\-data\-dir\fR\fR
.RS 4
gives the directory where data files are (default value is
\fIproject\-dir\fR/data)\&.
.RE
.PP
\fB\-\-pdf\-dir \fR\fB\fIpdf\-dir\fR\fR
.RS 4
sets the project pdf directory, where to output annotated scans (default value is
\fIproject\-dir\fR/cr/corrections/pdf)\&.
.RE
.PP
\fB\-\-names\-file \fR\fB\fIstudents\-list\&.csv\fR\fR
.RS 4
sets the students list file name\&.
.RE
.PP
\fB\-\-names\-encoding \fR\fB\fIencoding\fR\fR
.RS 4
selects an encoding for file
\fIstudents\-list\&.csv\fR
(default is utf\-8)\&.
.RE
.PP
\fB\-\-association\-key \fR\fB\fIkey\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-subject \fR\fB\fIsubject\&.pdf\fR\fR
.RS 4
sets the path to the PDF question file (default is
\fIproject\-dir\fR/DOC\-sujet\&.pdf)\&.
.RE
.PP
\fB\-\-compose \fR\fB\fImode\fR\fR
.RS 4
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
\fImode\fR
equals 1, the pages are taken from the subject, are filled or not according to the student\*(Aqs 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\&.
.RE
.PP
\fB\-\-corrected \fR\fB\fIcorrected\&.pdf\fR\fR
.RS 4
sets the path to the PDF corrected subject (default is
\fIproject\-dir\fR/DOC\-corrected\&.pdf)\&. If not present, this file will be built using values from options
\fB\-\-n\-copies\fR,
\fB\-\-with\fR,
\fB\-\-filter\fR
and
\fB\-\-filtered\-source\fR)\&.
.RE
.PP
\fB\-\-darkness\-threshold \fR\fB\fIt\fR\fR
.RS 4
sets the darkness threshold\&. Default value is stored in the database from value actually used for scoring, so this option should not be used\&.
.RE
.PP
\fB\-\-darkness\-threshold\-up \fR\fB\fIupper_t\fR\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-csv\-build\-name \fR\fB\fIname\-model\fR\fR
.RS 4
sets the model for building students names from the students list file\&. Default value is \*(Aq(nom|surname) (prenom|name)\*(Aq, 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\&.
.RE
.PP
\fB\-\-id\-file \fR\fB\fIids\&.txt\fR\fR
.RS 4
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
\fIstudent\fR:\fIcopy\fR
if the photocopy mode is on)\&. If no file is given, then all copies will be annotated\&.
.RE
.PP
\fB\-\-debug \fR\fB\fIfile\&.log\fR\fR
.RS 4
gives a file to fill with debugging information\&.
.RE
.SS "PDF output options"
.PP
\fB\-\-single\-output\fR
.RS 4
use this option if you need all annotated copies in a single PDF file\&. Default behavior is to build one PDF file per student\&.
.RE
.PP
\fB\-\-sort \fR\fB\fIs\fR\fR
.RS 4
sets the sort key (only useful when using
\fB\-\-single\-output\fR): use
.PP
l
.RS 4
to keep students in the same order as in the students list file\&.
.RE
.PP
m
.RS 4
to sort students according to their marks\&.
.RE
.PP
i
.RS 4
to sort students according to the copy id\&.
.RE
.PP
n
.RS 4
to sort students according to their names\&.
.RE
.RE
.PP
\fB\-\-filename\-model \fR\fB\fImodel\fR\fR
.RS 4
sets a file name model for annotated PDFs\&. In this model, some sequences will be substituted:
.PP
(N)
.RS 4
is replaced by the student\*(Aqs name (see
\fB\-\-csv\-build\-name\fR)\&.
.RE
.PP
(ID)
.RS 4
is replaced by the student number\&.
.RE
.PP
(\fICOL\fR)
.RS 4
is replaced by the value of column
\fICOL\fR
in the students list for the current student\&.
.RE
.sp
The default value is \*(Aq(N)\-(ID)\&.pdf\*(Aq\&.
.RE
.SS "Source file options"
.PP
These options are used when the
\fB\-\-corrected\fR
path points to a non\-existing file, so that this file can be rebuilt\&.
.PP
\fB\-\-src \fR\fB\fImcq\-source\-file\fR\fR\fB \-\-n\-copies \fR\fB\fIn\fR\fR\fB \-\-with \fR\fB\fIlatex\-engine\fR\fR\fB \-\-filter \fR\fB\fIfilter\-name\fR\fR\fB \-\-filtered\-source \fR\fB\fIfs\&.tex\fR\fR
.RS 4
see
\fBauto-multiple-choice-prepare\fR(1)\&.
.RE
.SS "Options for embedded scans"
.PP
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\&.
.PP
\fB\-\-embedded\-max\-size \fR\fB\fImaxsize\fR\fR
.RS 4
sets the maximal size for scans (in the format
\fIwidth\fRx\fIheight\fR, 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\&.
.RE
.PP
\fB\-\-embedded\-format \fR\fB\fIformat\fR\fR
.RS 4
sets the format for scans inclusion:
\fIjpeg\fR
or
\fIpng\fR\&.
.RE
.PP
\fB\-\-embedded\-jpeg\-quality \fR\fB\fIquality\fR\fR
.RS 4
sets the JPEG quality (from 1 to 100) for jpeg embedded scans\&.
.RE
.SS "Annotation options"
.PP
These options controls what kind of annotations are being to be drawn\&.
.PP
\fB\-\-font\-size \fR\fB\fIfs\fR\fR
.RS 4
sets the font size, in points, for annotations\&.
.RE
.PP
\fB\-\-text\-color \fR\fB\fIcolor\fR\fR
.RS 4
text color for annotations\&. Default value is
\fIred\fR\&.
.RE
.PP
\fB\-\-verdict \fR\fB\fIheader\fR\fR
.RS 4
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:
.PP
%S
.RS 4
is replaced by the student total score\&.
.RE
.PP
%M
.RS 4
is replaced by the maximum total score\&.
.RE
.PP
%s
.RS 4
is replaced by the student mark\&.
.RE
.PP
%m
.RS 4
is replaced by the maximum mark\&.
.RE
.PP
%(ID)
.RS 4
is replaced by the student\*(Aqs name\&.
.RE
.PP
%(\fICOL\fR)
.RS 4
is replaced by the value of column
\fICOL\fR
in the students list for the current student\&.
.RE
.RE
.PP
\fB\-\-position \fR\fB\fIpos\fR\fR
.RS 4
sets the position where question scores are to be written:
.PP
marge
.RS 4
the scores will be written in the left margin
.RE
.PP
marges
.RS 4
the scores will be written in the closest margin (left or right)\&.
.RE
.PP
case
.RS 4
the scores will be written near the boxes
.RE
.PP
none
.RS 4
the scores won\*(Aqt be written\&.
.RE
.RE
.PP
\-\-verdict\-question \fIperl\-expression\fR
.RS 4
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:
.PP
%S
.RS 4
is replaced by the student score for this question\&.
.RE
.PP
%M
.RS 4
is replaced by the maximum score for this question\&.
.RE
.PP
%s
.RS 4
is the same as
%S, but rounded to
\fInc\fR
significant digits (see option
\fB\-\-ch\-sign\fR)\&.
.RE
.PP
%m
.RS 4
is the same as
%M, but rounded to
\fInc\fR
significant digits (see option
\fB\-\-ch\-sign\fR)\&.
.RE
.sp
A standard value for this option is
"\e"%s/%m\e""\&. You can also use tests (with the perl syntax
( TEST ? IF\-YES : IF\-NO )) to write
\fIValid\fR
if the score is the maximal score, or
\fIFailed\fR
if not, using
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-verdict\-question "(%S==%M ? \e"Valid\e" : \e"Failed\e")"
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-\-verdict\-question\-cancelled \fIperl\-expression\fR
.RS 4
same as
\fB\-\-verdict\-question\fR, but applies for cancelled questions (see
allowempty
scoring strategy)\&. The default value is
"X"\&.
.RE
.PP
\fB\-\-indicatives\fR
.RS 4
use this option to request boxes annotation for indicative questions (these questions\*(Aq scores won\*(Aqt 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)\&.
.RE
.PP
\fB\-\-line\-width \fR\fB\fIwidth\fR\fR
.RS 4
sets the line width (in points) when drawing symbols to correct answers\&.
.RE
.PP
\fB\-\-symbols \fR\fB\fIsymbols\-definition\fR\fR
.RS 4
defines how boxes will be annotated\&. symbols\-definition is a comma separated list of
\fIH\fR\-\fIA\fR:\fIshape\fR:\fIcolor\fR
constructs, where
\fIH\fR
is
0
or
1
depending on whether the box has to be checked or not,
\fIA\fR
is
0
or
1
depending on whether the box is actually checked or not,
\fIshape\fR
is one of
none,
circle,
mark,
box
and
\fIcolor\fR
is a color (name or #RGB, see ImageMagick or GraphicsMagick documentation for details)\&.
.sp
Default value is "0\-0:none,0\-1:circle:red,1\-0:mark:red,1\-1:mark:blue"\&.
.RE
.SS "Lengths"
.PP
The following length can be given with a unit (in,
ft,
pt,
cm
or
mm)\&.
.PP
\fB\-\-dist\-to\-box \fR\fB\fId\fR\fR
.RS 4
sets the distance from the boxes (going left) where to write questions scores when using
\fB\-\-position case\fR\&.Defaults to
1cm\&.
.RE
.PP
\fB\-\-dist\-margin \fR\fB\fId\fR\fR
.RS 4
sets the margin size\&. Defaults to
5mm\&.
.RE
.PP
\fB\-\-dist\-margin\-global \fR\fB\fId\fR\fR
.RS 4
sets the margin size for the header\&. Defaults to
3mm\&.
.RE
.SH "AUTHORS"
.PP
\fBAlexis Bienven\(:ue\fR <\&paamc@passoire.fr\&>
.RS 4
Main author
.RE
.PP
\fBAnirvan Sarkar\fR
.RS 4
Author and Editor
.RE
.PP
\fBHiroto Kagotani\fR
.RS 4
Editor
.RE
.PP
\fBFr\('ed\('eric Br\('eal\fR
.RS 4
Author and Editor
.RE
.PP
\fBJean B\('erard\fR
.RS 4
Translation from French
.RE
.PP
\fBGeorges Khaznadar\fR
.RS 4
Translation from French
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2008-2022 Alexis Bienven\(:ue
.br
.PP
This document can be used according to the terms of the GNU General Public License, version 2 or later.
.sp