[Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
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: rdia...@gmail.com ramon.d...@iib.uam.es http://ligarto.org/rdiaz ___ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
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. Henrik On Aug 17, 2016 12:17, "Ramon Diaz-Uriarte" 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: rdia...@gmail.com >ramon.d...@iib.uam.es > > http://ligarto.org/rdiaz > > ___ > Bioc-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/bioc-devel [[alternative HTML version deleted]] ___ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
see Henrik's answer. Just adding that I would also like to see support for multiple formats, particularly HTML and PDF from a single source. Best, Kasper On Wed, Aug 17, 2016 at 1:02 PM, Henrik Bengtsson < henrik.bengts...@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. > > 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" 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: rdia...@gmail.com > >ramon.d...@iib.uam.es > > > > http://ligarto.org/rdiaz > > > > ___ > > Bioc-devel@r-project.org mailing list > > https://stat.ethz.ch/mailman/listinfo/bioc-devel > > [[alternative HTML version deleted]] > > ___ > Bioc-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/bioc-devel > [[alternative HTML version deleted]] ___ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
Dear Henrik, On Wed, 17-08-2016, at 13:02, 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. > 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" 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: rdia...@gmail.com >>ramon.d...@iib.uam.es >> >> http://ligarto.org/rdiaz >> >> ___ >> Bioc-devel@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: rdia...@gmail.com ramon.d...@iib.uam.es http://ligarto.org/rdiaz ___ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
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" 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: rdia...@gmail.com ramon.d...@iib.uam.es http://ligarto.org/rdiaz ___ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel [[alternative HTML version deleted]] ___ Bioc-devel@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@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
> On 17 Aug 2016, at 13:02, 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. 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. 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" 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: rdia...@gmail.com >> ramon.d...@iib.uam.es >> >> http://ligarto.org/rdiaz >> >> ___ >> Bioc-devel@r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/bioc-devel > > [[alternative HTML version deleted]] > > ___ > Bioc-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/bioc-devel ___ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
On Wed, 17-08-2016, at 15:08, Sean Davis wrote: >> On Aug 17, 2016, at 8:55 AM, Martin Morgan >> 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 mny years, I am finding the markdown experience painful and disconcerting; the idea of handling CSS trickery looks like additional pain and suprises :-). 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" 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: rdia...@gmail.com ramon.d...@iib.uam.es http://ligarto.org/rdiaz ___ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listin
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
On Thu, 18-08-2016, at 16:45, Wolfgang Huber wrote: >> On 17 Aug 2016, at 13:02, 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. > > 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" 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: rdia...@gmail.com >>> ramon.d...@iib.uam.es >>> >>> http://ligarto.org/rdiaz >>> >>> ___ >>> Bioc-devel@r-project.org mailing list >>> https://stat.ethz.ch/mailman/listinfo/bioc-devel >> >> [[alternative HTML version deleted]] >> >> ___ >> Bioc-devel@r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/bi
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
On Thu, Aug 18, 2016 at 4:45 PM, Wolfgang Huber wrote: > > >> On 17 Aug 2016, at 13:02, 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. > > 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. > > For (c), I suppose changing R would be handy. Or BiocStyle? Just a quick background: I was the one adjusting a large chunk of the vignette code for R 3.0.0 (Feb-March 2013) in order to add support for generic vignette engines after Yihui Xie and Duncan Murdoch had laid the groundwork adding support for knitr. When doing this I did think about supporting multiple weave output formats (and also keeping intermediate TeX / Markdown / ... files). What I can recall from this is that it shouldn't be too hard to do this. The reason why it wasn't done was mostly due to the fact that it would require an agreement by others / R core and time was very short (just before the R 3.0.0 release) so updates were kept at a minimum. Wolfgang, to answer you question: In my previous reply, I was focusing on the R CMD build process itself because that's where most of the action is happening when it comes to building vignettes, but there're other parts that need to be updated as well. But the core of the issue here is that R, or more precisely the tools package, assumes there should be exactly one output product per vignette. For instance, in tools:::find_vignette_product () [https://github.com/wch/r-source/blob/trunk/src/library/tools/R/Vignettes.R#L80-L84] we have checks like: if (length(output) > 2L || (final && length(output) > 1L)) stop(gettextf("Located more than one %s output file (by engine %s) for vignette with name %s: %s", sQuote(by), sQuote(sprintf("%s::%s", engine$package, engine$name)), sQuote(name), paste(sQuote(output), collapse=", ")), domain = NA) where 'output' holds any matching *.pdf and *.html file (and final = TRUE). (In my previous comment I said duplicated outputs would be ignored, but it seems that there'll be an error instead). There is also an internal vignette "meta data" data frame holding the vignette name, title, weave and tangle output files (or something like that). The weave output field is a character vector of one element per vignette. This data frame is used in several places. This has to be updated such that it can hold more than one weave output file per vignette, i.e. something like meta$weave[[idx]] should be able to hold one or more strings. Then functions / mechanisms that make use of this meta data need to be adjusted, e.g. vignettes(), vignette(), functions to build the vignette index HTML page etc. There's probably needs to be new features added, e.g. what format should be opened by default when calling vignette()? So, again, I think this is fairly straightforward to implement, but the first step is to convince R core that this should be done. I think one strong argument is that PDF alone is a rather bad format for screen readers while HTML is a much better in this sense. One could also imagine vignette engines that are designed to provide highly screen-reader friendly output files / formats in addition to the standard HTML / PDF formats. This raises the question whether R should do this or if that's better left to other software convert this from the HTML file. On the other hand, maybe the HTML file doesn't contain all necessary information and it's better to wor
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
On Fri, 19-08-2016, at 15:41, Sean Davis wrote: >> On Aug 19, 2016, at 9:10 AM, Ramon Diaz-Uriarte wrote: >> >> >> >> >> On Wed, 17-08-2016, at 15:08, Sean Davis wrote: On Aug 17, 2016, at 8:55 AM, Martin Morgan 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 mny 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; 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" 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. >> >> >>
Re: [Bioc-devel] Is it OK for Rmd package vignettes to be rendered as PDF?
On Mon, Aug 22, 2016 at 5:29 AM, Ramon Diaz-Uriarte wrote: > > > > On Fri, 19-08-2016, at 15:41, Sean Davis wrote: > >> On Aug 19, 2016, at 9:10 AM, Ramon Diaz-Uriarte > wrote: > >> > >> > >> > >> > >> On Wed, 17-08-2016, at 15:08, Sean Davis wrote: > On Aug 17, 2016, at 8:55 AM, Martin Morgan < > martin.mor...@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 mny 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-