[R-pkg-devel] check cross-references error: Non-file package-anchored link(s)

[Gábor Csárdi]

On Sat, Jun 13, 2020 at 8:10 PM Duncan Murdoch <murdoch.duncan using gmail.com> wrote:
>
> On 13/06/2020 1:17 p.m., Zhian Kamvar wrote:
[...]
> > Is this a new policy?

Zhian, it seems that some of the problematic links are created by
roxygen2. You can fix these using this PR:
https://github.com/r-lib/roxygen2/pull/1109
You can install this branch with
remotes::install_github("r-lib/roxygen2 using fix/link-to-file")

To fix the remaining ones, you need to modify your \link[]{} macros or
switch them to roxygen [pkg::fun()] links.

[...]
> This is probably a new test of the long-time requirement that links
> should be to filenames, not aliases, when they go to other packages.

I really like how the help system resolves links based on _topics_,
even for cross-package links. So I admit that I did not follow this
requirement too closely. It is better to link to topics instead of
files, because then links are independent of how the manual is
organized into files. E.g. it is not uncommon to split up a help file
that used to document multiple functions, into several files, because
the functions gain more functionality, or need more examples, etc. and
the manual page is getting less focused and harder to follow. It is
perfectly natural that the manual of a package is evolving together
with the code.

With enforcing this requirement, such documentation changes are
considered as breaking changes. If we need to link to files, then what
we get is more broken links, and more forced package updates, just to
fix the broken links. In particular, if a package moves a help topic
to another help file in a new release, then other packages linking to
this topic have to update their links, and if these happened to be
installed together with the old version of the linked package, they'll
have a broken link. This is a pity, because finding the right help
files is easy to automate, and in fact the help system already
supports it perfectly well.

As far as I can tell the only alternative of linking to the file is
using an unqualified link, i.e. not specifying the target package at
all. The help system can do the lookup at render time, and this is
usually OK, but for a non-trivial number of cases it is not, because
the resolution of the link depends on what packages are currently
loaded. If the right package is not loaded, then the link will
potentially go to the wrong help file, which is absurd. Or, if
multiple packages have the required topic, the user is presented with
a menu, which is also confusing. OTOH the manual authors know
perfectly well which package they want to link to, they just can't
specify it any more...

I am probably missing something, but what do we gain from linking to
files, instead of topics? Especially that linking to topics already
works perfectly well?

Gabor

[...]