============================== MCQ-XeLaTeX Full Documentation ============================== :Date: 2019-02-07 (updated 2023-04-21) .. highlight:: latex .. _MCQ-Latex: LaTeX documentation of mcq.sty ============================== The package can be called with any latex class, but recommended classes are ``article`` (for Multiple Choice Questions and Optical Mark Recognition). It also support the ``exam`` class(for open questions, see below :ref:`Exam`):: \documentclass{article} \usepackage{mcq} To install, download it: :download:`mcq.sty `. Then, put it somewhere. For example, in `ubuntu `__:: $ mkdir -p ~/texmf/tex/latex/mcq $ cd ~/texmf/tex/latex/mcq $ wget https://www.dlfer.xyz/var/mcq.sty $ texhash Package options: ~~~~~~~~~~~~~~~~ ``bubblesheet`` Print a cover sheet with the grid of bubbles (to be filled) for student UID and answers. ``dsa`` Use `OpenDyslexic `__ font, a typeface for Dyslexia. It has to be installed on the system. On ubuntu linux, for example:: $ sudo apt install fonts-opendyslexic ``extrasheet`` Print a second bubblesheet after the first, just in case, if the students are considered not careful enough in filling the bubbles (and therefore a high percentage will do a mistake). ``namedheader`` Print a named header, useful for when a multi-page document has to be returned by students, and therefore they need to write their own name on each sheet. ``noblankpage`` Do not print a blank page after the ``bubblesheet`` page. Usefule if one does not print on duplex printers. ``sol`` With this option, an explicit graphic mark will highlight the (correct) answers. Userful for proof-reading the exam document, but **absolutely** to remove befor generating the real production document. ``ttf`` Use the TTF version of `Linux Libertine `__ instead of the default OTF version. ``doexe`` when generating copies for the individual sheets, include not only ``exerm`` style questions, but also open-answer questions ``\begin{exe}...\end{exe}`` Preamble commands: ~~~~~~~~~~~~~~~~~~ ``\puntigiusta{}`` Number of points (float or signed integer) assigned to a correct answer. Typical value: *n - 1*, where *n* is the number of answers. Dafault value: ``1``. ``\puntisbagliata{}`` Number of points (float or signed integer) assigned to a wrong answer. Typical value: *-1*. Default value: ``0``. ``\puntiempty{}`` Number of points (float or signed integer) assigned to a ungiven answer. Typical value: *0*. Default value: ``0``. ``\formulavoto{}`` Formula to aggregate *x* = and *y* = . The exam might consist of a Multiple-Choice part, followed by some open questions or exercises. The mark of the MCQ part will be computed automatically, and denoted by . The mark of the open-ended part needs to be given by your grading. This formula is simply the way to sum the two parts, in python syntax. ``\UIDdigits{number}`` Number of UID digits. Default value: ``6``. ``\headline{text}`` Headline of the page (with info about the exam). ``\englishinfo`` Choose ``English`` language, instead of Italian, for the front sheet info. ``\variantlabel{ABC}`` Optional label to prepend to the permutation code of each sheet. ``\moodlecategory{categoryname/subcategory}`` Optional category name, in case a GIFT export is planned. Environments and list of questions: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Just after the ``\begin{document}``, one of the two following commands should appear: ``\nomeesame`` Write ``\Cognomename: \dotfill \Nomename: \dotfill \Firmaname:\dotfill``, or an analogue. ``\bubblesheet[optional number of columns]{number of questions}{number of anwsers}`` Print a cover page with fillable bubbles, to be fed to a document scanner and OMR. Then, there will be all questions/exercises, grouped in some environments. The top (numbered or \*-numbered) environment is ``esercizi``, which surrounds the list of questions, each given by an ``exerm`` or ``exe``. The ``exe`` type does not have any features. The ``exerm`` environment is a multiple choice question: its anwers are enumerated as in the following example:: % here a normal section of exercises \begin{esercizi}{Title of the section} \begin{exerm}[optional text] Body of the question. \begin{rispm}[2] % the optional argument is the number of columns of the answers. \risp[=] \risp \risp \risp \end{rispm} \end{exerm} ... continued \end{esercizi} % here an unnumbered section of exercises \begin{esercizi*}{Title of the unnumbered section} \begin{exerm} Body of the question. \begin{rispm} \risp[=] \risp \risp \risp \end{rispm} \end{exerm} ... continued \end{esercizi} The difference of ``esercizi`` and ``esercizi*`` is the same as the ``\section`` and ``\section*`` commands. The two questions/exercises types are ``exerm`` and ``exe``: the first is a **Multiple Choice Question**, the second is a normal **exercise**. More precisely, in ``exerm`` the question with answers can be formatted as in the following full example:: \begin{exerm}[Optional text] \qtitle{Optional command for the title of the question: it is not shown in the PDF} % the qtitle can be used to assign a unique ID to questions, % so that they can be kept in a Question Bank. Here write the text of the question. \begin{rispm}[4] % The answers will be on 4 columns. % The default value is 1. \risp[=] Correct answer % it will be graded as correct, with a number of points % given by \puntigiusta{number} command defined above \fb{Very well!} % This feedback is very important, for questions % converted to GIFT or HTML (interactive). \risp Wrong answer % it will be graded as wrong, if checked, with a number % of points given by \puntisbagliata{number} command \fb{No, you are wrong, since ...} % This feedback is very important, for questions % converted to GIFT or HTML (interactive). \risp[0.5] Kind of wrong answer. % It will be graded as an answer with a manual value, % given by the float 0.5. \fb{Almost correct! In fact ... (explanation)} % This feedback is very important, for questions % converted to GIFT or HTML (interactive). \risp[-10] Very wrong answer. % It will be graded with -10 points (signed integer). \fb{Very bad! You do not get it since (explanation)} % This feedback is very important, for questions % converted to GIFT or HTML (interactive). \end{rispm} \fb{General Feedback} \end{exerm} The other exercise type is a simple environment, that can be also used as follows:: \begin{exe}[Optional text] Text of the exercise \end{exe} \begin{sol} Solution \end{sol} Open answer questions can be used also to generate essay questions for MOODLE, with textarea solutions (visible with the ``sol`` mcq option and removed in the moodle exported version):: \begin{exe}[comment] \qtitle{Eventual tag of the question, it is only for MOODLE} How much is $1+1$? \blank{$2$} \end{exe} The GIFT output will be:: ::Eventual tag of the question, it is only for MOODLE:: How much is $1+1$? {} Questions with variants: ~~~~~~~~~~~~~~~~~~~~~~~~ Instead of just permuting the questions and the answers, it can randomly choose variants (with different numerical values, or different questions and different answers) of the questions. The syntax is as in the following example:: \begin{exerm} \begin{varianti} %% this is an exercise with two variants (randomly select just one of the two). \varitem $1+2=$? \begin{rispm} \risp[=] 3 \risp 2 \risp 1 \risp 0 \end{rispm} \varitem $2+3=$? \begin{rispm} \risp[=] 5 \risp 4 \risp 3 \risp 2 \end{rispm} \end{varianti} \end{exerm} The same can be done with ``\begin{exe} ... \end{exe}`` type exercises. When exportin in moodle GIFT format, all the variants will be sequentially exported. Other commands: ~~~~~~~~~~~~~~~ ``\begin{sol} ... \end{sol}`` It is a proof-like environment, for solutions of exercises. ``\WarningSign`` Default: the string ``★★!!★★````. ``\OrnamentalBreak`` An ornamental break (centered). ``\blank{Text of the solution}`` Will draw a blank line with space for a solution (until the end of the line). ``\blankarea[optional number of rows]{Text of the solution}`` Will draw a blank area with space for a solution. When compiled with the ``sol`` option:: \usepackage[sol]{mcq} the blank areas/lines will be filled with the texts of the solutions. Otherwise, they will be white or filled with squares. The default number of rows is 10, if omitted. Otherwise, it can be any positive integer. LaTeX variables: ~~~~~~~~~~~~~~~~ can be redefined with ``\renewcommand``, and are meant for internal use): ``\geninfo`` Definition of the text giving the instructions/info about the test/exam. ``\ansinfo`` Text to write before the bubblesheet answers. ``\uidname`` Name of the UID. Default: ``Matricola``. ``\Cognomename`` Name of FamilyName. Default: ``Cognome``. ``\Nomename`` Name of GivenName. Default: ``Nome``. ``\Firmaname`` Name of the signature. Default: ``Firma``. ``\SolName`` Name of the solution. Default: ``Soluzione``. ``\squarebox`` The character for the symbol appearing on the left of each possible item-answer. Check that the characters is included in the font Linux Libertine first. ``\variantlabel`` A label (possibly empty) to prepend to each permutation code. Further commands: ~~~~~~~~~~~~~~~~~ Other commands can be included in the [optional] file `mcq_commands.tex`. If it exists, it is included and processed automatically. If it does not exists, nothing is done (read the logs to see what happended). MCQ w/Bubblesheet example: ~~~~~~~~~~~~~~~~~~~~~~~~~~ An example of MCQ exam with bubblesheet (try to compile it with or without the ``sol`` package option):: %=================================================================== \documentclass[twoside,a4paper,leqno]{article} %=================================================================== \usepackage{mathpazo} % I like it. \usepackage[bubblesheet]{mcq} \englishinfo %% this if you want English sentences. \usepackage{polyglossia} \setdefaultlanguage{english} %% it needs to be *after* mcq. %=================================================================== \headline{Multiple Choice questions on Logic (2013-12-31)} %% this is the "name" of the exam % http://www.math.ucla.edu/\char`~tao/java/MultipleChoice/logic.txt \puntigiusta{6} % points for a correct answer \puntisbagliata{-1} % points for a wrong answer \puntiempty{0} % points for non-response. %=================================================================== \begin{document} \bubblesheet[2]{14}{7} % [number of columns] {number of questions} {number of answers} \begin{esercizi*}{} \begin{exerm}[Optional text] \qtitle{This is an unseen title} Let $X$ and $Y$ be statements. If we know that $X$ implies $Y$, then we can also conclude that \begin{rispm}[2] \risp $X$ is true, and $Y$ is also true. \fb{% This is a feedback comment (optional). Useful only in the conversion to HTML or for dynamical formats on MOODLE. } \risp[-2] $Y$ cannot be false. \fb{This was terribly wrong.} \risp[3] If $Y$ is true, then $X$ is true. \fb{Kind of true?} \risp[=] If $Y$ is false, then $X$ is false. \risp If $X$ is false, then $Y$ is false. \risp $X$ cannot be false. \risp[3.1415] At least one of $X$ and $Y$ is true. \end{rispm} \end{exerm} \begin{exerm} Let $X$ and $Y$ be statements. If we want to DISPROVE the claim that "Both $X$ and $Y$ are true", we need to show that \begin{rispm} \risp[=] At least one of $X$ and $Y$ are false. \risp $X$ and $Y$ are both false. \risp[0.5] $X$ is false. \fb{This will indeed disprove "Both $X$ and $Y$ are true", but $X$ does not need to be false in order to disprove the above statement.} \risp[0.5] $Y$ is false. \fb{This will indeed disprove "Both $X$ and $Y$ are true", but $Y$ does not need to be false in order to disprove the above statement.} \risp $X$ does not imply $Y$, and $Y$ does not imply $X$. \risp Exactly one of $X$ and $Y$ are false. \risp $X$ is true if and only if $Y$ is false. \end{rispm} \end{exerm} (..omissis..) \end{esercizi*} \end{document} .. _Exam: An exam class example: ~~~~~~~~~~~~~~~~~~~~~~ Some commands taken from the `exam latex class `__:: \documentclass{exam} \pointpoints{point}{points} \bonuspointspoints{bonus point}{bonus points} \qformat{Format specification} \bonusqformat{Format specification} \chqword{Exercise:} \chpword{Points:} \chbpword{Bonus points:} \chtword{Total} An example of an exam with blankareas and no bubblesheet (try to compile it with or without the ``sol`` option):: %=================================================================== \documentclass[twoside,a4paper,leqno,addpoints]{exam} %=================================================================== \usepackage{mathpazo} \usepackage[noblankpage,sol]{mcq} \usepackage[italian]{babel} \headline{Analisi 2 - Scritto \#3 -- 2019-02-25, 1430-1630, aula U2-07} %=================================================================== \usepackage{xspace} \newcommand{\quindi}{\fontspec[Scale=1.0]{Junicode}\char"2234\xspace} %=================================================================== \begin{document} \nomeesame \norme{\itshape\small Norme per la prova: \begin{compactenum} \item Scrivere cognome, nome e numero di matricola negli appositi spazi. \item Consegnare \emph{solo} il presente fascicolo. \item Rispondere alle domande utilizzando gli appositi spazi. \item Tempo: 120 minuti. \item I punti di ciascun esercizio sono indicati tra parentesi. \item I punti \emph{bonus} valgono soltanto se le parti precedenti nell'esercizio sono state valutate con punteggio pieno. \end{compactenum} } \begin{questions} \question[3] Il limite \begin{equation*} \lim_{(x,y) \to (0,0)}\, \frac{x \, {|y|}^\alpha}{x^2 + y^2} \end{equation*} esiste se e solo se $\alpha \in $ \blank{$(1,+\infty)$} \question[3] Sia $T$ il triangolo in $\mathbb{R}^2$ di vertici $\left(1,1\right)$, $\left(2,2\right)$ e $\left(1, 3\right)$. Calcolare l'integrale $\displaystyle \int_T xy\, dx\, dy =$ \blank{$\frac{8}{3}$} (..omissis..) \OrnamentalBreak \question[8] Sia $f_n(x) = \dfrac{\sin^2 nx}{n}$, e $f(x) = \lim_n f_n(x)$, dove esiste. Determinare in quali punti di $\mathbb{R}$ la successione $f_n$ converge puntualmente a $f$. \blankarea[5]{% $\forall x\in \mathbb{R}$, $\left|{\sin^2 nx}\right|\leq 1$, e quindi $\lim_n -\frac{1}{n} \leq \lim_n f_n(x) \leq \lim_n \frac{1}{n} $, \quindi $\lim_n f_n(x) = 0 $, $\forall x\in \mathbb{R}$. } \end{questions} \clearpage \fillwithdottedlines{\stretch{1}} \begin{center} \combinedpointtable[h] \end{center} \end{document} .. _MCQ-CLI: Documentation of the CLI ======================== The Command Line Interface, which runs simply by:: $ mcq.py has can be summarized by the following graph. Full documentation and use instructions are shown in the interface itself. .. graphviz:: digraph { welcome [shape = box, label="Welcome\n[prompt = ' mcq->>']" ] ; open [shape = oval , label = "Open a XeLaTeX file\n(uiFileNavigator)\n[prompt = '(File)mcq[folder]->> ']" ] ; create [shape = oval , label = "Create from guided template \n (newfileloop)\n[prompt='(New)mcq[default] >']" ] ; exit [shape = box, label="Exit" ]; active [shape = box, label = "Active File= 'file.tex'\n (uiMasterFile)\n[prompt='(Work)mcq[folder]->> '" ]; welcome -> open [label = " o "]; welcome -> create [label = " c " ] ; welcome -> exit [label = " q " ]; open -> active; create -> active; } After this, several commands are available, each with their own help (see below, prepending ``do_`` with the commands: for example, ``do_x`` will give the help for the command ``x`` in the CLI. .. autoclass:: mcq.uiMasterFile .. important:: Quitting the CLI keeps a persistent status, found in pickle objects saved in the home directory. Next time ``mcq.py`` is run, it will start from where left. Assuming the exam file name is ``f.tex``, the following hierarchy of files will be generated, among others. The commands are on the arrows. .. graphviz:: digraph { main [label="Main file: f.tex"]; xml [label="f.pos\n f.lbl\n f.pdf"] ; exam [label="f_exam.pdf\n(DEBUG: f_exam.tex, f_exam.sols, f.xml)"] ; gift [ label="f.gift" ]; html [ label="f.html" ]; answers [label="f_answers.txt\n f_answers.pdf"] ; esse3 [label="esse3.py\n -> f.uid",shape = box ] ; marked [label="f_exam.txt\nf_exam.csv"] ; stats [ label = "f_stats.pdf" ] ; end [ shape = box , label = "Exit" ]; main -> xml [ label = " make " ]; main -> gift [ label = "export f.gift"]; main -> html [ label = "export f.html"]; xml -> main [ label = " check and remake " ]; xml -> exam [label = " exam " ]; exam -> answers [ label = " omr " ] ; exam -> answers [ label = " (manual typing) " ] esse3 -> answers [label = " uid " ]; answers -> answers [ label = " check PDF and fix TXT " ] ; answers -> marked [ label = " mark " ]; marked -> stats [ label = " makestats " ]; stats -> main [ label = " check stats\n and fix f.tex " ]; stats -> end [label = " x " ]; } .. _MCQ-QB: Managing and using a Question Bank with Random Choices ====================================================== A ``question bank`` is simply a folder where there are TeX files with mcq.sty questions in them. Operating on question banks allows to generate random questions for a test:: You can use the commands listed below to choose random questions from the Question Bank. Main Commands (type `? ` for help): qbank [] : show or set the Question Bank Directory load : load a commandsfile lsbank : list files in the Question Bank Directory ls : list files add from : add questions from the list of files (separated by space, wildcard `*` acceptable). del | all : remove n-th question, or all the quesitons make : generate `
.pdf` open : open the file (e.g. for viewing, open main.pdf) random all| : draw all or just exercise , and create
.tex status : show status of the chosen questions rehash : reload the full set of questions from the qbank next : Accept the random choice and proceed. x : Exit (without accepting) A typical session, which can be saved in a ``txt`` file and loaded with the command ``load`` is as follows:: add 1 from c*-2018.tex add 3 from c*-2019.tex add 1 from richiami.tex add 1 from derivate.tex add 1 from integrali.tex add 1 from successioni.tex add 1 from fourier.tex add 1 from curvesup.tex add 1 from forme.tex add 1 from eqdiff.tex add 1 from lebes.tex add 1 from lebes2.tex add 1 from hilbert.tex .. _MCQ-export: Exporting to other formats: HTML and GIFT ========================================= The commandline:: $ mcq.py --gift filename.tex > questions.gift will convert **all** the questions in ``filename.tex`` to the GIFT moodle format, ready to be imported in MOODLE as questions. The two main types (``exerm`` and ``exe``) correspond to multiple choice questions or essays, in moodle. The preamble command ``\moodlecategory{categoryname}`` will trigger the following behavour: for each group of questions, all the questions in a single environment ``\begin{esercizi}{sectioname}..`` or ``\begin{esercizi*}{sectionname}`` will be categorized under the moodle GIFT category:: $CATEGORY: categoryname/sectionname or, if the sectionname is empty,:: $CATEGORY: category to facilitate categorized GIFT importing into MOODLE question banks. Exactly the same function is provided by the ``export filename.gift`` in the command line user interface. .. _MCQ-errors: When things go wrong ==================== (TODO) .. _MCQ-options: Advanced usage: command line options ==================================== (TODO) ---------------------------------------------------- .. highlight:: guess .. _MCQ-python: mcq as a python module: mcq CLASSES =================================== .. autoclass:: mcq.Esercizio :members: :show-inheritance: .. autoclass:: mcq.MultiEsercizio :members: :show-inheritance: .. autoclass:: mcq.Risposta :members: :show-inheritance: .. autoclass:: mcq.myTerm :members: :show-inheritance: .. autoclass:: mcq.ExamFile :members: :show-inheritance: .. autoclass:: mcq.uiShell :members: :show-inheritance: .. autoclass:: mcq.uiFileNavigator :members: :show-inheritance: .. autoclass:: mcq.uiMasterFile :members: :show-inheritance: .. autoclass:: mcq.uiChooser :members: :show-inheritance: JUNKYARD ======== **default_combina_voti ARGOMENTO**: .. autofunction:: mcq.default_combina_voti .. autofunction:: mcq.check_safe_dvipdfmx