14

After building a simple test package to isolate this issue, I receive the following warning when I run Rcmd.exe INSTALL --nomultiarch --with-keep.source simpleTest:

* installing to library 'C:/Users/user/Documents/R-dev'
* installing *source* package 'simpleTest' ...
** R
** preparing package for lazy loading
** help
*** installing help indices
  converting help for package 'simpleTest'
    finding HTML links ...    hello                                   html  
Rd warning: C:/user/RPackages/simpleTest/man/hello.Rd:11: missing file link 'transmute'
 done
** building package indices
** testing if installed package can be loaded
* DONE (simpleTest)

The issue occurs when you link to functions that point to an Rd file of a different name. For example, in my simpleTest package, the documentation links to both dplyr::mutate() and dplyr::transmute(), both of which are documented in the mutate.Rd file. The former link does not cause the Rd warning, while the latter does. However, both links work when you look at the help page for the current package.

The .R file for the simpleTest package is included below. I run devtools::document() and then build the package in a skeleton package directory.

hello.R

#' print hello
#'
#' This does something less complicated than \code{\link[dplyr:mutate]{dplyr::mutate()}} 
#' and \code{\link[dplyr:transmute]{dplyr::transmute()}}.

#' @export
hello <- function() {
  print("Hello, world!")
}
user2554330
  • 37,248
  • 4
  • 43
  • 90
r_alanb
  • 873
  • 8
  • 21
  • Have you seen this question: [Linking to other packages in documentation in roxygen2 in R](https://stackoverflow.com/questions/25489042/linking-to-other-packages-in-documentation-in-roxygen2-in-r) – MrFlick Jan 24 '18 at 19:50
  • @MrFlick - It does not matter if you use `\code{\link[dplyr:transmute]{dplyr::transmute()}}` or `\code{\link[dplyr]{transmute}}` as the link you provided instructs; either way, you receive the Rd warning. – r_alanb Jan 25 '18 at 18:57

1 Answers1

14

This is because the links are created based on the names of the files, not the aliases. If you just use \link{foo}, foo is a topic (and hence you can use aliases without problem). The moment however you use any of the forms :

\link[pkg]{foo}
\link[pkg:foo]{bar}

foo needs to be a file and hence you can only use the name and not the alias. If you check ?dplyr::mutate, you see that mutate is the name (upper left corner) and transmute is an alias. So when you try to use the alias the link will (likely) work, but you will see the warning you saw.

To avoid that, you need :

\link[dplyr:mutate]{dplyr::transmute()}

For reference: https://cran.r-project.org/doc/manuals/R-exts.html#Cross_002dreferences

Joris Meys
  • 106,551
  • 31
  • 221
  • 263
  • 1
    Thanks @JorisMeys. It strikes me as a bit dangerous to link to the file explicitly, as there is nothing to prevent another package's developer from changing the documentation structure in a way that would then render the link broken. I suppose you can say the same thing for functions too, but at least those are usually deprecated first, where as it seems like you might change the Rd name without thinking through any consequences. – r_alanb Jan 31 '18 at 01:31
  • @r_alanb I didn't write R. The official documentation provided by R core tells you that the construct you use, need to point to the file because that's how the R help system reads the link. You're free to try to convince them to change this ;-) – Joris Meys Jan 31 '18 at 11:53
  • 1
    Ha, hopefully I'll have more luck with addressing via roxygen: https://github.com/klutometis/roxygen/issues/707 – r_alanb Feb 06 '18 at 22:07
  • @r_alanb I hope they can catch it somehow, but I am quite positive this is tied to R itself, not so much to roxygen. – Joris Meys Feb 07 '18 at 09:49
  • 1
    you're totally right, specifically, its in install.R. But since roxygen already converts `[dplyr::transmute()]` to `\link[dplyr:transmute]{dplyr:transmute()}`, hopefully they could search at that point and convert to `\link[dplyr:mutate]{dplyr:transmute()}` instead. – r_alanb Feb 09 '18 at 00:53