exams2pandoc {exams}

Generation of Exams via Pandoc

Description

Automatic generation of exams via pandoc, by default in docx format.

Usage

  exams2pandoc(file, n = 1L, nsamp = NULL, dir = ".",
    name = "pandoc", type = "docx", template = "plain.tex",
    question = "Question", solution = "Solution",
    header = list(Date = Sys.Date()), inputs = NULL, options = NULL,
    quiet = TRUE, resolution = 100, width = 4, height = 4, svg = FALSE,
    encoding = "UTF-8", envir = NULL, engine = NULL,
    edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
    points = NULL, exshuffle = NULL, ...)

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.

name

character. A name prefix for resulting exercises.

type

character. The file type to convert to using pandoc. The default is "docx" (but other choices are also supported, e.g., "odt", "html", "markdown" etc.).

template

character. A specification of a template in either LaTeX, HTML, or Markdown format. The default is to use the "plain.tex" file provided but an alternative "plain.html" is also available.

question

character or logical. Should the question be included in the output? If question is a character it will be used as a header for resulting questions.

solution

character or logical, see argument question.

header

list. A list of named character strings (or functions generating such) to be substituted in the template.

inputs

character. Names of files that are needed as inputs for the template (e.g., images, headers). Either the full path must be given or the file needs to be in edir.

options

character. A string of options to be passed on to pandoc_convert.

quiet

logical. Should output be suppressed when calling xweave?

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.

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?

points

integer. How many points should be assigned to each exercise? Note that this argument overules any exercise points that are provided within the expoints tags of the exercise files (if any). The vector of points supplied should either have length 1 or the number of exercises in the exam.

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).

...

currently not used.

Details

exams2pandoc can generate exams in various output formats (by default docx) using xexams and pandoc_convert. It proceeds by (1) calling xweave on each exercise, (2) reading the resulting LaTeX or Markdown code, (3) transforming the code to the markup of some exam template (either LaTeX, HTML, or Markdown), (4) embedding the code in a template and converting it to the desired output format using pandoc.

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_pandoc. Depending on which format the template uses (LaTeX or HTML or Markdown) the transformation may or may not be trivial.

For step (4) all exercises are inserted into the template (and also replacing certain additional tags from header) and then pandoc_convert is used to convert to the desired output format (one file for each exam). In principle, all output types of pandoc are supported, but most of them have not been tested. (The main motivation for exams2pandoc was the generation of "docx" or "odt" files.)

Value

exams2pandoc returns a list of exams as generated by xexams.

See Also

xexams, pandoc_convert

Examples

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

## define an exams (= list of exercises)
myexam <- list(
  "boxplots.Rmd",
  c("tstat.Rmd", "ttest.Rmd", "confint.Rmd"),
  c("regression.Rmd", "anova.Rmd"),
  c("scatterplot.Rmd", "boxhist.Rmd"),
  "relfreq.Rmd"
)

## output directory
dir.create(mydir <- tempfile())

## compile two docx and odt versions each
set.seed(1090)
exams2pandoc(myexam, n = 2, dir = mydir, type = "docx")
set.seed(1090)
exams2pandoc(myexam, n = 2, dir = mydir, type = "odt")