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

[Duncan Murdoch]

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
>