[Rd] escaping 'comment' chars in example sections

[Duncan Murdoch]

Antonio, Fabio Di Narzo wrote:
> Dear list,
> I've noticed that, when writing examples in an Rd file, you need to
> escape the '%' character, even if it is valid R code.
> I can see maybe this is the intended behaviour, but I found it a bit
> surprising, and leads to cryptic error messages from 'R CMD check'.
> The relevant section in the "writing R extensions" manual isn't clear
> on that point either.
>   

It says "... Comments run from a percent symbol % to the end of the line 
in all types of text (as on the first line of the load example).

Because backslashes, braces and percent symbols have special meaning, to 
enter them into text sometimes requires escapes using a backslash. In 
general balanced braces do not need to be escaped, but percent symbols 
always do. For the complete list of macros and rules for escapes, see 
“Parsing Rd files”. "

I think that is clear on percent symbols. The situation for backslashes 
and braces is more complicated, and you need to follow the link for 
those rules.

Duncan Murdoch
> To reproduce the behaviour I'm talking about, you can run this snippet:
> ##
> library(tools)
> Rd2ex(parse_Rd(textConnection("
> \\title{a}
> \\name{b}
> \\examples{
> 'a' %in% letters
> }
> ")))
> ##
> You can see that everything from '%' on is dropped from the output, as
> a regular Rd comment. Should this be mentioned in the manual?
>
> cheers,
> fabio.
>
>   
>> R.version
>>     
>                _
> platform       x86_64-unknown-linux-gnu
> arch           x86_64
> os             linux-gnu
> system         x86_64, linux-gnu
> status         Patched
> major          2
> minor          11.0
> year           2010
> month          05
> day            19
> svn rev        52043
> language       R
> version.string R version 2.11.0 Patched (2010-05-19 r52043)
>