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

[Duncan Murdoch]

On 15/06/2020 12:05 p.m., Martin Maechler wrote:
>>>>>> 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.

Actually, I don't think I pushed for this change at the time (or at 
least I didn't push much).  I just wish now that I had, because I think 
it will be harder to do it now than it would have been then.

Duncan

> 
> 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 using 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
>      >>
>      >> [...]
>