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

[Carl Schwarz]

Here is some suggested text to be added to the Writing R Extensions manual.
Any suggestions for changes?

1.4.3. Customizing the vignette help index

R provides two indices to the vignettes in a package  (a) the
browseVignettes() function and (b) the html index of vignettes and other
user documentation available when you use help(package=xxx). The latter is
built when the package is installed.



In some cases, customization of the html index is desirable. For example,
currently the entries in the index  are sorted by the vignette engine used
to build the vignette and then by the file name of the vignette and a
different sort order may be desired. Or additional documents may wish to be
included, e.g., the purl()’d code from an “asis” vignette.



Previous sections of this guide indicate that if an “index.html” file is
present in the inst/doc directory at the time of the build, then a new
“index.html” file will not be built. Previous sections also indicate how to
add additional files to the inst/doc directory. The following is then a
summary of the steps needed to customize the html index to the vignettes in
a package.



1. Create a revised ‘index.html’ file in the vignettes directory. It may be
easiest to copy an existing ‘doc/index.html’ file from an installed
package. The vignettes/index.html file should be in plain html and can be
modified to change the sort order or to add links to additional files to be
available to users. Note that files are referred to using relative path
names – follow the pattern in the copied file.



2. Add any other additional files to the vignettes directory that are to be
available to the user via the vignette help index.



3. Add an ‘.install_extras’ file to the vignettes directory (don’t forget
the leading period in this file’s name). This is a text file with the names
of the files in the vignettes directory to be added to the inst/doc
directory. Each line can be coded as a regular expression. At a minimum,
include ‘index.html’ to copy the vignettes/index.html file to the inst/doc
directory.



4. Check/build the package in the regular way.



There is no evident way to modify the output of the browseVignettes()
function; however, this function currently sorts by the vignette file name
regardless of the vignette engine used.

On Wed, Jun 1, 2022 at 1:04 AM Martin Maechler <maechler using stat.math.ethz.ch>
wrote:

> >>>>> 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)
>

	[[alternative HTML version deleted]]