[Tex/LaTex] Feedback on new package for creating on-line quizzes from latex

ctanpackage-writingtex4htwebquiz

WebQuiz has now been released as a package on ctan. It will be included in TeXLive 2019. Accordingly, the links below have been updated to point to ctan, or disabled.

If you want to install WebQuiz from the ctan zipfile then run:

webquiz --tex-install

from an administrator account, or use

 sudo webquiz --tex-install

on unix-like systems (including macosx). This will install the package into the "standard" locations in the TeXLive tree. (The webquiz executable is in the webquiz/scripts directory of the zipfile.) I am not sure what this will do on a windows PC.

Arguably this question is either too broad or outside of the scope of TeX.SX, so I accept that it may be closed. As I only want feedback I'd also be happy if this was made a community wiki.

I have a close-to-finished latex package, WebQuiz , documentation, that can be used to write on-line quizzes starting from "normal" latex files. The package is basically ready for uploading to ctan but before I do this I would be really grateful for feedback from TeX.SX, both from TeX experts and from people who might use such a package. My hope is to fix any existing problems before the package appears on ctan rather than having to put out a new release soon after the code first appears.

Using an example from a "real" quiz, the idea of the package is that with a latex file like this:

\documentclass{webquiz}
\title{Quiz 1: Numbers and sets}
\begin{document}

    \begin{question}
    Which of the following are correct ways of writing the set
    \[ A=\{x \in \mathbb{R} \mid -3 < x \leq -1 \text{ or } x\geq 0\} ?\]
    \begin{choice}
    \incorrect $(-3,\infty)$
    The interval \response $(-3,\infty)$ includes the real numbers between $-1$ and $0$,
    which do not belong to $A$.

    \incorrect $[-3,\infty)$
    \response The interval $[-3,\infty)$ includes $-3$, as well as
    the real numbers between $-1$ and $0$, none of which belong to $A$.

    \incorrect $[-3,-1]\cap[0,\infty)$
    \response The interval $[-3,-1]\cap[0,\infty)$ is the empty set $\emptyset$. As $A$ is not empty (for example, $A$ includes $-1$), this option cannot be correct.

    \incorrect $(-3,-1)\cup[0,\infty)$
    \response The interval $-1$ is not in $(-3,-1)\cup[0,\infty)$, but $-1$ is in $A$.

    \correct $(-3,-1]\cup[0,\infty)$
    \end{choice}
    \end{question}

    ...more questions...
\end{document}

you can produce an on-line quiz that looks something like this (after some has unwisely answered option b):

enter image description here

WebQuiz displays one question at a time. It is a formative assessment tool. It does not collect assessment data or worry about any of the associated "security issues" this would entail. The quizzes made with the package are ideal for use as a revision resource. One key feature is that the quiz writer can give feedback to the students based on each possible answer that they can give to questions.

To write quizzes using WebQuiz you only need working knowledge of LaTeX. Nothing more. Behind the scenes the conversion of the quiz from LaTeX into HTML is done using using tex4ht (and
make4ht) and some python code. In more detail, tex4ht, make4ht, xml, python, HTML, mathjax, css and javascript all play a role but the LaTeX user only needs to know LaTeX.

As tex4ht is the underlying engine there certainly exists LaTeX code that WebQuiz cannot cope with. This said, the system has already been used to write literally thousands of quiz questions without any problems. In particular, it is possible to use tikz and pstricks in WebQuiz quizzes, although (very?) complicated drawings with these packages may fail.

I am interested in any feedback people are willing to give me. I am particularly interested in knowing the following:

  • Is the zip file packaged correctly for ctan?
  • Is the installation process clear and does it work? (The installation process works for me but it may fail for others. Once the package is on ctan this will be easier)
  • Are there any bugs or obvious improvements?
  • Is there anything missing from, or unclear in, the documentation?
  • Are there any font encoding issues? Perhaps unwisely everything is processed as UTF-8
  • In order to keep settings when the tex system is updated the package saves a system configuration file in $TEXMFLOCAL/scripts/webquiz/webquizrc. Is this the appropriate place and will this work under windows and MikTeX?
  • Are there any problems under windows? Preferably with a fix because I do not have access to a windows computer so I am unable to test such issues.

The first complete version of WebQuiz was written around 2004. This year I have almost completely rewritten it whilst making it compatible with HRML5 and, more significantly, changing it from in-house code to a more fully featured package. The bulk of the code has been used extensively, so it is well tested. Some of the new fewer features, such as the "programmable" \BreadCrumbs command and the installation procedure, are relatively untested. I would not be too surprised if I have broken something with the many recent changes that I have made whilst packaging it. This is why I'd like some feedback before putting the package on ctan.

WebQuiz requires an update-to-date version of LaTeX, including TeX4ht and make4ht, a recent version of python 3 and, of course, a web server. Page 5 of the manual, which is the file webquiz.pdf in the doc directory of the zip file, describes the steps necessary to get the code working. The short version is:

  • the files in the latex directory need to be put in the LaTeX search path (after which you have to run texhash or equivalent)
  • the MathQuiz program is in the scripts directory. On unix like systems the best option is to make a link like
    ls -s webquiz.py /usr/local/bin/webquiz
  • ideally the files in the scripts/www directory need to be put somewhere on your web server, which can be done using the command webquiz --initialise. In fact, WebQuiz will still work even if you don't do this but you will get (harmless) warning messages about initialising whenever you run the program and similar warning messages on every web page you create
  • documentation can be found in the doc directory and example code from the manual in the scripts/www/examples directory.

Once WebQuiz is installed, you can test your quiz file quiz.tex first using (pdf)LaTeX, to create a DVI or PDf file, and then use

webquiz quiz.tex

from the command-line to produce the file quiz.html, which you can view using your web browser.

I have used WebQuiz on linux and mac operating systems. Several groups have used it under windows, but I don't have access to a windows machine so I have not done this myself.

Finally, I apologise for the length of this post, any bugs in the package and for the many typos here and in the documentation that I am sure are there…

Best Answer

It has been quite some time since I posted this question so I am happy to say that the package is finally available on ctan. As suggested in the comments above, the name of the package has been changed to WebQuiz. The package has expanded a little since I posted the question. In particular, it now includes support for 11 languages (in principle, support for other languages is easy to add) and different colour themes (some of which are, arguably, horrible -- sorry!).

Apart from asking about the functionality of the package, the main question that I asked in the post was about how best to package the code for ctan (and TeXLive). I was told by the ctan and TeXLive maintainers that they strongly preferred a zipfile (and not a TDS file) with:

  • a README file in the top directory
  • separate directories for the latex, doc and script components of the package
  • TeXLive asked for a UNIX man page, since the package contains a standalone executable
  • I initially had all all of the web files, which need to be installed when the program is initialised, in the scripts directory. TeXLive asked for these files to be moved to the doc directory as files in the scripts are in the runtime search tree
  • if a file needs to be included twice in different directories then the second copy should be a symbolic link
Related Question