[R-pkg-devel] [Rd] static html vignette

[Uwe Ligges]

On 04.01.2024 21:23, Duncan Murdoch wrote:
> On 04/01/2024 11:43 a.m., Adrian Dușa wrote:
>  > (Moved here following Ivan's suggestion)
>  >
>  > On Thu, Jan 4, 2024 at 12:55 PM Ivan Krylov <krylov.r00t using gmail.com> 
> wrote:
>  >
>  >> On Thu, 4 Jan 2024 11:57:15 +0200
>  >> Adrian Dușa <dusa.adrian using gmail.com> wrote:
>  >>
>  >>> I wonder if it would be possible to include an html static vignette.
>  >>
>  >> I would say that static vignettes are against the spirit of vignettes:
>  >> the idea is to provide another layer of unit testing to the package by
>  >> providing a deeper executable example than is possible with just Rd
>  >> examples. I think that Bioconductor will even refuse a package with a
>  >> vignette with no executable code in it.
>  >>
>  >
>  > I understand that perfectly, but for instance my package declared 
> already
>  > has over 800 tests and 100% code coverage. More unit testing in the
>  > vignettes really strikes as unnecessary.
>  >
>  > One other reason to use a static vignette, in my case, is that package
>  > Sweave is not available for my version of R (on MacOS, M2 version)
> As far as I know, there is no package called Sweave, there's just the 
> Sweave() function in the utils package.>
>  >
>  >
>  >> Still, you can ue the R.rsp package to provide static vignettes in
>  >> both PDF and HTML formats:
>  >>
>  >> 
> https://cran.r-project.org/package=R.rsp/vignettes/R_packages-Static_PDF_and_HTML_vignettes.pdf
>  >>
>  >> This will add 6 packages to your total Suggests budget:
>  >>
>  >> setdiff(
>  >>   unlist(package_dependencies('R.rsp', recursive=TRUE)),
>  >>   unlist(standard_package_names())
>  >> )
>  >> # [1] "R.methodsS3" "R.oo"        "R.utils"     "R.cache"     "digest"
>  >
>  >
>  > Yes indeed, I know about R.rsp.
>  > To me at least, zero dependency means that users install that package 
> and
>  > that package alone, the reason for which I am now looking for static
>  > (preferably html) vignettes.
>  >
>  > I guess another question is why should the "Suggests" packages need 
> to be
>  > installed by end users. I understand CRAN checks need to make sure the
>  > Vignettes can be processed and the code inside runs fine (just like the
>  > examples in the Rd files) but it is very unlikely that end-users will 
> want
>  > to compile the vignettes themselves.
>  >
>  >  From my own experience of almost 20 years of using R, I never-ever 
> build
>  > the vignettes of a certain package because it is much simpler to read 
> them
>  > on CRAN. I wonder, then, why are end users forced to install
>  > Vignette-building "Suggests" packages (with long dependency chains) when
>  > they practically never do that.
>  >
>  > Life would be much simpler if the Suggests packages would not be
>  > (automatically) installed, or if CRAN provided a way to include static
>  > Vignettes to avoid the heavy dependencies of building them.
>  >
> Users aren't forced to install "Suggests" packages.  That's a choice 
> they make.  The default for `install.packages()` is `dependencies = NA`, 
> which says to install hard dependencies (Imports, Depends, LinkingTo).
> Users have to choose a non-default setting to include Suggests.

Also note that the maintainer builds the vignette whe calling
R CMD build
CRAN checks whether the vignette can be build.
If a user installs a package, the already produced vignette (on the 
maintainers machine by R CMD build) is instaled. There is no need for 
the user to install any extra package for being able to look at the 
vignettes.

Best,
Uwe Ligges




> 
> Duncan Murdoch
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel