AMC-TXT source file

For users who are not ready to learn LaTeX (if not already familiar with this language), AMC includes a filter to process simple plain text files in a particular format, named AMC-TXT. This section is devoted to detail the syntax of AMC-TXT files. If you prefer use LaTeX to gain a fine-control over your questionnaires, skip to next section.

Let us begin with a simple example:

# AMC-TXT source file
Title: My first AMC questionnaire

Presentation: Please answer the following questions
the best you can.

* What is the capital city of Cameroon?
+ Yaounde
- Douala
- Kribi

** From the following numbers, which are positive?
- -2
+ 2
+ 10

The file that contains your questionnaire must be a plain text file, UTF-8 encoded. This is the default encoding of several text editors, like gedit. Don’t use a text editor that can format your text with bold, images, and so on, like OpenOffice/LibreOffice, or equivalent: these save your text with a lot of other data, and AMC won’t be able to read it.

The default font that will be used is libertine, an open source font that contains characters for a lot of languages. You have to install this font or choose another one (see options below). If you install AMC with a debian/ubuntu package, this font will be install together as a recommended package.

You already understand AMC-TXT structure: some general options first, and then questions.

Comments

You can write some comments inside your AMC-TXT source file in lines beginning with a #. These lines won’t be considered by AMC.

General options

Here are the options you can use (in any order):

Lang

use it to specify a language the questionnaire is written in. At present, only DE (German), ES (Spanish), FR (French), IT (Italian), NL (Dutch), NO (Norwegian), PT (portuguese), JA (Japanese, see Japanese language) and AR (Arabic, see Arabic language) are supported. Without this option, English will be selected. You can also define the localized string used for another language (see the L-xxx options).

PaperSize

Sets the paper size. Possible values are A3, A4, A5, A6, B3, B4, B5, B6, letter, legal, ANSIA, ANSIB, ANSIC, ANSID, ANSIE.

LaTeXEngine

LaTeX engine : xelatex -shell-escape, for example.

Title

The exam title, written on top of the sheet.

Presentation

A text that presents the exam (length, rules
​).

ShuffleQuestions

If 1 (default), questions will be shuffled so that their order is different from one sheet to the other. If 0, the questions will always show with the same order as in your file.

RandomSeed

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

The value is saved in the xy file (as \rngstate{1}{1527384}). The default value is equal to 1527384.
Code

Give a positive integer value <n> to add boxes so that students will be able to code their student number on their sheets, with <n> digits.

CodeDigitsDirection

Sets the direction for code’s digits boxes (either vertical or horizontal). If unset, AMC will choose the direction from the number of digits (horizontal for small number of digits, and vertical for high number of digits).

Columns

Give a positive integer value <n> to get a subject with <n> columns.

CompleteMulti

If 1 (default), for multiple questions (those for which zero, one or several answers are correct), an answer "None of these answers are correct" will be added. Without it, it should be impossible to make a difference between "the student didn’t answer for this question" and "the student thinks no answer is correct for this question". If you don’t want this answer to be added, set this option to 0.

L-None

Give a string to replace None of these answers are correct (see previous option).

QuestionBlocks

If 1 (default), all questions will be enclosed in a invisible frame that prevents it to be split across several columns or pages. If 0, questions are allowed to be split if necessary: that can save pages at the cost of readability.

L-Question

Give a translation of Question in your questionnaire, if you need.

L-Name

Give a translation of Name and surname, a text written in the box where students are to write their identity.

L-Student

Small text that asks students to code their student numbers and write their name, when Code option is used.

TitleWidth

Width of the title zone, when Code: is not used. Default value is .47\linewidth.

NameFieldWidth

Width of the name field part. Usual LaTeX dimensions can be used. The default value is 5.8cm when Code: is used, and .47\linewidth without Code:.

NameFieldLines

Number of lines in the name field box. Default is 2 when Code: is used, and 1 otherwise.

NameFieldLinespace

Line space in the name field box. Defaut value is .5em.

Pages

Gives a minimal number of pages for each question sheet. If a question has less pages, some white pages will be added. When using a separate answer sheet, this option can be written q+a (eg. 4+2), where <q> will be the minimum number of pages for the question itself, and <q>+<a> the minimum number of pages for the whole sheet.

ManualDuplex

If 1 (this is not the default value), each subject will consist of an even number of pages, so that the user can manually print the PDF subject for all students in one go in duplex mode.

SingleSided

If 1 (this is not the default value), no blank page will be added between the question and the separate answer sheet, even if the question has an odd number of pages. This mode can be useful when the subjects are printed single-sided, or when it is not necessary to separate question and answer sheet.

BoxColor

Color of the boxes to be filled by the students. This allows to print the boxes with some color that won’t disturb too much the data capture (for example red, but some light gray can also be considered). The color has to be given as a valid xcolor color (see xcolor LaTeX package documentation for details), such as red, magenta, pink, lightgray, cyan, or in the form #RRGGBB, like #FFBEC8 for some light red.

DefaultScoringS

Default scoring strategy for simple questions (questions for which one and only one answer is correct). See Scale. for details. The default value gives one point for the right answer, and zero for others.

DefaultScoringM

Default scoring strategy for multiple questions (questions for which there can be zero, one or several correct answers). See Scale for details. The default value is haut=2, so that a perfect answer gives 2 points, and each error (ticking a box that should not be ticked, or leaving a box that should be ticked unticked) takes one point off (keeping the score non-negative).

LaTeX

Set this option to 1 if you want to use LaTeX commands in your texts. This allows for example to insert mathematical formulas, like $\sqrt{a+b}$. If 0 (default), all your texts will be written unmodified.

LaTeX-Preambule

Give commands you want to be added to the LaTeX preambule (for example \usepackage commands).

LaTeX-BeginDocument

Give commands to be inserted at the beginning of the LaTeX document environment (for example macro definitions).

LaTeX-BeginCopy

Give LaTeX commands to be inserted at the beginning of the copy description.

LaTeX-EndCopy

Give LaTeX commands to be inserted at the end of the copy description.

PDF-BeginCopy

Give the name of a PDF file to be inserted at the beginning of all copies of the exam.

PDF-EndCopy

Give the name of a PDF file to be inserted at the end of all copies of the exam.

Disable

Gives a comma-separated list of features to disable. Current implemented features are verbatim (see Verbatim content), images (see Images), embf (see Bold, italic, typewriter, underlined), local_latex (see Short pieces of LaTeX code) and latex (see LaTeX fragments).

PackageOptions

Gives some more options to pass to the automultiplechoice LaTeX package (see Package options).

Separate answer sheet

To use separate answer sheets for your questionnaire, consider the following options:

SeparateAnswerSheet

If 1, a separate answer sheet will be added.

AnswerSheetTitle

Title of the answer sheet.

AnswerSheetPresentation

Presentation of the answer sheet. For example, remind the students that the answers are to be given on this sheet only.

AnswerSheetColumns

Number of columns for the answer sheet.

AutoMarks

If 1, uses automarks option (see Package options).

Nominative sheets

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

PreAssociation

The list of the students' filename with .csv extension.

PreAssociationKey

Primary key from this list: the name of the column, in the list of students, with the students' numbers (see List of the students).

PreAssociationName

\forname\{} \name\{} headers in the students list for the current student

  • The students list has to be a CSV list. Suppose in the following that the file students.csv, in the project directory, is UTF8 encoded and that its content is like the following:

    name,forename,id,mail
Boulix,Jojo,001,jojo@boulix.fr
Golin,André,002,andre@golin.fr
Moniuszko,StanisƂaw,003,Moniuszko@StanisƂaw.fr

    Do not use _ (underscore) with the student’s name or forename. A compilation error will be displayed.

  • Code must be equal to zero or omitted.

# AMC-TXT source file and nominative sheets.

PaperSize: A4
Lang: EN
PreAssociation: students.csv
PreAssociationKey: id
PreAssociationName: \forename{} \name{}
Title: My first AMC questionnaire

Presentation: Please answer the following questions
the best you can.

* What is the capital city of Cameroon?
+ Yaounde
- Douala
- Kribi

** From the following numbers, which are positive?
- -2
+ 2
+ 10

More details about correction: see the last item Nominative sheets.

Questions

Simple questions (questions for which one and only one answer is correct) begin with a * at the beginning of the line, and multiple questions (questions for which there can be zero, one or several correct answers) begin with a **. Insert then the question itself, and the choices, introduced with a + for correct ones and with a - for wrong ones.

Questions options

Some options are available for questions. They must be separated by commas and enclosed by square brackets just after the leading `*’s, as in the following example:

*[ordered,horiz,id=sum] How much are
one plus one?
- 0
- 1
+ 2

Available options for questions:

horiz

present choices horizontally, not on separated lines.

columns=<n>

make <n> columns for the choices.

ordered

don’t shuffle the choices, keep the same order as in the description file.

id=<xxxx>

Give a name to the question, so as to locate the corresponding results easily in the exported spreadsheets. This name must contain only simple characters, without accents and LaTeX special characters such as _, ^, %
​

See also Identifier.

name can also be used instead of id for compatibility with old versions, but you should prefer using id.

indicative

don’t use this question score to compute the global student’s score.

next

Use this option if you want the question to stay next to the previous one, even when using questions shuffling with ShuffleQuestions general option.

first

Use this option to place the question always at the beginning of the group (see Questions groups).

last

Use this option to place the question always at the end of the group (see Questions groups).

Scoring strategy

You can set the scoring strategy for a particular question or choice enclosing it with braces just after the leading characters (*, **, + or -) and the possible options, as in the following example. See Scale for details about the scoring strategy syntax.

*{b=2,m=-1} What is the capital city of France?
+ Paris
- Lille
- Marseille
- Ouagadougou
-{-2} New York

**[ordered,horiz,id=positive]{haut=1} From the following numbers, which are positive?
- -2
+ 2
+ 10

Open questions

You can define open question giving options (see Open questions) enclosed with < and >, as in the following example:

*<lines=4> Describe the moon.
-[O]{0} O
-[P]{1} P
+[V]{2} V

You should also consider using the following global options:

L-OpenText

Text used to tell the student to write the answer on the separate answer sheet (if relevant).

L-OpenReserved

Text to be written along the open questions boxes to tell the student not to consider these boxes.

Multi-line

You can always continue some text on the next lines (even if some of them are empty), provided that these following lines cannot be considered as the beginning of an option definition, of a question or of a choice. As an example, consider the following question:

* How much are 2
+ 2?
- 0
+ 4
- 10

This is a correct AMC-TXT question. However, it won’t be treated as you’d like to, because here the second line is not considered as being the following of the first one, but form the first choice of the question!

A similar problem arises from the following AMC-TXT question, where ``Gershwin:’ is considered as a general option definition
​

* You all know Georges
  Gershwin: he is a composer.
  When was he born?
+ in 1898
- in 1892
- in 1902

This is a correct way to write it:

* You all know Georges Gershwin:
  he is a composer.
  When was he born?
+ in 1898
- in 1892
- in 1902

Note that line breaks can be inserted leaving an empty line, as:

Presentation: Title

Description of the exam.

** Difficult question.

How many stars in the sky?
- one
- two
- ten millions

Title

To get a title, enclose it between [== and ==].

Verbatim content

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

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

+ [| hello, world |]
- [| hello |]
- [| world |]

Bold, italic, typewriter, underlined

To get bold text, enclose it between [* and *]. To get italic text, enclose it between [_ and _]. To get typewriter text, enclose it between [| and |]. To get underlined text, enclose it between [/ and /].

* What is the [*capital city*] of [_France_]?
+ Paris
- Lille
- Marseille

Images

You can add images in your document using the following syntax:

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

Here, the image images/bird.png that is located in the project directory will be appended with 2cm height. Options that can be used inside the square brackets are those from the \includegraphics LaTeX command (width=3cm or keepaspectratio for example). To get a centered image that is three quarters of the line width, use

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

Short pieces of LaTeX code

You can include some small parts of LaTeX code in your document, including it in double square brackets, as in:

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

LaTeX fragments

To include a multi line LaTeX fragment, enclose it between [latex] and [/latex]:

* The following matrix is

[latex]
\[
\left[\begin{array}{ccccc}
1 & 0 & 0 & 0 & 1 \\
0 & 1 & 0 & 0 & 0 \\
0 & 0 & 1 & 0 & 0 \\
0 & 0 & 0 & 1 & 0 \\
0 & 0 & 0 & 0 & 1 \\
\end{array}
\right]\]
[/latex]

- diagonal
+ triangular
- symmetric

Questions groups

You can group some question so that they stay together even when shuffling, with the following syntax:

*( Questions about Martin Luther King.

* When was he born?
- in 1901
+ in 1929
- in 1968

* When did he die?
- in 1945
- in 1515
+ in 1968
- in 1999

* Where was he born?
+ Atlanta
- Memphis
- New York

*) End of questions on Martin Luther King.

You can specify some options on groups, like:

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

The following options are available:

shuffle=<xxx>

Give <true> or <false> to tell if you want to shuffle the questions inside the group. The default value if the global one, from the ShuffleQuestions option.

columns=<n>

Number of columns for the group’s questions.

group=<nom>

Give a name for the group (for internal matter).

numquestions=<n>

With this option, only the first <n> questions of the group will be used. If the questions are shuffled, this allows to get <n> questions chosen at random from the group.

Question with option first or last are not affected (they are always inserted). Moreover, questions stuck together with option next count as one single question.
needspace=<dimen>

Gives a height (dimension with unit, such as <4cm>) necessary to begin with the group. If the remaining vertical space on the current page is lower than this value, the group will begin on the next page.

Arabic language

Writing a questionnaire in Arabic is a little special. Use of course option

Lang: AR

You can also consider the following global options:

ArabicFont

This is the font used for Arabic text. Default value is Rasheeq, a font from the project ArabEyes (you can find it on debian/ubuntu in the ttf-arabeyes package).

To insert texts with non-Arabic characters, you must turn on LaTeX option and enclose these texts as a \textLR LaTeX command argument, as in \textLR{xelatex command}.

Japanese language

Japanese language questionnaires can be produced with option

Lang: JA

AMC will make some adjustments on the produced LaTeX source to allow Japanese characters to be included.

In this case, AMC will use pTex to process the LaTeX file made from your AMC-TXT source file. AMC needs a recent version of pTex to work.

Including other files

You can include other files with:

IncludeFile: file-to-include.txt

Be very careful when including a single file from different projects! Suppose for example that /home/alexis/questions-a.txt is included from projects A and B. You already processed project A, and you are currently working on project B. You update the scoring strategy of a question in /home/alexis/questions-a.txt, and also add another question. If you need to update the marks in project A with this new scoring strategy, AMC will also see a new question for which no data capture has been made, and this will spoil all your marks in A
​

A minimal example (a little bit more complete)

An example from french forum

# A minimal example (a little bit more complet)
PaperSize: A4
Lang: FR
CompleteMulti: 0 (1)
ShuffleQuestions: 0 (2)
LaTeX:1 (3)
LaTex-Preambule: \geometry{hmargin=2cm,headheight=2cm,headsep=.3cm,footskip=1cm,top=2.5cm,
bottom=2cm}

\usepackage{siunitx} (4)
\sisetup{locale = FR,detect-all,group-minimum-digits=3,per-mode=symbol}

\usepackage[french]{babel} (5)

LaTeX-BeginDocument: \def\multiSymbole{$\star$} (6)

Title: Évaluation de SVT \no{}4   : RĂ©gimes et Ă©quilibres alimentaires

Presentation: Colorier en noir la case correspondante Ă  la proposition correcte pour chaque
 phrase.

*([shuffle=true] (7)
 PARTIE I : Quelques connaissances du cours

**[horiz,last]Les aliments contiennent : (8)
+ Des lipides
- Des acides
+ Des sels minéraux

**La dépense énergétique minimum de notre corps est :
+ Le métabolisme de base
- Les besoins énergétiques
- L'IMC

**[columns=2]Les aliments nous apportent de :
+ La matiĂšre
- Du diabĂšte
+ De l'Ă©nergie

**[columns=2]Les besoins énergétiques d'une personne varient suivant :
+ Le sexe
+ Les activités physiques
- Les aliments consommés

*[columns=2]Manger équilibré signifie :
+ Equilibrer nos apports et nos dépenses
- Manger ce qui nous fait envie
- Manger plus que ce qu'on dépense

**[columns=2]Manger en excĂšs par rapport Ă  ses besoins peut aboutir Ă  :
- Des carences
+ Des maladies cardio-vasculaires
- Un manque de nutriments

**[columns=2]L'IMC signifie :
- Indice de Maladies cardio-vasculaires
+ Indice de Masse Corporelle
- Indice de MatiĂšre et de Composition

*)

*(PARTIE II : Le goûter de Vanessa

**[columns=2]Dans le gouter de Vanessa, l'aliment le plus énergétique est :
- les pruneaux
+ Les biscuits
- les deux sont identiques.

**[columns=2]Par rapport aux biscuits, les pruneaux contiennent  :
+ moins de protides
- plus de glucides
+ moins de lipides

**[columns=2]Les dépenses énergétiques journaliÚres d'une adolescente
  sont en moyenne de \qty{10000}{\kilo\joule}. (9)
  Vanessa a consommé \qty{3200}{kJ} au petit-déjeuner, \qty{3500}{kJ} à midi et
  \qty{2400}{\kilo\joule} au diner. Elle a donc mangé équilibré :
- Faux
+ Vrai

*)
1 The answer "None of these answers are correct" will be not added.
2 Questions will not be shuffled.
3 Allow to insert LaTeX code in all texts.
4 Different usefull packages included in the preambule.
5 Use of LaTeX language through the babelpackage.
6 The multisymbole is now a star.
7 Those questions will be shuffled.
8 This question will be always at last position.
9 LaTeX:1 and LaTeX-Preambule make possible this LaTeX code.