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

[Duncan Murdoch]

On 13/06/2020 1:17 p.m., Zhian Kamvar wrote:
> Hello,
> 
> I noticed a strange error pop up for R-devel (2020-06-12 r78687) check on travis: https://travis-ci.org/github/grunwaldlab/poppr/jobs/697831376#L4653-L4654
> 
> * checking Rd cross-references ... WARNING
> Non-file package-anchored link(s) in documentation object 'aboot.Rd':
>    ‘[ape:phylo]{ape::phylo()}’
> 
> I looked at the Cross-reference section of WRE, but I couldn't find any mention of non-file package-anchored links being a problem: https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Cross_002dreferences
> 
> Is this a new policy?
> 

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

"There are two other forms of optional argument specified as 
\link[pkg]{foo} and \link[pkg:bar]{foo} to link to the package pkg, to 
files foo.html and bar.html respectively."

The problem is that `phylo` is documented in the read.tree.Rd file in 
ape, so your link needs to be

  \link[ape:read.tree]{ape::phylo()}

I wish I had fixed this inconsistency years ago when I rewrote the Rd 
code, but I didn't.  It would have been painful at the time (there were 
already thousands of CRAN packages, and lots would have needed fixing), 
but would be much worse now.

Another design flaw that I didn't fix is that you can have an Rd with 
\name{foo} and no \alias{foo}, and searching ?foo won't find it.  In 
that case I failed to convince other R core members that it would have 
been a good change.

Duncan Murdoch