Links between help pages and vignettes

[dmurdoch]

Summary: I suggest adding two environment variables to facilitate links between help pages and vignettes.

Background:

I'm currently revising documentation in rgl, and want to improve the links from vignettes to help pages and from help pages to vignettes, all in HTML format.

The big problem here is that the directories holding the .html files have different names in different contexts. R dynamic help puts help files in ../<pkg>/html and vignettes in ../<pkg>/doc, while pkgdown puts help files in ../<pkg>[/dev]/reference and vignettes in ../<pkg>[/dev]/articles. CRAN puts vignettes in ../<pkg>/vignettes. (I don't think CRAN currently hosts the help pages in HTML format, but they're thinking about it. All help pages are in the big PDF reference manual.)

My current attempt at a solution uses a function in vignettes and a user macro in help files to construct the link, and uses environment variables to tell them what names to use. You can see the latest version of the macro here:

https://github.com/dmurdoch/rgl/blob/master/man/macros/macros.Rd

The two environment variables I've used are

• VignetteRdPath: The path to HTML versions of Rd files as seen from a vignette.
• RdVignettePath: The path to vignettes as seen from an HTML help file.

For pkgdown, I use these definitions in my pkgdown.yaml Github action:

  RdVignettePath: ../articles/
  VignetteRdPath: ../reference/

Then in a vignette, the help file for plot3d would be expanded to ../reference/plot3d.html, and in a help page the rgl vignette link would expand to ../articles/rgl.html.

A more general scheme would use sprintf() fmt strings instead of prefixes to the HTML filename. [EDIT HERE]: I tried that and then switched to this simpler scheme because I suspected a bug somewhere, but I haven't been able to reproduce it today. But in any case, I don't know of examples that need sprintf().

So my suggestion is that pkgdown should define these environment variable definitions into the pkgdown.yaml action or into the Rd and vignette processing code, and then other packages could automatically make use of this scheme. I'm happy to discuss other names or other ways to specify these paths.