ci: Document with a patched roxygen2 that keeps the sentence gap - #62
Open
krlmlr wants to merge 2 commits into
Open
ci: Document with a patched roxygen2 that keeps the sentence gap#62krlmlr wants to merge 2 commits into
krlmlr wants to merge 2 commits into
Conversation
krlmlr
force-pushed
the
claude/roxygen2-fork
branch
2 times, most recently
from
September 13, 2026 20:33
cb23607 to
c80fb79
Compare
krlmlr
added this pull request to stack #63
September 13, 2026 21:41
commonmark discards the whitespace a line break stands for, so roxygen prose written one sentence per line loses the gap between sentences in the rendered help. Only the text renderer is affected, which is what `?topic` shows. A new composite action installs roxygen2 from upstream with the R/ part of krlmlr/roxygen2@f-sentence-spacing applied on top, and runs just before the Roxygenize step. It shallow-clones upstream, fetches the branch, applies the diff restricted to R/ so conflicts in the test files cannot fail it, and aborts rather than silently installing an unpatched build. It then 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, so the explanation lives in a Config/cynkra/roxygen2 field. This is a separate decision from the line-break reformatting below it, and is kept in its own pull request so it can be taken or left on its own. Without it, the reformatting simply renders as it does today, with one space between sentences. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
krlmlr
force-pushed
the
claude/roxygen2-fork
branch
from
September 13, 2026 21:41
c80fb79 to
4676d38
Compare
…l escape The version stamp wrote the replacement as "\1". R parses that as the octal escape for \001, not as a regex backreference, so DESCRIPTION ended up with a malformed version and R CMD INSTALL aborted with "Malformed package version". Every job that installs roxygen2 through this action failed there. The replacement is now "\\1", verified to stamp 8.1.0.9000 to 8.1.0.9100. The post-install guard asserted only the .9100 suffix, and the corrupt "\001.9100" satisfies that too, which is why the bug survived the check meant to catch it. The guard now asserts the whole x.y.z.9100 shape, and passes inherits = FALSE to exists(). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out of #57 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
.Rdcarries a line break with nothing after it andRd2txt()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 why the reformatting below it had to leave long joined lines alone, or accept losing the gap.
Only the text renderer is affected.
Rd2HTML()andRd2latex()differ by whitespace that HTML and TeX collapse — and LaTeX applies its own sentence spacing regardless. But text is what?topicshows, so it is the version most people read, and in this package the data set topics are almost entirely prose.The change
A new composite action,
.github/workflows/roxygen2-fork, installs roxygen2 from upstream with theR/part ofkrlmlr/roxygen2@f-sentence-spacingapplied on top, andR-CMD-check.yamlruns 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 withgit apply --3way. Restricting toR/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/versionbecomes8.1.0.9100. The.9100suffix distinguishes a patched build from upstream's own.9000development builds; if upstream moves, thex.y.zpart follows it and the suffix stays.DESCRIPTIONis DCF and cannot carry a comment line —read.dcf()rejects one as malformed — so the explanation lives in aConfig/cynkra/roxygen2field.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 left to CINothing under
man/is committed here, and nothing is committed in the reformatting pull requests below either. The workflow roxygenises and commits the regenerated.Rdfiles itself, so merging this is what produces them, and both diffs stay reviewable.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 ine.g.oret 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.🤖 Generated with Claude Code
https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
Generated by Claude Code