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

[krlmlr]

Split out of #2903 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. In this package that is what forced the long single-line roxygen paragraphs, and why the earlier reformatting pass had to leave 26 places joined — undoing them would have kept the gap only at the price of lines of 1440 and 973 characters.

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 as the package renders today everywhere except where a sentence pair separated by two spaces was split across lines: tools::Rd2txt() over the 633 topics that branch regenerates finds 80 of them differing, each by that gap narrowing to a single space and by nothing else. 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 regenerated .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.

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

[github-actions]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if 35426dc is merged into claude/readme-rmd:

• ✔️as_adjacency_matrix: 182ms -> 182ms [-0.45%, +0.78%]
• ✔️as_biadjacency_matrix: 205ms -> 204ms [-1.21%, +0.24%]
• ✔️as_data_frame_both: 207ms -> 207ms [-1.87%, +2.26%]
• ✔️as_long_data_frame: 166ms -> 166ms [-1.96%, +1.36%]
• ✔️es_attr_filter: 192ms -> 191ms [-1.39%, +0.56%]
• ❗🐌graph_from_adjacency_matrix: 220ms -> 224ms [+0.27%, +3.66%]
• ✔️graph_from_data_frame: 223ms -> 222ms [-1.67%, +1.2%]
• ✔️vs_attr_filter: 236ms -> 237ms [-0.57%, +2.19%]
• ✔️vs_by_name: 215ms -> 214ms [-1.1%, +0.11%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[github-actions]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if 33adc59 is merged into claude/readme-rmd:

• ✔️as_adjacency_matrix: 181ms -> 179ms [-1.73%, +0.05%]
• ✔️as_biadjacency_matrix: 202ms -> 204ms [-1.36%, +3.1%]
• ✔️as_data_frame_both: 201ms -> 201ms [-0.81%, +0.6%]
• ✔️as_long_data_frame: 161ms -> 160ms [-1.94%, +1.27%]
• ✔️es_attr_filter: 192ms -> 191ms [-2.27%, +1.69%]
• ✔️graph_from_adjacency_matrix: 218ms -> 219ms [-0.69%, +2.04%]
• ✔️graph_from_data_frame: 217ms -> 215ms [-3.21%, +1.05%]
• ✔️vs_attr_filter: 234ms -> 234ms [-0.71%, +0.44%]
• ✔️vs_by_name: 211ms -> 213ms [-1.07%, +2.82%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[github-actions]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if 840234c is merged into claude/readme-rmd:

• ✔️as_adjacency_matrix: 178ms -> 178ms [-0.57%, +1.14%]
• ✔️as_biadjacency_matrix: 199ms -> 199ms [-0.66%, +0.88%]
• ✔️as_data_frame_both: 200ms -> 201ms [-0.28%, +0.87%]
• ✔️as_long_data_frame: 162ms -> 160ms [-2.9%, +1%]
• ✔️es_attr_filter: 189ms -> 191ms [-0.64%, +2.65%]
• ✔️graph_from_adjacency_matrix: 215ms -> 218ms [-0.36%, +2.76%]
• ✔️graph_from_data_frame: 216ms -> 216ms [-0.62%, +0.89%]
• ✔️vs_attr_filter: 230ms -> 230ms [-0.15%, +0.82%]
• ✔️vs_by_name: 211ms -> 211ms [-0.67%, +0.46%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[github-actions]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if cb1d208 is merged into claude/readme-rmd:

• ✔️as_adjacency_matrix: 189ms -> 190ms [-1.75%, +2.82%]
• ✔️as_biadjacency_matrix: 197ms -> 198ms [-3.63%, +4.04%]
• ✔️as_data_frame_both: 175ms -> 174ms [-2.33%, +0.9%]
• ✔️as_long_data_frame: 141ms -> 144ms [-0.91%, +4.47%]
• ✔️es_attr_filter: 187ms -> 185ms [-3.48%, +2%]
• ✔️graph_from_adjacency_matrix: 226ms -> 223ms [-3.71%, +1.14%]
• ✔️graph_from_data_frame: 193ms -> 193ms [-2.04%, +1.94%]
• ✔️vs_attr_filter: 189ms -> 192ms [-0.52%, +3.15%]
• ✔️vs_by_name: 168ms -> 167ms [-2.63%, +1.95%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[github-actions]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if c3533b7 is merged into claude/readme-rmd:

• ✔️as_adjacency_matrix: 246ms -> 245ms [-0.77%, +0.39%]
• ✔️as_biadjacency_matrix: 262ms -> 262ms [-0.35%, +0.87%]
• ✔️as_data_frame_both: 264ms -> 265ms [-0.25%, +1.15%]
• ✔️as_long_data_frame: 211ms -> 210ms [-1.38%, +0.41%]
• ✔️es_attr_filter: 248ms -> 248ms [-0.73%, +0.36%]
• ✔️graph_from_adjacency_matrix: 275ms -> 275ms [-0.33%, +0.57%]
• ✔️graph_from_data_frame: 278ms -> 277ms [-0.58%, +0.49%]
• ✔️vs_attr_filter: 336ms -> 337ms [-0.36%, +0.74%]
• ✔️vs_by_name: 319ms -> 318ms [-0.55%, +0.28%]
  Further explanation regarding interpretation and methodology can be found in the documentation.

[maelle]

I'd like to hear more on the use case of this.

[krlmlr]

Happy to. The concrete use case is making semantic line breaks usable in roxygen comments without silently degrading ?topic output.

Today the two things are mutually exclusive. commonmark discards the whitespace a line break stands for, so roxygen2 emits a bare newline and Rd2txt() renders it as a single space. That means a sentence pair written as ... end. Next ... on one line keeps its two-space gap, but the same pair split across two lines loses it. So if you want one sentence per line — easier review, sentence-level diffs — you pay for it by narrowing every sentence gap in the rendered text help.

That trade-off is what shaped the reformatting in #2903. It is why this package still carries long single-line roxygen paragraphs, and why that pass had to leave 26 places joined: splitting them would have kept the prose readable in the source only at the cost of losing the gap, and keeping the gap meant leaving lines of 1440 and 973 characters in place.

The effect is measured rather than assumed. Running tools::Rd2txt() over the 633 topics #2903 regenerates, 80 differ — each one by exactly that gap narrowing to a single space, and by nothing else. Only the text renderer is affected: Rd2HTML() and Rd2latex() differ by whitespace that HTML and TeX collapse, and LaTeX applies its own sentence spacing anyway. But text is what ?topic shows.

The cost is real and worth stating plainly: it documents with a roxygen2 that carries a patch not yet filed with r-lib. Nothing is vendored into the repo — CI installs upstream and applies the R/ part of the branch on top, aborts rather than silently installing an unpatched build, and asserts afterwards that what it installed carries the patch. Config/roxygen2/version gets a .9100 suffix so a patched build is never mistaken for an upstream development one. Still, until it is upstream, regenerating man/ locally with a stock roxygen2 drops the gaps again.

Which is why it is split out rather than folded into #2903. If you would rather not carry a patched documentation toolchain, #2903 stands on its own: the rendered help then matches what the package renders today everywhere except those 80 gaps. If the gap matters more than the patch costs, this one makes the reformatting lossless. Either way is coherent — I would rather you pick than have it decided by which pull request merges first.

---

Generated by Claude Code