From murdoch@dunc@n @end|ng |rom gm@||@com  Mon Nov  2 11:22:02 2020
From: murdoch@dunc@n @end|ng |rom gm@||@com (Duncan Murdoch)
Date: Mon, 2 Nov 2020 05:22:02 -0500
Subject: [Rd] vignettes present in 2 folders or won't work
In-Reply-To: <CAOKDuOjXytZnPFbrsq_P-z61e3uZPTRG=JDHi1p7WWoxbpH=AQ@mail.gmail.com>
References: <CAERMt4eKagsBYjGRbJOJugWgB03b0QeenJMSdRwbXcy0qqxCMA@mail.gmail.com>
 <aed3b504-93f0-fc77-3bc3-5c7b7286286b@gmail.com>
 <CAERMt4eknfdoHjgxN9gCbHeQ=odtO_YargCWNK=Ntsuv5HbyhQ@mail.gmail.com>
 <6c01a1ec-9846-e906-d46f-1175c866c4f1@gmail.com>
 <18624aa0-215e-3afe-28bd-d450a3bae725@gmail.com>
 <24479.4908.672903.801397@rob.eddelbuettel.com>
 <e271b365-a2cf-488a-b316-f89e7b46e885@gmail.com>
 <CAOKDuOjXytZnPFbrsq_P-z61e3uZPTRG=JDHi1p7WWoxbpH=AQ@mail.gmail.com>
Message-ID: <92e51613-b647-5d72-793a-dd64e0edac3c@gmail.com>

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



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