[Rd] Interpretation of escaped characters in \examples{}

[Kurt Hornik]

>>>>> Gordon Smyth writes:

> I've noticed a curious interpretation of escaped characters in \examples{} 
> in .Rd files.

> For example, if I type

>      files <- dir(pattern="\\.txt")

> at the R prompt, I will get a vector containing all file names in the 
> current directory containing the string ".txt". If I put

>      \examples{ files <- dir(pattern="\\.txt") }

> in an .Rd file of a package, then the generated documentation will replace 
> my command with

>      Examples

>      files <- dir(pattern="\.txt")

> i.e., the escaped backslash has been interpreted into a single backlash. If 
> a user types example(myfun) at the R prompt, where myfun is the topic alias 
> of the .Rd file, then they will actually get

>      files <- dir(pattern=".txt")

> i.e., the backslash is interpreted a second time.

> This seems an undesirable feature. What is in the .Rd file, what is
> displayed in the online help, and what is generated by example() are
> all different commands. I had expected anything in \examples{} to be
> reproduced in the online help and by \example{} entirely literally
> with no intepretation.

> I am using R 1.7.0pat under Windows 2000 Professional.

R-exts clearly says

	   The "comment" and "control" characters `%' and `\' _always_
	need to be escaped.  Inside the verbatim-like commands (`\code'
	and `\examples'), no other(1) characters are special.  Note that
	`\file' is *not* a verbatim-like command.

-k