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

[Carl Schwarz]

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


On Tue, May 31, 2022 at 7:50 AM Max Turgeon <Max.Turgeon using umanitoba.ca>
wrote:

> Hi Carl and Ivan,
>
> According to WRE Section 1.4, you may be able to override what
> tools:::.build_vignette_index creates:
>
> "At install time an HTML index for all vignettes in the package is
> automatically created from the \VignetteIndexEntry statements unless a file
> index.html exists in directory inst/doc. This index is linked from the HTML
> help index for the package."
>
> Unfortunately, I have no experience writing my own inst/doc/index.html.
> Maybe someone else on this list can provide some pointers.
>
> Best,
>
> Max Turgeon <https://www.name-coach.com/maxime-turgeon>
> Assistant Professor
>
> Department of Statistics
> University of Manitoba
>
> maxturgeon.ca
> ------------------------------
> *From:* R-package-devel <r-package-devel-bounces using r-project.org> on behalf
> of Ivan Krylov <krylov.r00t using gmail.com>
> *Sent:* Tuesday, May 31, 2022 2:05 AM
> *To:* Carl Schwarz <cschwarzstatsfuca using gmail.com>
> *Cc:* r-package-devel using r-project.org <r-package-devel using r-project.org>
> *Subject:* Re: [R-pkg-devel] Sort order of vignette index?; adding
> purl'ed Rcode from asis vignette to vignette index?
>
> ********************************************************
> Caution: This message was sent from outside the University of Manitoba.
> ********************************************************
>
> On Mon, 30 May 2022 18:10:28 -0700
> Carl Schwarz <cschwarzstatsfuca using gmail.com> wrote:
>
> > I'm hoping that a simple modification to devtool::build_vignettes()
> > might be the place to start, but don't know enough of the fine
> > details of package building on CRAN to know if this is the place.
>
> devtools is an unofficial package, separate from the package build
> machinery.
>
> The HTML vignette index for a package is contained in the
> (library)/(package)/doc/index.html file and is generated during package
> installation. The table itself is generated by
> tools:::makeVignetteTable, with no sort criterion applied. According to
> the comments in tools:::.install_package_vignettes3, R ≥ 3.0.2
> generates the vignette index at package build time. The vignette index
> is built by tools:::.build_vignette_index, again, with no sorting, from
> the output of tools::pkgVignettes.
>
> pkgVignettes() seems to loop over vignette engines, then over file name
> patterns accepted by every vignette engine. A sorting step could be
> added after the loop, but I'm not sure how to expose the sorting
> criterion as an API. Time to ask about this on the R-devel mailing list?
>
> As for locating the purl'ed scripts, you might be able to convince
> pkgVignettes() to locate them for you if you rename and place them the
> right way (you say doc/; shouldn't it be inst/doc?). Take a look at how
> pkgVignettes calls tools:::find_vignette_product and what the latter
> function does. But I might be wrong.
>
> --
> Best regards,
> Ivan
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]