[Rd] Documentation cross references

[Lluís Revilla]

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