Can pandoc metadata play nicely with vignettes written as .Rmd?

[Douglas Bates]

I am trying to work out how to have an .Rmd vignette use the YAML metadata or at least not conflict with it.  In other words, I would like to define title, author, date, etc. in the metadata and have them show up when the vignette is created.   None of my attempts have been successful and I am left either putting a title in the Markdown or losing it in the vignette version of the .html file.

[Douglas Bates]

Hmm.  I tried again and it seems to work as desired now.  Please ignore my earlier confusion.

[Douglas Bates]

Now I need to retract my retraction -- it's been a confusing day.

I'm beginning to think that it is not worthwhile creating vignettes if all the "good stuff" that one can do with pandoc does not get applied.

As I understood it, the sources for vignettes should be in the vignettes directory.  When the package is built these are converted to .html and .R files in the inst/doc directory which becomes the doc directory of the installed package.  I know there was a reason for this but I can't remember what it was.

Can one create the .html and .R files using RStudio and put them in the inst/doc directory?  No doubt this will violate some CRAN rule but I don't plan to submit this package to CRAN.  I would like those who install using, say, install_github, to be able to access the vignettes using the vignette function.  So, can I do the installation into inst/doc by hand? 

[Yihui Xie]

I think you probably can, and it should be easy to verify whether it
works. Or perhaps it works when you put .html in vignettes/.

Unless you vignettes are very time-consuming to build, you should tell
your users to use devtools::install_github(build_vignettes = TRUE).
The default is FALSE, which is probably a bad idea in my opinion, but
I'm not the author of devtools... The other option is to build the
source packages using other tools, such as RForge or Travis CI, then
install.packages() instead of install_github().

Regards,
Yihui
--
Yihui Xie <xiey...@gmail.com>
Web: http://yihui.name

[Carl Boettiger]

Hi Douglas,

Can you give us a bit more information? 

I'm not sure what "the good stuff" refers to, but I find most pandoc metadata can be added just as easily from the YAML of a .Rmd.  Re title, date, etc, see an easy example here: http://r-pkgs.had.co.nz/vignettes.html#vignette-workflow

Re inst/doc, yup, you can put them there.  Alternately you can run `devtools::build_vignettes()` and it will put the .Rmd, .html, and .R files into inst/doc.  If you commit those files in inst/doc to github, then a user can do:

    install_github("user/package")

    vignette("vignetteName", package="package")

Great question about providing pre-built vignettes by the way, I didn't try this until your question but I think this approach makes a lot of sense.  

Note that FWIW, you can include the .html and .R files created by building the vignette in either /inst/docs or vignettes/ and devtools::check() will not complain...

I disagree with Yihui that install_github() should default to build_vignettes=TRUE, for the simple reason that building vignettes requires installing the SUGGESTS list to guarantee that it works, and there is no guarantee that install_github can install the suggests list (e.g. dependencies on github, other repos).  This means that the user has to have pandoc installed (e.g. a user not using RStudio), or it will fail.  Notably install_github used to default to building vignettes, and it was a huge pain.  

  

--
You received this message because you are subscribed to the Google Groups "knitr" group.
To unsubscribe from this group and stop receiving emails from it, send an email to knitr+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Yihui Xie]

Yes, I was aware of the potential pain. It is a matter of which pain
hurts more: not having the vignettes, or having to install more R
packages + Pandoc to build the vignettes? I do not have a definite
answer. Not all vignettes use packages in Suggests, and not all
packages use Pandoc to build vignettes. The past default
build_vignettes = TRUE might have hurt you much more than me. So...
I'm not really 100% sure what the reasonable default behavior should
be.

As I mentioned to you before, nowadays I tend to publish HTML
vignettes as Github pages, so it does not matter if users choose not
to build vignettes. (Plus the fact that I have my secret XRAN :)
Publishing to Github and building packages can be made automatic, then
all I do is push to Github.

Regards,
Yihui
--
Yihui Xie <xiey...@gmail.com>
Web: http://yihui.name

>> email to knitr+un...@googlegroups.com.

>> For more options, visit https://groups.google.com/d/optout.
>

> --
> You received this message because you are subscribed to the Google Groups
> "knitr" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to knitr+un...@googlegroups.com.

[Carl Boettiger]

Yihui, yup, all great points (as usual).  I think having `install_github` not fail for the largest number of packages is more important than the convenience of building a vignette if the author hasn't bothered to do so.  

I guess it depends if users are more inclined to call `vignette` function or look for / notice a link to the gh-pages version.  I'm the latter; I had to double-check the syntax of `vignette()`, but I appreciate that others might be more used to the classic R method.  I'm thankful Doug got me to confirm that I could just commit pre-built vignettes.  

Completely agree with you about XRAN -- as you may have seen, Dirk Eddelbuettel has taken up a very similar idea with [drat](https://github.com/eddelbuettel/drat).  

>> email to knitr+unsubscribe@googlegroups.com.

>> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google Groups
> "knitr" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to knitr+unsubscribe@googlegroups.com.