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

[Gordon Smyth]

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