Consistently qualify [base] in Rd links #7095

Activity

1. MichaelChirico

   added

   documentation

   code-qualityIssues related to improving code quality/readabilityIssues related to improving code quality/readability

   on Jun 24, 2025
2. jangorecki commented on Jun 24, 2025

   

   jangorecki

   on Jun 24, 2025

   Member

   More actions

   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...
3. MichaelChirico commented on Jun 24, 2025

   

   MichaelChirico

   on Jun 24, 2025

   Last edited by MichaelChirico

   MemberAuthor

   More actions

   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-froll non-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

   froll drafts 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.
4. jangorecki commented on Jun 24, 2025

   

   jangorecki

   on Jun 24, 2025

   Last edited by jangorecki

   Member

   More actions

   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.
5. aitap commented on Jul 1, 2025

   

   aitap

   on Jul 1, 2025

   Last edited by aitap

   Member

   More actions

   It's not necessary to spell out \link[foo:bar]{bar} instead of \link[foo]{bar}, tools:::get_link resolves 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 check only gives a NOTE about unqualified non-(base or local) links, but it is useful in case a topic conflict does occur.
6. aitap commented on Mar 3, 2026

   

   aitap

   on Mar 3, 2026

   Member

   More actions

   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.Rd
   

   This is only a minor problem when using the dynamic help server (help.start()). With R CMD INSTALL --html, the links will be forced to resolve to the base and recommended packages before they can be resolved to CRAN packages.

   🚀React with 🚀1Reacted by Jan Gorecki