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.

[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.