R devel - May 2003 - Interpretation of escaped characters in \examples{}

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.

Gordon
---------------------------------------------------------------------------------------
Dr Gordon K Smyth, Senior Research Scientist, Bioinformatics,
Walter and Eliza Hall Institute of Medical Research,
1G Royal Parade, Parkville, Vic 3050, Australia
Tel: (03) 9345 2326, Fax (03) 9347 0852,
Email: smyth@wehi.edu.au, www: http://www.statsci.org

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

At 05:22 AM 26/05/2003, Kurt Hornik wrote:
> >>>>> 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
Dear Kurt,

Thanks very much for this reference from the R-exts document. You don't 
address though the main point of my post, which is that the code displayed 
the online help and executed and checked by R CMD check is different from 
the code extracted and executed by the function 'example'.

Suppose I have an .Rd file for a function 'readFiles' containing the
text
'\examples{dir(pattern="\\\\.txt")}'. The quadruple-backlash
will ensure
that 'help' displays and R CMD checks the correct command 
'dir(pattern="\\.txt")'. However, if a user types
'example("readFiles")' at
the R prompt, the command that R will execute is
'dir(pattern=".txt")'.
This is *different command* and will generally give *wrong* results. There 
is no way that I can see to ensure that R CMD check and 'example'
execute
the same code.

My concern here is the with actual behavior of R rather than what R-exts 
says but, since you are emphasising the clarity of the R-exts document, it 
may be worth pointing out that R-exts also says

        \examples{...}
        Examples of how to use the function. These are set verbatim in 
typewriter font.

This seems to say that \examples{} is a verbatim environment rather than 
merely verbatim-like. This statement comes 4 pages earlier in the pdf 
version than the paragraph you quote.

Best wishes
Gordon