[R-pkg-devel] \linkS4class anchoring

[Ivan Krylov]

В Fri, 11 Apr 2025 16:00:16 +0000
"Killick, Rebecca" <r.killick using lancaster.ac.uk> пишет:

> All of the \link uses within my package are anchored except for the
> \linkS4class{cpt} call so I think this is what it is referring to.
> I've checked the writing R extensions "Cross-references" section and
> it just says to use \linkS4class{<class>} but does so in reference to
> a class within the current package - which is what has been working
> up until now.
> 
> The class is within the changepoint package so, I tried the obvious
> inference, \linkS4class[changepoint]{cpt} but this creates the
> following warning on check:
> "prepare_Rd: ./man/envcpt.Rd:63: unexpected TEXT '[changepoint]',
> expecting '{' checkRd: (7)
> envcpt.Rd:63: Tag LIST is invalid in a \code block"

\linkS4class is a "primitive" Rd markup operation, included in the
grammar and implemented directly by the individual Rd converters.
Currently, the grammar says that \linkS4class{} takes no optional
arguments. The workaround used by ?stats::xtabs is:

>> \code{\link[Matrix:sparseMatrix-class]{sparseMatrix}}

(With \linkS4class{sparseMatrix} helpfully left commented out on the
same line.)

In your case, that would be \link[changepoint:cpt-class]{cpt}.

For the future packages depending on future R versions, the grammar and
one of the converters can be changed:

-----------------------------------8<-----------------------------------
Index: src/library/tools/R/Rd2HTML.R
===================================================================
--- src/library/tools/R/Rd2HTML.R	(revision 88138)
+++ src/library/tools/R/Rd2HTML.R	(working copy)
@@ -35,6 +35,8 @@
     option <- attr(arg, "Rd_option")
 
     topic <- dest <- paste(unlist(arg), collapse = "")
+    if (tag == "\\linkS4class") dest <- paste0(dest, "-class")
+
     targetfile <- NULL
     pkg <- NULL
     if (!is.null(option)) {
@@ -55,7 +57,6 @@
     } else if (!isTEXT)
         stopRd(arg, Rdfile, "Bad \\link topic -- must be text")
 
-    if (tag == "\\linkS4class") dest <- paste0(dest, "-class")
     list(topic = topic, dest = dest, pkg = pkg, targetfile = targetfile)
 }
 
Index: src/library/tools/src/gramRd.y
===================================================================
--- src/library/tools/src/gramRd.y	(revision 88138)
+++ src/library/tools/src/gramRd.y	(working copy)
@@ -1168,7 +1168,6 @@
     
     { "\\emph",    LATEXMACRO },    
     { "\\file",    LATEXMACRO },
-    { "\\linkS4class", LATEXMACRO },
     { "\\pkg",	   LATEXMACRO },
     { "\\sQuote",  LATEXMACRO },
     
@@ -1209,6 +1208,7 @@
        one LaTeX-like argument */
        
     { "\\link",    OPTMACRO },
+    { "\\linkS4class", OPTMACRO },
        
     /* These markup macros require an R-like text argument */
     
-----------------------------------8<-----------------------------------

With the patch applied, the output for \linkS4class[changepoint]{cpt}
and \link[changepoint:cpt-class]{cpt} will be the same:

library(tools)
r"{ \linkS4class[changepoint]{cpt} \link[changepoint:cpt-class]{cpt} }" |>
 textConnection() |> parse_Rd(fragment = TRUE) |>
 Rd2HTML(no_links = FALSE, fragment = TRUE)'
# <p><a href="../../changepoint/help/cpt-class.html">cpt</a>
# <a href="../../changepoint/help/cpt-class.html">cpt</a>

Rd2ex skips \linkS4class as before; Rd2txt prints the name on the link;
Rd2latex doesn't support the cross-package anchor; and Rd2HTML needs to
process the ...-class destination first, before the if (option) { ... }
branch sets targetfile based on it.

-- 
Best regards,
Ivan