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",
  name = NULL, quiet = TRUE, edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
  question = "Question
", solution = "Solution",
  mathjax = FALSE, resolution = 100, width = 4, height = 4,
  encoding = "", ...)
  make_exercise_transform_html(converter = c("ttm", "tth", "tex2image"),
    base64 = TRUE, ...)
    
  make_exams_write_html(template = "plain", name = NULL,
    question = "
Question
", solution = "Solution",
    mathjax = FALSE)

Arguments

file

character. A specification of a (list of) exercise files.

integer. The number of copies to be compiled from file.

nsamp

integer. The number 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

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. The package currently provides "plain.html".

name

character. A name prefix for resulting exercises.

quiet

logical. Should output be suppressed when calling Sweave?

edir

character specifying the path of the directory in which the files in file are stored (see also below).

tdir

character specifying a temporary directory, by default this is chosen via tempdir. Note that this is cleaned up and potentially temporary files are deleted.

sdir

character specifying a directory for storing supplements, by default this is chosen via tempdir.

verbose

logical. Should information on progress of exam generation be reported?

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

solution

character or logical, see to argument question.

mathjax

logical. Should the JavaScript from http://www.MathJax.org/ be included for rendering mathematical formulas?

resolution, width, height

numeric. Options for rendering PNG graphics passed to Sweave.

encoding

character, passed to Sweave.

converter

character. Workhorse function for transforming LaTeX code to HTML. For details see below.

base64

logical. Should images be embedded using Base 64 coding? Argument base64 may also be a character vector of file endings that should be Base 64 encoded, e.g. base64 = c("png", "rda") will only encode PNG images and binary

...

arguments passed on to make_exercise_transform_html.

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.

Details

exams2html generates exams in a very simple HTML format using xexams. It proceeds by (1) calling Sweave on each exercise, (2) reading the resulting LaTeX code, (3) transforming the LaTeX code to HTML, and (4) embedding the HTML code in a very simple exercise template (which is currently hard-coded). 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 three functions: ttm produces HTML with MathML for mathematical formulas, tth produces plain HTML that aims to emulate mathematical 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 hard-coded template and writes a single HTML file for each exam.

When generating only a single exam (as in the examples below), exams2html tries to display this directly in a browser using browseURL. This may not work properly in RStudio versions older than 0.97.133. To avoid these problems, one can either upgrade to a more recent version of RStudio or set R's browser option manually to a suitable value, e.g., to options(browser = NULL) on Windows, options(browser = "/usr/bin/firefox") on Linux, or options(browser = "/Applications/Firefox") on OS X.

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. http://www.jstatsoft.org/v58/i01/.

Examples

Run this code

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

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

## examples with different locales (UTF-8, ISO-8859-15)
## using special characters (Euro and Pound symbol, German umlaut)
if(!identical(Sys.getlocale(), "C")) {
## UTF-8
exams2html("currency8", encoding = "utf8", template = "plain8")

## ISO Latin 9 (aka ISO-8859-15)
exams2html("currency9", encoding = "latin9", template = "plain9")
}


## 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)
exams2html("tstat", converter = "tex2image")
}

Run the code above in your browser using DataLab