[R-pkg-devel] Fwd: Load data inside .Rd documentation file inside the item-field?

[Duncan Murdoch]

Whoops, forgot to cc the list.


-------- Forwarded Message --------
Subject: Re: [R-pkg-devel] Load data inside .Rd documentation file 
inside the item-field?
Date: Tue, 3 May 2022 06:07:01 -0400
From: Duncan Murdoch <murdoch.duncan using gmail.com>
To: Vincent van Hees <vincentvanhees using gmail.com>

On 03/05/2022 5:50 a.m., Vincent van Hees wrote:
> Dear list,
> 
> Is it possible in .Rd documentation to load and use data inside an
> item-field like we can integrate R data in text in R markdown files?
> 
> Something along the lines of:
> \item{max}{
>    Numeric, default value = `R max`, controls the upper limit of the plot.
> }
> where `R max` resolves into the actual default value.
> 
> I am guessing this is not possible, but it would be great if someone could
> either confirm or point me to the actual way to do this.

It is possible to execute R code and display the results on the help 
page.  You'll need to be able to compute the value you want to display. 
   Supposing "max" is the name of a parameter to function "fn" in 
package "pkg", the default value is

      formals(pkg::fn)[["max"]]

You insert this into the help page using syntax

      \Sexpr{formals(pkg::fn)[["max"]]}

which will apply `as.character()` to it (I think, though maybe it's 
format() ...) and insert the text there.

This is executed when the package installs.  I believe you'll already 
have the code installed so this runs the new installation, but you 
should check:  it might show you the default from a previous install.

You can also run the code when you build the tarball, using

       \Sexpr[stage=build]{formals(pkg::fn)[["max"]]}

in which case it will use whatever version of pkg happens to be 
installed on your system at the time of the build, not necessarily the 
one you are building.

Or finally, you could use

       \Sexpr[stage=render]{formals(pkg::fn)[["max"]]}

which won't run the code until the user asks to display the help page.

For more details and options, see Writing R Extensions section 2.12, 
"Dynamic pages".

Duncan Murdoch