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

[Ramon Diaz-Uriarte]

Dear Henrik,

On Wed, 17-08-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.
>

I wasn't aware of that. Thanks for the explanation.


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

Interesting; I hadn't thought of that. Nevertheless, IIUC that is not
currently provided by default, regardless of whether we use Rnw or Rmd or
the output format; if a users wants the intermediate md/tex this can be
done via knit or similar from the installed package.


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

Understood, thanks. The simplest case would only differ in the "output"
line.  However, would that not be considered abusing the BioC system and
possibly confusing users?: the source package would have two identical
files that differ in a single line and in their names, and there would be
two identical "R Script" files.



I guess a simple alternative is to, say, have the BioC page show the PDF
vignette, so that I write

output:
   BiocStyle::pdf_document:

in the "default, BioC uploaded package code".

Then, it is up to me (locally, or using travis) to have a sed script that
will replace the second line by whatever (say, BiocStyle::html_document),
will render the HTML, and then put that in Github Pages.



Best,


R.




> 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


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