Interpretation of escaped characters in \examples{}

Gordon Smyth writes:

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.

Gordon,

I may be missing something obvious here but if e.g. look at strsplit.Rd
in the base package, this has

     unlist(strsplit("a.b.c", "."))
     ## [1] "" "" "" "" ""
     ## Note that `split' is a regexp!
     ## If you really want to split on `.', use
     unlist(strsplit("a.b.c", "\\."))
     ## [1] "a" "b" "c"

in the rendered version and

strspl> unlist(strsplit("a.b.c", "."))
[1] "" "" "" "" ""

strspl> unlist(strsplit("a.b.c", "\\."))
[1] "a" "b" "c"

and I also get

R> unlist(strsplit("a.b.c", "\\."))
[1] "a" "b" "c"

so these seem rather consistent to me?

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.

And the same is said for \usage.  Perhaps the part about being set
verbatim should be removed then.

Thanks
-k