[Rd] \Sexpr{} within \examples{}

[Gábor Csárdi]

Hi all,

I am trying to use \Sexpr{} within \examples{} in the manual, and it
all works fine, except that I get an error and then a NOTE from R CMD
check when it checks for long lines in the manual.

The long line check calls `Rd2txt` with fragment = TRUE, because it
only checks the \usage{} and \examples{} sections, but fragment = TRUE
does not evaluate \Sexpr{}, and then an unevaluated \Sexpr{} is not
allowed in \examples{}. (Well, sometimes, see below.)

Apart from the check NOTE, I would think it could be better to
evaluate the \Sexpr{} in/before the long line check. Otherwise it is
surely not checking the text that'll appear in the manual in the end.

Maybe it would make sense to call prepare_Rd() before the check, to
evaluate the \Sexpr{} calls?

Here is a reproducible example, tools:::.check_Rd_line_widths()
eventually calls Rd2txt() with fragment = TRUE, via
tools:::find_wide_Rd_lines_in_Rd_object, so I'll just call Rd2txt()
directly here, for simplicity:

rd <- "
\\name{foo}
\\title{Title}
\\description{Desc.}
\\examples{
  \\Sexpr[stage=render]{\"# foobar\"}
}"

rd <- tools::parse_Rd(con <- textConnection(rd)); close(con)

tools::Rd2txt(rd)
pos <- which(tools:::RdTags(rd) == "\\examples")
tools::Rd2txt(rd[pos], fragment = TRUE)

#> Examples:
#>
#> Error: 6: Tag \Sexpr not expected in code block

# This fails. After prepare_Rd() it works fine:

rd2 <- tools:::prepare_Rd(rd, stages = "render")
pos2 <- which(tools:::RdTags(rd2) == "\\examples")
tools::Rd2txt(rd2[pos2], fragment = TRUE)

#> Examples:
#>
#>      # foobar

Interestingly, if Rd2txt() is called with the \examples tag only,
instead of the 1-element list consisting of the \examples tag, like
above and in tools:::find_wide_Rd_lines_in_Rd_object, it also works
fine, although it does not render the \Sexpr{}, of course:

tools::Rd2txt(rd[[pos]], fragment = TRUE)

#> \Sexpr[stage=render]{"# foobar"}

Do you think it would make sense to change the line width check, so
\Sexpr{} within \examples{} will not generate a NOTE?

Thank you,
Gabor