Repository navigation
Consistently qualify [base] in Rd links #7095
Description
Activity
Let's do so consistently, including a linter to prevent regression.
+1
But let's not make it top priority stuff that will cause new git conflicts. Adding it later on will not make any harm...To facilitate this type of discussion, I made LLM write a script (happily it worked copy+paste, but I tweaked it a bit anyway):
https://gist.github.com/MichaelChirico/64e981b4359a36d2279bf55c39c7d3dd
Here are the non-
frollnon-draft PRs that touch any existing Rd file#6899, #6879, #6624, #6360, #6136, #5168, #4978, #4868, #3093
They touch files:
all.equal.data.table.Rd, data.table.Rd, groupingsets.Rd, IDateTime.Rd, last.Rd, na.omit.data.table.Rd, setDT.Rd
frolldrafts all only touch man/froll.Rd, except #5441, which appears to have an ongoing merge conflict/rebase issue where unrelated edits are showing up in other man/ files.extant_rd = list.files('man') pr_files[ !is_draft & !grepl("froll", labels) & basename(filename) %in% extant_rd, paste0("#", unique(pr_number), collapse = ", ") ]
I think it's fine to file a PR for this issue now, if the PR author agrees to also resolve any conflicts with the listed PRs afterwards, should any arise.
If it is just a few PRs then we could alternatively try to merge or close them before. That will end up to be less work in total, than the other way around.
It's not necessary to spell out
\link[foo:bar]{bar}instead of\link[foo]{bar},tools:::get_linkresolves them the same way, but it shouldn't hurt too much either.This issue isn't of high priority because even unqualified links to base topics should never fail to resolve, people usually don't create conflicts with base topics, and
R CMD checkonly gives a NOTE about unqualified non-(base or local) links, but it is useful in case a topic conflict does occur.To quantify the problem:
# list of topics documented on CRAN tools::CRAN_aliases_db() -> cran_aliases # (takes a long time) cran_aliases |> names() |> lapply(\(pkg) cran_aliases[[pkg]] |> names() |> lapply(\(file) data.table(alias = cran_aliases[[pkg]][[file]], file = file, pkg = pkg) ) ) |> unlist(FALSE) |> rbindlist() -> cran_alias_db # list of documented topics in base packages (destinations for \link{foo}) tools::base_aliases_db() |> unlist(use.names=FALSE) |> unique() -> base_aliases length(base_aliases) # ⇒ [1] 4696 # links from the data.table help pages tools::CRAN_rdxrefs_db()$data.table |> as.data.table() -> dt_xrefs # Any unqualified links from data.table to base topics intersecting with CRAN? dt_xrefs[ # Any unqualified links from data.table... !nzchar(Anchor), -'Anchor' ][ # ...to base topics.... J(Target = base_aliases), on = .(Target), nomatch = NULL ][ # ...intersecting with aliases from CRAN, not in data.table itself? cran_alias_db[pkg != 'data.table'], on = .(Target = alias), nomatch = NULL ][ , .(Source = paste(unique(Source), collapse = ', '), dest = paste(pkg, file, sep = ':', collapse = ', ')), by = .(Target) ] -> potential_conflicts potential_conflicts[,-'dest'] # the last column can be really long
Target Source <char> <char> 1: format as.matrix.Rd 2: object.size tables.Rd 3: unique duplicated.Rd, fdroplevels.Rd, setops.Rd 4: merge merge.Rd 5: data.frame data.table.Rd, setDT.Rd 6: head last.Rd 7: tail last.Rd 8: duplicated duplicated.Rd, fdroplevels.Rd, setops.Rd 9: %in% chmatch.Rd 10: as.matrix as.matrix.Rd 11: as.vector as.matrix.Rd 12: round IDateTime.Rd 13: na.omit data.table.Rd 14: print.default print.data.table.Rd 15: download.file fread.Rd 16: is.numeric data.table.Rd 17: all.equal duplicated.Rd 18: POSIXct fread.Rd 19: patterns melt.data.table.Rd 20: array as.matrix.Rd 21: ls tables.Rd 22: as.Date IDateTime.Rd 23: grep patterns.Rd 24: strptime IDateTime.Rd 25: strtrim print.data.table.RdThis is only a minor problem when using the dynamic help server (
help.start()). WithR CMD INSTALL --html, the links will be forced to resolve to the base and recommended packages before they can be resolved to CRAN packages.Reacted by Jan Gorecki
Let's specify destinations of non-local links. That won't give us
R CMD checkproblems, but it should help the resolver.Originally posted by @aitap in #7075 (comment)
This was applied in #7075, but it's not consistent in our code base:
data.table/man/data.table.Rd
Line 88 in a5eac7d
Let's do so consistently, including a linter to prevent regression.