From hb at biostat.ucsf.edu  Fri Feb 15 04:29:24 2013
From: hb at biostat.ucsf.edu (Henrik Bengtsson)
Date: Thu, 14 Feb 2013 19:29:24 -0800
Subject: [Rd] Suggestion: Custom filename patterns for non-Sweave vignettes
Message-ID: <CAFDcVCQs4GEYznPmqkz=gRuq2=KEWMnOqsSq3fGU92mUN0hbUA@mail.gmail.com>

Hi,

as far as I understand it, the new R devel feature of processing
non-Sweave vignettes will (a) locate any "[.][RrSs](nw|tex)$" or
".Rmd" files, (b) check for a registered vignette engine, (c) process
the file using the registered "weave" function, (d) and possibly post
process the generated weave artifact (e.g. a *.tex file).

I'd like to propose to extend this non-Sweave mechanism to allow for
any filename patterns still using a very similar setup.  Here is how
I'd like it to see it work with RSP vignettes (cf. the R.rsp package):

  tools::vignetteEngine("rsp", weave=rspWeave, tangle=rspTangle,
patterns="[.]rsp$")

Argument 'patterns' could default to patterns=c("[.][RrSs](nw|tex)$",
"[.]Rmd$").

This is just a sketch/mock up and it may be that there are better
solutions.  However, the idea is that when specify 'VignetteBuilder:
R.rsp' in DESCRIPTION of a package, R locates all engines registered
by the builder package.  In this case it finds 'rsp'.  (An alternative
to this lookup would be to use a DESCRIPTION field 'VignetteEngines:
R.rsp:rsp, knitr:knitr'.)  It next looks for custom filename patterns
and use those to scan for vignette source files.  With this approach,
the '%\VignetteEngine{knitr}' specifier would become optional.  (I can
see how R now scans for Rnw and Rmd files, checks them for a
\VignetteEngine{} markup, and then looks up the corresponding engine).

Continuing, the above would make it possible to process RSP vignettes
that have filenames:

  reportA.tex.rsp
  reportB.html.rsp
  reportC.md.rsp
  reportD.Rnw.rsp

where rspWeave() will produce the following files:

  reportA.tex
  reportB.html
  reportC.html
  reportD.tex

I included the latter case just to illustrate a special case where
rspWeave() first generates a reportC.Rnw (Sweave or knitr) which is
the processed using the corresponding weaver to generate reportC.tex.

My point is that restricting vignette filenames to ".[RrSs](nw|tex)$"
or ".Rmd" is unnecessary and conceptually it would not be too hard to
extend it to handle any filename patterns.

I am aware that implementing this would require updates in several
place.  If R core would approve on the above extended functionality, I
would be happy to dig into the source code and provide minimal and
backward compatible patches.

Finally, without knowing the details of all the other report
generating packages, my guess is that this extended feature would be
useful also for some of those packages, which in the long run
hopefully results in more packages having more vignettes (regardless
of the vignette format).

All the best,

Henrik



[Rd] Suggestion: Custom filename patterns for non-Sweave vignettes
Henrik Bengtsson