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

Some quick comments:

- You could place the index.html directly in the inst/doc folder of your
package sources, avoiding the need for .install_extras from the
vignettes folder. This approach is useful if there is additional
non-vignette material in inst/doc.

- As you say, links in index.html need to be relative to the installed
*doc* dir, where the index file is located. For example, the simple links
     <a href="template.R">template script</a>,
     <a href="vignetteA.Rnw">source of vignette A</a>
should work to reference a static Rscript inst/doc/template.R and a
vignette built from vignettes/vignetteA.Rnw (copied to inst/doc by R CMD
build), respectively.

- It seems you could even generate the index.html via a vignette,
index.Rmd, say. The downside is that this index vignette will be listed
as a vignette (by browseVignettes(), for example) although it isn't
really a vignette.

- browseVignettes() sorts by vignette title, not by file name.
Furthermore, its purpose is to browse *vignettes* also across packages,
so is unrelated to the *doc* index for a given package, which may
contain more than vignettes.

Best regards,

        Sebastian Meyer


Am 01.06.22 um 23:47 schrieb 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 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)

      [[alternative HTML version deleted]]