[R-pkg-devel] A replacement idiom for \value{\item{\var{...}}{}}

[Sebastian Meyer]

Am 10.07.23 um 16:30 schrieb Ivan Krylov:
> Hello R-package-devel,
> 
> I've got a function that returns a data.frame. The columns (and their
> names) of the return value are parametrised by the arguments of the
> function. See, for example, the following function:
> 
> foo <- function(n = 10, out.M = c(2, 3, 5))
>   as.data.frame(setNames(
>    lapply(out.M, \(M) M * runif(n)),
>    paste0('fooval.', out.M)
>   ))
> 
> If I call it as foo(out.M = 1), I get a data.frame containing a column
> named fooval.1. If I call it as foo(), I get columns fooval.2,
> fooval.3, and fooval.5 instead.
> 
> I would like to document this relationship between the arguments and
> the output value like so:
> 
> \arguments{
>   \item{out.M}{Return the foo vectors for every M value given here.}
>   % more arguments that behave in a similar manner
> }
> % ...
> \value{
>   A \code{data.frame} containing the following columns:
> 
>   \item{fooval.\var{m}}{
>    The foo values, for every \var{m} in \code{out.M}.
>   }
>   % more parametrised output columns to follow
> }
> 
> It turns out that \value{} description lists now escape their \item{}
> arguments, preventing me from using \var{} markup there, but only in
> plain text and HTML outputs. I think that the change occurred in the
> last year or so; old versions of R process markup in \item{} arguments
> even in \value{} description lists, but they have other Rd problems. I
> understand the motivation of the change: in \arguments{} and \value{}
> environments, it makes sense to typeset \item{} headings as \code{}.

Thank you for the report. AFAICS, this only affects HTML conversion in R 
 >= 4.3.0. It is an "internally" known limitation (see corresponding 
source code comment in Rd2HTML).

OTOH, WRE does not clearly specify that \item labels in \arguments or 
\value could actually contain any markup. That said, the referenced 
"Parsing Rd files" document 
(<https://developer.r-project.org/parseRd.pdf>) does tell us that 
\item{}{} arguments are parsed as LaTeX-like text, \dots probably being 
the most common example.

> 
> Should I try to fix Rd2latex (or at least file a ticket) to escape the
> \item{...} arguments in \value{} (but not \describe{}!) environments
> too?

Yes, I think this belongs to "R-devel" and a problem report in Bugzilla 
would be useful; the problem being that Rd markup in \item labels is 
handled inconsistently by the Rd converters. It is currently unclear to 
me, however, which one is at fault here. Your example at least provides 
one (admittedly quiet special) use case for LaTeX-like content in an 
\item label of the \value section.

> 
> What would be a better Rd idiom for such function argument — output
> component relationships?
> 

I think a workaround that currently works for your use case is to use 
\code{fooval.\var{m}} as the label (i.e., wrapped inside \code).

Best regards,

	Sebastian Meyer