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

[Gordon Smyth]

Dear Kurt,

At 03:21 PM 26/05/2003, Kurt Hornik wrote:
> >>>>> 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?

No I'm the one who was missed something. As the strsplit example shows, I 
could have got "*\\.txt" as I wanted in the help file by putting four 
backlashes, "*\\\\.txt", in the .Rd file.

There are still aspects though to the substitution of backlashes when going 
from the help file to running examples which seem unexpected to me. I tried 
out the following example.

In the example in the .Rd file:

c("\\\\","\\\","\\\\#","\\#","\#")
c("\\+","\\?","\\.","\\*","\\^","\\$","\\(","\\)","\\[","\\]","\\{","\\}","\\|","\\_")
c("\+","\?","\.","\*","\^","\$","\(","\)","\[","\]","\{","\}","\|","\_")
c("\\w","\\W","\\s","\\S","\\d","\\D","\\A","\\Z","\\b","\\B","\\G","\\n","\\r","\\f","\\t")
c("\w","\W","\s","\S","\d","\D","\A","\Z","\b","\B","\G","\n","\r","\f","\t")

This results in the help file:

c("\\","\\","\\#","\#","\#")
c("\+","\?","\.","\*","\^","\$","\(","\)","\[","\]","\{","\}","\|","\_")
c("\+","\?","\.","\*","\^","\$","\(","\)","\[","\]","{","}","\|","\_")
c("\w","\W","\s","\S","\d","\D","\A","\Z","\b","\B","\G","\n","\r","\f","\t")
c("\w","\W","\s","\S","\d","\D","\A","\Z","\b","\B","\G","\n","\r","\f","\t")

Executed by example():

c("\\", "\\", "\\#", "#", "#")
c("+", "?", ".", "*", "^", "$", "(", ")", "[", "]", "{", "}", "|", "_")
c("+", "?", ".", "*", "^", "$", "(", ")", "[", "]", "{", "}", "|", "_")
c("w", "W", "s", "S", "d", "D", "A", "Z", "\b", "B", "G", "\n", "\r", "\f", 
"    ")
c("w", "W", "s", "S", "d", "D", "A", "Z", "\b", "B", "G", "\n", "\r", "\f", 
"    ")

When going from the .Rd file to the help file, single backslashes are left 
as-is but double backslashes are converted to singles. So to get a double 
backslash one has to start with four backslashes. This is fine.

When going from the help file to rendered code, double backlashes are now 
left as-is. Single backslashes are removed, *except* for "\b", "\n", "\r" 
and "\f". Escaped t's, "\t" are converted to actual tabs.

Is this all as it is supposed to be? The conversion of \t to <tab> does 
seem a potential problem.

The conversion of \t to <tab> occurs in other examples of rendering code 
also, for example:

 > myfun <- function(x,pattern="\t") "hello"
 > args(myfun)
function (x, pattern = "        ")

Best
Gordon

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