[R-pkg-devel] Sort order of vignette index?; adding purl'ed Rcode from asis vignette to vignette index?

[Martin Maechler]

>>>>> Jeff Newmiller 
>>>>>     on Tue, 31 May 2022 16:09:16 -0700 writes:

    > FWIW the RStudio build is often not complete... it intentionally takes shortcuts that make test/run iteration faster... but you should make a habit of using the command line to build artifacts for sharing... it will help avoid gotchas.

Yes, definitely.

Notably, e.g., reloading the package sources (often via
devtools) into a running R process instead of restarting R and
loading/attaching the newly built and installed package (that
you are developing) is much faster, but *NOT* equivalent and
sometimes misleading -- because it's not easily possible to
"revert" everything you did in your running R session {caches,
method tables, DLLs, internal pointers, ...}.

(read on, further down)

    > On May 31, 2022 3:53:57 PM PDT, Carl Schwarz <cschwarzstatsfuca using gmail.com> wrote:
    >> Success!
    >> 
    >> Building on MT's note that if the inst/doc has an index.html file, R does
    >> NOT build a new index.
    >> At the end of Writing R Extensions Section 1.4, it states
    >> "  When R CMD build builds the vignettes, it copies these and the vignette
    >> sources from directory vignettes to inst/doc. To install any other files
    >> from the vignettes directory, include a file vignettes/.install_extras which
    >> specifies these as Perl-like regular expressions on one or more lines.."
    >> 
    >> So I copied the existing inst/doc/index.html file from the installed
    >> SighatbilityModel with the wrong sort order to my vignettes/index.html,
    >> edited this index.html file to get the right sort order. The index.html is
    >> just vanilla html so it is easy to modify "manually".
    >> Then I created a vignettes/.install_extras with a single entry "index.html"
    >> and now vignettes/index.html appears to be copied to inst/doc and so stops
    >> the building of the wrongly sorted index.
    >> 
    >> Then I did a Rstudio -> Build -> BuildSourcePackage to create a tar.gz
    >> file; installed from the tar.gz file, and now my vignette index is sorted
    >> properly on my Mac machine.
    >> Also tried using devtools::check_win_release() to generate a windoze zip
    >> file; installed that; and the vignette index is again sorted properly on
    >> Windows machines.
    >> 
    >> I'm hoping I can use this for (b) from my original query as well.
    >> 
    >> This will mean that I have to "manually'" maintain the vignettes/index.html
    >> file, but that is straightforward.
    >> 
    >> I hope this works when I submit to CRAN.
    >> 
    >> How do I suggest to the R maintainers that an explicit section be added to
    >> the Writing R Extensions manual with the above steps so that future package
    >> writers don't repeat history? I'm willing to write the paragraph explaining
    >> the steps, but don't know who/how to proceed to get it added to Writing R
    >> Extensions.
    >> 
    >> Carl Schwarz

The WRE manual is part of the R sources, so formally you are
proposing to improve (the documentation part of) R.

You can propose a patch against the "R-devel" sources.
If the changes are quite small and compact (as here), even on by e-mail.
The source file  is  doc/manual/R-exts.texi
in R's SVN (source server)
  https://svn.r-project.org/R/trunk/doc/manual/R-exts.texi
or one of its mirrors (notably on github)