Re: [Rd] vignettes present in 2 folders or won't work

[Georgi Boshnakov]

From: Duncan Murdoch 
To: Mark van der Loo 
Cc: Dirk Eddelbuettel , r-devel



Further to Duncan's comments:

> It would be nice if the documents in inst/doc were linked to on the CRAN 
> landing page of a package. I think that documents under inst/doc are a 
> bit hard to find if package authors do not create (possibly many) links 
> to them in Rd files or vignettes.

There is the seemingly underused option "package" of help():

help(package = "pkgname", help_type = "html")

The vignettes and other documents (including sources of vignettes, etc) are at 
the top of the html page (help_type is used in case the default for help is 
text format, when the output is less convenient in this case). 

What is shown can be customised by a custom index.tml under inst/doc (described 
in WRE).  An inconvenience for users of devtools::check()  is that it wipes out 
inst/doc (but it does ask for confirmation).


Georgi Boshnakov



--

Message: 12
Date: Mon, 2 Nov 2020 05:22:02 -0500
From: Duncan Murdoch 
To: Mark van der Loo 
Cc: Dirk Eddelbuettel , r-devel
    
Subject: Re: [Rd] vignettes present in 2 folders or won't work
Message-ID: <92e51613-b647-5d72-793a-dd64e0eda...@gmail.com>
Content-Type: text/plain; charset="utf-8"; Format="flowed"

On 02/11/2020 4:07 a.m., Mark van der Loo wrote:
> 
> 
> On Sun, Nov 1, 2020 at 10:39 PM Duncan Murdoch  <mailto:murdoch.dun...@gmail.com>> wrote:
> 
> 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
> 
> 
> It would be nice if the documents in inst/doc were linked to on the CRAN 
> landing page of a package. I think that documents under inst/doc are a 
> bit hard to find if package authors do not create (possibly many) links 
> to them in Rd files or vignettes.

What I'd suggest is that you write a "browseDocs" function that displays 
them in some nice format (similar to "browseVignettes").  Maybe CRAN 
would choose to add a new category listing its results, but at a 
minimum, you could very easily add a vignette called "Other documents" 
that contains a list of links.   It wouldn't be as prominent as 
"Vignettes" on CRAN, but you could make the display as prominent as you 
want on your own web page.

Duncan Murdoch




--

Subject: Digest Footer

___
R-devel@r-project.org mailing list  DIGESTED
https://stat.ethz.ch/mailman/listinfo/r-devel


--

End of R-devel Digest, Vol 213, Issue 1
***
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Duncan Murdoch]

On 02/11/2020 4:07 a.m., Mark van der Loo wrote:



On Sun, Nov 1, 2020 at 10:39 PM Duncan Murdoch > wrote:


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


It would be nice if the documents in inst/doc were linked to on the CRAN 
landing page of a package. I think that documents under inst/doc are a 
bit hard to find if package authors do not create (possibly many) links 
to them in Rd files or vignettes.


What I'd suggest is that you write a "browseDocs" function that displays 
them in some nice format (similar to "browseVignettes").  Maybe CRAN 
would choose to add a new category listing its results, but at a 
minimum, you could very easily add a vignette called "Other documents" 
that contains a list of links.   It wouldn't be as prominent as 
"Vignettes" on CRAN, but you could make the display as prominent as you 
want on your own web page.


Duncan Murdoch

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Mark van der Loo]

On Sun, Nov 1, 2020 at 10:39 PM Duncan Murdoch 
wrote:

> 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
>
>
It would be nice if the documents in inst/doc were linked to on the CRAN
landing page of a package. I think that documents under inst/doc are a bit
hard to find if package authors do not create (possibly many) links to them
in Rd files or vignettes.

Cheers,
Mark

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Duncan Murdoch]

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

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Spencer Graves]

	  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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel


__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel


__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Dirk Eddelbuettel]

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 | e...@debian.org

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Ben Bolker]

  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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel


__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Duncan Murdoch]

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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Alexandre Courtiol]

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.

Many thanks

On Sun, 1 Nov 2020 at 18:19, Duncan Murdoch 
wrote:

> You are doing a lot of things that are non-standard, so I doubt if
> anyone is going to be able to help you without access to a simple
> reproducible example of a package that does what you do.  Try to cut out
> as much as you can to make it minimal.  For example,
> devtools::document() (indeed, most of your code) is probably irrelevant
> to your problem with vignettes, but things like your .Rbuildignore file
> are not.
>
> Duncan Murdoch
>
> On 01/11/2020 11:22 a.m., Alexandre Courtiol wrote:
> > Dear all,
> >
> > I am struggling with an issue related to static vignettes: they work, but
> > only when present in double in the tarball -- in the folder inst/doc and
> > vignettes; see below for details.
> >
> > Details:
> >
> > I am pre-compiling heavy vignettes thanks to the vignette builder R.rsp.
> > So basically, I have PDF files which I want the package to use as
> Vignettes.
> >
> > For this, I have the following in my Description file:
> > VignetteBuilder: R.rsp
> >
> > I am organising the vignette by hand using a Makefile (because this is
> the
> > only way that has proven 100% reliable to me, across a variety of
> > situations).
> >
> > In my Makefile, I have something like:
> >
> > build: clean
> >mkdir -p inst/doc
> >mkdir vignettes
> >-cp sources_vignettes/*/*.pdf* vignettes
> >Rscript -e "tools::compactPDF(paths = 'vignettes', gs_quality =
> > 'printer')"
> >cp vignettes/*.pdf* inst/doc
> >Rscript -e "devtools::document()"
> >mkdir inst/extdata/sources_vignettes
> >cp sources_vignettes/*/*.Rnw inst/extdata/sources_vignettes
> >Rscript -e "devtools::build(vignettes = FALSE)"
> >
> > That works fine, the vignettes show up using browseVignettes() after
> > installing the package the normal way.
> >
> > However, after building, the tar.gz contains each pdf corresponding to a
> > vignette twice: once in vignettes and once in inst/doc (which is obvious,
> > when reading the Makefile).
> >
> >  From the reading of "Writing R Extensions" and other material, I cannot
> > tell if that is a must or not, but I hope it is not since I wish to avoid
> > that (my pdfs are large even once compressed).
> >
> > My problem is that when I delete either inst/doc or vignette just before
> > calling the last command of the Makefile (Rscript -e
> > "devtools::build(vignettes = FALSE)"), then browseVignettes() does not
> find
> > the vignettes after a normal installation.
> >
> > If anyone knows of some _complete_ documentation about the ever
> troublesome
> > topic of vignettes building in R, I would be very grateful too...
> >
> > Many thanks!
> >
> > Alex
> >
>
>

-- 
Alexandre Courtiol

http://sites.google.com/site/alexandrecourtiol/home

*"Science is the belief in the ignorance of experts"*, R. Feynman

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] vignettes present in 2 folders or won't work

[Duncan Murdoch]

You are doing a lot of things that are non-standard, so I doubt if 
anyone is going to be able to help you without access to a simple 
reproducible example of a package that does what you do.  Try to cut out 
as much as you can to make it minimal.  For example, 
devtools::document() (indeed, most of your code) is probably irrelevant 
to your problem with vignettes, but things like your .Rbuildignore file 
are not.


Duncan Murdoch

On 01/11/2020 11:22 a.m., Alexandre Courtiol wrote:

Dear all,

I am struggling with an issue related to static vignettes: they work, but
only when present in double in the tarball -- in the folder inst/doc and
vignettes; see below for details.

Details:

I am pre-compiling heavy vignettes thanks to the vignette builder R.rsp.
So basically, I have PDF files which I want the package to use as Vignettes.

For this, I have the following in my Description file:
VignetteBuilder: R.rsp

I am organising the vignette by hand using a Makefile (because this is the
only way that has proven 100% reliable to me, across a variety of
situations).

In my Makefile, I have something like:

build: clean
   mkdir -p inst/doc
   mkdir vignettes
   -cp sources_vignettes/*/*.pdf* vignettes
   Rscript -e "tools::compactPDF(paths = 'vignettes', gs_quality =
'printer')"
   cp vignettes/*.pdf* inst/doc
   Rscript -e "devtools::document()"
   mkdir inst/extdata/sources_vignettes
   cp sources_vignettes/*/*.Rnw inst/extdata/sources_vignettes
   Rscript -e "devtools::build(vignettes = FALSE)"

That works fine, the vignettes show up using browseVignettes() after
installing the package the normal way.

However, after building, the tar.gz contains each pdf corresponding to a
vignette twice: once in vignettes and once in inst/doc (which is obvious,
when reading the Makefile).

 From the reading of "Writing R Extensions" and other material, I cannot
tell if that is a must or not, but I hope it is not since I wish to avoid
that (my pdfs are large even once compressed).

My problem is that when I delete either inst/doc or vignette just before
calling the last command of the Makefile (Rscript -e
"devtools::build(vignettes = FALSE)"), then browseVignettes() does not find
the vignettes after a normal installation.

If anyone knows of some _complete_ documentation about the ever troublesome
topic of vignettes building in R, I would be very grateful too...

Many thanks!

Alex



__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

[Rd] vignettes present in 2 folders or won't work

[Alexandre Courtiol]

Dear all,

I am struggling with an issue related to static vignettes: they work, but
only when present in double in the tarball -- in the folder inst/doc and
vignettes; see below for details.

Details:

I am pre-compiling heavy vignettes thanks to the vignette builder R.rsp.
So basically, I have PDF files which I want the package to use as Vignettes.

For this, I have the following in my Description file:
VignetteBuilder: R.rsp

I am organising the vignette by hand using a Makefile (because this is the
only way that has proven 100% reliable to me, across a variety of
situations).

In my Makefile, I have something like:

build: clean
  mkdir -p inst/doc
  mkdir vignettes
  -cp sources_vignettes/*/*.pdf* vignettes
  Rscript -e "tools::compactPDF(paths = 'vignettes', gs_quality =
'printer')"
  cp vignettes/*.pdf* inst/doc
  Rscript -e "devtools::document()"
  mkdir inst/extdata/sources_vignettes
  cp sources_vignettes/*/*.Rnw inst/extdata/sources_vignettes
  Rscript -e "devtools::build(vignettes = FALSE)"

That works fine, the vignettes show up using browseVignettes() after
installing the package the normal way.

However, after building, the tar.gz contains each pdf corresponding to a
vignette twice: once in vignettes and once in inst/doc (which is obvious,
when reading the Makefile).

>From the reading of "Writing R Extensions" and other material, I cannot
tell if that is a must or not, but I hope it is not since I wish to avoid
that (my pdfs are large even once compressed).

My problem is that when I delete either inst/doc or vignette just before
calling the last command of the Makefile (Rscript -e
"devtools::build(vignettes = FALSE)"), then browseVignettes() does not find
the vignettes after a normal installation.

If anyone knows of some _complete_ documentation about the ever troublesome
topic of vignettes building in R, I would be very grateful too...

Many thanks!

Alex

-- 
Alexandre Courtiol

http://sites.google.com/site/alexandrecourtiol/home

*"Science is the belief in the ignorance of experts"*, R. Feynman

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel