AMC-TXT syntax

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

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

	Note
	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 the section called “Japanese language”) and AR (Arabic, see the section called “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.

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.

	Note
	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 the section called “Scoring strategy” 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 the section called “Scoring strategy” 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 the section called “Verbatim content”), images (see the section called “Images”), embf (see the section called “Bold, italic, typewriter, underlined”) and local_latex (see the section called “Pieces of LaTeX code”).

PackageOptions:

Gives some more options to pass to the automultiplechoice LaTeX package (see the section called “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 the section called “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 the section called “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
```
Warning
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 the section called “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 _, ^, %...

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 the section called “Questions groups”).

last

Use this option to place the question always at the end of the group (see the section called “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 the section called “Scoring strategy” 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 the section called “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!

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.

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.

	Note
	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).

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

	Warning
	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. Versions of pTex from texlive 2009, that can be found on old versions of some linux distributions, are not compatible.

Including other files

You can include other files with:

IncludeFile: file-to-include.txt

Warning

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  
ShuffleQuestions: 0  
LaTeX:1  
LaTex-Preambule: \geometry{hmargin=2cm,headheight=2cm,headsep=.3cm,footskip=1cm,top=2.5cm,
bottom=2cm}  

\usepackage{siunitx}  
\sisetup{locale = FR,detect-all,per-mode=symbol,quotient-mode=fraction,input-product=*,%
list-final-separator = { \translate{et} },list-pair-separator = { \translate{et} },%
range-phrase = { \translate{à} },separate-uncertainty = true,group-minimum-digits=3,%
per-mode=symbol,inter-unit-product=\ensuremath{{}\!\cdot{}\!{}}}

\usepackage[french]{babel}  

LaTeX-BeginDocument: \def\multiSymbole{$\star$}  

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]
 PARTIE I : Quelques connaissances du cours 

**[horiz,last]Les aliments contiennent : 
+ 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
\SI{10000}{\kilo\joule} .
 Vanessa a consommé \SI{3200}{kJ} au petit-déjeuner, \SI{3500}{kJ} à midi et
  \SI{2400}{\kilo\joule} au diner. Elle a donc mangé équilibré :
- Faux
+ Vrai

*)

	The answer "None of these answers are correct" will be not added.
	Questions will not be shuffled.
	Allow to insert LaTeX code.
	Different usefull packages.
	The multisymbole is now a star.
	Use of LaTeX language through the babelpackage.
	Those questions will be shuffled.
	This question will be always at last position.
	LaTeX:1 and LaTeX-Preambule make possible this LaTeX code.

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