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

Duncan Murdoch murdoch@dunc@n @end|ng |rom gm@||@com
Mon Nov 2 11:22:02 CET 2020

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 using gmail.com 
> <mailto:murdoch.duncan using 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

More information about the R-devel mailing list