Interpretation of escaped characters in \examples{}

Sun, May 25, 2003 9:05 PM

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

Interpretation of escaped characters in \examples{}

Thread (4 messages)