| name | md4c-sync |
| description | Check the current md4c upstream release on GitHub and integrate it into this package if newer than the vendored copy. Updates `src/md4c.c`, `inst/include/md4c.h`, and the spec files under `inst/specs/md4c/`, then surfaces any new MD4C enums/flags that may need wrapper updates and runs the test suite. |
Sync the vendored md4c sources to the latest upstream release at https://github.com/mity/md4c.
Step 1: Detect currently vendored version
Read the most recent "Based on md4c version X.Y.Z" line from NEWS.md. That is the authoritative record. Note the version as CURRENT.
Step 2: Find the latest upstream release tag
md4c does not publish GitHub Releases — it uses tags of the form release-X.Y.Z. Query:
gh api repos/mity/md4c/tags --jq '.[].name' | grep '^release-' | sed 's/^release-//' | sort -V | tail -5
Pick the highest version as LATEST. If LATEST <= CURRENT, report that the package is up to date and stop.
Step 3: Confirm with the user
Use AskUserQuestion to confirm before fetching:
- Show CURRENT and LATEST.
- Ask whether to proceed with the sync.
If the user wants to pin to a specific tag (not necessarily the highest), let them override via the question's "Other" option.
Step 4: Fetch files from the chosen tag
Use curl against https://raw.githubusercontent.com/mity/md4c/release-<TAG>/<PATH>. Fetch to a scratch directory first, then move into place after Step 5's review. The mapping from upstream paths to package paths is:
| Upstream | Package |
|---|
src/md4c.c | src/md4c.c |
src/md4c.h | inst/include/md4c.h |
test/LICENSE.md | inst/specs/md4c/LICENSE.md |
test/coverage.txt | inst/specs/md4c/coverage.txt |
test/regressions.txt | inst/specs/md4c/regressions.txt |
test/spec.txt | inst/specs/md4c/spec.txt |
test/spec-*.txt | inst/specs/md4c/spec-*.txt |
Only overwrite spec files that already exist in inst/specs/md4c/. If upstream introduces new spec-*.txt files (e.g. spec-spoilers.txt, spec-subscripts.txt, spec-superscripts.txt), list them but do NOT add them automatically — they correspond to flags the R wrapper does not yet support, which needs separate wiring. Surface these as a follow-up item for the user.
Use gh api repos/mity/md4c/contents/test?ref=release-<TAG> --jq '.[].name' to enumerate upstream test/ so you can compare against the local set.
Step 5: Review what changed
Before overwriting, run a quick scan of upstream src/md4c.h against the current inst/include/md4c.h to flag wrapper-relevant API changes. Specifically grep for new entries in any of these enums:
MD_BLOCKTYPE (block kinds; handled in src/markdownparser.cpp::onEnterBlock)MD_SPANTYPE (span kinds; handled in src/markdownparser.cpp::onEnterSpan)MD_TEXTTYPE (text kinds; handled in src/markdownparser.cpp::onText)MD_FLAG_* macros (flags; mirrored in R/flags.R::flags_describe)- Any new
MD_*_DETAIL struct fields (attributes are propagated in src/markdownparser.cpp callbacks)
Also note any signature change to MD_PARSER or the callback prototypes — those would break MarkdownParser::MarkdownParser() in src/markdownparser.cpp.
Report the list of new enum values / flags / struct fields to the user before applying. These are potential wrapper updates the user may want to handle in a follow-up.
Step 6: Apply the file updates
Move the fetched files into place. Run a clean rebuild and the full test suite:
Rscript -e 'devtools::clean_dll(); devtools::test()'
Report pass/fail counts. If tests fail, do NOT proceed to Step 7 — report the failures and ask the user how to handle them. Common reasons:
- A regenerated md4c spec file produces test diffs because spec wording or example numbering changed (spec-driven tests under
tests/testthat/test-to_*-md4c.R are auto-regenerated by tests/testthat/helper-tests.R from the new spec files; the diff is expected, but inspect a sample to confirm it is benign).
- A new MD4C behavior changes existing parser output — review the diff.
Step 7: Update bookkeeping
After tests pass:
- NEWS.md: add a bullet to the development version entry:
* Updated vendored md4c to version X.Y.Z. (or create a new entry if the user wants to bump the package version too).
- DESCRIPTION: if upstream copyright year changed, update the copyright headers/comments. Do NOT modify the package
Version field unless the user explicitly asks (they track md4c versions intentionally, with an extra component for in-version package iterations — confirm the version policy with them before changing).
- Spec files note: if Step 4 surfaced new upstream spec files that were not synced, leave a TODO bullet in NEWS or report it separately so the user can decide whether to wire up the corresponding flag(s) in
R/flags.R and the inst/specs/md4c/ directory.
Step 8: Final report
Summarize:
- Version delta (CURRENT → LATEST)
- File counts changed
- Any new enums/flags/struct fields surfaced in Step 5
- Test results
- Any new upstream spec files that were skipped
- Suggested follow-up work, if any
Do not commit. Leave the user to review the diff and commit themselves.
Notes
- The package's MIT license depends on md4c remaining MIT — the upstream
LICENSE.md we vendor is the source of truth. If the upstream license file changed, flag that prominently.
src/httpuv_url_tools.cpp is unrelated (vendored from httpuv) — do not touch.- Pre-built artifacts (
*.o, *.so) under src/ are build outputs; do not touch.
- The package user has stated they intentionally track md4c versions in the package version (
0.5.2.X follows md4c 0.5.2). Respect that policy: never bump the major/minor/patch components without explicit confirmation, even after a successful md4c sync.
