Re: [Rd] Changes to Rd handling in R-devel

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Sat, 20 Jun 2009 04:56:43 +0200

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

---

R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Sat 20 Jun 2009 - 03:01:11 GMT