Always resolve to "anchored" Rd xrefs

[jeroen]

In order to improve cross-package links in the new single-page-html documentation, CRAN will start showing NOTEs for Rd pages which link to a topic that exists in multiple CRAN packages, such as toJSON (in jsonlite, RJSONIO, rjson).

Seemingly it is not trivial at CMD check time to resolve a topic to a given based on the package imports/suggests. They suggest you use "anchored" Rd links, which simply means using the full \link[pkg:topic]{topic} syntax.

If possible, way to reduce some of the fallout would be to resolve a [topic] name to the full \link[pkg:topic]{topic} at roxygenize time, by inspecting at the package namespace, i.e. to automatically determine the pkg: value when unset:

roxygen2/R/markdown-link.R

Lines 12 to 23 in 2357de6

	#' MARKDOWN LINK TEXT CODE RD
	#' -------- --------- ---- --
	#' [fun()] fun() T \\link[=fun]{fun()}
	#' [obj] obj F \\link{obj}
	#' [pkg::fun()] pkg::fun() T \\link[pkg:file]{pkg::fun()}
	#' [pkg::obj] pkg::obj F \\link[pkg:file]{pkg::obj}
	#' [text][fun()] text F \\link[=fun]{text}
	#' [text][obj] text F \\link[=obj]{text}
	#' [text][pkg::fun()] text F \\link[pkg:file]{text}
	#' [text][pkg::obj] text F \\link[pkg:file]{text}
	#' [s4-class] s4 F \\linkS4class{s4}
	#' [pkg::s4-class] pkg::s4 F \\link[pkg:file]{pkg::s4}

[gaborcsardi]

Seemingly it is not trivial at CMD check time to resolve a topic to a given based on the package imports/suggests.

...

If possible, way to reduce some of the fallout would be to resolve a [topic] name to the full \link[pkg:topic]{topic} at roxygenize time,

So, to be clear, they don't want to do this, but they want us to do it? :D

[gaborcsardi]

Btw. anyone knows a package that has this issue?

[gaborcsardi]

Btw.2. Is this change documented anywhere? I can't see anything in `Writing R Externsions'. It would be good to know the rules before we update roxygen2. E.g. are unqualified links to base packages allowed?

[jeroen]

You can probably email kurt directly, he presented about this today. I would guess all cross package links need to be anchored, incl base. Op di 9 jul. 2024 20:41 schreef Gábor Csárdi ***@***.***>:

…

Btw.2. Is this change documented anywhere? I can't see anything in `Writing R Externsions'. It would be good to know the rules before we update roxygen2. E.g. are unqualified links to base packages allowed? — Reply to this email directly, view it on GitHub <#1612 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABUZ74LQNXNBMCFK35FVU3ZLQVFPAVCNFSM6AAAAABGRITATSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMJYGQYDEMRSG4> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[gaborcsardi]

From the check message it seems that references to base packages do not need to be qualified:

  Please provide package anchors for all Rd \link{} targets not in the
  package itself and the base packages.