AMC-TXT syntax

For users who are not ready to learn LaTeX (if not already speaking 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 exemple:

# 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]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]Note

The default font that will be used is libertine, an open source font that contains chracaters 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), 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 allways show with the same order as in your file.

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.

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 qeustions will be enclosed in a invisible frame that prevents it to be splitted accross several columns or pages. If 0, questions are allowed to be splitted 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 udentity.

L-Student:

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

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 grey 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 anser 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 exemple 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 exemple \usepackage commands).

LaTeX-BeginDocument:

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

Disable:

Gives a comma-separated list of features to disable. Current implemented features are images (see the section called “Images”), embf (see the section called “Bold, italic”) and local_latex (see the section called “Pieces of LaTeX code”).

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 exemple, remind the students that the answers are to be given on this sheet only.

AnswerSheetColumns:

Number of columns for the answer sheet.

Questions

Simple questions (questions for which one and only one anser 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 exemple:

*[ordered,horiz,name=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.

name=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 _, ^, %...

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 exemple. 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,name=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 beginnig 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

Bold, italic

To get bold text, enclose it between [* and *]. To get italic 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 appened 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.

Arabic language

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

[Warning]Warning

For better working and portability, give an explicit value for L-Name and L-Student options.

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