Document and export asisWeave and asisTangle

Author: eddelbuettel

ChangeLog

@@ -9,6 +9,8 @@
 	* vignettes/*.asis: New files with vignette info from .Rnw files
 	* vignettes/pdf/*.pdf: Moved to directory vignettes/
 	* vignettes/*.Rnw: Removed
+	* man/asisWeave.Rd: Documentation
+	* NAMESPACE: Export asisWeave and asisTangle
 
 2025-07-01  Dirk Eddelbuettel  <[email protected]>
 

NAMESPACE

@@ -33,7 +33,9 @@ export(Module,
        cpp_object_initializer,
        cpp_object_dummy,
        Rcpp.plugin.maker,
-       getRcppVersion
+       getRcppVersion,
+       asisTangle,
+       asisWeave
        )
 S3method(print, bytes)
 S3method(format, Rcpp_stack_trace)

R/asis.R

@@ -2,6 +2,33 @@
 ## by Henrik Bengtsson licensend under LPGL (>= 2.1) and somewhat simplified / shortened
 ## feature-reduced here. Please the R.rsp for a full-featured version and documentation
 
+##' Simple \sQuote{asis} Vignette Processor
+##'
+##' To pass pre-made pdf vignette vignettes through \dQuote{as is}, a simple vignette
+##' process is added. It is derived from the more feature-complete one in the \pkg{R.rsp}
+##' package. To use it, add files named like the pdf file plus an appended \code{.asis}
+##' with the vignette metainformation and register the vignette processor, see the examples.
+##'
+##' @title Process pdf vignettes \sQuote{asis}
+##' @name asisWeave
+##' @param file character Filename to be processed
+##' @param ... dots Currently ignored
+##' @param pattern character A regular expression describing the filename pattern
+##' @return The respective filename is returned, invisibly
+##' @author Henrik Bengtsson for the original versions in package \pkg{R.rsp},
+##' Dirk Eddelbuettel for the shortened ones used here
+##' @examples
+##' # To register this vignette engine use
+##' \dontrun{tools::vignetteEngine("asis", package = pkgname, pattern = "[.](pdf|html)[.]asis$",
+##'                                weave = asisWeave, tangle = asisTangle)}
+##' # and add \code{VignetteBuilder: Rcpp} as well as \code{Suggests: Rcpp} to \code{DESCRIPTON}
+##'
+##' # Use a .asis file as in the Rcpp package, for example Rcpp-FAQ.pdf.asis has these lines:
+##' #   %\VignetteIndexEntry{Rcpp-FAQ}
+##' #   %\VignetteKeywords{Rcpp, FAQ, R, Cpp}
+##' #   %\VignettePackage{Rcpp}
+##' #   %\VignetteEncoding{UTF-8}
+##' #   %\VignetteEngine{Rcpp::asis}
 asisWeave <- function (file, ...) {
     output <- tools::file_path_sans_ext(basename(file))
     if (!file.exists(output)) {
@@ -14,9 +41,10 @@ asisWeave <- function (file, ...) {
         }
     }
     Sys.setFileTime(output, time = Sys.time())
-    output
+    invisible(output)
 }
 
+##' @rdname asisWeave
 asisTangle <- function (file, ..., pattern = "(|[.][^.]*)[.]asis$") {
     workdir <- "."
     filename <- basename(file)