Maybe someone can help shed some light on an odd and repeatedly irritating error I noticed when running the check Perl script on my R 1.3 project. In following it line by line, I traced my problem down to the code/documentation matching within check, the most recent version of which seems to verify proper .Rd formatting by means of R's codoc and undoc functions. Under R --vanilla, those two then unpack and repack my project, with each assembling a kind of test tempfile to ensure various structural requirements within my project. At first, I got bogged down in a mysterious "parse" problem, R's not-too-revealing result of a simple eval, but after discovering the keep.tempfiles flag I was able to trace the obvious errors without running codoc line by line interactively. Apparently, R keeps very stringent requirements on its documentation's usage field. If it's anything other than myFunc(arg1, arg2...), codoc won't parse it correctly in its tempfiles. And the particular S code I was translating used chiefly example calls in its documentation's usage fields. Is this formatting an intended necessity? I know it ensures consistency but it's too often the source of cryptic errors. Anyway, fixing these usage fields worked for the time being but without fail another similar problem soon emerged, this time with the check for undocumented objects. This leg of the script uses undoc, and after examination I found that undoc's concatenation of the R code in the project/R directory fails to insert a newline at the end of each .R file's contribution to the appended tempfile. Now I'm a clean kind of guy and I like to keep my code immaculate, so it was more than disturbing when my R functions, each stored in a single .R file, bombed out because each did not have a newline proceeding its closing bracket. Without that, undoc's file appending sticks the next function right up against the last's final bracket, triggering an obvious syntax error, albeit one hidden underneath tempfiles and a parse/eval combo. Now I can understand somewhat the benefits of establishing consistency in the usage fields, but for the life of me I can't figure out the reasoning behind this seemingly superfluous stringency. Is this R's intended behavior, and if so, forgive me for asking, but why? Thanks in advance for any light you can cast on the issue. Kevin -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.- r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html Send "info", "help", or "[un]subscribe" (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
On Fri, 27 Jul 2001, Bartz, Kevin wrote in part:> Apparently, R keeps very > stringent requirements on its documentation's usage field. If it's anything > other than myFunc(arg1, arg2...), codoc won't parse it correctly in its > tempfiles. And the particular S code I was translating used chiefly example > calls in its documentation's usage fields. Is this formatting an intended > necessity? I know it ensures consistency but it's too often the source of > cryptic errors.This is intended. It makes sure that the help page contains all the arguments in the correct order (for positional matching), which is usually a good idea. You can override the check in cases where it is not useful to have this sort of usage example, by providing the function prototype in a \synopsis section instead. help(abline) does this because the actual prototype would be more confusing than what is given. However, quite a lot of user-written S code comes with help pages that don't document all the arguments or have the order of arguments wrong. codoc at least checks this. In most cases it really is better to put examples in the \examples section and usage in the \usage section. -thomas Thomas Lumley Asst. Professor, Biostatistics tlumley at u.washington.edu University of Washington, Seattle -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.- r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html Send "info", "help", or "[un]subscribe" (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
On Fri, 27 Jul 2001, Bartz, Kevin wrote:> Maybe someone can help shed some light on an odd and repeatedly irritating > error I noticed when running the check Perl script on my R 1.3 project. In > following it line by line, I traced my problem down to the > code/documentation matching within check, the most recent version of which > seems to verify proper .Rd formatting by means of R's codoc and undoc > functions. Under R --vanilla, those two then unpack and repack my project, > with each assembling a kind of test tempfile to ensure various structural > requirements within my project. At first, I got bogged down in a mysterious > "parse" problem, R's not-too-revealing result of a simple eval, but after > discovering the keep.tempfiles flag I was able to trace the obvious errors > without running codoc line by line interactively. Apparently, R keeps very > stringent requirements on its documentation's usage field. If it's anything > other than myFunc(arg1, arg2...), codoc won't parse it correctly in its > tempfiles. And the particular S code I was translating used chiefly example > calls in its documentation's usage fields. Is this formatting an intended > necessity? I know it ensures consistency but it's too often the source of > cryptic errors. > > Anyway, fixing these usage fields worked for the time being but without fail > another similar problem soon emerged, this time with the check for > undocumented objects. This leg of the script uses undoc, and after > examination I found that undoc's concatenation of the R code in the > project/R directory fails to insert a newline at the end of each .R file's > contribution to the appended tempfile. Now I'm a clean kind of guy and I > like to keep my code immaculate, so it was more than disturbing when my R > functions, each stored in a single .R file, bombed out because each did not > have a newline proceeding its closing bracket. Without that, undoc's fileDo you mean a newline *after* the closing brace (to be precise)? That would explain the rest of the sentence. A well-formed .R file *does* have a final newline, so `immaculate' code should have one. (BTW, the tidying-up procedure mentioned in `Writing R Extensions' does ensure a final newline.)> appending sticks the next function right up against the last's final > bracket, triggering an obvious syntax error, albeit one hidden underneath > tempfiles and a parse/eval combo. Now I can understand somewhat the benefits > of establishing consistency in the usage fields, but for the life of me I > can't figure out the reasoning behind this seemingly superfluous stringency. > Is this R's intended behavior, and if so, forgive me for asking, but why?(Assuming I have decoded your explanation correctly.) Because Unix text files do have a final newline. It's a very widespread convention, and the most widespread editor, vi, enforces it. Now undoc could be asked to insert a newline (and given your experience it is probably a good idea) for files which lack one, but this has not arisen in the hundreds of packages which have been tested to date.> Thanks in advance for any light you can cast on the issue. > > Kevin > -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.- > r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html > Send "info", "help", or "[un]subscribe" > (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch > _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._ >-- Brian D. Ripley, ripley at stats.ox.ac.uk Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/ University of Oxford, Tel: +44 1865 272861 (self) 1 South Parks Road, +44 1865 272860 (secr) Oxford OX1 3TG, UK Fax: +44 1865 272595 -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.- r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html Send "info", "help", or "[un]subscribe" (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._