QCM – A L^{A}TEX 2ε package for making Multiple Choices Questionnaires^{∗}

Didier Verna

               mailto:didier@lrde.epita.fr
            http://www.lrde.epita.fr/~didier

November 27, 2004

Abstract

QCM is a package for making multiple choices questionnaires (“QCM” is the corresponding French acronym) under L^{A}TEX 2ε. A special environment allows you to define questions and possible answers. You can specify which answers are correct and which are not. QCM not only formats the questions for you, but also generates a “form” (a grid that your students will have to fill in), and a “mask” (the same grid, only with correct answers properly checked in). You can then print the mask on a slide and correct the questionnaires more easily by superimposing the mask on top of students’ forms.

The QCM package is Copyright \begin{matrix}c \\ ◯ \end{matrix} 2004 Didier Verna, and distributed under the terms of the LPPL license.

1 Using QCM (attention users of version 1)

As of version 2.0, QCM comes both in style and class form. The style provides all the basic features: making questions, generating the form and the mask… You can use it with any class you want, which is useful when you want to incorporate multiple choice questions in a larger document (a full exam for instance).

If you want to make simple multiple choice questionnaires, with just a list of questions, you can alternately use the class which provides some basic formatting on top of the style itself.

2 The QCM Style

First of all, please note that QCM requires the packages ifthen, calc and tabularx. As of version 2.1, the verbatim package is also required. You don’t have to require these packages explicitly though. As long as L^{A}TEX 2ε is able to locate them, they will be used automatically.

In order to use the QCM style, say \usepackage[⟨options⟩]{qcm} in the preamble of your document. The available options are described along the text, where appropriate.

∗This document describes QCM v2.1, class release date 2004/11/27, style release date 2004/11/27.

2.1 Creating Questions

Here’s a simple example demonstrating how to produce a new question:

 \begin{question}{What is the color of Henri the Fourth's white horse?}
   \false black,
   \true white,
   \false yellow,
   \false red.
 \end{question}
 \begin{correction}
 The correct answer is white, because it's in the question.
 \end{correction}

2.1.1 The question environment

question The question environment allows you to insert questions into your document. It takes one mandatory argument which specifies the actual question’s text. The question will be displayed in a frame box, the size of the line.

\true The proposed answers are displayed below the question in a list fashion (the \false question environment is a list-based one). Instead of using \item however, use

either \true or \false to insert a possible answer.

2.1.2 Question Numbers

The question environment is associated with a L^{A}TEX counter named question. This counter stores the number of the next (or current) question. It is initialized to 1, and automatically incremented at the end of question environments. You might want to use it to format question titles. For instance, you could decide that each question belongs to a subsection in the article class, and use something like

this before each question: \subsection*{Question \thequestion}

2.2 The Form and the Mask

Based on the questions appearing in your document, QCM has the ability to generate a “form” (a grid that your students will have to fill in), and a “mask” (the same grid, only with correct answers properly checked in). This can make the correction process easier.

\makeform To generate a form and a mask, use the macros \makeform and \makemask. \makemask QCM uses two auxiliary files to build them. These files have respectively an

extension of frm and msk. If you use these macros, you will need two passes of L^{A}TEX 2ε in order to get a correctly formatted document.

2.3 Typesetting corrections

correction As of version 2.1, QCM comes with a “correction” mode which allows you to automatically typeset and distribute corrections to your students. These corrections are slightly modified versions of your questionnaire: each possible answer is prefixed with a small symbol (a visual clue) indicating whether the answer was correct or wrong. In addition, you can typeset explanations below each question.

To activate the correction mode, use the correction option. It is off by default.

To typeset explanations below the questions, use the correction environment (no argument). The contents of this environment is displayed only in correction mode. In normal mode, it is simply discarded.

In addition, note that QCM cancels the actions performed by \makeform and \makemask in correction mode. This is to avoid further edition of the source when typesetting a correction.

2.4 Important Note

Currently, QCM requires that you provide a constant number of proposed answers across all questions in your QCM. This is something natural when you want to build forms, but this might me too restrictive otherwise, I’m not sure, so it is possible that this restriction will be removed in future versions.

Currently, there is a built-in mechanism for checking that the number of proposed answers remains constant: when QCM encounters the first occurrence of the question environment, it remembers the number of proposed answers from there. Afterwards, any noticed difference in subsequent occurrences will generate an error. As a consequence, you never have to tell QCM explicitly what that number is.

2.5 Customizing the QCM style

2.5.1 The question environment

\questionspace \questionspace is the amount of extra vertical space to put under the question,

before the list of proposed answers. This is a L^{A}TEX length that defaults to 0pt.

\answerstitlefont Before the list of possible answers, a short title is displayed (for English, it reads “Possible answers:”). The \answerstitlefont macro takes one mandatory argument which redefines the font to use for the answers title. By default,

\bfseries is used.

\answernumberfont Each proposed answer in the list is numbered automatically (and alphabetically). The \answernumberfont macro takes one mandatory argument which redefines the font to use for displaying the answer number. By default, \bfseries is used.

2.5.2 The Form and the Mask

\headerfont The \headerfont macro takes one mandatory argument which redefines the font to use for the headers (first line and first column) of the form and mask arrays. By default, \bfseries is used.

\X In the mask, correct answers are checked in by filling the corresponding cell with an “X” character. If you want to change this, call the \X macro with one (mandatory) argument.

2.5.3 The correction

\truesymbol In correction mode, labels in front of answers are modified to give a visual clue \falsesymbol about whether the answer was correct or wrong. By default, a cross and a small

arrow are used. You can change these symbols by using the \truesymbol and \falsesymbol macros. For instance, you could give a fancier look to your correction by using the pifont package and issuing:

 \truesymbol{\ding{'063}~}
 \truesymbol{\ding{'067}~}

\correctionstyle The appearance of the contents of the correction environment can be adjusted by using the \correctionstyle macro. By default, \itshape is used.

2.5.4 Internationalization

english QCM currently supports English, and French. You can select the language you

french, francais want to use by using the corresponding option. The french and francais options are synonyms. If you want a finer grain on the language-dependent parts of QCM, the following macros are provided.

\answerstitle This macro takes one mandatory argument which lets you redefine the answers’titles. For English, the answers title defaults to “Possible answers:”.

3 The QCM Class

The QCM class provides a wrapper around the style to allow you to format simple multiple choice questionnaires, with just a list of questions.

In order to use the QCM class, say \documentclass[⟨options⟩]{qcm} at the beginning of your document. The available options are described along the text, where appropriate. Note that the underlying QCM style is loaded automatically.

3.1 Standard Class Features

3.2 Page Size and layout

a4paper The a4, a5, b4, letter, legal and executive “paper” options allow you to

a5paper
b4paper
letterpaper
legalpaper
executivepaper
landscape

select the type of page format you want. By default, letterpaper is used. The landscape options switches the horizontal and vertical settings. I’m not sure why I propose this option. Nobody wants to write a QCM in landscape mode, right?

QCM also supports the standard oneside and twoside class options. By

oneside
twoside

default, oneside is used. In twoside mode, odd and even pages have a different geometry and headings layout.

3.3 Font Size

10pt The 10pt, 11pt and 12pt options let you choose the size of the default font you

11pt
12pt

want to use. By default, 10pt is used.

3.4 Output Mode

final In draft mode, a black rule will be drawn at the end of overfull lines (as done by draft standard classes).

3.5 Page styles

QCM supports the standard L^{A}TEX page style mechanism. Available styles are empty, plain, headings and myheadings. These styles have their usual meaning, except that there are no sectioning commands in the QCM class. By default, the page style is plain. Also, note that the form and the mask have an empty page style, whatever the setting for the rest of the document.

3.6 Title

\title The \title macro takes one mandatory argument which defines a title for your questionnaire (repeated on the form and the mask). It can be used in the document’s preamble only. The title will be centered on the page.

\titlefont The \titlefont macro takes one mandatory argument which redefines the

font to use for the title. By default, \LARGE\bfseries is used.

\titlespace \titlespace is the amount of extra vertical space to put after the title. This

is a L^{A}TEX length that defaults to 20pt.

\maketitle If you have defined a title, make it appear by calling \maketitle after the beginning of your document. If you call \maketitle without having defined a title, an error will be generated.

3.7 Modifications to the question environment

The QCM class modifies the question environment so as to display a title before each question (something that you would probably do with a sectioning command in other classes). This title is displayed in a frame box, the size of a quarter of the line. For English, the default reads “Question n.⟨X ⟩:”.

3.8 Modifications to \makeform and \makemask

The QCM class modifies \makeform and \makemask along the following lines: each grid is printed on a page of its own, and the document’s title is repeated on top of each. Also, the page style is set to empty.

3.9 Customizing the QCM class

3.9.1 The question titles

\questiontitlefont The \questiontitlefont macro takes one mandatory argument which redefines

the font to use for each question title. By default, \bfseries is used.

\questiontitlespace \questiontitlespace is the amount of extra vertical space to put after the question title (and before the questions’ text). This is a L^{A}TEX length that defaults

to 5pt.

\questionsepspace In addition, questions are separated from each other by some vertical space. \questionsepspace is the amount of extra vertical space to put between each question block. This is a L^{A}TEX length that defaults to 20pt.

3.9.2 Internationalization

english QCM currently supports English, and French. You can select the language you

french, francais want to use by using the corresponding option. The french and francais options are synonyms. If you want a finer grain on the language-dependent parts of QCM, the following macros are provided.

\questiontitle This macro takes one mandatory argument which lets you redefine the questions’titles. For English, the question title defaults to “Question N.\thequestion:”.

4 AUC-TEX support

AUC-TEX is a powerful major mode for editing TEX documents in Emacs or XEmacs. In particular, it provides automatic completion of macro names once they are known. QCM supports AUC-TEX by providing a style file named qcm.el which contains AUC-TEX definitions for the relevant macros. This file should be installed to a location where AUC-TEX can find it (usually in a subdirectory of your L^{A}TEX styles directory). Please refer to the AUC-TEX documentation for more information on this.

For people already knowing AUC-TEX: note that the AUC-TEX command LaTeX-insert-item (usually bound to M-Ret) inserts \false by default in a QCM, since it replaces \item. If you want to insert a \true, use a prefix.

5 Style Code

 1 \NeedsTeXFormat{LaTeX2e}
 2 \ProvidesPackage{qcm}[2004/11/27 v2.1
 3  Multiple Choice Questionnaire style for LaTeX2e]

4

 5 \RequirePackage{ifthen}
 6 \RequirePackage{calc}
 7 \RequirePackage{verbatim}
 8 \RequirePackage{tabularx}

9

5.1 The Form and Mask

Here are the customization parameters:

10 \def\@headerfont{\bfseries}
11 \newcommand\headerfont[1]{\gdef\@headerfont{#1}}

12

13 \def\@X{X}
14 \newcommand\X[1]{\gdef\@X{#1}}

15

We use two new column types in the form and mask arrays: Q for header cells and D for data cells. We also use centered cells for the X specification. Note that this might clash with a user setting one day, but let’s not anticipate problems.

16 \def\pbs#1{\let\tmp=\\#1\let\\=\tmp}
17 \newcolumntype{D}{>{\pbs\centering}X}
18 \newcolumntype{Q}{>{\@headerfont}X}

19

20 \renewcommand\tabularxcolumn[1]{m{#1}}

21

22 \newcommand\makeform@nocorrection{%
23 \addtocontents{frm}{\protect\end{tabularx}}

24 \@starttoc{frm}}
25 \newcommand\makeform@correction{%
26 \addtocontents{frm}{\protect\end{tabularx}}}

27

28 \newcommand\makemask@nocorrection{%
29 \addtocontents{msk}{\protect\end{tabularx}}
30 \@starttoc{msk}}
31 \newcommand\makemask@correction{%
32 \addtocontents{msk}{\protect\end{tabularx}}}

33

5.2 The question Environment

Here are the customization parameters:

34 \newlength\questionspace
35 \setlength\questionspace{0pt}

36

37 \newcommand\answerstitle[1]{\gdef\@answerstitle{#1}}

38

39 \def\@answerstitlefont{\bfseries}
40 \newcommand\answerstitlefont[1]{\gdef\@answerstitlefont{#1}}

41

42 \def\@answernumberfont{\bfseries}
43 \newcommand\answernumberfont[1]{\gdef\@answernumberfont{#1}}

44

The question counter starts at one, and is incremented at the end of each question.

45 \newcounter{question}\stepcounter{question}
46 \newcounter{@choice}

47

The macro \@initorcheck is called at the end of each question. After the first one, it initializes the number of proposed answers (this must be constant across all questions). This is used to build the form and mask arrays description lines, and initialize the auxiliary files. Afterwards, it redefines itself so that subsequent calls will just check that the number of answers remains the same across all questions.

48 \def\@initorcheck{%
49 \xdef\@choices{\the@choice}%
50 \setcounter{@choice}{1}%
51 \gdef\@arraydesc{|Q||}%
52 \gdef\@headerline{}%
53 \whiledo{\not{\value{@choice}>\@choices}}{
54  \xdef\@arraydesc{\@arraydesc D|}
55  \def\@appendheader{\g@addto@macro\@headerline}
56  \@appendheader{&\protect\@headerfont}
57  \edef\@the@choice{{\alph{@choice}}}
58  \expandafter\@appendheader\@the@choice
59  \stepcounter{@choice}}%
60 \addtocontents{frm}{%
61  \protect\begin{tabularx}{\protect\linewidth}{\@arraydesc}
62  \protect\hline
63  \@headerline\protect\\\protect\hline\protect\hline}%
64 \addtocontents{msk}{%

65  \protect\begin{tabularx}{\protect\linewidth}{\@arraydesc}
66  \protect\hline
67  \@headerline\protect\\\protect\hline\protect\hline}%
68 \gdef\@initorcheck{%
69  \ifthenelse{\value{@choice} = \@choices}{}{%
70  \ClassError{QCM}{Question \thequestion: wrong number of choices
71  (\the@choice\space instead of \@choices)}{%
72  Questions must all have the same number of proposed answers.%
73  \MessageBreak
74  Type X <return> to quit, fix your QCM and rerun LaTeX.}}}}

75

A minipage environment is used in order to prevent page breaks in the middle of a question.

76 \newenvironment{question}[1]{%
77 %% \begin{question}
78 \begin{minipage}{\textwidth}

Each line in the form and mask arrays is stored in the macros \@formanswerline and \@maskanswerline. They are initialized here, updated progressively by each call to \true or \false, …

79  \xdef\@formanswerline{\@questionheader}%
80  \xdef\@maskanswerline{\@questionheader}%
81  \fbox{\parbox[c]{\linewidth}{#1}}
82  \vspace\questionspace\par
83  {\@answerstitlefont\@answerstitle}
84  \begin{list}{\@answernumberfont\alph{@choice}.~}{\usecounter{@choice}}}{%
85 %% \end{question}
86  \end{list}
87  \@initorcheck%

… and added to the form and mask auxiliary files here:

88  \addtocontents{frm}{\@formanswerline\protect\\\protect\hline}%
89  \addtocontents{msk}{\@maskanswerline\protect\\\protect\hline}%
90 \end{minipage}
91 \stepcounter{question}}

92

93 \def\@truesymbol{$\rightarrow$~}
94 \def\@falsesymbol{$\times$~}
95 \newcommand\truesymbol[1]{\gdef\@truesymbol{#1}}
96 \newcommand\falsesymbol[1]{\gdef\@falsesymbol{#1}}

97

98 \def\@true@nocorrection{\item}
99 \def\@false@nocorrection{\item}
100 \def\@true@correction{\item[\@truesymbol\refstepcounter{@choice}]}
101 \def\@false@correction{\item[\@falsesymbol\refstepcounter{@choice}]}

102

103 \newcommand\true{%
104 \xdef\@formanswerline{\@formanswerline&}%
105 \xdef\@maskanswerline{\@maskanswerline&\@X}%
106 \@true}%
107 \newcommand\false{%
108 \xdef\@formanswerline{\@formanswerline&}%
109 \xdef\@maskanswerline{\@maskanswerline&}%
110 \@false}%

5.3 The correction environment

Here, we only define the visible version of the correction environment. The other one is provided by verbatim’s comment environment.

112 \def\@correctionstyle{\itshape}
113 \newcommand\correctionstyle[1]{\gdef\@correctionstyle{#1}}

114

115 \newenvironment{@correction}{\@correctionstyle}{}

116

5.4 Internationalization

117 \DeclareOption{english}{%
118 \def\@questionheader{Question n.\thequestion}
119 \answerstitle{Possible answers:}}
120 \DeclareOption{french}{%
121 \def\@questionheader{Question n$^o$~\thequestion}
122 \answerstitle{R\'eponses possibles~:}}
123 \DeclareOption{francais}{%
124 \ExecuteOptions{french}}

125

5.5 Options Processing

Note that we don’t use \let but \def to implement the correct behavior of \makeform and \makemask. This is because when using the class, the underlying macros might be redefined, so we want to use their latest definition.

126 \DeclareOption{nocorrection}{%
127 \let\@true\@true@nocorrection
128 \let\@false\@false@nocorrection
129 \let\correction\comment
130 \let\endcorrection\endcomment
131 \def\makeform{\makeform@nocorrection}
132 \def\makemask{\makemask@nocorrection}}
133 \DeclareOption{correction}{%
134 \let\@true\@true@correction
135 \let\@false\@false@correction
136 \let\correction\@correction
137 \let\endcorrection\end@correction
138 \def\makeform{\makeform@correction}
139 \def\makemask{\makemask@correction}}

140

141 \ExecuteOptions{english,nocorrection}
142 \ProcessOptions

143

6 Class Code

144 \NeedsTeXFormat{LaTeX2e}
145 \ProvidesClass{qcm}[2004/11/27 v2.1
146  Multiple Choice Questionnaire class for LaTeX2e]

148 \RequirePackage{qcm}[2004/11/09]

149

6.1 The Title

150 \def\@titlefont{\LARGE\bfseries}
151 \newcommand\titlefont[1]{\gdef\@titlefont{#1}}
152 \@onlypreamble\titlefont

153

154 \newlength\titlespace
155 \setlength\titlespace{20pt}

156

157 \@onlypreamble\title

158

\maketitle informs QCM that the title should be repeated on the form and mask pages by defining \@maketitle.

159 \def\@make@title{%
160 \begin{center}
161  \@titlefont\@title
162 \end{center}
163 \vspace\titlespace}
164 \let\@maketitle\empty
165 \newcommand\maketitle{%
166 \@make@title%
167 \let\@maketitle\@make@title}

168

6.2 The Form and Mask

The qcm style \makeform and \makemask macros are saved and wrapped into new ones that first repeat the document’s title on a new page. The page style is also set to empty.

For a reason I don’t recall anymore, \addtocontents fails to write anything in the auxiliary files when nothing has been written on the page yet. To cope with this problem, we restate the title first.

169 \let\old@makeform@nocorrection\makeform@nocorrection
170 \def\makeform@nocorrection{%
171 \newpage
172 \@maketitle
173 \thispagestyle{empty}
174 \old@makeform@nocorrection}

175

176 \let\old@makemask@nocorrection\makemask@nocorrection
177 \def\makemask@nocorrection{%
178 \newpage
179 \@maketitle
180 \thispagestyle{empty}
181 \old@makemask@nocorrection}

182

6.3 The question Environment

183 \newcommand\questiontitle[1]{\gdef\@questiontitle{#1}}

185 \def\@questiontitlefont{\bfseries}
186 \newcommand\questiontitlefont[1]{\gdef\@questiontitlefont{#1}}

187

188 \newlength\questiontitlespace
189 \setlength\questiontitlespace{5pt}

190

191 \newlength\questionsepspace
192 \setlength\questionsepspace{20pt}

The real space used is \@questionsepspace. It is initialy set to 0 to prevent extra space from appearing before the first question. It is redefined to the real value at the end of the question environment.

193 \gdef\@questionsepspace{0pt}

194

The qcm style question environment is saved and wrapped into a new one that outputs a question title.

195 \let\old@question\question
196 \let\old@endquestion\endquestion
197 \renewenvironment{question}[1]{%
198 %% \begin{question}
199 \vspace\@questionsepspace
200 \fbox{\parbox[c]{0.25\linewidth}{\@questiontitlefont\@questiontitle}}
201 \nopagebreak\vspace\questiontitlespace\par
202 \old@question{#1}}{%
203 %% \end{question}
204 \old@endquestion
205 \gdef\@questionsepspace{\questionsepspace}}

206

6.4 Language Processing

207 \DeclareOption{english}{%
208 \questiontitle{Question N.\thequestion:}}
209 \DeclareOption{french}{%
210 \questiontitle{Question N$^{o}$~\thequestion~:}}
211 \DeclareOption{francais}{%
212 \ExecuteOptions{french}}

213

6.5 Standard Class Processing

214 \DeclareOption{a4paper}{
215 \setlength\paperheight{297mm}
216 \setlength\paperwidth{210mm}}
217 \DeclareOption{a5paper}{
218 \setlength\paperheight{210mm}
219 \setlength\paperwidth{148mm}}
220 \DeclareOption{b5paper}{
221 \setlength\paperheight{250mm}
222 \setlength\paperwidth{176mm}}
223 \DeclareOption{letterpaper}{
224 \setlength\paperheight{11in}
225 \setlength\paperwidth{8.5in}}
226 \DeclareOption{legalpaper}{
227 \setlength\paperheight{14in}

228 \setlength\paperwidth{8.5in}}
229 \DeclareOption{executivepaper}{
230 \setlength\paperheight{10.5in}
231 \setlength\paperwidth{7.25in}}
232 \DeclareOption{landscape}{
233 \setlength\@tempdima{\paperheight}
234 \setlength\paperheight{\paperwidth}
235 \setlength\paperwidth{\@tempdima}}

236

237 \DeclareOption{10pt}{\def\@ptsize{0}}
238 \DeclareOption{11pt}{\def\@ptsize{1}}
239 \DeclareOption{12pt}{\def\@ptsize{2}}

240

241 \DeclareOption{oneside}{\@twosidefalse\@mparswitchfalse}
242 \DeclareOption{twoside}{\@twosidetrue\@mparswitchtrue}

243

244 \DeclareOption{draft}{\setlength\overfullrule{5pt}}
245 \DeclareOption{final}{\setlength\overfullrule{0pt}}

246

247 \ExecuteOptions{english,letterpaper,10pt,oneside,final}
248 \ProcessOptions

249

250 \input{size1\@ptsize.clo}
251 \setlength\parindent{0pt}
252 \setlength\parskip{0pt}
253 \setlength\tabcolsep{6pt}
254 \setlength\arrayrulewidth{0.4pt}
255 \raggedbottom
256 \onecolumn
257 \pagestyle{plain}
258 \pagenumbering{arabic}

259

260 \if@twoside
261 \def\ps@headings{%
262  \let\@oddfoot\@empty\let\@evenfoot\@empty
263  \def\@evenhead{\thepage\hfil\slshape\leftmark}%
264  \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
265  \let\@mkboth\markboth

266 }

267 \else
268 \def\ps@headings{%
269  \let\@oddfoot\@empty
270  \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
271  \let\@mkboth\markboth

272 }

273 \fi
274 \def\ps@myheadings{%
275 \let\@oddfoot\@empty\let\@evenfoot\@empty
276 \def\@evenhead{\thepage\hfil\slshape\leftmark}%
277 \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
278 \let\@mkboth\@gobbletwo

279 }

280

Well, I think that’s it. Enjoy using QCM!

Copyright \begin{matrix}c \\ ◯ \end{matrix} 2004 Didier Verna.

13