[Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?

[Ramon Diaz-Uriarte]

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