[Rd] R v2.10.0: Doc clarification for cross references and where are we heading?

[Duncan Murdoch]

On 24/09/2009 5:42 AM, Romain Francois wrote:
> On 09/24/2009 11:28 AM, Duncan Murdoch wrote:
>> On 23/09/2009 11:21 PM, Gabor Grothendieck wrote:
>>> On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch
>>> <murdoch at stats.uwo.ca> wrote:
>>>> - Ways to link from man pages to vignettes. The reverse would be
>>>> nice, but
>>>> it's not possible with the current design, so that would be far off.
>>>>
>>> If feasible I would like to be able to link to any text, html or pdf
>>> file in the package. For example, it would be nice to be able to link
>>> to the NEWS file and pdf files that are included in the package even
>>> if they are not vignettes, etc.
>> The \Sexpr mechanism probably allows this, though there are currently no
>> built-in support functions to help you get there. As I mentioned, that
>> could all be done by code in a contributed package.
>>
>> One way would be to have one help page which contains only
>>
>> \Sexpr[stage=render, results=rd]{generatePage()}
>>
>> and it will be 100% generated at render time, containing whatever you
>> want it to contain. (Presumably you'll have some way to communicate what
>> you want through variables that generatePage() can see.) Each time you
>> link to it you'll see something different.
>>
>> Duncan Murdoch
> 
> Brilliant. Thanks. That solves my question as well.
> 
> I did not see results = documented in ?Rd2HTML, what is allowed ?
> Is \Sexpr ignored when rendering other formats (tex, ...) ?
> or is there a way (similar to #ifdef) to only provide some content to 
> some renderers ?

As of yesterday, it's documented in Writing R Extensions.  \Sexpr is 
format-agnostic:  it doesn't output HTML, it outputs plain text which is 
wrapped in the appropriate HTML/LaTeX/whatever, or Rd input which is 
processed by the whole system.  So the generator would currently have to 
use sneaky methods to figure out the format, looking at which function 
called it, etc.  I imagine in the long run we'll define some state 
variables which the code can look at, but I'd rather see use-cases 
before deciding what those should be.

Duncan Murdoch