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

The Rd file is mplus.Rd, so
 ?[lubridate:mplus]{lubridate::add_with_rollback()}? would do.

Georgi Boshnakov

-----Original Message-----
From: R-package-devel <r-package-devel-bounces at r-project.org> On Behalf
Of David Hugh-Jones
Sent: 16 June 2020 07:51
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)

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

        [[alternative HTML version deleted]]