Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Links in @family tag don't have anchors #1650

Open
llrs opened this issue Aug 27, 2024 · 1 comment
Open

Links in @family tag don't have anchors #1650

llrs opened this issue Aug 27, 2024 · 1 comment

Comments

@llrs
Copy link

llrs commented Aug 27, 2024

CRAN (and Bioconductor) wish that all cross-references were anchored (And testing via a new environmental variable).
I was checking the current state of CRAN's cross references and I found out that some of my own cross-references were missing the anchor (See for example the source and the output). This happens when they are generated with #' @family group.

library(roxygen2)
roc_proc_text(rd_roclet(), "
  #' Title1
  #'
  #' See [bar()]
  #' @family check
  #' @md 
  foo <- function() {}
  
  #' Title2
  #'
  #' @family check
  bar <- function() {}
  "
)
#> $foo.Rd
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{foo}
#> \alias{foo}
#> \title{Title1}
#> \usage{
#> foo()
#> }
#> \description{
#> See \code{\link[=bar]{bar()}}
#> }
#> \seealso{
#> Other check: 
#> \code{\link{bar}()}
#> }
#> \concept{check}
#> 
#> $bar.Rd
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{bar}
#> \alias{bar}
#> \title{Title2}
#> \usage{
#> bar()
#> }
#> \description{
#> Title2
#> }
#> \seealso{
#> Other check: 
#> \code{\link{foo}()}
#> }
#> \concept{check}

Created on 2024-08-27 with reprex v2.1.1

I think the root cause is that it is handled different than in other cases where links are created (as in markdown it works well), see:

roxygen2/R/rd-family.R

Lines 56 to 60 in 9652d15

by_file <- map_chr(other_aliases[order_c(other_aliases_order)], function(x) {
obj <- find_object(x[1], env)
suffix <- if (is.function(obj$value)) "()" else ""
paste0("\\code{\\link{", escape(x[1]), "}", suffix, "}")
})

Different from:

links <- paste0(
"\\code{\\link[", pkg$pkg,
ifelse(pkg$file == pkg$fun, "", paste0(":", pkg$file)),
"]{", escape(pkg$fun), "}}",
collapse = ", ")
paste0("\\item{", pkg$pkg[[1]], "}{", links, "}")

I'm not sure how it handles multiple topics in the same file after #1109 or how to find the right topic on the rd-family.R, but fixing this will eventually help solve a note from packages that use roxygen2.

@llrs
Copy link
Author

llrs commented Aug 29, 2024

Apologies, I think they are not needed in this case (yet?) because the links are always to topics in the same package and CRAN doesn't complain about it.

I am not sure if then the anchors are needed according to the documentation. I leave it open in case this helpful or you want to harmonize both ways have links.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant