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

[Duncan Murdoch]

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.

Duncan Murdoch