From murdoch at stats.uwo.ca  Thu Sep 24 13:30:59 2009
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Thu, 24 Sep 2009 07:30:59 -0400
Subject: [Rd] R v2.10.0: Doc clarification for cross references and
 where are we heading?
In-Reply-To: <4ABB49F7.8000606@dbmail.com>
References: <59d7961d0909231908q4ba58b99gdee28c1c49ffd6bc@mail.gmail.com>	<4ABADF79.9050106@stats.uwo.ca>	<971536df0909232021k2ba884fey43ae89fb5fe474be@mail.gmail.com>
	<4ABB3BA2.3020503@stats.uwo.ca> <4ABB3F10.9040505@dbmail.com>
	<4ABB442F.4040406@stats.uwo.ca> <4ABB49F7.8000606@dbmail.com>
Message-ID: <4ABB5873.7080402@stats.uwo.ca>

On 24/09/2009 6:29 AM, Romain Francois wrote:
> On 09/24/2009 12:04 PM, Duncan Murdoch wrote:
>  >
>  > 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
> 
> Sure. One last thing, can the \Sexpr trigger some code that redirects to 
> some other page ? I suppose one could just call browseURL, but this 
> would bring another tab, ...
> 
> Do I need to depend on R >= 2.10.0  if I use \Sexpr ?

I think so.

Duncan Murdoch

> 
> Gabor, would you like to team up to generate some sort of incubator 
> package to take advantage of the new system ?
> 
> Romain
>



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