[R] Link from vignette to package documentation

[Duncan Murdoch]

On 22/09/2018 4:14 AM, Martin Maechler wrote:
>>>>>> Duncan Murdoch
>>>>>>      on Fri, 21 Sep 2018 05:02:32 -0400 writes:
> 
>      > On 21/09/2018 4:54 AM, Sigbert Klinke wrote:
>      >> Hi,
>      >>
>      >> is it possible to make a link from a vignette to a (Rd)
>      >> help files in my own or other packages?
> 
>      > Only with some significant compromises.  R normally acts
>      > as the web server for Rd files, and the URL is not really
>      > predictable.  So you would need to make the URL
>      > predictable, either by something like
> 
>      > options(help.ports = 12345)
> 
>      > (which will put help on port 12345, blocking that port for
>      > any other use, including help in another R session), or by
>      > putting a static copy of the help pages on some other web
>      > server.
> 
>      > Duncan Murdoch
> 
> Yes, and the other way around -- making working links from
> package (*.Rmd or *.Rnw) vignettes to help pages of the same
> package is also not easily and portably possible AFAICS.

Actually I was overly pessimistic above.  If both the vignette and the 
help page are being viewed in a web browser, it should be possible using 
relative links.

My rgl package does this:  the "rgl Overview" vignette is written in R 
Markdown and displayed in HTML.  It has links to the help pages.  There 
are some limitations:  the links only work while the same R session is 
running.

To make a link to help topic "points3d", it inserts code that produces 
the anchor

<a href="../../rgl/help/points3d">`points3d`</a>

in the text.  (It should also work to replace the prefix "../../rgl/" 
with just "../", but the longer path allows for links to help pages in 
other packages.)

This won't work if you are looking at the vignette somewhere else (e.g. 
at https://cran.r-project.org/web/packages/rgl/vignettes/rgl.html).

Duncan Murdoch


> 
> Both would be desirable quite desirable for improved R
> documentation and ideally so in a way that could also work with
> an internet connection.
> 
> [and if we continue this, it may become more of an issue for
> 'R-devel' instead of 'R-help' ...]
> 
> Martin Maechler
>