[Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
On Thu, 18-08-2016, at 16:45, Wolfgang Huber <whuber at embl.de> wrote:
On 17 Aug 2016, at 13:02, Henrik Bengtsson <henrik.bengtsson at gmail.com> wrote: R CMD build, which is what triggers vignette building, only supports one output file (HTML or PDF) per vignette. It will basically ignore duplicate output formats. This is by design / legacy reasons. Technically it wouldn't be hard to add support for multiple output formats, but that would require changes to R itself - I think it could be a useful feature.
Henrik, I?m sure you have more experience and insight with this than I, but I wonder when (at what stage) and what for R needs to be changed? It seems there are several issues: (a) having both the PDF and HTML be built by the build system and be shipped with the package (b) making them discoverable on the Bioc package landing page, and on the index page of the R-help system. (c) making (a) and (b) easy and standardized for package authors Re (a), on first sight, it seems that simply adding the YAML lines Ramon mentioned to the vignette will NOT achieve this (it looks like only whatever is the first output format stated, is produced), but according to https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-package-vignettes https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Non_002dSweave-vignettes
I expect that with sufficient cleverness with (i) a Makefile and/or (ii) registering your own VignetteBuilder (some wrapper around knitr::render that makes sure both outputs are built, with only one run of the R code) it should be possible to achieve (a). For something almost as good as (b) [or better?], you could have the HTML indexed, and in it e.g. at the top have a button with a link to the PDF file, for those who want to print it.
bookdown::gitbook (https://bookdown.org/yihui/bookdown/html.html) provides those buttons (PDF, epub, etc): and some other niceties (though I have not had luck getting the TOC to behave as I wanted with single-file vignettes). R.
For (c), I suppose changing R would be handy. Or BiocStyle?
Wolfgang
A related question is where some prefer to have access to also the intermediate plain Markdown / TeX rather than the final HTML / PDF product, e.g. because they work better with screen readers. The only way I see you can have a PDF and a HTML version at the same time is to create to identical vignettes each outputting a specific format. Henrik On Aug 17, 2016 12:17, "Ramon Diaz-Uriarte" <rdiaz02 at gmail.com> wrote:
Dear All,
I am considering rewriting the vignette of one BioC package I maintain as
Rmd (it is currently Rnw). But I would like that the entry under
"Documentation" contain a PDF of the vignette; it can ideally also contain
the HTML version too, but I do not want it to not have the PDF[1].
I know I can add entries to the document header such as
output:
BiocStyle::pdf_document:
toc: true
BiocStyle::html_document:
toc: true
that will, when run locally via "render('file.Rmd', output_format =
'all')", produce both formats.
I've googled around, but I am not sure about:
1. If I have both output formats specified in the document header, will the
BioC page of the package actually show both the PDF and the HTML of the
vignette?
2. Is it OK (in conforming with BioC policies, sensible[1], whatever) to
even try/want this? My reading of the doc for the BiocStyle
(https://www.bioconductor.org/packages/devel/bioc/vignettes/
BiocStyle/inst/doc/HtmlStyle.html)
seems to suggest that the "natural" thing for Rmd vignettes is to be
rendered as HTML, but I have not seen that producing PDF is discouraged
explicitly.
Best,
R.
[1] Why do I want to get a PDF if I am using Rmd? I want a PDF because this
is a fairly long document that some users want to be able to print. I want
HTML because some users prefer HTML and because I'd like to also place the
vignette as HTML in Github Pages. I think that the only way to accomplish
both is to use Rmd (not Rnw, even if I really, really, prefer LaTeX :-).
--
Ramon Diaz-Uriarte
Department of Biochemistry, Lab B-25
Facultad de Medicina
Universidad Aut?noma de Madrid
Arzobispo Morcillo, 4
28029 Madrid
Spain
Phone: +34-91-497-2412
Email: rdiaz02 at gmail.com
ramon.diaz at iib.uam.es
http://ligarto.org/rdiaz
_______________________________________________ Bioc-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
[[alternative HTML version deleted]]
_______________________________________________ Bioc-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
Ramon Diaz-Uriarte
Department of Biochemistry, Lab B-25
Facultad de Medicina
Universidad Aut?noma de Madrid
Arzobispo Morcillo, 4
28029 Madrid
Spain
Phone: +34-91-497-2412
Email: rdiaz02 at gmail.com
ramon.diaz at iib.uam.es
http://ligarto.org/rdiaz