From hornik at ci.tuwien.ac.at  Sun May 25 22:22:10 2003
From: hornik at ci.tuwien.ac.at (Kurt Hornik)
Date: Sun May 25 23:06:20 2003
Subject: [Rd] Interpretation of escaped characters in \examples{}
In-Reply-To: <5.2.0.9.1.20030524191550.00ac35c0@imaphost.wehi.edu.au>
References: <5.2.0.9.1.20030524191550.00ac35c0@imaphost.wehi.edu.au>
Message-ID: <16081.6114.772360.84685@mithrandir.hornik.net>

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


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