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

[Duncan Murdoch]

On 13/06/2020 9:00 p.m., Gábor Csárdi wrote:
> 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?

I think the argument was that static builds of the help pages would have 
trouble resolving the links.  With the current system, you can build a 
help page that links to a page in package foo even if package foo is not 
installed yet, and have the link work later after you install foo.

Duncan Murdoch