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

Duncan Murdoch   on Sun, 14 Jun 2020 07:28:03 -0400 writes:

     > I agree with almost everything you wrote, except one thing:  this isn't
     > newly enforced, it has been enforced since the help system began.  What
     > I think is new is that there are now tests for it.  Previously those
     > links just wouldn't work.

     > Duncan Murdoch

Yes, to all... including Duncan's agreement with G?bor.

Also, Duncan M earlier did mention that he had wanted to
*change* the link-to-file behavior for these cases (when he
wrote most of the Rd2html source code) but somehow did not get it.

And that's why we had partial workarounds (as the dynamic server
still finding the links under some circumstances).

My personal opinions was also that "we" (the R community; i.e.,
people providing good patches to the R sources / collaborating
with R core / ...) should rather work to fix the current
design/implementation "infelicity" than the current checks
starting to enforce something which is really a wart in my view,
and indeed, as G?bor also notes, will create R source
documentation that depends on implementation details of other
package's documentation.
I don't like it either, not at all.

Martin

     > On 14/06/2020 6:26 a.m., G?bor Cs?rdi wrote:

     >> On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
     >> <murdoch.duncan at gmail.com> wrote:
     >> [...]

     >>>
     >>> 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.

     >>
     >> That is true, but it is also not a big problem, I think. The CRAN
     >> Windows R installer does indeed build static help pages by default.
     >> But the built-in web server that serves these works around broken
     >> links by treating them as help topics instead of files. As you know.
     >> :) So this would only be a problem if you wanted to serve the static
     >> help pages with another web server. (Which is not a bad use case, but
     >> then maybe Rd2HTML() can just resolve them as topics and avoid the
     >> broken links.)
     >>
     >> Btw. the problem of linking to the wrong page is even worse with
     >> static builds of help pages, because if a link w/o a package (e.g.
     >> \link{filter}) picks up the wrong package at install time, then the
     >> wrong link is hard-coded in the html. If you are building binary
     >> packages, then they will link to the wrong help pages.
     >>
     >> WRE says that specifying the package in the link is rarely needed.
     >> This was probably the case some time ago, especially when packages did
     >> not have (compulsory) namespaces. But I am not sure if it still holds.
     >> I would argue that it is better to specify the package you are linking
     >> to. But the newly enforced requirement that we need to link to files
     >> instead of topics makes this more error prone.
     >>
     >> Gabor
     >>
     >> [...]