Getting started with convertxlsform
In convertxlsform: Convert an 'XLSForm' to a 'Word' or PDF Document

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

convertxlsform reads an XLSForm, the questionnaire format used by Open Data Kit (ODK) and KoboToolbox, and writes a paper version as a Word document or a PDF. This vignette walks through the main steps using the example form that ships with the package. All output goes to tempdir(), so nothing is written next to the installed package.

The example form

The example is all_types.xlsx. It covers the question types and features the package renders, including groups, repeats, cascading choice lists, and geo and media questions.

library(convertxlsform)

path <- system.file("extdata", "all_types", "all_types.xlsx",
                    package = "convertxlsform")
basename(path)

Languages

xlsform_languages() lists the languages in the form and marks the default. Language columns are named like label::English (en) or label::French (fr).

xlsform_languages(path)

The default language is used when no lang is given. Pass a code ("fr"), a name ("French") or the full suffix ("French (fr)") to choose another one.

Inspecting the form

xlsform_outline() returns one row per item on the paper form, with the question numbers, the question kind and the skip logic in plain language. Use it to check a form before converting it. The example below shows the first ten rows.

outline <- xlsform_outline(path)
nrow(outline)
head(outline[, c("serial", "block", "kind", "name", "relevant_text")], 10)

Groups and notes also appear as rows. Notes are not numbered, so their serial is NA.

Converting to Word

convertxlsform() writes a Word document. The default output is a .docx file with the same base name as the form. Here the output goes to tempdir(), and the function returns the path of the file it wrote.

docx <- convertxlsform(path, output = tempdir(), overwrite = TRUE,
                       verbose = FALSE)
basename(docx)
file.exists(docx)

To produce the French version, pass lang. Where a French hint is blank, the English hint is shown, because a blank cell falls back to the plain column and then to the default language.

docx_fr <- convertxlsform(path, output = file.path(tempdir(), "all_types_fr.docx"),
                          lang = "fr", overwrite = TRUE, verbose = FALSE)
basename(docx_fr)

Converting to PDF

A PDF is made by converting the Word document with LibreOffice, or with Microsoft Word through the doconv package. PDF output needs LibreOffice (or Word with doconv), so the code below is shown but not run when the vignette is built.

pdf <- convertxlsform(path, output = tempdir(), format = "pdf",
                      overwrite = TRUE, verbose = FALSE)
basename(pdf)
file.exists(pdf)

If LibreOffice is installed in an unusual place, set options(convertxlsform.soffice = "/path/to/soffice") before converting.

Next steps

The README lists every option, the terminal commands and how to translate the built-in phrases with strings.
?convertxlsform gives the full description of the options.
?xlsform_outline describes the columns of the outline.