[R-pkg-devel] A replacement idiom for \value{\item{\var{...}}{}}
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