Skip to content

docs: State the goals and non-goals - #66

Open
krlmlr wants to merge 1 commit into
mainfrom
claude/readme-goals
Open

krlmlr wants to merge 1 commit into
mainfrom
claude/readme-goals

Conversation

@krlmlr

@krlmlr krlmlr commented Sep 13, 2026

Copy link
Copy Markdown
Member

Replaces #61, which had its head on a fork and so could not join the pull request stack. Same branch, same commits.

Evidence behind each non-goal:

  • "does not run unattended" — the roxygen of both roxygen2md() and find_rd() says "designed for interactive use", and the README already warns "The substitutions are not completely safe, please carefully examine the results!"
  • "does not find a Markdown translation for every nested construct" — the README's "Removing links" section: "unlink" "isn't a valid conversion, but a helper to split up complex instances of \code{...\link{...}...} for which no easy-to-read translation to Markdown exists".
  • "does not convert sources in other encodings" — the README's Limitations section, and check_utf8() in R/md.R, which aborts unless Encoding is UTF-8 or ASCII.

"Does not touch .Rd files in man/" was considered and dropped — true (only .R files are transformed, and devtools::document() runs afterwards), but it describes the mechanism rather than a deliberate boundary.

Only README.Rmd, README.md and index.md change — no R/, no man/. Rendered twice, byte-identical.

Stacked on #60, which this PR targets.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m


Generated by Claude Code

@krlmlr
krlmlr added this pull request to stack #68 September 13, 2026 21:48
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from 90e3911 to 96f2667 Compare September 13, 2026 21:49
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from 96f2667 to c014ed8 Compare September 14, 2026 05:58
Base automatically changed from claude/sembr to main September 26, 2026 19:47
Scope drawn from the repository: the list of converted Rd elements, the
`DESCRIPTION` edit and the warning that the substitutions are not completely
safe are the README's own introduction, the staged workflow and the encoding
requirement are its "Converting large packages" and "Limitations" sections,
the interactive-use restriction is the roxygen of `roxygen2md()` and
`find_rd()`, and the note that `"unlink"` is not a valid conversion but a
helper is the README's "Removing links" section.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from c014ed8 to 08981bc Compare September 26, 2026 19:48

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant