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
______________________________________________ [EMAIL PROTECTED] mailing list https://www.stat.math.ethz.ch/mailman/listinfo/r-devel
