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

On Fri, 19-08-2016, at 15:41, Sean Davis <seandavi at gmail.com> wrote:

On Aug 19, 2016, at 9:10 AM, Ramon Diaz-Uriarte <rdiaz02 at gmail.com>

wrote:

On Wed, 17-08-2016, at 15:08, Sean Davis <seandavi at gmail.com> wrote:

On Aug 17, 2016, at 8:55 AM, Martin Morgan <

martin.morgan at roswellpark.org> wrote:

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.

And with some CSS trickery (may not even be needed if basing things on

an established CSS framework), an HTML vignette can be rendered in a very
nice printable form if folks want to print it.

http://stackoverflow.com/a/12303057/459633

Thanks Sean, didn't know about that.

But then, doesn't this somehow defeats part of the purpose (or the

spirit)

of R markdown: a single file, with low barrier of entry, that allows

you to

produce HTML, PDF (and epub) just by calling one or another function in

the

call to render?  (Context: after having used LaTeX for maaaany years, I

am

finding the markdown experience painful and disconcerting; the idea of
handling CSS trickery looks like additional pain and suprises :-).

Hi, Ramone.

Well, before worrying too much about needing to do extra work, take a

look at this page:

http://bioconductor.org/packages/release/bioc/

vignettes/BiocStyle/inst/doc/HtmlStyle.html

Then, choose ?print page?.  As you can see, the rendered pdf is actually
quite usable, including page numbers, clickable TOC, and originating URL.
If you were to take a look at the CSS for biocstyle, it does not include
any special ?trickery? for printing, but it could if there is behavior
needed beyond the ?default?.

Thanks Sean. You are right: this is a very usable PDF and can be obtained
very easily. (Just for the record, and in case someone else stumbles upon
this, at least under Linux clickable links can depend a lot on the browser;

uses one of the extensions available. htmldoc and wkhtmltopdf also work
fine from the command line).


Best,

R.

That said, I still use .Rnw for some things where I want the true print
beauty of LaTeX, but for collaborators, vignettes, and everyday work, I
still find rmarkdown compelling.  Moving beyond the single vignette, the
ecosystem around markdown is impressive, particularly with respect to
HTML/web.

Sean

As the one producing the vignette, what do I gain from inserting a link

in

the HTML vignette that points to a place where I've left the PDF

(produced

using pdf_document or similar)? (Aside from not inserting the link and

not

having to produce the PDF, which can be automated via hooks or similar).




Best,

R.

Sean

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

  [[alternative HTML version deleted]]

This email message may contain legally privileged

and/or...{{dropped:2}}

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

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