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

[Kurt Hornik]

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