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

[Sebastian Meyer]

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 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]]
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel