From ||u|@@rev|||@ @end|ng |rom gm@||@com  Mon Sep  9 08:00:00 2024
From: ||u|@@rev|||@ @end|ng |rom gm@||@com (=?UTF-8?Q?Llu=C3=ADs_Revilla?=)
Date: Mon, 9 Sep 2024 08:00:00 +0200
Subject: [Rd] Documentation cross references
Message-ID: <CAN+W6_sBbuyThDTJX27rYAxwyrZLBsm1FKYtDtRnttAYP+6Ltg@mail.gmail.com>

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



[Rd] Documentation cross references
=?UTF-8?Q?Llu=C3=ADs_Revilla?=