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
On Sun, Nov 1, 2020 at 10:39 PM Duncan Murdoch <murdoch.duncan at 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. Cheers, Mark [[alternative HTML version deleted]]
On 02/11/2020 4:07 a.m., Mark van der Loo wrote:> > > On Sun, Nov 1, 2020 at 10:39 PM Duncan Murdoch <murdoch.duncan at gmail.com > <mailto:murdoch.duncan at 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