From: Duncan Murdoch <murdoch.duncan at gmail.com>
To: Mark van der Loo <mark.vanderloo at gmail.com>
Cc: Dirk Eddelbuettel <edd at debian.org>, r-devel
<r-devel at r-project.org>
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 <murdoch.duncan at gmail.com>
To: Mark van der Loo <mark.vanderloo at gmail.com>
Cc: Dirk Eddelbuettel <edd at debian.org>, r-devel
<r-devel at r-project.org>
Subject: Re: [Rd] vignettes present in 2 folders or won't work
Message-ID: <92e51613-b647-5d72-793a-dd64e0edac3c at 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 <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
------------------------------
Subject: Digest Footer
_______________________________________________
R-devel at r-project.org mailing list DIGESTED
https://stat.ethz.ch/mailman/listinfo/r-devel
------------------------------
End of R-devel Digest, Vol 213, Issue 1
***************************************
