Hi all,
I am checking the cross references at CRAN and base R, and I am having
trouble understanding how to reconcile the documentation and how R
help links work.
Checking the documentation [1] it seems that in a cross reference such
as \link[pkg:x]{text} x should be a topic (created with \alias{topic}
in R documentation).
But I found some cases exploring the output of
tools::base_rdxrefs_db() where it is a file name (without the .Rd
extension).
For instance, ?print has a link with text (Target as named by the
output) ".print.via.format" and the anchor
"tools:print.via.format".
The topic would be print.via.format, but if one uses:
help(topic = "print.via.format", package = "tools"):
No documentation for 'print.via.format' in specified packages and
libraries:
you could try '??print.via.format'
However, if one accesses the html help page and clicks
.print.via.format, is redirected to the right help page (found in the
REPL too with help(topic = ".print.via.format", package =
"tools") ).
I see a paragraph in R 4.1 NEWS about a change in behaviour [2] (also
hinted in WRE), where it is described as:
... "and fall back to a file link only if the topic is not found in
the target package. The earlier rule which prioritized file names over
topics can be restored by setting the environment variable
_R_HELP_LINKS_TO_TOPICS_ to a false value."
The internal variable _R_HELP_LINKS_TO_TOPICS_ isn't mentioned on
R-internals and this behaviour of html pages is not mentioned on WRE.
- Perhaps documentation at R-internals and WRE could be updated to
show how html page links are created?
- And/or the behaviour could continue the path started on R 4.1 and
start complaining about anchors pointing to files?
In the second case, ~10 links in base R would be affected but on CRAN
this could affect ~1700 more packages than those currently with "Rd
cross-references" notes.
Regards,
Llu?s
[1]:
https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Cross_002dreferences
[2]:
https://developer.r-project.org/blosxom.cgi/R-4-1-branch/NEWS/2021/04/20#n2021-04-21