summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/webquiz/webquiz.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/webquiz/webquiz.tex')
-rw-r--r--Master/texmf-dist/doc/latex/webquiz/webquiz.tex2306
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}