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

[Martin Morgan]

On 08/17/2016 07:02 AM, Henrik Bengtsson 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.
>
> 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.

A consideration from the build machine perspective is the cost to 
process the vignettes, in particular the code chunks. These would be 
done across platforms and vignettes, because the build system wouldn't 
know about the trickery you're engaged in.

Also from the end user perspective I don't think having two vignettes 
with identical content is particularly helpful; as a user I wouldn't be 
confident that they were equally current (however adeptly the 
duplication of content were implemented).

Personally, I think the HTML presentation is much more conducive to the 
way vignettes are used.

Martin


>
> 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
>


This email message may contain legally privileged and/or...{{dropped:2}}