diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/webquiz/webquiz.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/webquiz/webquiz.tex | 2306 |
1 files changed, 2306 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/webquiz/webquiz.tex b/Master/texmf-dist/doc/latex/webquiz/webquiz.tex new file mode 100644 index 00000000000..f0b63b41a05 --- /dev/null +++ b/Master/texmf-dist/doc/latex/webquiz/webquiz.tex @@ -0,0 +1,2306 @@ +%----------------------------------------------------------------------------- +% Copyright (C) 2004-2019 Andrew Mathas, University of Sydney +% +% Distributed under the terms of the GNU General Public License (GPL) +% http://www.gnu.org/licenses/ +% +% This file is part of the WebQuiz system. +% +% <Andrew.Mathas@sydney.edu.au> +%----------------------------------------------------------------------------- + +\synctex=1 + +\PassOptionsToClass{tikz,svgnames}{xcolor} +\documentclass[svgnames]{article} +\usepackage[a4paper,margin=30mm]{geometry} +\parindent=4mm +\parskip=1mm +\hfuzz 5pt +\synctex=1 + +% load webquiz-ini and webquiz-doc code -- doc needs ini so ini is first +\input{webquiz-ini.code} +\input{webquiz-doc.code} + +% Can't use same definition in webquiz-online-manual because of conflict +% with code in webquiz.cfg to make color work with listings +\newcommand\WebQuiz{\textcolor{Sienna}{WebQuiz}\xspace} + +\usepackage{textcomp} +\usepackage{pdfpages} +\usepackage{manfnt} +\usepackage{booktabs} +\usepackage{bbding} +\usepackage{pifont} +\usepackage{pgffor} + +\usepackage{etoolbox}% used below to patch l@section to remove extraneous spacing +\usepackage{appendix} +\def\sectionautorefname{Chapter} +\def\subsectionautorefname{Section} +\def\subsubsectionautorefname{\S\kern-0.8ex} +\def\appendixautorefname{Appendix} + +\usepackage{imakeidx} +\indexsetup{level=\section*,toclevel=section,noclearpage} +\makeindex[intoc,columns=3] + +\newenvironment{heading}[1][] +{\noindent\trivlist\item[\hskip\labelsep\textbf{#1}]} + {\endtrivlist} + +\newenvironment{dangerous}{\trivlist\item[\hskip\labelsep\textcolor{red}{\textdbend}]}{\endtrivlist} + +\setcounter{secnumdepth}{3} +\setcounter{tocdepth}{3} +\renewcommand\thesubsubsection{\thesubsection\alph{subsubsection}} +\newcommand\lowerCaseIndex[1]{% + \lowercase{\def\temp{#1}}% + \expandafter\index\expandafter{\temp@#1}% +} +% usage: \CrossIndex[*]{main entry}[*]{subentry} with *'s for macros +\NewDocumentCommand\CrossIndex{ smsm }{% + \IfBooleanTF{#1}{% + \lowercase{\def\tempa{#2}}% + \xdef\tempa{\tempa@\noexpand\textbackslash#2}% + }{\def\tempa{#2}}% + \IfBooleanTF{#3}{% + \lowercase{\def\tempb{#4}}% + \xdef\tempb{\tempb@\noexpand\textbackslash#4}% + }{\def\tempb{#4}}% + \expandafter\index\expandafter{\tempa!\tempb}% + \expandafter\index\expandafter{\tempb}% +} +\newcommand\macroIndex[1]{% + \lowercase{\def\temp{#1}}% + \expandafter\index\expandafter{\temp@\textbackslash#1}% +} +\newcommand\gobbleone[1]{}% https://tex.stackexchange.com/questions/318472 +\newcommand{\See}[2]{\unskip\emph{see } #1} +\newcommand\SeeIndex[2]{\index{#1!zzzz@\protect\gobbleone|See{#2}}} + +\newif\ifCtan\Ctantrue % condition compilation for ctan distribution + +\renewcommand*\contentsname{\relax} + +% hyperref links to ctan +\newcommand\TeXLive{\ctan[/]{\TeX Live}\xspace} +\newcommand\Ctan{\ctan[]{ctan}\xspace} +\newcommand\ddash{\texttt{\textemdash\textemdash}} +\NewDocumentCommand\webquizrc{s}{\index{webquizrc}% +\BashCode|webquizrc| file\IfBooleanF{#1}{ (\autoref{SS:rcfile})}\xspace% +} + +\NewDocumentCommand\OnlineManual{s}{% + \href{http://www.maths.usyd.edu.au/u/mathas/WebQuiz/webquiz-online-manual.html}{Online manual}% + \IfBooleanF{#1}{ (\hyperref[S:online]{Appendix B})}\xspace% +} + +\indexprologue{% + \noindent\textit{This is an index only for the main \WebQuiz manual. + It does not index the \OnlineManual.}} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\input{webquiz.themes} % defines a comma separated list of themes \WebQuizThemes +\newcommand\ListWebQuizThemes{% + \begin{quote} + \def\sep{} + \foreach \theme in \WebQuizThemes {% + \ifx\theme\empty\gdef\sep{ and }% + \else\sep\index{theme!\theme}\theme\gdef\sep{, }% + \fi + } + \end{quote} +} +\newcommand\ShowcaseThemes{% + \foreach \theme in \WebQuizThemes { + \ifx\theme\empty\relax% + \else% + \ScreenShot[0.75]{Example of the \textbf{\theme} theme}{theme-\theme}% + \index{theme!\theme}% + \fi + } +} + +\input{webquiz.languages} % defines a comma separated list of themes \WebQuizLanguages +\newcommand\ListWebQuizLanguages{% + \begin{quote} + \def\sep{} + \foreach \lang in \WebQuizLanguages {% + \ifx\lang\empty\gdef\sep{ and }% + \else\sep\index{language!\lang}\lang\gdef\sep{, }% + \fi + } + \end{quote} +} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% WebQuiz title box for front page +\usepackage{tikz} +\usetikzlibrary{shadows.blur} + +\definecolor{stone}{HTML}{E9E0D8} +\tikzset{shadowed/.style={blur shadow={shadow blur steps=5}, + top color=stone, + bottom color=PapayaWhip, + draw=SaddleBrown, + shade, + font=\normalfont\Huge\bfseries\scshape, + rounded corners=8pt, + }, + boxes/.style={draw=Sienna, + fill=Cornsilk, + font=\sffamily\small, + inner sep=5pt, + rectangle, + rounded corners=8pt, + text=Brown, + } +} + +\def\WebQuizTitle{ + \begin{tikzpicture}[remember picture,overlay] + \node[yshift=-3cm] at (current page.north west) + {\begin{tikzpicture}[remember picture, overlay] + \draw[shadowed](30mm,0) rectangle node[Brown]{\WebQuiz} (\paperwidth-30mm,16mm); + \node[Sienna,font=\normalfont\small\itshape] at (\paperwidth/2,2mm) + {\small \webquiz{description}}; + \node[anchor=west,boxes] at (4cm,0cm) {\webquiz{name}}; + \node[anchor=east,boxes] at (\paperwidth-4cm,0) {Version \webquiz{version}}; + \end{tikzpicture} + }; + \end{tikzpicture} +} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%% headers and footers +\makeatletter +\def\ps@webquiz{ + \ps@empty + \def\@oddfoot{\tiny\WebQuiz\space -- version \webquiz{version}\hfill% + \textsc{\ifodd\thepage The \WebQuiz manual\else \webquizheader\fi}\hfill\thepage} +} +% hijack section and subsectionmark for our headers +\def\webquizheader{\WebQuiz} +\def\sectionmark#1{\def\webquizheader{#1}} +\def\subsectionmark#1{\def\webquizheader{#1}} +\pagestyle{webquiz} +\patchcmd\l@section{1.0em}{0.5em}{}{} +\makeatother + +\begin{document} + \hypersetup{pdftitle={WebQuiz manual}} + + \WebQuizTitle + + \begin{quote} + \WebQuiz is a \LaTeX{} package for writing online quizzes. It allows + the quiz author to concentrate on the content of quizzes, written + in standard \LaTeX, unencumbered by the technicalities of \HTML and + \Javascript. Online quizzes written using \WebQuiz can contain any + material that can be written using \LaTeX, including text, + mathematics, graphics and diagrams. + \ScreenShot[0.68]{An example \WebQuiz web page}{quiz-page} + \begin{center} + \hfil + \begin{minipage}{0.75\textwidth} + \tableofcontents + \end{minipage} + \end{center} + \end{quote} + + \newpage + + \section{Introduction} + Online quizzes provide a good way to reinforce learning, especially + because they can give ``interactive'' feedback to the + students\footnote{Throughout this manual, ``student'' means any + person taking the online quiz.\index{student}} based on the answers that they + give. Unfortunately, in addition to writing the actual quiz content there + are significant technical hurdles that need to be overcome when + writing an online quiz -- and there are additional complications if + the quiz involves mathematics or diagrams. + + \WebQuiz makes it possible to write online quizzes using \LaTeX, + which is the typesetting language used by mathematicians who use + \LaTeX\ to write their research papers, books and teaching + materials. In principle, a \WebQuiz quiz can contain anything that + can be typeset using \LaTeX. In practise, the \LaTeX\ is converted + to \HTML using \TeXfht (and + \ctan{make4ht}), so the + quizzes can contain any \LaTeX commands that are understood by \TeX + 4ht, which is almost everything. In particular, it is possible to + use graphics constructed using \ctan{pstricks} and + \ctan{tikz}; see \autoref{SS:graphics}. + + \WebQuiz supports the following three types of questions: + \begin{itemize} + \item Multiple choice questions with a unique correct answer + \item Multiple choice questions zero or more correct answers + \item Questions with an answer that is supplied by the student. + \end{itemize} + Each time a student answers a question it is possible to give them + feedback, reinforcing their learning when they answer correctly and + giving them further hints when they are wrong. This allows the + quiz author to give targeted feedback to the student based on their + answer. + + The online quizzes constructed using \WebQuiz can, in principle, + contain anything that can be typeset by \LaTeX. In particular, they + do not need to contain mathematics. In fact, the quizzes do not even + have to contain ``questions'' as it is possible for a \WebQuiz + ``quiz'' to contain only \LatexCode|discussion| environments that can + be used to revise material, or to introduce new material, for the + students; see \autoref{SS:discussion}. + + This introduction outlines how to use \WebQuiz, however, the + impatient reader may want to skip ahead directly to the + \autoref{S:documentclass}, where the \LaTeX\ commands used by + \WebQuiz are described. + + The easiest way to explain how \WebQuiz works is by example. The + following \LaTeX\ file defines a quiz with a single multiple choice + question that has four possible answers, each of which has a + customised feedback. Giving feedback to the students in each + question is optional but the capability of being able to give + students feedback on their answer is one of the main pedagogical + advantages of online quizzes. + + \InputLatexCode{simple} + + Since this is a \LaTeX\ file it can be processed using + \BashCode|pdflatex|, or \BashCode|latex|, to produce a readable and + printable version of the quiz, which can be useful when + proofreading. With the example above, the PDF version of the quiz looks + like this: + \ScreenShot[0.5]{Sample \BashCode|PDF| output}{simple-pdf} + Of course, the real reason for using \WebQuiz is to create a + web page for the quiz, which you do by processing the quiz using + the \BashCode|webquiz| command )instead of, say + \BashCode|pdflatex|). If you do this and open the resulting + web page in your favourite browser, after selecting answer~(a), you + will see a web page like this: + \ScreenShot{Sample web page}{simple-html} + The actual page that you see may be slightly different to + this because the appearance of the web page depends partly on your + choice of browser. + + By default, the online version of the quiz displays one question at + a time, with the question buttons serving the dual purpose of + navigation between questions and displaying how successful the + student was in answering the question. The decorations on the + question buttons indicate whether the question has been attempted + and, if so, whether it was answered correctly or incorrectly on the + first or subsequent attempts. One of the main points of \WebQuiz is + that (optional) targeted feedback can be given to the student taking + the quiz based on their answer. + + \subsection{What \WebQuiz does and does not do} + + \WebQuiz is a tool that makes it possible to write ``interactive'' + online quizzes using \LaTeX{}. To use \WebQuiz you only need + basic working knowledge of \LaTeX{}. In particular, no familiarity + of the underlying \CSS, \HTML or \Javascript is required. + + \WebQuiz can be used to ask students a series of ``quiz'' + questions. In addition, your online quiz web pages can contain + course material using the \WebQuiz \LatexCode|discussion| + environment; see \autoref{SS:discussion}. You can write \WebQuiz + quizzes that only contain questions, and no + \LatexCode|discussion|, quizzes that contain questions and + \LatexCode|discussion|, and (pseudo) quizzes that contains only + \LatexCode{discussion} and no quiz questions. + + By default, the online quizzes display one question (or + \LatexCode|discussion| environment) at a time. It is also possible + to display all of the quiz questions on a single web page + (\autoref{SS:classOptions}). One of the key features of \WebQuiz is + that you can give feedback to the students based on their answers. + In this way you can give hints to the students to correct their + mistakes and you can reinforce the students' understanding when they + are correct. Each question in a quiz, and each quiz itself, can be + attempted as many times as the student wants. \WebQuiz does not + limit the number of times that questions can be attempted. + + As described in \autoref{SS:Questions}, \WebQuiz supports the following question types: + \begin{itemize} + \item Multiple choice questions with a unique correct answer + \item Multiple choice questions zero or more correct answers + \item Questions that require students to type in an answer. There + are several different ``comparison'' methods available for + comparing the students answer where + for example, the entered answers can be a ``string'' or a ``number''. + \end{itemize} + + Questions can appear in either the same order that they appear in + the \LaTeX{} file for the quiz or in a random order that changes + each time the quiz page is loaded. For multiple choice questions the + order in which the choices appear is always the order that they + appear in the \LaTeX{} file for the quiz, even if the questions + appear in random order. + + \WebQuiz supports several different languages and it + provides a number of different colour schemes (see + \autoref{SS:commandline} and \hyperref[SS:themes]{Appendix A}). + + \WebQuiz quizzes are not timed and they do not have time-limits. + + Quizzes made using \WebQuiz are intended to be used as a + revision resource rather than as an assessment tool. In particular, + \WebQuiz does not provide a mechanism for recording the marks + obtained by the students taking the quiz + (\autoref{SS:classOptions}). Technically, it probably would not be + very hard to record marks but this introduces a significant amount + of extra overhead in terms of student authentication and interfacing + with a database. In addition, if \WebQuiz were used as an assessment + tool then there would be additional ``security issues'' to ensure + that the quiz content is secure. Currently, even though the + solutions to the quiz questions do not appear in the \HTML source + code for the quiz pages it is possible to access the answers if you + know what you are doing. + + The questions in a \WebQuiz quiz are static. In particular, + \WebQuiz quiz questions do not accept variables. + + The \WebQuiz program was designed to be run from the command-line. + To process the file \BashCode|quiz.tex| using \WebQuiz you would + type + \begin{bashcode} + > webquiz quiz or > webquiz quiz.tex + \end{bashcode} + \index{$>$ command-line prompt}\index{command-line prompt!$>$} + (Throughout this manual, \BashCode|>| is used for the command-line + prompt.) + + It is possible to use \WebQuiz from inside editors like + \TeX Shop, but exactly how this is done will depend on the program + that you use. In the case of \TeX Shop you need to define a + new \textit{engine} following, for example the instructions at + \href{https://tex.stackexchange.com/questions/376649} + {tex.stackexchange.com/questions/376649}. + \index{TeXShop@\TeX Shop} + + \subsection{Credits} + \WebQuiz{} was written and developed in the + \href{http://www.maths.usyd.edu.au/}{School of Mathematics and + Statistics} at the \href{http://www.usyd.edu.au/}{University of + Sydney}. The system is built on \LaTeX{} with the conversion from + \LaTeX{} to \HTML being done by Eitan Gurari's + \TeXfht and \ctan{make4ht}. + + To write quizzes using \WebQuiz it is only necessary to know + \LaTeX, however, the underlying \WebQuiz system actually has three + components: + \begin{itemize} + \item A \href{https://www.latex-project.org/}{\LaTeX} document class + file, \BashCode|webquiz.cls|, and a \TeXfht + configuration file, \BashCode|webquiz.cfg|, that enables the + quiz files to be processed by \LaTeX{} and \TeXfht, respectively. + \item A \python program, + \BashCode|webquiz|, that translates the + \LaTeX{} into \XML, using \TeXfht, and then into \HTML. + \item \CSS, \HTML and \Javascript code controls and style the + quiz web pages. + \end{itemize} + + The \LaTeX{} component of \WebQuiz{} was written by Andrew Mathas and + the \python, \CSS and \Javascript code was written by Andrew Mathas + based on an initial prototype that was written by Don Taylor in 2001-2. + Since 2004 the program has been maintained and developed by Andrew + Mathas. Although the program has changed substantially since 2004, + Don's idea of using \TeXfht, and some of his code, is still + in use. Prior to releasing \WebQuiz on \Ctan, the program was known + as \texttt{MathQuiz}. + + Hendrik Suess contributed code to improve session history + and suggested the \LatexCode|\qref| command. + + Thanks are due to Bob Howlett for general help with \CSS and to + Michal Hoftich for invaluable technical advice on \TeXfht. Thanks + are due to + Thomas Cailleteau + Michael Palmer and + Hendrik Suess, + for helpful feedback on the package. + + \section{The \WebQuiz document class --- \hologo{LaTeX}{} commands} + \label{S:documentclass} + + This chapter describes the commands and environments provided by the + \WebQuiz document class. This assumes that you have already installed + and configured \WebQuiz. If you have not yet initialised \WebQuiz + then please follow the instructions in \autoref{S:configuration}. + + All of the code examples given in this and other sections can be + found in the \BashCode|examples| subdirectory of the \WebQuiz web + directory.\footnote{After you have initialised \WebQuiz, you can find the + \WebQuiz example directory from the command-line using: + \texttt{webquiz --settings webquiz-www}.} + Additional examples can be found in the \OnlineManual*, + which is included, in \BashCode|PDF| form, as + \hyperref[S:online]{Appendix B}. + + Zoomed out, the structure of a typical \WebQuiz quiz file is a \LaTeX{} file of the form: + \begin{latexcode} + \documentclass{webquiz} + \title{A quiz}% optional, but potentially informative, title + \begin{document} + + \begin{question}% text for first question + \end{question} + + \begin{question}% text for second question + \end{question} + + \begin{question}% text for third question + \end{question} + + ... + + \end{document} + \end{latexcode} + You should write your quizzes using the editor that you normally use + to write \LaTeX{} documents. As you write your quiz, say + \BashCode|quiz.tex|, you should use \BashCode|pdflatex| + (or \BashCode|latex|), in the usual way: + \begin{bashcode} + > pdflatex quiz + \end{bashcode} + This is the easiest way to check that your quiz compiles and to + proofread the output, just as if you were writing a normal \LaTeX{} + document. When you are satisfied with the content of the quiz, then + you can convert the quiz to an online quiz using the command + \begin{bashcode} + > webquiz quiz or > webquiz -d quiz # -d = draft mode = faster! + \end{bashcode} + The quiz file, \BashCode|quiz.tex|, should be in a directory on your + web server because \WebQuiz creates a number of different files and + directories when it converts the file into an online quiz and all + of these files are needed to display the quiz on the web. + + The reasons for using this workflow are: + \begin{itemize} + \item \textit{Every file that you give to \WebQuiz must be a valid + \LaTeX{} file!} + + \item The \BashCode|dvi| or \BashCode|PDF| file produced by \LaTeX{} + shows all of the information in the quiz + \textit{in an easy-to-read format}. That is, the \BashCode|PDF| file + displays the questions, the answers and the feedback that you are + giving to the students. In contrast, by design, the online version + of the quiz hides most of this information and shows it to the + student only when they need to see it. + + \item Typesetting the quiz file with \LaTeX{} is \textit{much + faster} than processing it with \WebQuiz. In fact, \WebQuiz uses + \BashCode|htlatex| to process the quiz file at least + \textit{three times} in order to produce an \XML file and it is only + then that the \WebQuiz program kicks in to rewrite this data as an + \HTML file. (If you use \textit{draft mode} then + \BashCode|htlatex| processes the quiz file only once.) + + \item If \LaTeX{} produces errors then \WebQuiz will produce more + errors. Further, \textit{\LaTeX{} error messages are much easier to + read and understand than those produced by \TeXfht and \WebQuiz}. + \end{itemize} + This said, \WebQuiz does check for more errors in the quiz than + \LaTeX{} is (easily) able to do. + + The \BashCode|PDF| version of a quiz does not contain information about + the unit, department or institution, which can be used in the + breadcrumbs. + + The next sections describe the commands and environments provided by + \WebQuiz for typesetting quizzes as well as the document-class options + for the package. If you plan to use \ctan{pstricks} or + \ctan[pgf]{tikz} then you should read \autoref{SS:graphics}, which + describes how to use graphics in a \WebQuiz quiz. + \autoref{SS:config} describes a work-around for using (some?) \LaTeX{} + features that have not been configured for use with \TeXfht. + + \subsection{Question environments}\label{SS:Questions} + + The \WebQuiz document class defines the following four environments: + \begin{quote} + \begin{description} + \item[question] Each quiz question needs to be inside + \LatexCode|question| environment + \item[choice] Typesets multiple choice questions, with + one or more correct answers + \item[discussion] Includes (optional) discussion, or revision, + material at the start of the quiz web page + \item[quizindex] Writes an index file for the quizzes in + a ``unit of study'' and generates drop-drop menus in each quiz for + the unit + \end{description} + \end{quote} + This section describes these environments and gives examples + of their use. + + \subsubsection{Question environments and the \textcolor{blue}{\textbackslash answer} macro} + \index{environment!question} + \index{question environment} + + Each quiz question must be placed inside a \LatexCode|question| + environment. Typically, a quiz has several questions, each wrapped in + its own \LatexCode|question| environment. For brevity, most of the + examples in this chapter have only one question. See the + \OnlineManual, in the \WebQuiz web directory for a more complete quiz + file. + + This manual describes the \WebQuiz commands, often by example. The + following code-block generates a quiz with one question for which the + student has to enter the answer. This answer is then compared with the + correct answer as a string, which it must match exactly. + \InputLatexCode{answer-string} + \macroIndex{answer}\CrossIndex{question environment}*{answer} + \CrossIndex*{answer}*{whenRight} + \CrossIndex*{answer}*{whenWrong} + \index{feedback!whenRight} + \index{feedback!whenWrong} + The \textit{optional} macros \LatexCode|\whenRight| and + \LatexCode|\whenWrong| are used to give the student additional + feedback, when they are right, or further hints etc for approaching + the question, when they are wrong. This feedback is displayed on the + quiz page only when the student checks their answer. + + The web page created by the code above, when an incorrect answer of + ``canberra'', instead of ``Canberra'' is given, looks something like + the following: + \ScreenShot{A question with an answer}{answer-string} + This example shows one way of using the \LatexCode|\answer| macro, which + asks for the student to type in an answer to the question. The general syntax of + this macro is: + \begin{latexcode} + \answer[comparison type]{correct answer} + \end{latexcode} + where the optional \textit{comparison type} is one of: + \begin{latexcode} + complex integer lowercase number string + \end{latexcode} + with \LatexCode|string| being the default. In addition, there is a + $*$-variant of the answer macro that does not print the word + ``Answer'' (or equivalent in other languages) before the input box. + The syntax for the \LatexCode|\answer*| command is identical to that + for the \LatexCode|\answer| except, of course, that there is a~$*$: + \begin{latexcode} + \answer*[comparison type]{correct answer} + \end{latexcode} + As \LatexCode|string| is the default answer comparison method, if we + instead use \LatexCode|\answer*{Canberra}| in the last example then + the quiz page generated by \WebQuiz looks like: + \ScreenShot{A question with answer$*$}{answer-star} + Notice that the word \LatexCode|Answer| no longer appears in front of + the answer box. Of course, if you use the unstarred version of the + \LatexCode|\answer|-macro together with the document class option + \LatexCode|language=xxx| to change the default language + (\autoref{SS:classOptions}), then the appropriate translation of + \LatexCode|Answer| will appear on the web page. + + We now give a description of the other comparison types for the + \LatexCode|\answer| and \LatexCode|\answer*| macros together with + code examples and screenshots. + + \CrossIndex*{answer}{complex} + \begin{heading}[complex comparison] The answers are compared as complex + numbers: the answer is marked as correct if it has the same real and + imaginary parts. + \InputLatexCode{answer-complex} + \ScreenShot{A question with a complex answer}{answer-complex} + \end{heading} + Observe that the correct answer is given in the quiz file as $7+i$ + and that \WebQuiz accepts $i+7$ as the correct answer. + + \begin{heading}[integer comparison] The answers are compared as + integers. If the correct answer was $18$ and a student entered + $36/2$ then their answer would be marked wrong. + \CrossIndex*{answer}{integer} + \InputLatexCode{answer-integer} + \ScreenShot{A question with a integer answer}{answer-integer} + \end{heading} + + \begin{heading}[lowercase comparison] The quiz answer and the + students' answer are both converted to lower case and then compared as + strings. + \CrossIndex*{answer}{lowercase} + \InputLatexCode{answer-lowercase} + \ScreenShot{A question with a lowercase string answer}{answer-lowercase} + \end{heading} + + \begin{heading}[number comparison] The quiz answer and the students' + answer are compared as numbers. \CrossIndex*{answer}{number} + \InputLatexCode{answer-number} + \ScreenShot{A question with a numeric answer}{answer-number} + Notice that the answer is given in the \LaTeX{} file as $3/4$ and + that the equivalent fraction, $0.75$, is accepted as the correct + answer. + \end{heading} + + \begin{heading}[string comparison] + This is the default, so \LatexCode|\answer{word}| and + \LatexCode|\answer[string]{word}| are equivalent. The student's + answer is marked correct if and only if it agrees exactly with + the quiz answer. + \CrossIndex*{answer}{string} + \end{heading} + + \subsubsection{Multiple choice questions}\label{SS:choice} + \index{environment!choice} + \index{question environment!choice} + \SeeIndex{multiple choice}{choice environment} + + The multiple choice options for a quiz question need to be placed inside + a \LatexCode|choice| environment -- and every \LatexCode|choice| + environment needs to be inside a \LatexCode|question| environment. + + The \LatexCode|choice| environment accepts two optional arguments, + can appear in any order: + \begin{itemize} + \item\CrossIndex{choice environment}{single} + \CrossIndex{choice environment}{multiple} + The word \LatexCode|single| (default, and can be omitted) or + \LatexCode|multiple|, which indicates whether the quiz has a + \textit{single} correct answer or whether 0 or more of the answers are + correct, respectively. + \item \index{choice environment!columns} + The number of \textit{columns} in which to typeset the choices. This + is specified as \LatexCode|columns=n|, where $n$ is a non-negative integer. + By default, the choices appear in $n=1$ columns + (\DefaultValue{columns=1}).\\ + \textit{Use \LatexCode|columns=n| with care when $n>1$ as multiple + columns do not always display well on mobile devices.} + \end{itemize} + The key difference between these two types of \LatexCode|choice| + questions is that a \LatexCode|single|-choice environment uses radio + boxes, so it is only possible to select \textit{one correct answer}. + In a \LatexCode|multiple|-choice environment checkboxes are used, so + that is possible to select \textit{zero or more correct answers}. + + A \LatexCode|choice| environment modelled on the standard + \LaTeX{} list environments (\textit{enumerate}, \textit{itemize}, + \textit{description}, ...), except that instead of using the + \LatexCode|\item| command to separate the items the + \LatexCode|choice| environment uses \LatexCode|\correct| + \CrossIndex{choice environment}*{correct} \LatexCode|\incorrect| + \CrossIndex{choice environment}*{incorrect}, which indicate correct + and incorrect answers respectively. In addition, after each + \LatexCode|\correct| or \LatexCode|\incorrect| you can, optionally, use + \LatexCode|\feedback| \CrossIndex{choice environment}*{feedback} to give + feedback to the student taking the quiz. Like + \LatexCode|\whenRight| and \LatexCode|\whenWrong| this feedback is + displayed only when the student checks their answer. + \index{feedback} + \CrossIndex{feedback}*{whenRight} + \CrossIndex{feedback}*{whenWrong} + + Here is an example of a \LatexCode|single|-choice question with a unique + answer: + \InputLatexCode{choice-single} + Note that \LatexCode|single| is the default, so this could also be written as + \begin{latexcode} + \begin{choice}[columns=3, single] + ... + \end{choice} + \end{latexcode} + It is not necessary to put the \LatexCode|\feedback| lines on the same + line as the \LatexCode|\incorrect| and \LatexCode|\incorrect|; this is + done only to make the example more compact. This results in the + following web page: + \ScreenShot{Single answer multiple choice question}{choice-single} + + Here is an example of a multiple choice question that has + two correct answers: + \InputLatexCode{choice-multiple} + Notice that this example uses the document-class option + \LatexCode{theme=vibrant}, which changes the \WebQuiz colour theme; + see \autoref{SS:classOptions}. + \ScreenShot{Multi-answer multiple choice question}{choice-multiple} + + When the optional argument \LatexCode|multiple| to the + \LatexCode|choice| environment is used, as above, then the question is + marked correct if and only if \textit{all} of the correct choices, and + none of the incorrect choices, are selected. If the student's + selections are not completely correct then are given feedback that is + randomly selected from amongst their wrong choices (that is, the + feedback is randomly selected from the set of \LatexCode|\correct| + choices that were not selected and the \LatexCode|\incorrect| choices + that were selected). + + Finally, observe that the multiple choice items in the screenshot + above are labelled by roman numerals. The items in a + \LatexCode{choice} environment are labelled by a standard \LaTeX{} + counter, that is also called \LatexCode|choice|. Redefining the + \LaTeX{} macro \LatexCode|\thechoice| changes how the corresponding + question choices are labelled in the online quiz. For example, to + label the items in a \LatexCode|choice| environment by A), B), C) + $\dots$ add the line: + \begin{latexcode} + \renewcommand\thechoice{\Alph{choice})} + \end{latexcode} + to the preamble of the \LaTeX{} file for your quiz. + \CrossIndex{choice environment}*{thechoice}\macroIndex{thechoice} + + \subsubsection{Discussion environments}\label{SS:discussion} + \index{environment!discussion} + + In addition to asking questions, it is possible to display revision, + or discussion, material on the quiz web page using the + \LatexCode|discussion| environment. All discussion material is + displayed on the quiz page \textit{before} the questions in the quiz + and the (short) titles for the discussion items appear before the quiz + questions in the menu on the left-hand side of the page --- it is + not possible to interleave discussion items and questions in the side + menu. + + Each quiz can have zero or more discussion environments. These + environments can, in principle, contain arbitrary \LaTeX{} code. The + syntax for the \LatexCode|discussion| environment is: + \begin{latexcode} + \begin{dicussion}[short heading][heading] + ... + \end{dicussion} + \end{latexcode} + The \textit{short heading} is used in the side-menu. Both the + \textit{heading} and \textit{short-heading} are optional, both + defaulting to \LatexCode|Discussion|. If only one heading is given + then this sets both the \textit{short heading} and \textit{heading} + for the discussion item. For example, running the following \LaTeX\ + file, which uses \LatexCode|theme=muted|, through \WebQuiz + \InputLatexCode{discussion} + produces the quiz page: + \ScreenShot{Web page: discussion environment}{discussion} + As with the questions, only one \LatexCode|discussion| environment is + displayed on the quiz web page at a time (unless the document-class + option \LatexCode|onepage| is used). It is possible to have quizzes + that contain only \LatexCode|discussion| environments, with no + questions, and quizzes that contain only \LatexCode|question| + environments, with no discussion. + + If you have a mixture of \LatexCode|discussion| and + \LatexCode|question| environments then it is useful to be able to add + thinks between them. \LaTeX{} provides the \LatexCode|\label| and + \LatexCode|\ref| commands for cross-referencing, so \WebQuiz builds + on this idea and provides the three commands \LatexCode|\dref|, + \LatexCode|\qref| and \LatexCode|\Qref| to reference + \LatexCode|discussion| and \LatexCode|question| environments. The + syntax for these commands is as follows: + \begin{latexcode} + \dref[optional text]{LaTeX label} % inserts discussion button + \dref*[optional text]{LaTeX label} % inserts discussion link + \qref[optional text]{LaTeX label} % inserts question button by label + \qref*[optional text]{LaTeX label} % inserts question link by label + \Qref[optional text]{question number} % inserts question button by number + \Qref*[optional text]{question number} % inserts question link by number + \end{latexcode} + \CrossIndex{cross-reference}*{dref} + \CrossIndex{cross-reference}*{qref} + \CrossIndex{cross-reference}*{Qref} + \CrossIndex{cross-reference}*{label} + In each case the text in the link or button defaults to either the + short-title, for discussion environments, or the question number for + questions. The ``optional text'' is used instead whenever it is + supplied. These commands can be used anywhere in a quiz, including + \LatexCode|discussion|, \LatexCode|question| and \LatexCode|choice| + environments and inside feedback text for the students written using + \LatexCode|\feedback|, \LatexCode|\whenRight| and \LatexCode|\whenWrong|. + + The macros \LatexCode|\dref| and \LatexCode|\qref| use a standard + \LaTeX{} \textit{label}, defined using the \LatexCode|\label| command, + to insert a button or a link. In contrast, \LatexCode|\Qref| uses the actual + \textit{question number}, so it is not necessary to define a + \LatexCode|\label| for a question when using \LatexCode|\Qref|. + + Even though the macros \LatexCode|\qref| and \LatexCode|\Qref| are + quite similar they serve different functions when the + \LatexCode|randomorder| document class option is used (see + \autoref{SS:classOptions}). In this case we do not know ahead of time + the question numbers that will be used in the quiz. So if + \LatexCode|q:one| is the label for the first question in the \LaTeX{} + file then \LatexCode|\qref{q:one}| will insert a button to this + question \textit{but} this will almost certainly not be Question~$1$. + On the other hand, we can create a ``Start quiz'' button, for example, + that will open Question~1 on any quiz, using + \LatexCode|\Qref[Start quiz]{1}|. + + Here is an example that shows how \LatexCode|\Qref| works: + \InputLatexCode{discussion-Qref}\macroIndex{Qref} + which produces the online quiz: + \ScreenShot{Crossing-referencing using question numbers}{discussion-Qref} + Similarly, here is an example showing how \LatexCode|\dref| and \LatexCode|qref| + are used: + \InputLatexCode{discussion-ref}\macroIndex{dref}\macroIndex{qref} + This code produces the online quiz: + \ScreenShot{Crossing-referencing using labels}{discussion-ref} + + \begin{dangerous} + When using the \LatexCode|randomorder| document class option + (\autoref{SS:classOptions}), ``optional text'' should always be + given when using \LatexCode|\qref|. This is because the question + number that is displayed by default will always be the question + number \textit{in the \LaTeX{} file} rather than the question number + in the online quiz. + \end{dangerous} + + \subsubsection{Index pages for quizzes}\label{SS:index} + \index{quizindex environment} + \index{environment!quizindex} + + Most quizzes occur in sets that cover related material, such as for + a particular unit of study. The \LatexCode|quizindex| environment + creates an index web page for related sets of quizzes. The \LaTeX{} + files for all of these quizzes must be in the same directory, or + folder, on the web server. The index web page is a \WebQuiz file of + the form: + \InputLatexCode{index-en} + which generates a web page that looks like: + \ScreenShot[0.7]{Example index page}{index-en} + As the next section describes, index files are also used to + automatically add a drop-down menu that contains the quiz-index to + the breadcrumbs on all of the quiz web pages. This drop-down menu + provides an easy way to navigate between all of the quizzes for a + particular unit of study. + + As the example above shows, the entries in the \LatexCode|quizindex| are + given using the \LatexCode|\quiz| or the \LatexCode|\quiz*| command. + \CrossIndex{quizindex environment}*{quiz} + The syntax for these commands is + \begin{latexcode} + \quiz[URL for quiz]{Title for quiz} + \quiz*[URL for quiz]{Title for quiz} + \end{latexcode} + The \LatexCode|\quiz| macro automatically inserts the quiz numbers + into the index listing. The \LatexCode|\quiz*| command is identical + \textit{except} that it does not add \BashCode|Quiz 1.|, + \BashCode|Quiz 2| etc to the index listing. By default, the URLs for + the quizzes in the index are assumed to be of the form + \BashCode|quiz1.html|, \BashCode|quiz2.html|, \BashCode|quiz3.html|, + .... These URLs can be changed using the optional argument of the + \LatexCode|\quiz| and \LatexCode|\quiz*| commands. For example, + \begin{latexcode} + \quiz[realquiz.html]{This is the real quiz} + \end{latexcode} + would create an item in a quiz index that links to the web page + \BashCode|realquiz.html|. + + Index pages in other languages are produced in exactly the same way. For example, + \InputLatexCode{index-cz} + produces the web page: + \ScreenShot[0.7]{A Czech index}{index-cz} + The next section describes the \LatexCode|\BreadCrumb| and + \LatexCode|\BreadCrumbs| commands. + + At most one file in each directory should contain a + \LatexCode|quizindex| environment. This is because \WebQuiz creates + the file \Javascript file \BashCode|quizindex.js| whenever it + compiles a \LatexCode|quizindex| environment. This file contains + \Javascript commands for displaying the quiz index. + + \subsubsection{Breadcrumbs}\label{SS:breadcrumbs}\index{breadcrumbs} + \WebQuiz provides a straightforward way to place navigation breadcrumbs + at the top of the quiz web page. By default the + breadcrumbs are disabled. If you have a \LatexCode|\BreadCrumbs| command + like: + \begin{latexcode} + \BreadCrumbs{Mathematics /|Math1001 /u/Math1001|quizindex|title} + \end{latexcode} + in your \LaTeX{} file then \WebQuiz will add a corresponding strip + of breadcrumbs, or navigation links, to the top of your quiz page: + \ScreenShot{Example breadcrumbs}{breadcrumbs} + The drop-down menu is normally hidden, appearing only after the + $\equiv$ ``button'' on the web page is clicked. + + Usually, most of the breadcrumbs are navigation links to other web pages. In + the example above: + \begin{itemize} + \item The first ``crumb' inside the + \LatexCode|\BreadCrumbs| command is \BashCode|Mathematics /|. This inserts the text + \BashCode|Mathematics| together with a (relative) URL to + \BashCode|/|, the root directory for the web + server, which is often the correct URL for the department (or the + institution) + \item The \BashCode|Math101 /u/math101| inserts the text + \BashCode|Math101| as the second breadcrumb with URL + \BashCode|/u/math101|. + \item The \BashCode|quizindex| inserts the text \BashCode|Quizzes| + together with the symbol $\equiv$, which opens a drop-down menu + that contains the list of quizzes in the quiz index for the unit. + This is described in more detail below. + \item Finally the \LatexCode|title| in the breadcrumbs inserts, as + text, the part of the title \textit{before the first colon} in the title, + where the title is given by \LatexCode|\title{...}|. + \end{itemize} + The breadcrumbs for the quiz web page can be either be configured + quiz-by-quiz, using the \LatexCode|\BreadCrumbs| macro + \macroIndex{BreadCrumbs}, as above, or by setting default + \LatexCode|breadcrumbs| in the \webquizrc using the command-line + option + \begin{bashcode} + > webquiz --edit-settings + \end{bashcode} + as described in \autoref{SS:commandline}. Breadcrumbs are disabled by default. + + The breadcrumbs inside the \LatexCode|\BreadCrumbs{...}| command are given as + a ``|-separated list''. For example, quite reasonable breadcrumbs are given by: + \begin{latexcode} + \BreadCrumbs{ department | unitcode | quizindex | title } + \end{latexcode} + To make this the default set of breadcrumbs use + \BashCode{webquiz --edit-settings} to set breadcrumbs + in the \webquizrc to: + \begin{latexcode} + department | unitcode | quizindex | title + \end{latexcode} + More generally, the breadcrumbs can be specified as: + \begin{latexcode} + \BreadCrumbs{ crumb1 | crumb2 | crumb3 | crumb4 | ... } + \end{latexcode} + In principle, there can be arbitrarily many crumbs in your + breadcrumbs but, in practice, five is more than enough. + The crumbs inside a \LatexCode|\BreadCrumbs| command have the + following meanings: + + \begin{description} + \item[breadcrumb] The breadcrumb for the current quiz, which is + set using the \LatexCode|\BreadCrumb| macro. This breadcrumb is + purely descriptive, with no hyperlink being added: only the text given by + \LatexCode|\BreadCrumb| appears. + \CrossIndex*{BreadCrumbs}{breadcrumb}\macroIndex{BreadCrumb} + + \item[department] This expands to a link to your department, where + the department text is set using the macro \LatexCode|\Department| and its URL is set by + \LatexCode|\DepartmentURL|. + \macroIndex{Department}\macroIndex{DepartmentURL} + \CrossIndex*{BreadCrumbs}{department} + + \item[institution] This expands to a link to your institution, where + the institution text is set using \LatexCode|\Institution| and its URL is set by + \LatexCode|\InstitutionURL|. The institution also appears in the + side-menu above the \WebQuiz copyright notice. + \macroIndex{Institution}\macroIndex{InstitutionURL} + \CrossIndex*{BreadCrumbs}{institution} + + \item[quizindex] This expands to \BashCode|Quizzes|, which is a + link to the index page for your unit, as defined by + \LatexCode|\QuizzesURL|, which is described below. In addition, + if the directory contains a BashCode|quizindex.js| file, which is + created by the \LatexCode|quizindex| environment (see + \autoref{SS:index}), then the symbol {\large$\equiv$} will appear, + giving access to a drop-down menu to the index page, looking + something like this: + \ScreenShot{Drop-down menu giving index of quizzes}{quizindex-dropdown} + \macroIndex{QuizzesURL} + \CrossIndex*{BreadCrumbs}{quizindex} Such drop-down menus are + automatically added to quiz web pages that have a + \LatexCode|quizindex| breadcrumb| as soon as + an quiz page that contained a \WebQuiz \LatexCode|quizindex| environment has + been compiled in the current directory. + \CrossIndex{breadcrumbs}{quizindex} + + For those interested in how this is done, whenever \WebQuiz + compiles a \LatexCode|quizindex| environment it creates a + \Javascript file \BashCode|quizindex.js|. Every quiz file includes + this \Javascript file, if it exists, and this allows it to display + a drop-down menu for the quiz index. + + \item[Title] This expands to the full title of the quiz page, + without a hyperlink, as given by the \LatexCode|\title|. + \CrossIndex*{BreadCrumb*}{Title} + + \item[title] This expands to the part of title of the quiz page, + without a hyperlink, that occurs \textit{before} the first colon + in the title of the quiz. For example, if the title is given as + \begin{latexcode} + \title{Quiz 1: The wonders of life} + \end{latexcode} + then ``Quiz 1'' will be added to the list of breadcrumbs. If the + title does not contain a colon then the full title is printed. + \CrossIndex*{BreadCrumbs}{title} + + \item[unitcode] This expands to a link to the unit code, where the + unit code text is set using \LatexCode|\UnitCode|, and its URL is + set by + \LatexCode|\UnitURL| + \macroIndex{UnitCode}\macroIndex{UnitURL} + \CrossIndex*{BreadCrumbs}{unitcode} + + \item[unitname] This expands to a link to the unit name, where the + unit name text is set using \LatexCode|\UnitName|, and its URL is + set by + \LatexCode|\UnitURL| + \macroIndex{UnitName}\macroIndex{UnitURL} + \CrossIndex*{BreadCrumbs}{unitname} + + \end{description} + + \noindent + In addition, each \textit{crumb} in a breadcrumb, except for the + ``magic crumbs'' listed above, is allowed to be arbitrary text --- + although, non-ascii characters may cause problems. In this case, the + last ``word'' in the crumb is treated as a URL if it either beings + with a forward slash, \BashCode|/|, or if it begins with + \BashCode|http|. For example, the code: + \InputLatexCode{montypython} + \noindent + results in the following breadcrumbs: + \ScreenShot{Guaranteed to offend some one}{montypython} + Notice that it is necessary to correctly escape spaces etc in + URLs that are specified this way. Similarly, all of the characters + in the breadcrumbs should be ascii characters as unicode is likely to + cause encoding issues (compare with the Czech index given in + \autoref{SS:index}). + + If any part of a ``magic'' breadcrumb has not been defined then it + is printed with a question mark on the web page. For example, the + quiz file + \InputLatexCode{nounits} + does not define the unit code, so it results in the ``questionable'' first breadcrumb: + \ScreenShot{Breadcrumbs with no unit code}{nounits} + + Here is the list of \WebQuiz macros that we be used to set the + values of the ``magic'' breadcrumbs inside a + \LatexCode|\BreadCrumbs|. Note that default values for many of these + ``crumbs'' can be given in the \webquizrc. + + \newcommand\Item[1]{\item[\textbackslash#1]\CrossIndex{breadcrumbs}*{#1}} + \begin{description} + \Item{BreadCrumb}\macroIndex{BreadCrumb} + The \LatexCode|\BreadCrumb| command sets the \LatexCode|breadcrumb| + variable in the \LatexCode|\BreadCrumbs|. The primary use for this + is when you have default breadcrumbs in the \webquizrc like + \begin{bashcode} + breadcrumbs = department | unitcode | breadcrumb + \end{bashcode} + Using \LatexCode|\BreadCrumb| allows you to set the last crumb to + some meaningful text that describes the quiz. + + \Item{Department}\macroIndex{Department} + The \LatexCode|\Department| command sets the name of the + \LatexCode|department|. As described earlier in this section, by + default, the \LatexCode|department| is the first item in the + breadcrumbs that appear at the top of the web page. + + The default department can be set in the \webquizrc using + \BashCode|webquiz --edit-settings|. + + Default value: \BashCode{''} \qquad(i.e. the empty string) + + \Item{DepartmentURL}\macroIndex{DepartmentURL} + The \LatexCode|\DepartmentURL| command sets URL for the department. As + described earlier in this section, by default the department URL is + the link in the first breadcrumb on each web page. + + The default department URL can be set in the \webquizrc using + \BashCode|webquiz --edit-settings|. + + Default value: \DefaultValue{/} + + \Item{Institution}\macroIndex{Institution} + The \LatexCode|\Institution| command sets the institution, or university. + The \LatexCode|institution| appears below the question buttons in the + left-hand navigation menu that appears on every quiz web page + (provided that the screen size is not too small). As described + earlier in this section, the institution can be used in the web + page breadcrumbs. + + The default institution can be set in the \webquizrc using + \BashCode|webquiz --edit-settings|. + + Default value: \BashCode{''} \qquad(i.e. the empty string) + + + \Item{InstitutionURL}\macroIndex{InstitutionURL} + The \LatexCode|\InstitutionURL| command sets the institution URL. This is + used as the link for the \LatexCode|institution| in the left-hand + navigation menu that appears on every quiz page. As described + earlier in this section, the institution URL can be used in the + web page breadcrumbs. + + The default institution URL can be set in the \webquizrc using + \BashCode|webquiz --edit-settings|. + + Default value: \DefaultValue{/} + + \Item{QuizzesURL}\macroIndex{QuizzesURL} + The \LatexCode|\QuizzesURL| command sets the URL for the suite of quizzes + attached to this unit of study. As described earlier in this + section, this can be used in the breadcrumb at the top of the quiz + web page. + + Default value: \DefaultValue{UnitURL/Quizzes}, where \DefaultValue{UnitURL} is set + using \LatexCode|\UnitURL| + + \Item{UnitCode}\macroIndex{UnitCode} + The \LatexCode|\UnitCode| command sets the unit of study code for the + unit that the quiz is part of. + + \Item{UnitName}\macroIndex{UnitName} + The \LatexCode|\UnitName| command sets the name of the unit of study for + the unit that the quiz is attached to. + + \Item{UnitURL}\macroIndex{UnitURL} + The \LatexCode|\UnitURL| command sets the URL for the unit of study code + for the unit that the quiz is attached to. + + \end{description} + + \noindent + It makes sense to set defaults for \LatexCode|\BreadCrumbs| + \LatexCode|\Department|, \LatexCode|\DepartmentURL|, + \LatexCode|\Institution| and \LatexCode|\InstitutionURL| in the + \webquizrc. After doing this, a typical \WebQuiz file might look like this: + + \begin{latexcode} + \documentclass{webquiz} + \UnitName{Fundamental stuff} + \UnitCode{Stuff101} + \UnitURL{/courses/stuff101} + + \title{Stuffing: the art of taxidermy} + + \begin{document} + \begin{question} + first question... + \end{question} + \begin{question} + second question... + \end{question} + \end{document} + \end{latexcode} + + If you have many quizzes for many different units then a better approach is to create + a \LaTeX{} ``package'', say \BashCode|ourunits.sty|, to set these variables: + \begin{latexcode} + % ourunits.sty - set unit names, codes and URLs + \DeclareOption{stuff101}{ + \UnitName{Fundamental stuff} + \UnitCode{Stuff101} + \UnitURL{/courses/stuff101} + } + \DeclareOption{stuff102}{ + \UnitName{Fundamental stuff too} + \UnitCode{Stuff102} + \UnitURL{/courses/stuff102} + } + \ProcessOptions + \endinput + \end{latexcode} + Then you can replace the opening lines of the quiz file with + \LatexCode|\usepackage[stuff101]{ourunits}|. Of course, you could also + set the default \LatexCode|\Department|, \LatexCode|\DepartmentURL|, + \LatexCode|\Institution| and \LatexCode|\InstitutionURL| in such a + style file as well. + + \subsection{\WebQuiz document class options}\label{SS:classOptions} + + The \WebQuiz document class supports the following options: + \begin{latexcode} + fixedorder, hidesidemenu, language, onepage, pst2pdf, + separatepages, showsidemenu, theme, tikz + \end{latexcode} + This section describes all of these document-class options except for + \ctan{tikz} and \ctan{pst2pdf}, which are discussed in + \autoref{SS:graphics}. Many of the document-class options below occur + in pairs and defaults for many of these can be set in the \webquizrc + file. The settings given in the \LaTeX{} file + for a quiz will always override the default settings in the \webquizrc*. + + \begin{description} + + \item[fixedorder, randomorder] + \CrossIndex{document class options}{fixedorder} + \CrossIndex{document class options}{randomorder} + By default, the questions in the quiz are displayed in a + \DefaultValue{fixedorder} for all students who take the quiz. + This order is the order that the question appear in the \LaTeX{} + file for the quiz. That is, the first question in the online quiz + is the first question appearing in the \LaTeX file, the second + question in the quiz is the second question in the \LaTeX{} file, + and so on. With the \LatexCode|randomorder| option the questions + in the quiz are displayed in a random order that changes each time + that the quiz is run. With this option, the online quiz questions + are generally in a different order for every student. For example, + the code: + \InputLatexCode{random} + produces the quiz with randomly arranged quiz questions, such as: + \ScreenShot{Randomly ordered questions}{random} + (So the first question in the \LaTeX{} file is being displayed as + the fourth online quiz question. The next time the page is + loaded, such as for the next student, the question order will + change again.) When using the \LatexCode|randomorder| + document-class option only the questions appear in random order. + If the quiz contains multiple choice questions then the choices + are \textit{not} randomly permuted. That is, the choices always + appear in the order that they are written in the \LaTeX{} file. + + \item[hidesidemenu, sidemenu] + \CrossIndex{document class options}{hidesidemenu} + \CrossIndex{document class options}{showsidemenu} + If the \LatexCode|hidesidemenu| option is set then the side menu + on the left-hand side of the quiz web page will not be displayed + when the quiz first loads. By default, the side menu appears + unless the screen size is too small, such as on a mobile phone. + Many examples of the \LatexCode|hidesidemenu| and + \LatexCode|showsidemenu| class options can be found above. + + The display of the side menu can is also toggled by clicking on + the {\textcolor{red}{\small\XSolidBold}} and + {\textcolor{red}{\large\ding{118}}} symbols. The side-menu + automatically disappears for devices with narrow screens, such as + mobile phones. + + \item[language=<lang>] \CrossIndex{document class options}{language} + Set the language used by the \textit{web pages} constructed by \WebQuiz. + The following languages are currently supported by \WebQuiz: + \ListWebQuizLanguages + The languages files are used to print the various buttons and text + that is generated on the web pages constructed by \WebQuiz. The + \LatexCode|language| option does not affect the DVI or + \BashCode|PDF| versions of the quiz and it does not load language + packages like \ctan{babel} or \ctan{polyglossia}. + + The \LatexCode|language| keyword can be in upper or lower case, with + the result that either (but not both!) of the following two lines set the + quiz language to German: + \begin{latexcode} + \documentclass[language=German]{webquiz} + \documentclass[language=german]{webquiz} + \end{latexcode} + + Typical usage of the \LatexCode|language| option is the following: + \lstinputlisting[style=latexcode,extendedchars=false]{examples/french} + This produces a web page like this: + \ScreenShot{A web page with \textsf{language=french}}{french} + As a general rule, \LaTeX{} and \TeXfht do not cope well with + unicode characters, so if your quiz contains (a lot of) unicode + characters then we recommend using \hologo{LuaLaTeX} or \hologo{XeLaTeX}, which + corresponds to the \WebQuiz command-line options + \BashCode|webquiz -x| or \BashCode|webquiz -l|, respectively. The + default \TeX{} engine can be set in the \webquizrc. + \index{unicode}\index{lualatex}\index{xelatex} + + The language files were created largely using google translate so + they may well need fine-tuning\footnote{The word ``Copyright'' in + the left-hand side-margin is not translated but perhaps it should + be.}. You can use \BashCode|kpsewhich| to look at the language + files, which all have names of the form \BashCode|webquiz-xxx.lang|, + where \BashCode|xxx| is the name of the language in lower case. For example, + the \textit{English} language file, which is the default, can be + found using the command: + \begin{bashcode} + > kpsewhich webquiz-english.lang + \end{bashcode} + The file \BashCode|webquiz-english.lang| contains the following: + \InputBashCode{webquiz-english.lang} + In these files, the material to the left of the equals signs are + effectively variables, and so they should never be changed, or + deleted, whereas anything to the right of the equals signs is the + text that will appear on the \WebQuiz web pages. \textit{The pairs + of braces, }\LatexCode|{}|, \textit{in the language files must be present + because in the online quizzes they expand to expressions like} + \LatexCode|(a)|, \LatexCode|(b)|\dots + + To add \WebQuiz support for a new language, say language + \LatexCode|xxx|, copy any \WebQuiz language file to a new file + \BashCode|webquiz-xxx.lang| and then translate all of the words to + the right of the equals signs.\footnote{\WebQuiz assumes that all + language names are in lower case so \texttt{xxx}, and not + \texttt{XXX}, should be used.} \WebQuiz will be able to find the new + language file as long as it appears in the \LaTeX{} search + path\footnote{To help \LaTeX/\WebQuiz fined your language file you + may need to run a program like \texttt{mktexlsr} using an + administrators account}. Once the new language file + \BashCode|webquiz-xxx.lang| is in the \LaTeX{} search path it can be + used by \WebQuiz using \LatexCode|language=xxx| as a document-class + option: + \begin{latexcode} + \documentclass[language=xxx]{webquiz} + \begin{document} + ...quiz code here... + \end{document} + \end{latexcode} + Please submit any new language files, or corrections to existing + language files, as a \textit{new issue} at: + \href{https://\webquiz{repository}}{\webquiz{repository}}. + + \item[onepage, separatepages] + \CrossIndex{document class options}{onepage} + \CrossIndex{document class options}{separatepages} + By default, only one question, or one discussion environment, is displayed + by the quiz at any time. As \LatexCode|separatepages| is the default, every + example so far is of this form. With the document-class option + \LatexCode|onepage| all questions, and discussion environments, are + displayed at the same time on a single web page. So, for example, the code: + \InputLatexCode{onepage} + produces the quiz page: + \ScreenShot{A one page quiz}{onepage} + + \item[theme]\CrossIndex{document class options}{theme} + + \WebQuiz\ has a small number of different themes for setting the + colours on the quiz web pages. The theme can be set as an option to + the document class or in the \webquizrc. Most, but not all, of the examples + so far have used the \LatexCode|default| theme. + \WebQuiz currently supports the following themes: + \ListWebQuizThemes + Example screenshots of all \WebQuiz themes can be found in + \hyperref[SS:themes]{Appendix A}. + + \end{description} + + + \subsection{Including graphics and using pstricks and tikz}\label{SS:graphics} + It is also possible to include complicated diagrams in \WebQuiz + quizzes using packages like \ctan{tikz} and \ctan{pstricks}. + \textit{As there have been several recent updates to these packages it + is advisable to install the latest version of both of these packages, + as well as the packages \ctan{make4ht}, \ctan{pgf} and \TeXfht.} In + fact, it is recommended that you update all installed \TeX{} packages. + + By far the easiest way to include images when using \WebQuiz is by + adding the following lines to your document preamble: + \begin{latexcode} + \usepackage[dvipdfmx]{graphicx} + \DeclareGraphicsExtensions{.png} + \end{latexcode} + to your document preamble. You need to use + \LatexCode|\DeclareGraphicsExtensions| to tell \WebQuiz the different + types of images you are using, so the code above works for + \LatexCode{png} images. More generally, you can use a comma separated + list of extensions, such as: + \begin{latexcode} + \DeclareGraphicsExtensions{.png, .jpg, .gif} + \end{latexcode} + The option \LatexCode|dvipdfmx| + to \LatexCode|graphicx| is only necessary if you want to be able to + rescale images. For example, the code: + \InputLatexCode{ctanLion} + produces the quiz page: + \ScreenShot{Including a lion}{ctanLion} + Note that \WebQuiz assumes that all images are \BashCode|SVG| images by + default so it is necessary to give the full filename in any + \LatexCode|\includegraphics| command. + + Using \ctan{pstricks} is often just as easy, such as the following + code that works out of the box: + \InputLatexCode{pstricks-ex} + to produce the web page: + \ScreenShot{Pstricks example}{pstricks-ex} + + Even though \ctan{tikz} and \ctan{pstricks} can be used in \WebQuiz + quizzes, both of these packages sometimes have problems. \WebQuiz tries + to solve some these problems for you if you use the + \LatexCode|pst2pdf| or \LatexCode|tikz| document-class options, which + we now describe. + + \begin{description} + \item[pst2pdf] \index{pstricks}\CrossIndex{document class options}{pst2pdf} + + For the most part, \ctan{pstricks} drawings display correctly. + When they do fail they can sometimes be salvaged using + \ctan{pst2pdf}. Applying \ctan{pst2pdf} to a \WebQuiz quiz is not + completely straightforward, so \WebQuiz provides the + document-class option \ctan{pst2pdf} to automatically apply + \ctan{pst2pdf} as part of the quiz web page build process. If your + \ctan{pstricks} drawings do not display correctly it is worthwhile + to see if \ctan{pst2pdf} fixes the problems. + + For example, the following quiz compiles only with the + \ctan{pst2pdf} document-class option: + \InputLatexCode{pst2pdf} + to produce the quiz: + \ScreenShot{Example requiring the pst2pdf document class option}{pst2pdf} + The position of the image adjusts with the screen size and it + does, in fact, display well on a mobile device. \WebQuiz is not + able to display this image without the \LatexCode|pst2pdf| + document-class option. + + \begin{dangerous} + Unfortunately, \ctan{pst2pdf} can fail silently without giving any + warnings. If you plan to use the \LatexCode|pst2pdf| + document-class option then you should first check to make that the + \ctan{pst2pdf} package and executable is properly installed. + According to the \ctan{pst2pdf} manual: + \begin{quote} + \ctan{pst2pdf} needs \Ghostscript (>=9.14), perl (>=5.18), pdf2svg, pdftoppm + and pdftops (from poppler-utils or xpdf-utils) to process a file + using \ctan{pst2pdf}. + \end{quote} + If using \ctan{pst2pdf} does not produce an image then, rather + than \ctan{pst2pdf} not working, the problem might be that you + have not installed all of the programs that \ctan{pst2pdf} relies + upon, so look in your log files for error messages and check that + all of the programs listed above are correctly installed, with the + specified version numbers. See also \autoref{SS:pstricks}. + \end{dangerous} + + \item[tikz]\CrossIndex{document class options}{tikz} + Giving this class option both loads the \ctan[pgf]{tikz} package + and it fixes several issues with PGF that prevent it from working + with \TeXfht. It is important that you use the \WebQuiz + \LatexCode|tikz| document-class option, and not + \LatexCode|\usepackage{tikz}|, because \WebQuiz loads slightly + different configuration files for \ctan[pgf]{tikz} that are + optimised for use with \TeXfht. \textit{Please note that for + \ctan[pfd]{tikz} you need to use \TeXLive \textsf{2018} with all + packages updated.} Thanks are due to Michal Hoftich for the + enormous amount of effort that he has put into making \TeXfht and + \ctan[pgf]{tikz} more compatible. As an example, the quiz file + \InputLatexCode{tikz-ex} + produces the online quiz: + \ScreenShot{Tikz example}{tikz-ex} + \end{description} + + Most people use either \ctan{pstricks} or \ctan{tikz}. A quiz that + tries to use both \ctan{pstricks} and \ctan{tikz} will probably not + compile. + + \subsection{Configuring commands and environments for \TeXfht}\label{SS:config}\macroIndex{DisplayAsImage} + + The underlying engine used by \WebQuiz is \TeXfht so, because + \TeXfht is not able process all \LaTeX{} code, there is \LaTeX{} + code that \WebQuiz is not able to cope with. This said, \TeXfht is + able to display \textit{most} \LaTeX{} code and \WebQuiz has been + used to write literally thousands of quiz questions so it is likely + that you will be able to typeset what you want in your online + quizzes. In particular, as discussed in \autoref{SS:graphics}, it + is possible to use \ctan[pgf]{tikz} and \ctan{pstricks} in \WebQuiz + quizzes. + + \WebQuiz uses \TeXfht{} to convert the quiz content from \LaTeX{} to + \HTML. If \TeXfht{} has not been configured to for some of the + commands or environments that you are using then they may not + display correctly in your online quizzes. The ``correct'' way to + fix such problems is to write appropriate \TeXfht{} configuration + commands, however, this can be tricky to do --- especially if you + are not familiar with the inner workings of \TeX{} and \TeXfht. + + As a workaround, \WebQuiz provides the command + \LatexCode|\DisplayAsImage| that, in effect, tells \TeXfht to treat + your command as an image when it creates the web page. This is an + easy work-around that often produces good results -- and it is much + easier than writing your own \TeXfht configuration commands. + + For example, the \ctan{mhchem} package is a powerful package that + defines a macro \LatexCode{\ce} for writing chemical symbols but, + unfortunately, the \LatexCode{\ce} macro has not (yet) been + configured to work with \TeXfht, which means that this command does + not work very well when used in \WebQuiz quizzes. + + For example, the following code: + \InputLatexCode{display-as-image} + shows that if you add the line + \LatexCode|\DisplayAsImage{ce}| to your quiz after + \LatexCode|\begin{document}| then it is + possible to use \LatexCode|\ce| in your quizzes: + \ScreenShot{Using DisplayAsImage}{display-as-image} + As the example code shows, \LatexCode|\DisplayAsImage| accepts an optional + argument that can be used to fine-tune the placement of the image on + the quiz web page using \CSS. For those interested in the technical details, the + definition of \LatexCode|\DisplayAsImage| is: + \begin{latexcode} + \RequirePackage{etoolbox} + \renewcommand\DisplayAsImage[2][]{% + \csletcs{real:#2}{#2}% + \NewConfigure{#2}{2} + \csdef{#2}##1{\Picture+[#1]{}\csuse{real:#2}{##1}\EndPicture} + \Configure{#2}{\Picture+[#1]{}}{\EndPicture} + } + \end{latexcode} + + \section{System requirements, installation and configuration} + \label{S:configuration} + \index{system requirements} + \CrossIndex{system requirements}{tex4ht} + \CrossIndex{system requirements}{make4ht} + \CrossIndex{system requirements}{python} + + \WebQuiz takes a \LaTeX\ file and translates it into a functional + web page. To use \WebQuiz the quiz author only needs to know how to + use \LaTeX\ \textit{and} to have all of the programs used by \WebQuiz + installed. Fortunately, most of the system requirements will already + be installed on a system with an up-to-date installation of + \TeXLive, however, some tweaking may still be necessary. + + Behind the scenes, \WebQuiz uses \TeXfht, \python, \Javascript and + several other tools to construct and operate the online quizzes. + The \WebQuiz program has three main components: + \begin{itemize} + \item \LaTeX\ files (a class file and \TeXfht configuration files) + \item A Python3 program that uses \TeXfht to convert \LaTeX\ + files into web pages + \item Web files (\Javascript, \CSS and online documentation) + %\item Documentation + \end{itemize} + Of course, to use the online quizzes created by \WebQuiz you + need a web server. To use \WebQuiz all of these files need to + be in appropriate places. Fortunately, \Ctan takes care of + most of this but the web-related files still need to be put onto + your web server. + + \WebQuiz has been tested extensively on Linux and Mac operating + systems. Several people have used \WebQuiz on windows computers, + but I have not tested the program on a windows computer myself. + + \subsection{System requirements}\index{system requirements} + + In order to work \WebQuiz needs the following programs to be + installed on your system: + \begin{itemize} + \item An up-to-date \LaTeX{} distribution, such as that provided + by \TeXLive. In particular, you need to have \TeXfht{} and + \ctan{make4ht} installed. + + Unfortunately, the version of \ctan{make4ht} that was released + with \TeXLive{} 2018 had some bugs and there have been many + recent changes to \ctan{make4ht} and \ctan{pstricks}, + so it is strongly recommended that you update all packages + from \Ctan before you try and use \WebQuiz. + + \item \python[Python 3]. As of writing python 3.7.2 is available. + \item \Javascript + \item If your quizzes use \ctan{pstricks}, or if you want to + compile the \OnlineManual, then you need to ensure that + \Ghostscript and \ctan{dvisvgm} are installed and properly + configured; see \autoref{SS:pstricks} for more details. + \item A web server. As detailed in \autoref{SS:Initialise}, you + will need to install the web components of \WebQuiz. + \end{itemize} + + \subsection{Initialising \WebQuiz}\label{SS:Initialise} + \CrossIndex{command-line option}{initialise} + \index{initialisation} + + \WebQuiz is a tool for creating online quizzes and in order for + it to work efficiently various files + (\href{https://en.wikipedia.org/wiki/JavaScript}{javascript} and + \href{https://www.w3schools.com/css/css_intro.asp}{cascading style + sheets}) need to put onto your web server. \WebQuiz has an + \textit{initialisation} routine for installing the web components + of the program. In fact, until \WebQuiz has been initialised it + will ask you if you to run the initialisation routine every time + you use \WebQuiz. You can reinitialise \WebQuiz at any time using + the command-line option: + \begin{bashcode} + > webquiz --initialise + \end{bashcode} + \WebQuiz will actually work without being initialised, however, any + quiz web pages that are created before initialisation will be + emblazoned with a message reminding you to initialise \WebQuiz. + + The location of the files on the web server depends both on the + operating system that is running on your computer and how your web + server has been configured. It is essential that the \WebQuiz files + are installed in a directory that is accessible from the web. It + does not matter if they are put into a user web directory or into a + system web directory. If in doubt please consult your system + administrator. + + Common locations for the \textit{web root} of the server are: + \begin{center} + \begin{tabular}{ll} + \toprule + Operating system & Root of web server \\\midrule + Mac OSX & \BashCode|/Library/WebServer/Documents|\\ + Linux & \BashCode|/var/www/html|\\ + Windows & \BashCode|C:\inetpub\wwwroot|\\ + \bottomrule + \end{tabular} + \end{center} + \WebQuiz needs to copy several files into a subdirectory of this + \textit{web root}. When you run + \begin{bashcode} + > webquiz --initialise + \end{bashcode} + you will be prompted for the following: + \begin{itemize} + \item The location of the \WebQuiz web directory, which needs to + be a directory that is visible to your web server + \item The relative URL for this directory, which tells your web + browser where to find these files + \end{itemize} + For example, on my system the web root for our web server is + \BashCode|/usr/local/httpd/| and the \WebQuiz web files are in + the directory \BashCode|/usr/local/httpd/UoS/WebQuiz|. So, I set: + \begin{quote} + \begin{tabular}{lll} \WebQuiz web + directory &=& \BashCode|/usr/local/httpd/UoS/WebQuiz|\\ + \WebQuiz relative URL &=& \BashCode|/UoS/WebQuiz| + \end{tabular} + \end{quote} + Once the initialisation step is complete, \WebQuiz is ready to use + although you, possibly from an administrators account or using + \BashCode|sudo|, may also want to run: + \begin{bashcode} + > webquiz --edit-settings + \end{bashcode} + This will talk you the process of setting system defaults for the quizzes that, + for example, specify the name and URL for your department and + institution as well as the default language and theme used for the + quizzes. If in doubt about any of the option press return to accept + the default. See \autoref{SS:rcfile} for more details. + + You can test your \WebQuiz installation by compiling the example + files from the \WebQuiz manual. You can find these files in the + directory \BashCode|web_root/doc/examples|, where the + \BashCode|web_root| is the directory where you just installed + the \WebQuiz web files. If \Ghostscript and \ctan{dvisvgm} are + installed and properly configured (see \autoref{SS:graphics}) then you + should also be able to compile the \OnlineManual using \WebQuiz. + + \begin{dangerous} + \textit{To install the \WebQuiz files for general use on + your system, or to save system wide settings, you need to run + the initialisation command }\BashCode|webquiz --initialise| + \textit{using an administrator account or using \BashCode|sudo| on a + UNIX or Mac OSX system.} + + If you have already saved a \textit{user} \webquizrc file then to + change the \textit{system} \webquizrc* you will use need to + use the \BashCode|--rcfile| command-line option: + \begin{latexcode} + > webquiz --rcfile /path/to/system/rc-file --initialise + \end{latexcode}\index{rcfile} + \end{dangerous} + + \begin{heading}[Remark] + To remove all \WebQuiz files from your web server use: + \begin{bashcode} + > webquiz --uninstall + \end{bashcode} + \end{heading} + + \subsection{Graphics and \texorpdfstring{\ctan{dvisvgm}}{dvisvgm}} + \label{SS:pstricks} + + \index{pstricks} + \noindent + \WebQuiz, via \TeXfht, uses \ctan{dvisvgm} to convert certain images to + \href{https://en.wikipedia.org/wiki/Scalable_Vector_Graphics}{Scalable + Vector Graphics} (SVG). This is done using his is done + using \ctan{dvisvgm}. At first sight this is OK because \ctan{dvisvgm} is + included in \TeXLive and Mik\TeX, however, \ctan{dvisvgm} uses + \Ghostscript and this needs to be correctly configured and, as + outlined in \href{http://dvisvgm.bplaced.net/FAQ}{FAQ}, \ctan{dvisvgm} + needs to know where to find the \Ghostscript libraries. For example, + to get \ctan{dvisvgm} to work on my system I needed to add the line + \begin{bashcode} + export LIBGS=/usr/local/lib/libgs.dylib + \end{bashcode} + to my \BashCode|.bashrc| file. To see whether you need to do something + similar on your system you need to look at the output from the following + two commands: + + \begin{bashcode} + > dvisvgm -h + > dvisvgm -l + \end{bashcode} + + \noindent There are three possibilities: + + \begin{itemize} + \item the \BashCode|-h| output does not contain \BashCode|-libgs| + and the \BashCode|-l| output contains \BashCode|ps|: + ghostscript was linked at build time, so everything should work + \item + the \BashCode|-h| output contains \BashCode|-libgs| and the + \BashCode|-l| output does not contain \BashCode|ps|: + gpostscript support is enabled but ghostscript is not linked. You + need to locate the ghostscript library + \BashCode|libgs.so| or \BashCode|libgs.dylib| on your system and set + the \BashCode|LIBGS| environment variable, or equivalent, + accordingly + \item the \BashCode|-h| output does not contain \BashCode|-libgs| + and the \BashCode|-l| output does not contain \BashCode|ps|: + \ctan{dvisvgm} was not built with postscript support. In this + case, \WebQuiz will not be able to process \ctan{svg} images. You + need to reinstall \ctan{dvisvgm} with ghostscript support. + \end{itemize} + + \section{The \WebQuiz program} \index{usage} + + The \WebQuiz program was designed to be run from the command-line. + To produce an online quiz from a \WebQuiz \LaTeX{} file \BashCode|quiz.tex| + type: + \begin{bashcode} + > webquiz quiz or > webquiz quiz.tex + \end{bashcode} + One feature of \WebQuiz is that you can process more than one + quiz file at a time. For example, if you have quiz files + \BashCode|quiz1.tex|, ..., \BashCode|quiz9.tex| in the current directory + then, on a UNIX system, you can rebuild the web pages for all of + these quizzes using the single command: + \begin{bashcode} + > webquiz quiz[1-9].tex + \end{bashcode} + This is useful if some generic aspect of all of the quizzes has + changed, such as the theme, the language, thebreadcrumbs or a + department URL. In fact, one would probably use + \begin{bashcode} + > webquiz -dqq quiz*.tex + \end{bashcode} + because the \BashCode|webquiz --qq| command-line option suppresses + almost all of the output produced by \LaTeX\ and \TeXfht and + \BashCode|-d|, which is \textit{draft mode}, is faster and it is + probably sufficient if the quizzes were compiled recently. The + next section discusses the \WebQuiz command-line options. + + \subsection{Command-line options}\label{SS:commandline} + \index{command-line option} + Typing \BashCode|webquiz -h|, or \BashCode|webquiz --help| on + the command-line gives the following summary of the \WebQuiz + command-line options: + \InputBashCode{webquiz.usage} + The command-line options are listed on separate lines above to + improve readability. In practice, the different options need to be + one the same line, although they can appear in any order. + + We describe the different options, grouping them according to + functionality. + + \begin{description} + \item[-h, --help] \CrossIndex{command-line option}{help} + list the command-line options and exit + \CrossIndex{command-line option}{help} + + \item[-q, -qq, \ddash quiet] \CrossIndex{command-line option}{quiet mode} + Suppress \LaTeX{} and \TeXfht error messages: \BashCode|-q| is + quiet and \BashCode|-qq| is very quiet. If you use + \BashCode|webquiz -qq texfile.tex| then almost no output will + be printed by \WebQuiz when it is processing your quiz file. Be + warned, however, that both of these options can make it harder + to find and fix errors, so using the \BashCode|-q| and + \BashCode|-qq| options is recommended if your file is known + to compile. + \CrossIndex{command-line option}{quiet} + + \end{description} + + \subsubsection*{\TeX{} options} + + \begin{description} + + \item[-d, \ddash draft] draft mode. The \LaTeX file is processed + only once by \BashCode|htlatex|, which gives a much faster + compilation time but cross references etc may not be completely + up to date. This is equivalent to using: + \BashCode|make4ht --mode draft| + \CrossIndex{command-line option}{draft mode} + + \item[-s,\ddash shell-escape] Shell escape for \LaTeX/ht\LaTeX/make4ht + \CrossIndex{command-line option}{shell-escape} + + \item[\ddash latex] Use \LaTeX{} to compile the quiz (the default) + \CrossIndex{command-line option}{lua} + + \item[-l,\ddash lua] Use lua\LaTeX{} to compile the quiz + \CrossIndex{command-line option}{lua} + + \item[-x, \ddash xelatex] Use xe\LaTeX{} to compile the quiz + \CrossIndex{command-line option}{xelatex} + \index{xelatex} + + \end{description} + + \subsubsection*{Settings and configuration} + + \begin{description} + + \item[-r {[RCFILE]}, \ddash rcfile {[RCFILE]}] + \CrossIndex{command-line option}{rcfile} Specify the + location of the \webquizrc file to use. This setting is only + necessary if you want to override the default \webquizrc*. + + \item[-i, \ddash initialise] \CrossIndex{command-line + option}{initialisation} Initialise files and settings for + webquiz. See \autoref{SS:Initialise} for more details. + + \item[\ddash edit-settings] \CrossIndex{command-line + option}{edit-settings} Edit the webquiz settings in the + \WebQuiz rc-file. See \autoref{SS:rcfile} for more details. + + \textit{If you do not have permission to write to the system + rc-file, which is in the \WebQuiz scripts directory, then you + will be given the option of saving the \WebQuiz settings to an + rc-file in your home directory or another file of your choice. + If you want to save the settings to a particular rc-file use + the \BashCode|--rcfile| option. If you want to change the + system \webquizrc then use a administrator account or, + on a unix-like system,} use \BashCode|sudo webquiz --edit-settings|. + + \item[\ddash settings {[SETTING]}] \CrossIndex{command-line option}{settings} + \SeeIndex{rcfile}{webquizrc} + \SeeIndex{default settings}{webquizrc} + List system settings for webquiz stored in \webquizrc, the + (\textit{run-time configuration file}). Optionally, a single + \BashCode|SETTING| can be given in which case the value of + only that setting is returned. If \BashCode|SETTING| is + omitted then the list of current settings are printed. Use + \BashCode|SETTING=verbose| for a more verbose listing of the + settings and \BashCode|SETTING=help| for a summary of the + settings. + + The rc-file can be edited by hand, however, it is + recommended that you instead use + \begin{bashcode} + webquiz --edit-settings + \end{bashcode} + Typical settings returned by this command look like: + \InputBashCode{webquiz.settings} + See \autoref{SS:rcfile} for more details. + + \end{description} + + \subsubsection*{Advanced command-line options} + + \begin{dangerous} + \textit{Change these settings with care: an incorrect value for + these settings can stop \WebQuiz from working.} + \end{dangerous} + + \begin{description} + \item[\ddash make4ht MAKE4HT-OPTIONS] + \CrossIndex{command-line option}{make4ht} + Options to be passed to \ctan{make4ht} when converting the + \LaTeX{} to \XML. This option is equivalent to setting + the \BashCode|make4ht| in the \webquizrc; see + \autoref{SS:rcfile}. At least under UNIX, multiple arguments + should be enclosed in quotes. For example, to give + \ctan{make4ht} a custom mk4 file (note that + \BashCode|myquiz.mk4| is included, if it exists), you would use + \begin{bashcode} + > webquiz --make4ht "-e file.mk4" myquiz.tex + \end{bashcode} + The \BashCode|make4ht| command-line option will be required + only in rare instances. + \index{lualatex}\index{xelatex} + + \item[\ddash uninstall] Remove all \WebQuiz files from your + web server directory. This command only removes files that + \WebQuiz may have installed on your web server. It does + \textit{not} remove \WebQuiz from your \LaTeX{} distribution. + + \item[\ddash webquiz-layout WEBQUIZ-LAYOUT] + \CrossIndex{command-line option}{layout} + Name of (local) \python code that controls the layout of quiz web page. This + option is equivalent to setting the \LatexCode|webquiz-layout| + in the \webquizrc. See \autoref{SS:layout} for + more details. + + \end{description} + + \subsubsection*{Other options} + + The following command-line options are mainly useful mainly for + code developers. + + \begin{description} + \item[\ddash version] Prints the \WebQuiz version number and + exit (currently \webquiz{version}) + + \item[\ddash tex-install] Use this command-line option if + are are installing the \LaTeX{} components of + \WebQuiz from the \Ctan zip-file. It will install the different + \LaTeX{} components of \WebQuiz into \BashCode|TEXMFMAIN|. If + you installed \WebQuiz as part of a \TeX{} distribution, such as + \TeXLive, then you do not need to use this option. + + \item[\ddash tex-uninstall] Use this command-line option to + remove the \LaTeX{} components of \WebQuiz from your system. + Only use this option if you installed \WebQuiz using the \Ctan + zip-file. + + \item[\ddash debugging] Displays extra debugging information + when compiling and prevents \WebQuiz from deleting the many + intermediary files that are created when building the quiz web + pages. + \end{description} + + \subsection{\WebQuiz settings and the webquizrc file} + \label{SS:rcfile}\index{default settings}\index{webquizrc} + + \WebQuiz stores the following default sets in \webquizrc*, a + \textit{run-time configuration file}: + \begin{description}[nosep, labelwidth=18ex] + \item[breadcrumbs] breadcrumbs at the top of quiz page (\autoref{SS:breadcrumbs}) + \item[department] name of department (\autoref{SS:breadcrumbs}) + \item[department-url] url for department (\autoref{SS:breadcrumbs}) + \item[engine] default tex engine used to compile web pages (\autoref{SS:classOptions}) + \item[hide-side-menu] do not display the side menu at start of quiz + (\autoref{SS:classOptions}) + \item[institution] institution or university (\autoref{SS:breadcrumbs}) + \item[institution-url] url for institution or university (\autoref{SS:breadcrumbs}) + \item[language] default language used on web pages (\autoref{SS:classOptions}) + \item[one-page] display questions on one page (\autoref{SS:classOptions}) + \item[random-order] randomly order the quiz questions (\autoref{SS:classOptions}) + \item[theme] default colour theme used on web pages (\autoref{SS:classOptions}) + \item[version] webquiz version number for webquizrc settings + (\autoref{SS:rcfile}) + \item[webquiz-url] relative url for webquiz web directory (\autoref{SS:Initialise}) + \item[webquiz-www] full path to webquiz web directory (\autoref{SS:Initialise}) + \item[make4ht] build file for make4ht (\autoref{SS:Initialise}) + \item[mathjax] url for mathjax (\autoref{SS:Initialise}) + \item[webquiz-layout] name of \python module that formats the quizzes + (\autoref{SS:layout}) + \end{description} + The last three options are \textit{advanced options} that you should + change with care. + + The default values of all of these settings can be overridden in the + \LaTeX{} file for the quiz, or with the command-line options. The + default values can be changed at any time using + \begin{bashcode} + webquiz --edit-settings + \end{bashcode} + When changing the settings \WebQuiz tries to explain what it is + doing at each step. If you are unsure what a particular setting does + then \textit{press return} to accept the default value --- the + default value is printed inside square brackets as + \BashCode|[default]|. In particular, when you first start using + \WebQuiz it is recommended that you accept the default values + for all of the advanced options because it is very unlikely that you + will need to change these initially. + + The first line of output from \BashCode|webquiz --settings| gives + the location of the rc-file being used. The system rc-file, + \webquizrc*, is saved in the \BashCode|tex/latex/webquiz| subdirectory + of the \BashCode|TEXMFLOCAL| directory. A typically location for + this file is + \begin{bashcode} + /usr/local/texlive/texmf-local/tex/latex/webquiz/webquizrc + \end{bashcode} + By default, the \WebQuiz settings are saved here so that you do not + need to reinitialise \WebQuiz whenever you update your \TeX{} + distribution. If you do not have permission to write to this + directory then you will be asked if you would like to save the + rc-file somewhere else. The location of the user rc-file is: + \begin{itemize} + \item \BashCode|~/.dotfiles/config/webquizrc| + if the directory \BashCode|~/.dotfiles/config| exists, + \item \BashCode|~/.config/webquizrc| + if the directory \BashCode|~/.config| exists, + \item \BashCode|~/.webquizrc| otherwise. + \end{itemize} + Each time \WebQuiz is run it reads the system and user rc-files, if + they exist. When using \BashCode|webquiz --edit-settings| you will + be promoted for a different installation location if you do not have + permission to write to the specified rc-file. To use a particular + \webquizrc* use the \BashCode|--rcfile| command-line option: + \begin{bashcode} + > webquiz --rcfile <full path to rc-file> ... + \end{bashcode} + If you save the settings to a non-standard location then you will + need to use the command-line option \BashCode|webquiz --rcfile RCFILE| to access + these settings. + + \noindent To describe the \WebQuiz defaults settings we consider them by category. + + \subsubsection*{Institution settings} + \begin{description} + + \item[department] + Sets the default department name. This can be overridden in + the \LaTeX{} file using \LatexCode|\Department| in + \autoref{SS:breadcrumbs} + \CrossIndex{webquizrc}*{Department} + + \item[department-url] + Sets the URL for the department. This can be overridden in + the \LaTeX{} file using \LatexCode|\DepartmentURL| in + \autoref{SS:breadcrumbs} + \CrossIndex{webquizrc}*{DepartmentURL} + + \item[institution] + Sets the default institution name. This can be overridden in the + \LaTeX{} file using \LatexCode|\Institution| in + \autoref{SS:breadcrumbs} + \CrossIndex{webquizrc}*{Institution} + + \item[institution-url] + Sets the URL for the institution.This can be overridden in + the \LaTeX{} file using \LatexCode|\InstitutionURL| in + \autoref{SS:breadcrumbs} + \CrossIndex{webquizrc}*{InstitutionURL`} + + \end{description} + + \subsubsection*{Formatting options} + + \begin{description} + + \item[breadcrumbs]\index{breadcrumbs} + Sets the default breadcrumbs at the top of quiz page. The + default breadcrumbs can be overwritten in the quiz file using + the \LatexCode{\BreadCrumbs} command. See + \autoref{SS:breadcrumbs} for more details. + \CrossIndex{webquizrc}*{BreadCrumbs} + + \item[engine] Sets the default \TeX{} engine to be used when + compiling the quiz. By default, \BashCode|latex| is used, with + the two other possibilities being \BashCode|lua| and + \BashCode|xelatex|, for \Hologo{LuaLaTeX} and \hologo{XeLaTeX} + respectively. Behind the scenes, the two choices + correspond to invoking \ctan{make4ht} with the + \BashCode|--lua| and \BashCode|--xelatex| options, + respectively. The \BashCode|engine| setting in the + \webquizrc* can be overridden by the webquizrc + \BashCode|--latex|, \BashCode|--lua| and \BashCode|--xelatex|. + \CrossIndex{webquizrc}{engine} + \CrossIndex{webquizrc}{latex} + \CrossIndex{webquizrc}{lualatex} + \CrossIndex{webquizrc}{xelatex} + + \item[language]\index{language} + Sets the default language for the \WebQuiz web pages. This can + be overridden in the quiz file by using the document class + \LatexCode|language| option: \LatexCode|language=xxx| + See \autoref{SS:classOptions}. + \CrossIndex{webquizrc}{language} + + \item[theme]\index{theme} + Sets the default colour theme for the \WebQuiz web pages. This can + be overridden in the quiz file by using the document class + \LatexCode|theme| option: \LatexCode|theme=xxx|. + See \autoref{SS:classOptions}. + \CrossIndex{webquizrc}{theme} + + \end{description} + + \subsubsection*{Advanced options} + + \begin{description} + + \item[make4ht]\index{make4ht} + Options for \ctan{make4ht}. Rather than using \TeXfht + directly, \WebQuiz uses \ctan{make4ht} to convert the + \LaTeX\ file to \XML. Use this option to + customise how \ctan{make4ht} is called. See the + \ctan[make4ht]{make4ht manual} for more information. + \CrossIndex{webquizrc}{make4ht} + + \item[mathjax] \WebQuiz web pages use \href{https://www.mathjax.org/}{mathjax} to + render the mathematics on the quiz web pages. By default this + is done by loading \BashCode|mathjax| from + \begin{bashcode} + https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js + \end{bashcode} + Fetching \BashCode|mathjax| from an external site can + cause a delay when the quiz web pages are loaded. This setting + in the rc-file allows you to change where \BashCode|mathjax| is + loaded from. For example, if you install \BashCode|mathjax| on + your web server then you would replace this will the + corresponding relative URL. + \CrossIndex{webquizrc}{mathjax} + + \item[webquiz-layout] + Sets the \python file that writes the \HTML file for the quiz. + Most people will not need this option. The next subsection + describes how to do this in more detail. + \CrossIndex{webquizrc}{layout} + + \end{description} + + \subsubsection*{Configuration settings} + Use \BashCode|webquiz --initialise| to change these settings. + + \begin{description} + + \item[webquiz-url] This is the relative URL for \WebQuiz web directory + \CrossIndex{webquizrc}{webquiz-url} + + \item[webquiz-www] This is the full path to the \WebQuiz web + directory. The \OnlineManual and other example code can be found + in the \BashCode|docs| subdirectory. If you use \BashCode|bash|, + then the command + \begin{bashcode} + > cd $(webquiz --settings webquiz-www)/docs + \end{bashcode}%$ + will take you to the \WebQuiz online \BashCode|docs/| directory. + \CrossIndex{webquizrc}{webquiz-www} + + \end{description} + + \subsection{Changing the layout of the \WebQuiz web pages} + \label{SS:layout}\index{layout} + + \begin{dangerous} + \textit{This is an advanced \WebQuiz feature that most people will + not need. To change the layout of the quiz web pages created by + \WebQuiz requires working knowledge of \HTML and \python.} + \end{dangerous} + + The construction of the online quizzes is controlled by the \python + file \PythonCode|webquiz_standard.py|. If you want to change the + structure of the web pages for the quizzes then the easiest way to + do this is to make a copy of \PythonCode|webquiz_standard.py|, say + \PythonCode|webquiz_myformat.py|, and then edit this file directly. + This will require working knowledge of \python and \HTML. To give + you an idea of what needs to be done, the \python file + \PythonCode|webquiz_standard| contains a single function + \PythonCode|write_web_page| that returns the \HTML for the page as a + string using the following: + \begin{htmlcode} + quiz_page = r'''<!DOCTYPE HTML> + <html lang="en"> + <head> + <title> {title} </title> + {htmlpreamble} + </head> + <body> + {no_script}{breadcrumbs} + <div class="quiz-page"> + {side_menu} + <div class="quiz-questions"> + {quiz_header} + {quiz_questions} + </div> + </div> + {webquiz_init} + </body> + </html> + ''' + \end{htmlcode} + By changing this output you can change the layout of the quizzes + produced by \WebQuiz. For example, by adding code to the + \HTMLCode|<head>...</head>| section of \HTMLCode|quiz_page| it is + easy to include new \CSS code and by modifying + \HTMLCode|<body>....</body>| you can change the layout of the page. + More sophisticated versions of \PythonCode|webquiz_standard.py|, + where you change the underlying \python code, are possible. At the + University of Sydney we have a custom version of + \PythonCode|webquiz_standard.py| that calls our content management + system and, in this way, embeds the quiz web page inside a web page + that used the official ``branding'' required by our university. + + When experimenting with a new layout can run + \WebQuiz using the command: + \begin{bashcode} + > webquiz --webquiz-layout webquiz_myformat quizfile.tex + \end{bashcode} + Once the new layout is finalised you can make it the default + layout by setting \BashCode|webquiz-layout| equal to \BashCode|webquiz_my_format| + in the \webquizrc using \BashCode|webquiz --edit-settings|. + \index{edit-settings}\index{webquiz-layout} + + If you do make modifications to any of these files then, by the + \WebQuiz Licensing agreement, you are required to create a new + version of this file that has a \textit{different name}. Doing this + will also make it easier for you to integrate your changes with any + future releases of \WebQuiz. + + \subsection{Bugs, issues and feature requests}\index{bug reports} + Please report any bugs, issues or feature requests using the + \textit{issue} tracker at + \begin{quote} + \href{https://\webquiz{repository}}{\webquiz{repository}}. + \end{quote} + When reporting a bug please provide a \textit{minimal working example} + that clearly demonstrates your problem. This should be a compilable + \LaTeX file that looks something like the following: + \begin{latexcode} + \documentclass{webquiz} + \begin{document} + ** insert problematic code here ** + \end{document} + \end{latexcode} + Bug reports that do not have a minimal working example can be + hard to reproduce in which case it is not possible to fix them. + Before submitting a bug export please first compile your quiz using + (pdf)latex to check to see if your problem is an issue with \LaTeX + or with \WebQuiz. If you can, please also test to see if your code + compiles using \TeXfht directly. + +\appendix +\section*{Appendices} + \addcontentsline{toc}{section}{Appendices} +\renewcommand\thesection{} +\renewcommand\thesubsection{\Alph{subsection}} + + \subsection{Catalogue of web page themes}\index{theme}\label{SS:themes} + \WebQuiz{} comes with different themes for changing the colour scheme + of the online quizzes, which can be set using the \LatexCode|theme| + document-class option or in the \webquizrc; see + \autoref{SS:classOptions} for more details. Themes are easy to + construct in principle although finding colours that work well together + can be tricky in practice so, as a result, there are some themes that + I would not personally recommend! + + New themes, and modifications to existing themes, can be submitted as + an \textit{issue} at: + \begin{quote} + \href{https://\webquiz{repository}/issues}{\webquiz{repository}/issues}. + \end{quote} + Where possible these will be incorporated into a future release of the + package, although there is a potential technical issue here in that + the underlying \CSS files are written using + \href{http://sass-lang.com/}{sass}. + + \ShowcaseThemes + +\subsection{The online \WebQuiz manual}\label{S:online} + + \WebQuiz has an \OnlineManual* that is a \LaTeX file written with the + \LatexCode|webquiz| document class. The conversion of the manual from + \LaTeX{} to \HTML is done by \WebQuiz. The \BashCode|PDF| version of + this manual is included here as an easy reference. The source file + for the \OnlineManual* is included in the documentation of \WebQuiz to + allow you to create a local version of the \OnlineManual*. Look for the + file \BashCode|webquiz-online-manual.tex| in the + \BashCode|webquiz-www/docs| directory; see~\autoref{SS:rcfile}. + + The online manual can either be compiled as a PDF file (see below), + or using \WebQuiz to produce an online version of the manual. + The \OnlineManual* was written for ``internal use'' when \WebQuiz was + first written in 2004. \WebQuiz has evolved quite a lot since then. + There is some overlap between the \OnlineManual* and previous sections, + however, the \OnlineManual* only describes how to typeset questions and + it does not cover some of the more recent features of \WebQuiz, such + as the document class options, or how to use the program. If there + are any discrepancies between the \OnlineManual* and the earlier + sections of this manual then the \OnlineManual* should be discounted. + + The \OnlineManual* has diagrams that are drawn using \ctan{pstricks} + and, as a result, to create a \BashCode|PDF| version of the \OnlineManual* + use \BashCode|latex webquiz-online-manual| to create a + \BashCode|dvi| file. The \BashCode|dvi| file can be converted to + \BashCode|PDF| using \BashCode|dvipdf|. The online manual needs to be + compiled using \BashCode|latex| rather than \BashCode|pdflatex|, + which will generate errors. + + \includepdf[pages=-,pagecommand={\pagestyle{webquiz}}]{webquiz-online-manual} + + +\subsection{Licence} + +Version 3, Copyright (C) 2007, + +\href{https://www.gnu.org/licenses/gpl-3.0.en.html} + {GNU General Public License, Version 3, 29 June 2007} + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License (GPL) as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. + + +\vfil +\begin{tabular}{@{}ll} +Authors & \webquiz{authors}\\ +Description & \webquiz{description}\\ +Maintainer & \webquiz{name}\\ +System requirements & \webquiz{requirements}\\ +Licence & \webquiz{licence}\\ +Release date & \webquiz{release date}\\ +Repository & \href{https://\webquiz{repository}}{\webquiz{repository}} +\end{tabular} +\eject + +\printindex + +\end{document} |