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

Vincent Carey stvjc at channing.harvard.edu
Mon Aug 22 14:56:26 CEST 2016 

On Mon, Aug 22, 2016 at 5:29 AM, Ramon Diaz-Uriarte <rdiaz02 at gmail.com>
wrote:

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

This is true under MacOSX El Capitan as well.  When PDF is generated from
Safari, the TOC links
are live but refer to the bioconductor.org URLs (not internal to the
document).  With chrome, no
TOC links.  Neither produces page numbers, and the Safari-generated version
crowds the
page.   With firefox  (v48) there are page numbers but all links are dead
except for one in the header, to
the original URL, and it is truncated and does not resolve.  But good to
know all the same.

chrome does it fine, but for Firefox links are not preserved, unless one
> 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
> >>>>>>
> >>>>>> _______________________________________________
> >>>>>> 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}}
> >>>>
> >>>> _______________________________________________
> >>>> 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
>
>
> --
> 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
>



-- 

Vincent J. Carey, Ph.D.
Professor of Medicine
Channing Division of Network Medicine
Brigham and Women's Hospital
Harvard Medical School
181 Longwood Avenue
Boston, MA 02115 USA

	[[alternative HTML version deleted]]

More information about the Bioc-devel mailing list