convertxlsform

convertxlsform turns an XLSForm, the questionnaire format used by Open Data Kit (ODK) and KoboToolbox, into a formatted paper version. Survey managers can use the output to review a questionnaire with colleagues, print it for interviewers, or check skip logic and constraints in one readable document. It writes a Word file (.docx) by default, and a PDF when LibreOffice or Microsoft Word is available. Forms can be multilingual, and the paper version follows the language you choose.

The bundled all_types example, converted to PDF.

Full reference and articles: https://masud90.github.io/convertxlsform/. New here? Start with the Getting started vignette.

Installation

install.packages("remotes")
remotes::install_github("masud90/convertxlsform")

To install a specific release, add its tag:

remotes::install_github("masud90/convertxlsform@v0.3.0")

Word output needs only R. PDF output needs one of the following:

• LibreOffice (free, all platforms). Install it, then run the command for your system:
  • macOS: brew install --cask libreoffice, or download it from https://www.libreoffice.org/download/.
  • Windows: download it from https://www.libreoffice.org/download/.
  • Ubuntu: sudo apt install libreoffice-writer.
• Microsoft Word, through the doconv package. Install doconv in R. convertxlsform uses Word only when LibreOffice is not found.

has_libreoffice() detects LibreOffice only. Word is used through docx_to_pdf(engine = "word") with doconv, and convertxlsform() falls back to it when LibreOffice is not found.

Quick start

In R (RStudio or any R session):

library(convertxlsform)

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

convertxlsform(path, output = tempdir())                  # Word file
convertxlsform(path, output = tempdir(), format = "pdf")  # PDF file

From a terminal, run the command with Rscript. Put the form path and the options after the quoted expression:

Rscript -e 'convertxlsform::cli()' form.xlsx --format pdf --lang bn

The package ships the example form above, which covers the question types and features the package renders. Replace path with the path to your own form, for example convertxlsform("survey.xlsx"). The output is written next to the form, with the same base name and a .docx or .pdf extension. The function returns the path of the file it wrote, invisibly.

EXAMPLE=$(Rscript -e 'cat(system.file("extdata", "all_types", "all_types.xlsx", package = "convertxlsform"))')
Rscript -e 'convertxlsform::cli()' "$EXAMPLE" --format pdf --output .

Rscript -e "convertxlsform::cli()" form.xlsx --format pdf --lang bn
Rscript -e "cat(system.file('extdata', 'all_types', 'all_types.xlsx', package = 'convertxlsform'))"

Rscript -e 'quit(status = convertxlsform::cli())' form.xlsx --format pdf

What you get

• Front matter: the form title, version and form ID, the language, the date of generation, and a legend that explains the marks used in the document.
• Groups: headings numbered by depth. Repeat groups carry a “Repeat for each …” line that describes the repeat count.
• Questions: the number and label, a * for required questions, the hint in italics, and the variable name when show_variable_names = TRUE. “Ask if” and “Constraint” lines follow the answer area.
• Single choice (select_one): a hollow circle before each choice. Lists of seven or fewer choices print in one column; longer lists print in columns.
• Multiple choice (select_multiple): a hollow square before each choice.
• Rank: a box beside each choice to write its rank.
• Long choice lists: when a list is longer than max_choices, the paper form shows a code box for the respondent to write the code, and a compact table of every choice with its code.
• Text and numbers: a bordered write-in box. Multiline text gets a taller box.
• Date and time: a printed pattern (dd/mm/yyyy, hh:mm).
• Location: latitude, longitude and accuracy fields for geopoint. geotrace and geoshape get a prompt and a reference line.
• Media: an image is printed at its size, scaled down to fit (questions up to 2 inches tall, choices up to 0.6 inches). A missing file prints a placeholder with its name, and convertxlsform warns about it.
• Notes: printed without a number.
• Hidden types (calculate, start, end, deviceid and similar) are left out unless include_hidden = TRUE.

Languages

How language columns are read

Translated columns carry the language in the header. convertxlsform accepts any of these forms:

• label::English (en): name and code. This is the form used in the bundled examples.
• label::en: code only.
• label::English: name only.

The same pattern works for hint, guidance_hint, required_message, constraint_message, image, audio and video. A plain label column (no suffix) is used when no translated column exists.

To list the languages in a form and see which one is the default:

xlsform_languages(system.file("extdata", "multilang", "multilang.xlsx",
                              package = "convertxlsform"))

The result has one row per language, with suffix, code, name and default. It has no rows for a single-language form.

Choosing a language

lang accepts a code, a name, or the full header suffix. If the requested language is not in the form, convertxlsform warns, lists the languages it found, and uses the default language instead.

Within a language, a blank cell falls back in this order: the column for the chosen language, then the plain column (for example hint), then the column of the default language. A blank French hint, for example, shows the English hint when the form has one.

Connective phrases

Phrases such as “Ask if”, “Constraint” and “Repeat for each” come from built-in tables. convertxlsform includes English and French. Any other language uses the English phrases unless you supply translations with strings.

To translate them, pass a named list. Only the names listed below can be used, and an unknown name is an error:

The full list of names is in R/strings.R. A Bengali version of the bundled multilingual form would look like this. The "..." values are placeholders to replace with translations that you write or check with a Bengali speaker:

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

convertxlsform(
  path,
  output = tempdir(),
  lang = "bn",
  strings = list(
    ask_if          = "...",  # Bengali for "Ask if"
    constraint      = "...",  # Bengali for "Constraint"
    choice_filter   = "...",  # Bengali for "Choices shown if"
    repeat_for_each = "...",  # Bengali for "Repeat for each"
    other_specify   = "..."   # Bengali for "Other (specify)"
  )
)

Until every placeholder is filled in, the paper form will show the placeholder text.

Options

PDF output and fonts

PDF output converts the Word document, so it needs LibreOffice, or Microsoft Word through doconv as a fallback (see Installation). Word output has no such requirement.

convertxlsform looks at the characters in the labels of the language in use. When it finds Bengali, Arabic, Devanagari or Ethiopic text, it sets the complex-script font to the matching Noto font:

Latin text uses font_family. To choose the complex-script font yourself, pass font_family_cs:

convertxlsform(path, lang = "bn", font_family_cs = "Noto Sans Bengali")

The font must be installed on the machine that converts the document to PDF. If the named font is missing, LibreOffice or Word substitutes another font, which can show boxes or the wrong script.

Right-to-left layout is not yet supported. Arabic and Hebrew text is detected, but the document is still laid out left to right.

Known issue: PDF output can show blank text for Bengali and other complex scripts when LibreOffice cannot find a suitable font on the machine. The Word document is correct. A fix is planned for 0.4.0. See Troubleshooting below for workarounds.

Inspect a form

xlsform_outline() returns the numbered form as a data frame, one row per item on the paper form. It is a quick way to check numbering, question types, choice counts and skip logic before you convert the form:

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

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

The columns are row (the Excel row), serial, depth, block, kind, name, label, required, n_choices, relevant_text, constraint_text and layout. Use lang to inspect another language, and nested_serial_numbers = FALSE for flat numbers.

Troubleshooting

options(convertxlsform.soffice = "/path/to/soffice")

Performance

Very large forms (hundreds of questions and long choice lists) can take tens of seconds to convert, and longer for PDF because LibreOffice has to lay out every page.

Contributing

Work on a feature branch and open a pull request against main. Tests use testthat:

testthat::test_local()

Build and check the package from a temporary folder, so that build products stay out of the repository:

cd "$(mktemp -d)" && R CMD build "$OLDPWD" && R CMD check --no-manual convertxlsform_*.tar.gz

License

convertxlsform is released under the MIT license. The LICENSE file names the copyright holder and year, in the form CRAN requires.