R devel - Feb 2013 - Suggestion: Custom filename patterns for non-Sweave vignettes

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

There are several reasons I decided against that:

   - two packages may request overlapping patterns, making it much 
messier to do the matching, checking etc, since the matching would have 
to depend on the package being processed.

   - one package may request a pattern that another package uses for 
auxiliary files, e.g. .bib.  If a user has both types of vignette it 
would just be a mess.

   - the extension is also used to determine the output format.  We only 
support LaTeX (which will be converted to PDF) and HTML output.  It 
would be reasonable to support direct PDF output, but I don't think any 
other output formats should be supported.

I understand that forcing you to use .Rmd instead of .html.rsp may look 
unsightly, but I think the extensions need to be fixed, not customizable.

Duncan Murdoch

On 13-02-14 10:29 PM, Henrik Bengtsson wrote:
> 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
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>