exams2html: Generation of Exams in HTML Format

Description

Automatic generation of exams in HTML format.

Usage

exams2html(file, n = 1L, nsamp = NULL, dir = ".", template = "plain.html",
    name = NULL, quiet = TRUE, edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    rds = FALSE, question = "Question
", solution = "Solution",
    mathjax = NULL, resolution = 100, width = 4, height = 4, svg = FALSE,
    encoding = "UTF-8", envir = NULL, engine = NULL, converter = NULL, seed = NULL,
    exshuffle = NULL, ...)
  make_exercise_transform_html(converter = c("ttm", "tth", "pandoc", "tex2image"),
    base64 = TRUE, options = NULL, ...)
  make_exams_write_html(template = "plain", name = NULL,
    question = "
Question
", solution = "Solution",
    mathjax = FALSE)

Value

exams2html returns a list of exams as generated by xexams.

make_exercise_transform_html returns a function that is suitable for being supplied as driver$transform to xexams.

make_exams_write_html returns a function that is suitable for being supplied as driver$write to xexams.

Arguments

file: character. A specification of a (list of) exercise files.
n: integer. The number of copies to be compiled from file.
nsamp: integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir: character specifying the output directory (default: current working directory). If only a single HTML file is produced and no dir is explicitly specified, the file is displayed in the browser rather than saved in dir.
template: character. A specification of a HTML template.
name: character. A name prefix for resulting exercises.
quiet: logical. Should output be suppressed when calling xweave?
edir: character specifying the path of the directory (along with its sub-directories) in which the files in file are stored (see also xexams).
tdir: character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir: character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose: logical. Should information on progress of exam generation be reported?
rds: logical indicating whether the return list should also be saved as an RDS data file.
question: character or logical. Should the question be included in the HTML output? If question is a character it will be used as a header for resulting questions. Argument question may also be a vector that controls the output for the templates.
solution: character or logical, see argument question.
mathjax: logical. Should the JavaScript from https://www.MathJax.org/ be included for rendering mathematical formulas? By default mathjax = FALSE unless converter = "pandoc-mathjax".
resolution, width, height: numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg: logical. Should graphics be rendered in SVG or PNG (default)?
encoding: character, ignored. The encoding is always assumed to be UTF-8.
envir: argument passed to xweave (which passes it to knit).
engine: argument passed to xweave indicating whether "Sweave" (default) or "knitr" should be used for rendering Rnw exercises.
base64: logical. Should supplementary files be embedded using Base 64 coding? Argument base64 may also be a character vector of file suffixes that should be encoded, e.g. base64 = c("png", "rda") will only encode PNG images and binary .rda files. If set to NULL only image files will be encoded.
converter, ...: arguments passed on to make_exercise_transform_html. The default for converter is set to "ttm" unless there are Rmd exercises in file where "pandoc" is used.
seed: integer matrix or logical. Either NULL (default), logical, or a matrix of random seeds for each possible exercise to be set prior to calling driver@sweave. If NULL no random seeds are set. If a matrix, the number of rows must be n and the number of columns must correspond to unlist(file). If TRUE a suitable matrix of seeds is sampled.
exshuffle: logical or integer. If the exshuffle argument is non-NULL it is used to overrule the exshuffle tag from the file (e.g., exshuffle = FALSE can be used to keep all available answers without permutation).
options: list of options to be passed on to pandoc_convert.

Details

exams2html generates exams in a very simple HTML format using xexams. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting LaTeX code, (3) transforming the LaTeX code to HTML, and (4) embedding the HTML code in a template (a simple and plain template is used by default).

For steps (1) and (2) the standard drivers in xexams are used.

For step (3) a suitable transformation function is set up on the fly using make_exercise_transform_html. This transforms the LaTeX code in question/questionlist and solution/solutionlist by leveraging one of four functions: ttm produces HTML with MathML for mathematical formulas, tth produces plain HTML that aims to emulate mathematical formulas, pandoc_convert employs pandoc offering different options for handling formulas, and tex2image runs LaTeX and turns the result into a single image. In all cases, images can either be stored in supplementary files or embedded directly in Base 64 coding.

For step (4) a simple writer function is set up on the fly that embeds the transformed HTML code into a template and writes a single HTML file for each exam.

References

Zeileis A, Umlauf N, Leisch F (2014). Flexible Generation of E-Learning Exams in R: Moodle Quizzes, OLAT Assessments, and Beyond. Journal of Statistical Software, 58(1), 1--36. tools:::Rd_expr_doi("10.18637/jss.v058.i01").

Examples

Run this code

## load package and enforce par(ask = FALSE)
options(device.ask.default = FALSE)

if(interactive() && requireNamespace("png")) {
## compile a single random exam (displayed in the browser)
exams2html(list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  "scatterplot.Rmd",
  "relfreq.Rmd"
))

## various versions of displaying mathematical formulae

## via MathML (displayed correctly in MathML-aware browsers, e.g. Firefox)
exams2html("tstat")

## via MathML + MathJax (should work in all major browsers,
## note the display options you get when right-clicking on the formulas
## in the browser)
exams2html("tstat", mathjax = TRUE)

## via plain HTML (works in all browsers but with inferior formatting)
exams2html("tstat", converter = "tth")

## via HTML with embedded picture (works in all browsers but
## is slow and requires LaTeX and ImageMagick)
if (FALSE) {
exams2html("tstat", converter = "tex2image")
}
}

Run the code above in your browser using DataLab