# Get started with lssdoc

lssdoc turns a LimeSurvey `.lss` export into a polished Word (`.docx`) or PDF questionnaire document, displaying up to four languages side by side, and runs a rule-based audit of the survey. Everything stays on your machine.

The public API is four functions:

Function | Role
--- | ---
`read_lss(file)` | Parse a `.lss` into a structured `lss` object.
`audit_lss(input)` | Inspect a survey for anomalies.
`render_questionnaire(input, output, ...)` | Render the full questionnaire to Word or PDF.
`render_audit(input, output, ...)` | Render the audit findings alone.

This vignette uses the demo survey that ships with the package – a synthetic four-language questionnaire (English, French, German, Spanish) with quotas and a consent block.

    demo <- system.file("extdata", "demo_survey.lss", package = "lssdoc")

## Parse

`read_lss()` reads the `.lss` (XML) export into a structured object, preserving every user-entered string verbatim.

    lss <- read_lss(demo)
    lss$languages
    #> [1] "en" "de" "es" "fr"

## Audit

`audit_lss()` flags reviewable anomalies – missing translations, duplicate codes, forward filter references, array-scale inconsistencies, orphan references – as a classed object with a `print()` method. The demo survey is clean; a deliberately broken fixture is included to show the output:

    broken <- system.file("extdata", "audit_demo.lss", package = "lssdoc")
    audit_lss(read_lss(broken))
    #>
    #> ── lssdoc audit ────────────────────────────────────────────────────────────────
    #> File:
    #> 'C:/Users/at/AppData/Local/Temp/RtmpEpE6gp/Rinst5d686e5540f5/lssdoc/extdata/audit_demo.lss'
    #> Languages: "en" and "fr"
    #> 12 findings: 5 errors, 7 warnings, 0 notes.
    #> ✖ Survey: Duplicate question code: 'age'.
    #> ✖ Question 'blank_q': The question text is empty in every language.
    #> ✖ Question 'age': Filter references variable 'income' (item 4), which is not
    #>   asked before this question (item 1).
    #> ✖ Answer 'X': Answer points to question id '99999', which does not exist.
    #> ✖ Subquestion 'orphan_sq': Subquestion points to question id '99999', which
    #>   does not exist.
    #> Question 'arr': Subquestions reference scale_id '0' but no answer options are
    #> defined for it.
    #> Question 'arr': Answer options reference scale_id '1' but no subquestions are
    #> defined for it.
    #> Question 'comment ': The question code 'comment ' contains whitespace;
    #> LimeSurvey will export it verbatim, which usually breaks downstream lookups.
    #> Group: The group name is empty in every language.
    #> Question 'satisf': Type 'Single choice' expects answer options, but none are
    #> defined.
    #> Question 'rating': Type 'Multiple choice' expects subquestions, but none are
    #> defined.
    #> Question 'income' [fr]: The question text is missing in 'fr' but present in
    #> other languages.

## Render

`render_questionnaire()` writes the document; the output format is inferred from the file extension (`.docx` or `.pdf`). Rendering uses the suggested packages and .

    # Parse once (above), then render different variants without re-reading.
    render_questionnaire(lss, "review.docx")

Two templates are available. The `"cards"` template (default) stacks one block per item – closest to the printed questionnaire:

The `"table"` template is one dense codebook covering the whole document – one row per variable, with its value codes beneath:

    render_questionnaire(lss, "codebook.docx", template = "table")

### Useful arguments

- `languages` – which content columns appear, and in which order (`c("en", "fr")`); the first is the primary language.
- `chrome_lang` – language of the document chrome (column headers, row labels, type labels), independent of the content languages.
- `template` – `"cards"` (default) or `"table"`.
- `variable_names` – `"brackets"` (default) reproduces the LimeSurvey CSV/Excel export column names, so the variable index matches the raw data file; `"underscore"` uses the SPSS/Stata code form.
- `base_size` – body type size in points (default `10`); raise it (e.g. `12`) for a roomier single-language render.
- `page_format` – `"auto"`, `"A4-portrait"`, `"A4-landscape"` or `"A3"`.

    render_questionnaire(
      lss, "review_en_fr.docx",
      languages   = c("en", "fr"),
      template    = "table",
      chrome_lang = "en"
    )

## PDF output

Pass a `.pdf` path: the package writes a `.docx` to a temporary location and converts it locally via LibreOffice (which must be installed and on the `PATH`). No upload, no network call.

    render_questionnaire(lss, "review.pdf")

## Audit-only document

`render_audit()` produces a focused QA document – the cover page, then one section per severity – separate from the full review.

    render_audit(lss, "qa.docx")