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

Wed, Jun 1, 2022 2:47 PM

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

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

Thread (6 messages)