[Rd] Changes to Rd handling in R-devel

[Duncan Murdoch]

hadley wickham wrote:
> On Fri, Jun 19, 2009 at 6:12 PM, Duncan Murdoch<murdoch at stats.uwo.ca> wrote:
>   
>> I've just committed some fairly big changes to R-devel.  - There's a new tag
>> \Sexpr which allows R code to be embedded within the Rd file, similar to
>> Sweave,  \RdOpts
>>   corresponds to \SweaveOpts.
>>  - The parser now mainly issues warnings, rather than errors, in case of
>> syntax errors.  It throws away a few tokens and tries to restart.  This
>> should let you see most of your errors in one pass, rather than one at a
>> time.  (Don't ignore the warnings -- you've lost some of your file if you
>> get them!)  (Romain:  yes, this is done using the special "error" token in
>> bison.)
>>  - There are also a number of bug fixes to the rendering code (e.g.
>> Rd2HTML).  I'm hoping to switch over soon to the new parser being used to
>> produce all man pages.
>>
>> I need to write up more about \Sexpr, but the basic idea is that the format
>> is
>>
>> \Sexpr{R code}
>>
>> or
>>
>> \Sexpr[options]{R code}
>>
>> Currently the R code is not executed unless you do it manually, but once
>> we're using this engine for man pages, you'll be able to choose when to
>> execute the code:  build time, install time, or render time.
>>     
>
> Can the R code emit top-level rdoc tags? i.e. could the complete rd
> file just be \Sexpr{} ?

There are details to be worked out (and bugs to be fixed) as this is 
integrated into the build/install system, but so far I can't think of 
any reason why that would not be possible, as long as the required tags 
(e.g. \alias, \name, \title) were emitted early enough. 

The current plan is that you would use a name like foo.Rdin to indicate 
that you have code to execute before building the tarball, and the build 
system would emit a text .Rd file.  At install time that would be 
converted to a binary representation which is what would be installed, 
and the final conversion to HTML or displayed text or other rendered 
format would happen as late as possible.  (Ideally, this would be fully 
dynamic, doing the conversion when the user asks for help, but that is 
not feasible for all formats, and I'm not sure how much of the final 
implementation will be done before 2.10.0.)

Duncan Murdoch