ci: Document with a patched roxygen2 that keeps the sentence gap

[krlmlr]

Split out of #606 so it can be decided on its own.

The problem

commonmark discards the whitespace a line break stands for. roxygen2 turns every softbreak into a bare newline, so the .Rd carries a line break with nothing after it and Rd2txt() renders it as a single space. Prose written one sentence per line therefore comes out single-spaced, while the same words wrapped to a fixed width with two spaces after the period keep the gap.

That makes the two styles mutually exclusive: splitting a sentence pair separated by two spaces silently drops one of them. That is what forced the very long single roxygen lines this package used to carry, because joining was the only way to keep the gap.

Only the text renderer is affected. Rd2HTML() and Rd2latex() differ by whitespace that HTML and TeX collapse — and LaTeX applies its own sentence spacing regardless. But text is what ?topic shows, so it is the version most people read.

The change

A new composite action, .github/workflows/roxygen2-fork, installs roxygen2 from upstream with the R/ part of krlmlr/roxygen2@f-sentence-spacing applied on top, and R-CMD-check.yaml runs it immediately before the Roxygenize step.

It shallow-clones upstream, fetches the branch, computes the diff against their merge base restricted to R/, and applies it with git apply --3way. Restricting to R/ means an unrelated upstream change to a test fixture cannot fail the documentation step. It aborts if the patch is empty or does not apply, rather than silently installing an unpatched build, and afterwards asserts that what it installed really carries the patch.

Config/roxygen2/version becomes 8.1.0.9100. The .9100 suffix distinguishes a patched build from upstream's own .9000 development builds; if upstream moves, the x.y.z part follows it and the suffix stays. DESCRIPTION is DCF and cannot carry a comment line — read.dcf() rejects one as malformed — so the explanation lives in a Config/cynkra/roxygen2 field.

Why it is a separate pull request

Taking it changes rendered help across the package; leaving it means the reformatting below renders exactly as the package renders today, with one space between sentences. Neither half needs the other to be correct, so they should be able to be decided separately.

man/ is not edited by hand here. The .Rd files are generated output, so CI roxygenises and commits them itself — they arrive on this branch as an automated commit rather than in the hand-written diff. That commit has already landed: 10 regenerated .Rd files are part of this pull request's diff, and the hand-written half stays reviewable on its own.

Upstream

The roxygen2 side is krlmlr/roxygen2#8, on the fork, not yet filed with r-lib. It is deliberately narrow: mid-sentence breaks are untouched, links are unaffected, and two guards keep it from firing wrongly — an abbreviation list so a line ending in e.g. or et al. does not gain a mid-sentence gap, and a fix for a determinism bug where a line starting with \doi{} or \code{} gained or lost its gap at random, because the test was reading roxygen2's own random placeholder for protected Rd tags.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m

---

Generated by Claude Code