R devel - May 2010 - escaping 'comment' chars in example sections

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.

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)
-- 
Antonio Fabio Di Narzo, PhD.
Swiss Institute for Bioinformatics - Bioinformatics Core Facility
Office 2029, G?nopode, Quartier Sorge
CH-1015 Lausanne, Switzerland
Tel: +41 21 692 4087
Fax: +41 21 692 4065

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)
>