I take Duncan's point but would second the motion to have WRE clarify how static vignettes are supposed to work; it's a topic I am repeatedly confused about despite being an experienced package maintainer. If knowledgeable outsiders compiled a documentation patch would it be likely to be considered ...?? On 11/1/20 2:29 PM, Duncan Murdoch wrote:> On 01/11/2020 1:02 p.m., Alexandre Courtiol wrote: >> Noted Duncan and TRUE... >> >> I cannot do more immediately unfortunately, that is always the issue >> of asking a last minute panic attack question before teaching a course >> involving the package... >> I do have /doc in my .Rbuildignore for reasons I can no longer >> remember... I will dig and create a MRE/reprex. >> The students will download heavy packages, but they probably won't >> notice. >> *Apologies* >> >> In the meantime, perhaps my question was clear enough to get clarity on: >> 1) whether having vignettes twice in foders inst/doc and vignettes is >> normal or not when vignettes are static. >> 2) where could anyone find a complete documentation on R vignettes >> since it is a recurring issue in this list and elsewhere. > > The Writing R Extensions manual describes vignette support in R, but R > allows contributed packages (like knitr, rmarkdown, R.rsp) to handle > vignettes.? WRE explains enough to write such a package, but it's up to > their authors to document how to use them, so "complete documentation" > is spread out all over the place.? As with any documentation, there are > probably errors and omissions. > > Duncan Murdoch > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel
The closest to a canonical reference for a static vignette is the basic blog
post by Mark at
https://www.markvanderloo.eu/yaRb/2019/01/11/add-a-static-pdf-vignette-to-an-r-package/
which I follow in a number of packages.
Back to the original point by Alexandre: No, I do _not_ think we can do
without a double copy of the _pre-made_ pdf ("input") and the
_resulting_ pdf
("output").
That bugs me a little too but I take it as a given as static / pre-made
vignettes are non-standard (given lack of any mention in WRE, and the pretty
obvious violation of the "spirit of the law" of vignette which is
after all
made to run code, not to avoid it). Yet uses for static vignettes are pretty
valid and here we are with another clear as mud situation.
Dirk
--
https://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
CRAN policies say, "neither data nor documentation should exceed 5MB (which covers several books). A CRAN package is not an appropriate way to distribute course notes, and authors will be asked to trim their documentation to a maximum of 5MB."[1] I post R Markdown vignettes as companions to Wikiversity articles. For example, the Wikiversity article on "Forecasting nuclear proliferation" is a tech report on the indicated topic with two R Markdown vignettes as part of an appendix.[2] Wikiversity is similar to Wikipedia but supports teaching materials and original research, which are forbidden on Wikipedia. Both are projects of the Wikimedia Foundation and have very similar rules and management. For both, almost anybody can change almost anything. What stays tends to be written from a neutral point of view citing credible sources. If you don't do that, your work may be speedily deleted or reverted. Shi et al (2017) "The wisdom of polarized crowds" did a content analysis of all edits to English Wikipedia articles relating to politics, social issues and science from its start to December 1, 2016. This included almost 233,000 articles representing approximately 5 percent of the English Wikipedia. They found that the best articles had a large number of editors with a very diverse views. They said that 95% of articles could benefit from greater conflict; the conflict became counterproductive in only about 5% of articles.[3] Spencer Graves [1] https://cran.r-project.org/web/packages/policies.html [2] https://en.wikiversity.org/wiki/Forecasting_nuclear_proliferation#Appendix._Companion_R_Markdown_vignettes [3] https://en.wikipedia.org/wiki/Reliability_of_Wikipedia#Articles_on_contentious_issue On 2020-11-01 13:35, Ben Bolker wrote:> ? I take Duncan's point but would second the motion to have WRE clarify > how static vignettes are supposed to work; it's a topic I am repeatedly > confused about despite being an experienced package maintainer. If > knowledgeable outsiders compiled a documentation patch would it be > likely to be considered ...?? > > On 11/1/20 2:29 PM, Duncan Murdoch wrote: >> On 01/11/2020 1:02 p.m., Alexandre Courtiol wrote: >>> Noted Duncan and TRUE... >>> >>> I cannot do more immediately unfortunately, that is always the issue >>> of asking a last minute panic attack question before teaching a >>> course involving the package... >>> I do have /doc in my .Rbuildignore for reasons I can no longer >>> remember... I will dig and create a MRE/reprex. >>> The students will download heavy packages, but they probably won't >>> notice. >>> *Apologies* >>> >>> In the meantime, perhaps my question was clear enough to get clarity on: >>> 1) whether having vignettes twice in foders inst/doc and vignettes is >>> normal or not when vignettes are static. >>> 2) where could anyone find a complete documentation on R vignettes >>> since it is a recurring issue in this list and elsewhere. >> >> The Writing R Extensions manual describes vignette support in R, but R >> allows contributed packages (like knitr, rmarkdown, R.rsp) to handle >> vignettes.? WRE explains enough to write such a package, but it's up >> to their authors to document how to use them, so "complete >> documentation" is spread out all over the place.? As with any >> documentation, there are probably errors and omissions. >> >> Duncan Murdoch >> >> ______________________________________________ >> R-devel at r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-devel > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel
On 01/11/2020 2:57 p.m., Dirk Eddelbuettel wrote:> > The closest to a canonical reference for a static vignette is the basic blog > post by Mark at > > https://www.markvanderloo.eu/yaRb/2019/01/11/add-a-static-pdf-vignette-to-an-r-package/ > > which I follow in a number of packages. > > Back to the original point by Alexandre: No, I do _not_ think we can do > without a double copy of the _pre-made_ pdf ("input") and the _resulting_ pdf > ("output"). > > That bugs me a little too but I take it as a given as static / pre-made > vignettes are non-standard (given lack of any mention in WRE, and the pretty > obvious violation of the "spirit of the law" of vignette which is after all > made to run code, not to avoid it). Yet uses for static vignettes are pretty > valid and here we are with another clear as mud situation. >In many cases such files aren't vignettes. By definition, packages should contain plain text source code for vignettes. They can contain other PDF files in inst/doc, but if you don't include the plain text source, those aren't vignettes. An exception would be a package that contains the source code but doesn't want to require CRAN or other users to run it, because it's too time-consuming, or needs obscure resources. The CRAN policy discusses this. Duncan Murdoch