exams2html: Generation of Exams in HTML Format

Description

Automatic generation of exams in HTML format.

Usage

exams2html(file, n = 1L, nsamp = NULL, dir = ".", template = NULL,
    name = NULL, quiet = TRUE, edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    question = "Question
", solution = "Solution",
    mathjax = FALSE, resolution = 100, width = 4, height = 4, svg = FALSE,
    encoding = "", converter = NULL, …)
  make_exercise_transform_html(converter = c("ttm", "tth", "pandoc", "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(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. The default is to use the "plain.html" file provided in the package unless there are Rmd exercises in file. Then, "plain8.html" is used (which expects UTF-8 encoding as used by pandoc).

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 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 the templates.

solution

character or logical, see 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 (or SVG) graphics passed to xweave.

svg

logical. Should graphics be rendered in SVG or PNG (default)?

encoding

character, passed to xweave.

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 .rda files.

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.

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

Run the code above in your browser using DataLab