Package {lssdoc}

Title:	Render 'LimeSurvey' '.lss' Questionnaires as Word and PDF Documents
Version:	0.2.0
Description:	Render 'LimeSurvey' '.lss' survey exports as questionnaire documents in Word ('.docx') or PDF, displaying one to four languages side by side with localized chrome in English, French, German, Spanish and Italian. Includes a rule-based automated audit that flags missing translations, forward filter references, duplicate codes, array-scale inconsistencies and orphan structural references. Designed for anyone working with a 'LimeSurvey' survey: researchers, methodologists, ethics committees, translators and reviewers. Processing is fully local: the source file is the only input and no questionnaire content is uploaded to a third-party service.
License:	MIT + file LICENSE
Encoding:	UTF-8
Language:	en-US
Depends:	R (≥ 4.1)
Imports:	cli, lifecycle, rlang, xml2
Suggests:	flextable, knitr, officer, rmarkdown, testthat (≥ 3.0.0), zip
VignetteBuilder:	knitr
Config/testthat/edition:	3
URL:	https://amaltawfik.github.io/lssdoc/, https://github.com/amaltawfik/lssdoc
BugReports:	https://github.com/amaltawfik/lssdoc/issues
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-09-13 20:57:25 UTC; at
Author:	Amal Tawfik [aut, cre, cph]
Maintainer:	Amal Tawfik <amal.tawfik@hesav.ch>
Repository:	CRAN
Date/Publication:	2026-09-13 21:20:02 UTC

lssdoc: Render 'LimeSurvey' '.lss' Questionnaires as Word and PDF Documents

Description

Render 'LimeSurvey' '.lss' survey exports as questionnaire documents in Word ('.docx') or PDF, displaying one to four languages side by side with localized chrome in English, French, German, Spanish and Italian. Includes a rule-based automated audit that flags missing translations, forward filter references, duplicate codes, array-scale inconsistencies and orphan structural references. Designed for anyone working with a 'LimeSurvey' survey: researchers, methodologists, ethics committees, translators and reviewers. Processing is fully local: the source file is the only input and no questionnaire content is uploaded to a third-party service.

Example surveys

Two example .lss files ship with the package and are reachable with base::system.file(), so every reader can reproduce the examples and the Get started vignette without supplying their own LimeSurvey export:

• demo_survey.lss – a clean, synthetic four-language survey (English, French, German, Spanish) with quotas and a consent block: system.file("extdata", "demo_survey.lss", package = "lssdoc").

• audit_demo.lss – a deliberately flawed survey seeded with every anomaly audit_lss() detects: system.file("extdata", "audit_demo.lss", package = "lssdoc").

Author(s)

Maintainer: Amal Tawfik amal.tawfik@hesav.ch (ORCID) (ROR) [copyright holder]

Authors:

• Amal Tawfik amal.tawfik@hesav.ch (ORCID) (ROR) [copyright holder]

See Also

Useful links:

• https://amaltawfik.github.io/lssdoc/

• https://github.com/amaltawfik/lssdoc

• Report bugs at https://github.com/amaltawfik/lssdoc/issues

Audit a LimeSurvey survey for reviewable anomalies

Description

Inspect a LimeSurvey survey and flag anomalies that can be detected without any AI. The audit guides a human reviewer; it does not silently correct anything. Every finding names a precise location and a severity.

Usage

audit_lss(input)

Arguments

Details

Checks performed:

• Missing translations – a question, help, answer, or subquestion text present in at least one language but empty in another.

• Empty in all languages – a translatable text empty in every language.

• Duplicate codes – a question variable code repeated in the survey, or an answer/subquestion code repeated within one question.

• Whitespace in codes – a question, subquestion or answer code containing leading, trailing or interior whitespace (likely a typo; causes subtle bugs in the data export).

• Missing options for the type – a question whose type requires answer options or subquestions but has none (per the type taxonomy).

• Forward filter references – a relevance expression that names a variable appearing at or after the filtered question (the value is not yet collected when the filter is evaluated).

• Array-scale inconsistencies – an array (single or dual) whose subquestions reference a scale_id that has no answer options, or vice versa.

• Orphan references – a subquestion or answer pointing to a question that does not exist.

Value

An object of class lss_audit: a list with file, languages, summary counts, and a findings data frame (severity, check, location, language, message). It has a print() method and an as.data.frame() method.

See Also

render_audit() to write the same findings to a Word or PDF document.

Examples

# A deliberately flawed demo survey ships with the package, seeded
# with every anomaly the audit detects.
demo <- system.file("extdata", "audit_demo.lss", package = "lssdoc")
audit_lss(demo)

Build and validate a survey specification

Description

Usage

lss_spec(
  title,
  groups,
  languages = NULL,
  language = NULL,
  welcome = NULL,
  end_text = NULL,
  quotas = NULL
)

Arguments

Details

Experimental. Assemble a survey specification – the authoring-side counterpart of the lss object – that write_lss() can turn into an importable LimeSurvey .lss file. The specification is validated in depth at construction time, because LimeSurvey itself imports silently: a mistyped attribute, a filter referencing a missing answer code, or a cap larger than the option list are all accepted on import and only surface once respondents hit them.

Each question is a list with fields:

• code – stable technical code (letters then letters/digits, at most 20 characters), unique across the survey. Codes become variable names in the data and are pinned once fieldwork starts.

• kind – the question type. Choice kinds: "single" (radio list), "dropdown", "singlecomment" (list with comment), "multiple", "ranking". Array kinds: "array" (rows and columns), "array5", "array10", "arrayyesno", "arraytrend" (rows only, the scale is implicit). Item batteries: "multitext", "multinumeric" (one field per option). Scalar kinds: "text", "shorttext", "hugetext", "numeric", "date", "yesno" (implicit Y/N), "gender" (implicit M/F), "fivepoint" (implicit 1-5). Plus "display" (text shown without input). Every kind maps to a LimeSurvey type attested by real exports; types that would require an unverified mechanism (dual-scale arrays of texts or numbers, equations, file upload) are deliberately not supported yet.

• text – the question wording. mandatory – logical, default FALSE. help – optional help text shown under the wording.

• options – for single, multiple and ranking: list of options, each a list with text and optionally code, other = TRUE (native LimeSurvey "other" with a free-text field; single and multiple only) and exclusive = TRUE (multiple only; unchecks every other box). Options without a code are numbered ⁠1..n⁠ in order, skipping the other option, which LimeSurvey codes natively.

• rows / columns – for array: the subquestions and the answer scale, same shape as options.

• relevance – display condition in a minimal syntax: code = 1, ⁠code in [1, 2, autre]⁠, count(code) >= 2 (at least n boxes ticked in a multiple-choice question). The keyword autre designates the native "other" option. Conditions may only reference questions defined earlier in the survey.

• max_answers – cap for multiple (strictly below the number of options) and ranking (at most the number of items).

• other_position – where the "other" option is displayed: "end" (LimeSurvey default), "beginning", or "specific" together with other_position_code, the code of the option AFTER which "other" appears. In practice "other" usually belongs before the "none of the above"-type exclusive options, which the default position puts it after.

• attributes – optional named list of extra global question attributes passed through verbatim (e.g. display_columns).

Value

An object of class lss_spec: the validated specification with normalized questions (auto-numbered option codes filled in).

Languages

languages declares the survey languages, the primary one first; languages[1] is the language write_lss() emits. Every localizable text – survey title, welcome and end texts, group titles, question texts and help, option, row and column labels, the "other" label, quota names and messages – accepts either a plain string (read as the primary language) or a named character vector or list keyed by language code:

lss_spec(
  title = c(fr = "Enquete", en = "Survey"),
  languages = c("fr", "en"),
  groups = list(list(
    title = c(fr = "Profil", en = "Profile"),
    questions = list(list(
      code = "q1", kind = "yesno",
      text = c(fr = "Etes-vous d'accord ?", en = "Do you agree?")))))
)

The spec keeps one canonical form (a named list over the declared languages) and is strict: as soon as several languages are declared, every text must supply every one of them. A missing translation is precisely what audit_lss() flags when reading a .lss, so the spec refuses to author one. In this version write_lss() emits the primary language only, and errors with class lssdoc_unsupported_multilang on a spec that declares more than one; multi-language emission is planned for 0.3.0.

See Also

write_lss() to emit the .lss file, read_lss() and audit_lss() to read it back and check it.

Examples

spec <- lss_spec(
  title = "Demo",
  languages = "fr",
  groups = list(list(
    title = "Profil",
    questions = list(
      list(code = "consent", kind = "single", text = "Participez-vous ?",
           mandatory = TRUE,
           options = list(list(text = "Oui"), list(text = "Non"))),
      list(code = "raisons", kind = "multiple", text = "Pourquoi ?",
           relevance = "consent = 1", max_answers = 2,
           options = list(
             list(text = "Une raison"), list(text = "Une autre"),
             list(text = "Encore une"),
             list(text = "Aucune raison", exclusive = TRUE),
             list(text = "Autre raison", other = TRUE)))
    )
  ))
)
spec$groups[[1]]$questions[[2]]$options[[4]]$code

Print an lss_audit object

Description

Pretty-printed audit summary on the console, capped at the first n findings. Severity-based bullet symbols (errors, warnings, notes) mirror what is shown in the audit table inside the rendered .docx.

Usage

## S3 method for class 'lss_audit'
print(x, ..., n = 20L)

Arguments

Value

The audit object, invisibly.

Read a LimeSurvey .lss file

Description

Read a LimeSurvey survey structure export (.lss, an XML file) and turn it into a structured lss object that the rest of the package can audit (audit_lss()) and render (render_questionnaire(), render_audit()). Parsing is fully local: the file is never uploaded anywhere.

Usage

read_lss(file)

Arguments

Details

The .lss format is a LimeSurvey XML export. Since DBVersion 4xx/7xx the translatable text lives in dedicated localization sections (⁠*_l10ns⁠), keyed by language, while the structural sections hold identifiers and settings. read_lss() reads every section into a tidy data frame without mutating any user-facing identifier or text. A field that is present but empty (e.g. ⁠<help/>⁠) is read as ""; a field that is absent from a row is read as NA.

Value

An object of class lss: a list with the survey languages, metadata, and one data frame per .lss section. Structural sections (surveys, groups, questions, subquestions, answers, question_attributes, conditions) stay separate from the localized text sections (survey_language_settings, group_l10ns, question_l10ns, answer_l10ns), which carry the per-language titles, labels, and help texts. All values are read verbatim as character.

Examples

# A synthetic four-language demo survey ships with the package.
demo <- system.file("extdata", "demo_survey.lss", package = "lssdoc")
lss <- read_lss(demo)
lss$languages

Render the audit as a focused Word or PDF document

Description

Build a short, action-oriented document containing only the audit findings: the same cover page as the full questionnaire document, summary counts, then one table per severity (errors, warnings, notes) listing every finding with its location and message. Use it for QA follow-up or to share issues with a colleague without distributing the full questionnaire.

Usage

render_audit(
  input,
  output,
  languages = NULL,
  logo = NULL,
  logo_width = 1.5,
  logo_height = 0.75,
  font = NULL,
  font_code = NULL,
  colors = NULL,
  authors = NULL,
  description = NULL,
  chrome_lang = NULL
)

Arguments

Value

The output path, invisibly.

See Also

audit_lss() to inspect the same findings in the console; render_questionnaire() for the full questionnaire document.

Examples

## Not run: 
# One-shot (path -> .docx)
render_audit(
  system.file("extdata", "demo_survey.lss",
              package = "lssdoc"),
  tempfile(fileext = ".docx")
)

# PDF output -- same call, just pass a .pdf path
render_audit("survey.lss", "qa.pdf")

## End(Not run)

Render a LimeSurvey questionnaire to a Word or PDF document

Description

Build a professional questionnaire document from a LimeSurvey survey, displaying up to four languages side by side. Each question becomes a compact flextable with a meta header (variable code, type, mandatory, filter) shown once, language column headers, the question text per language, and the subquestion or answer-option rows underneath – codes on the left, labels per language on the right. Headings, a metadata cover page, an optional table of contents, and an optional audit summary tie the document together. Rendering uses the suggested packages officer and flextable; both must be installed.

Usage

render_questionnaire(
  input,
  output,
  languages = NULL,
  template = c("cards", "table"),
  layout = c("auto", "side-by-side", "stacked"),
  show_audit = TRUE,
  show_help = TRUE,
  show_attrs = c("prefix", "suffix", "other_replace_text", "validation"),
  show_technical_attrs = FALSE,
  page_format = c("auto", "A4-portrait", "A4-landscape", "A3"),
  show_toc = TRUE,
  show_index = TRUE,
  show_quotas = TRUE,
  show_header_title = TRUE,
  show_source = TRUE,
  show_item_heading = FALSE,
  show_raw_filter = FALSE,
  show_groups = TRUE,
  show_welcome = TRUE,
  show_endtext = TRUE,
  show_description = TRUE,
  show_consent = TRUE,
  show_privacy_settings = FALSE,
  show_admin_settings = FALSE,
  title = NULL,
  logo = NULL,
  logo_width = 1.5,
  logo_height = 0.75,
  font = NULL,
  font_code = NULL,
  colors = NULL,
  authors = NULL,
  description = NULL,
  chrome_lang = NULL,
  variable_names = c("brackets", "underscore"),
  base_size = 10L
)

Arguments

Value

The output path, invisibly.

"LimeSurvey last save" date on the cover

The cover metadata table carries a row labelled "LimeSurvey last save" (or its localized equivalent). It is read verbatim from the surveys.lastmodified column of the .lss, which is the only timestamp LimeSurvey writes into the export – no other table (questions, question_l10ns, answer_l10ns, groups, etc.) carries a per-row modification date. The row is named "last save" rather than "last modified" because LimeSurvey only bumps that field reliably when the user clicks Save on a survey-level form (Settings tab); editing a question text, an answer label, or a translation through the Question Editor does not consistently update it across LimeSurvey versions. If the date looks stale relative to your most recent edits, the workaround is to open Survey settings in LimeSurvey, click Save (no other change needed), then re-export the .lss. The next render will show the bumped timestamp.

Field-update prompt in Word

Opening the rendered .docx in Microsoft Word may surface a security-style prompt: "This document contains fields that may refer to other files. Do you want to update the fields in this document?". This is expected: the package marks the page-number and bookmark-reference fields as needing a refresh so the footer shows the correct page count and the table of contents links resolve to the right pages on first open (this is also what makes headless PDF conversion via LibreOffice produce correctly paginated output without a manual F9). Clicking Yes is safe – the document has no INCLUDETEXT, INCLUDEPICTURE-linked, or DDE fields; the only external links are the ORCID and DOI URLs in the cover credits, which are static HYPERLINK targets and not fetched on update.

PDF output

When output ends in .pdf, the function first renders a .docx to a temporary location and then converts it locally via LibreOffice headless (or Word on Windows). LibreOffice (soffice executable) must be installed and on PATH; otherwise a classed error explains how to install it. Conversion stays on the user's machine: no upload, no network call. LibreOffice headless does not refresh Word field values (TOC, page counts) during conversion, so the table of contents may appear empty in the converted PDF. To obtain a PDF with a populated TOC, render to .docx instead, open it in Word (the TOC refreshes automatically) and use ⁠File > Save As > PDF⁠.

See Also

render_audit() for the audit-only document; audit_lss() to inspect findings in the console without rendering; read_lss() to pre-parse a .lss file once and render multiple variants.

Examples

## Not run: 
file <- system.file("extdata", "demo_survey.lss", package = "lssdoc")

# One-shot: parse + render Word document
render_questionnaire(file, tempfile(fileext = ".docx"))

# Same call, PDF output (format inferred from extension)
render_questionnaire(file, tempfile(fileext = ".pdf"))

# Parse once, render several variants without re-parsing
lss <- read_lss(file)
render_questionnaire(lss, tempfile(fileext = ".docx"),
                     languages = "en")
render_questionnaire(lss, tempfile(fileext = ".docx"),
                     template = "table",
                     languages = c("en", "fr"))

# Branded cover with authors block and palette override
render_questionnaire(
  lss,
  tempfile(fileext = ".docx"),
  template    = "table",
  chrome_lang = "en",
  colors      = list(primary = "#5C9F1A", accent = "#7FA82E"),
  authors     = list(
    list(name = "Jane Doe", affiliation = "HESAV",
         orcid = "0009-0001-2345-6789"),
    list(name = "John Doe", affiliation = "HESAV",
         orcid = "0009-0002-3456-7890")
  )
)

## End(Not run)

Write a survey specification to an importable .lss file

Description

Usage

write_lss(spec, file, sid = 100001L, settings = list())

Arguments

Details

Experimental. Turn an lss_spec() specification into a LimeSurvey structure file (.lss) that imports directly through Create survey -> Import. The output targets LimeSurvey 6 (DBVersion 700). The emitted file can be read back with read_lss(), checked with audit_lss() and rendered with render_questionnaire() – so the document reviewers read is produced from the very file LimeSurvey receives.

Mapping choices, each validated against real LimeSurvey 6 imports:

• Each kind maps to a LimeSurvey type and theme attested by a corpus of real exports (see lss_kind_map in the sources). Options of single-choice lists, rankings and array columns are emitted as answers; options of multiple-choice questions, item batteries and array rows as subquestions; scalar kinds and implicit scales (yes/no, gender, five-point, 5/10-point arrays) emit none.

• The native other option is emitted as other = "Y" plus the localized attribute other_replace_text. Localized attributes MUST carry the language code: emitted without one, LimeSurvey silently ignores them and shows its default wording. Global attributes (exclude_all_others, max_answers, ...) stay language-less.

• other_position / other_position_code control where the other option is displayed; exclude_all_others accepts several codes separated by ⁠;⁠.

• Relevance equations are translated from the minimal syntax of lss_spec() into ExpressionScript (code.NAOK == "1").

• Quotas are emitted with limit zero and the terminate action.

• A mandatory or capped ranking also receives min_answers = 1, overridable through the question's attributes.

Value

Invisibly, the path to the written file.

Languages

The spec model is multilingual (lss_spec() accepts languages and per-language texts); the emitter is not yet. This version writes the primary language – languages[1] – only, exactly as it did when a spec could hold a single language. A spec declaring more than one language raises a classed error (lssdoc_unsupported_multilang) rather than silently dropping the translations; multi-language emission is planned for 0.3.0.

See Also

lss_spec(), read_lss(), audit_lss(), render_questionnaire().

Examples

spec <- lss_spec(
  title = "Demo",
  groups = list(list(title = "G", questions = list(
    list(code = "q1", kind = "single", text = "Oui ou non ?",
         options = list(list(text = "Oui"), list(text = "Non")))
  )))
)
out <- tempfile(fileext = ".lss")
write_lss(spec, out)
audit_lss(out)