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

[David Hugh-Jones]

On this note, I just got

Non-file package-anchored link(s) in documentation object
'brk_width-for-datetime.Rd':
  ‘[lubridate:%m+%]{lubridate::add_with_rollback()}’

The correct filename appears to be %m+% in the lubridate help. Can anyone
tell me the right way to format this? I would work it out myself, but the
check didn't cause problems on the r-devel systems I tested with, so I'd be
testing blind.

Cheers,
David


On Mon, 15 Jun 2020 at 17:30, Duncan Murdoch <murdoch.duncan using gmail.com>
wrote:

> 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
> >      >>
> >      >> [...]
> >
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]