Package {convertxlsform}

convertxlsform: Convert an XLSForm to a Word or PDF Paper Form

Description

Reads an XLSForm questionnaire (as used by Open Data Kit and KoboToolbox) and writes a formatted paper version as a Word document, or as a PDF converted from that document with LibreOffice.

Author(s)

Maintainer: Masud Rahman write2masud+convertxlsform@gmail.com [copyright holder]

Authors:

• Masud Rahman write2masud+convertxlsform@gmail.com [copyright holder]

See Also

Useful links:

• https://github.com/masud90/convertxlsform

• Report bugs at https://github.com/masud90/convertxlsform/issues

Convert an XLSForm from the terminal

Description

Runs convertxlsform() with options taken from the command line. Use it from a shell without opening R:

Usage

cli(args = commandArgs(trailingOnly = TRUE))

Arguments

Details

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

Put the XLSForm path and the options after the quoted expression. If a script or CI job needs the exit status, use ⁠Rscript -e 'quit(status = convertxlsform::cli())' form.xlsx⁠. The plain form above also works for normal use.

This function is a terminal interface. Its help and version text go to standard output, and usage errors go to standard error, because that output is its purpose. Progress messages are sent with message() and --quiet suppresses them (the same as verbose = FALSE in convertxlsform()).

Value

The exit status invisibly: 0 on success, 1 on a usage error or a failed conversion. The function does not quit R.

Usage

cli(args): form.xlsx [options]. Options accept ⁠--name value⁠ and --name=value.

• -o, ⁠--output PATH⁠: output file or folder (default: next to the form).

• -f, ⁠--format docx|pdf|both⁠: output format (default: from the extension of --output, else docx).

• -l, ⁠--lang LANG⁠: language code, name or header suffix.

• --flat-numbers: number questions 1, 2, 3 instead of 1.1, 1.2.

• --no-relevants: hide skip logic.

• --no-constraints: hide constraints.

• --no-hints: hide hints.

• --no-choice-codes: hide choice codes.

• --show-names: show variable names.

• --include-hidden: include calculate, start, end and similar rows.

• ⁠--media-root DIR⁠: folder for media and external files (default: the folder of the form).

• ⁠--title TEXT⁠: form title.

• ⁠--page-size A4|letter⁠ (default A4).

• --landscape: landscape orientation.

• ⁠--margins IN⁠: margins in inches (default 1).

• ⁠--font NAME⁠ (default Arial) and ⁠--font-size PT⁠ (default 11).

• ⁠--template FILE⁠: reference .docx for styles.

• ⁠--max-choices N⁠: longest choice list printed in full (default 30).

• ⁠--repeat-copies N⁠: copies of each repeat group (default 1).

• --overwrite: replace existing output.

• --quiet: no progress messages.

• -h, --help: show the help and stop.

• --version: show the package version and stop.

See Also

convertxlsform()

Examples

path <- system.file("extdata", "minimal", "minimal.xlsx",
                    package = "convertxlsform")
cli(c(path, "-o", tempdir(), "--overwrite", "--quiet"))

Convert an XLSForm to a Word or PDF document

Description

Reads an XLSForm (as used by Open Data Kit and KoboToolbox) and writes a formatted paper version for interviewing and review. The default output is a Word document next to the input file. A PDF is made by converting the Word document with LibreOffice (or Microsoft Word through the doconv package); see docx_to_pdf() and has_libreoffice().

Usage

convertxlsform(xlsform, output = NULL, format = NULL, lang = NULL, ...)

Arguments

Value

The path or paths of the files written, as a character vector, invisibly.

Where the file goes

• output = NULL: same folder and base name as xlsform, with the new extension.

• output is an existing folder: ⁠<base name>.<ext>⁠ inside it.

• output is a file path: used as given. Its extension (.docx or .pdf) sets format when format is NULL, and must agree with format otherwise.

• Two formats (format = c("docx", "pdf")) write two files with the same base name. With a file path in output, its extension is replaced.

An existing file is never replaced unless overwrite = TRUE.

See Also

xlsform_outline() to inspect a form before converting it, docx_to_pdf(), and cli() for the terminal.

Examples

path <- system.file("extdata", "minimal", "minimal.xlsx",
                    package = "convertxlsform")
out <- file.path(tempdir(), "minimal.docx")
convertxlsform(path, output = out, verbose = FALSE, overwrite = TRUE)


# A multilingual form: another language, flat question numbers, US letter
path_ml <- system.file("extdata", "multilang", "multilang.xlsx",
                       package = "convertxlsform")
convertxlsform(path_ml, output = tempdir(), lang = "bn",
               nested_serial_numbers = FALSE, page_size = "letter",
               verbose = FALSE, overwrite = TRUE)

# PDF needs LibreOffice
if (interactive() && has_libreoffice()) {
  convertxlsform(path, output = tempdir(), format = "pdf",
                 verbose = FALSE, overwrite = TRUE)
}

Convert a Word document to PDF

Description

Converts a .docx file to PDF with LibreOffice, or with Microsoft Word through the doconv package. LibreOffice is free and runs on all platforms. Each call uses a fresh temporary LibreOffice profile, so it works while a LibreOffice window is open and in parallel runs.

Usage

docx_to_pdf(
  docx,
  pdf = NULL,
  engine = c("auto", "libreoffice", "word"),
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Details

If LibreOffice is installed in an unusual place, set the option convertxlsform.soffice or the environment variable CONVERTXLSFORM_SOFFICE to the path of the soffice binary.

Value

The path of the PDF, invisibly.

Examples

if (interactive() && has_libreoffice()) {
  docx <- tempfile(fileext = ".docx")
  doc <- officer::read_docx()
  doc <- officer::body_add_par(doc, "Hello")
  print(doc, target = docx)
  pdf <- docx_to_pdf(docx, pdf = tempfile(fileext = ".pdf"))
  file.exists(pdf)
}

Is LibreOffice available?

Description

Reports whether a LibreOffice binary can be found, which is needed to convert Word documents to PDF with docx_to_pdf(). The search checks the option convertxlsform.soffice, the environment variable CONVERTXLSFORM_SOFFICE, the PATH, and the default install locations for the operating system.

Usage

has_libreoffice()

Value

TRUE or FALSE.

Examples

has_libreoffice()

List the languages of an XLSForm

Description

Finds the languages used in the ⁠label::<language>⁠ style columns of the survey and choices sheets, for example label::English (en), label::en or label::English.

Usage

xlsform_languages(xlsform)

Arguments

Value

A data.frame with one row per language and columns suffix (the text after ::), code, name and default (TRUE for the language used when no lang is requested: the default_language of the settings sheet if it matches, otherwise the first language). The data.frame has no rows for a single-language form.

Examples

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

Outline of an XLSForm

Description

Parses an XLSForm and returns one row for each item that would appear on the paper form: sections, questions, notes and the end of repeat groups. It shows the question numbers, the answer type, the number of choices, and the skip logic and constraints in plain language, so a form can be checked before it is converted.

Usage

xlsform_outline(xlsform, lang = NULL, ...)

Arguments

Value

A data.frame with one row per block and columns row (Excel row of the form), serial (question number, NA when unnumbered), depth (number of enclosing groups), block ("section", "section_end", "note" or "question"), kind (the question kind, for example "select_one", or "begin_group", "begin_repeat", "end_repeat", "note"), name, label, required, n_choices (all choices of a select or rank question, not counting an "other" row), relevant_text, constraint_text (the constraint message when the form has one, else the humanized expression) and layout (for select and rank questions: "list", "columns" or "code_box", from the number of choices and max_choices; NA otherwise). A label may contain line breaks (⁠\n⁠).

Examples

path <- system.file("extdata", "minimal", "minimal.xlsx",
                    package = "convertxlsform")
out <- xlsform_outline(path)
out[, c("serial", "block", "kind", "name", "relevant_text")]


# A multilingual form: another language, with flat question numbers
path_ml <- system.file("extdata", "multilang", "multilang.xlsx",
                       package = "convertxlsform")
out <- xlsform_outline(path_ml, lang = "bn", nested_serial_numbers = FALSE)
head(out[, c("serial", "name")], 5)