Preserve order of @example and @examples

[HenrikBengtsson]

I'd like to propose a new tag @import that takes a file as input. It reads the content of that file and injects it as is.

One use case would be to allow for something like (just a toy example):

#' @examples
#' \dontshow{
#' oopts <- options()
#' }
#' @import incl/my_fcn.R
#' \dontshow{
#' options(oops)
#' }

The above allows you to keep a standalone, syntax-valid file incl/my_fcn.R that can be source():ed while still having additional Rd markup in the example() code.

[gaborcsardi]

#' @example filename
#' @examples
#' code

almost does that, @examples and the code in filename will be put in the \examples.

[HenrikBengtsson]

Thanks. I didn't know that this was possible. However, did you mean that "almost" to be emphasized? I just tried with:

#' @examples
#' \dontshow{
#' ## BEFORE
#' }
#' @example incl/my_fcn.R
#' @examples
#' \dontshow{
#' ## AFTER
#' }

and that ends up putting all the @examples code at the top and the @example content at the bottom;

\examples{
\dontshow{
## BEFORE
}
\dontshow{
## AFTER
}
y <- my_fcn(42)
y <- my_fcn(3.14)

[gaborcsardi]

and that ends up putting all the @examples code at the top and the @example content at the bottom

yes, that's what I meant by almost, sorry.

[HenrikBengtsson]

No worries. Thxs for confirming.

[gaborcsardi]

It is a bit hard to keep the order internally, because roxygen collates all @examples blocks previously, before putting that and the @example files together.

Also, CRAN do not like this, potentially, depending on what you put in the setup and teardown chunks.

[hadley]

Looking at topic_add_examples(), I don't think it should be too hard to interleave @example and @examples in the order that they're encountered, rather than in individual blocks.