Rolf Turner wrote: > I must say I agree with Richard O'Keefe who wrote: > > >> I wrote: >> R documentation comments really belong >> in [.Rd] files where help() can find them. >> >> Barry Rowlingson <[EMAIL PROTECTED]> replied: >> R documentation comments belong in .Rd files at the moment, but how >> joyous would it be if they could be included in the .R files? >> >> How joyous? About as joyous as a root canal job without anaesthetic. >> > > <etc.> > <snip> > > (a) I don't speak Python and I don't believe I ever will; I'm > not sure what Python does; I don't want to know. R does what > I want to do. I don't want to have to learn Python syntax to > do something with which I am very happy doing the R way > currently. > To be fair, I don't think anyone proposed that. As I read it, the suggestion was to take Python's idea of inline documentation into R, not necessarily an identical implementation. > (b) Modularity is a ***Good Thing***. Code should be code, > documentation should be documentation. They should click > together but be kept separate. > I tend to like comments in code. Rd-style documentation has a different purpose, but not all that different. I tend not to put so many comments into my R code because I spend the time writing .Rd files, but then it's inconvenient to see the docs when I'm working on the code. > (c) The R documentation system is neat, efficient, well > thought out, and well constructed. It is an intrinsic part > of the nature of R. (It's one of the --- many --- reasons I > like R better than Splus, which I no longer use.) Changing > the R documentation system to something (Monty?) Pythonesque > would change the nature of R and make it uglier. > I'd rather wait to see an actual proposal before I decided if it was uglier or more beautiful.
Current .Rd documentation has some obvious problems: - the parser strips comments out of examples when it runs them - there's no way to put images into the documentation - the keywords aren't much use - there's isn't a definition anywhere of what the format really is, so it's hard to know whether something will work other than by trying it -- and it may break with the next release. - there's no way to link from a help man page to a vignette or other form of documentation. None of these would be addressed by inline help, but other people may have other complaints. I think it was DSC 2001 where R Core decided to replace the .Rd system with something better; I would say it's a reasonable prediction that that won't happen soon, but incremental improvements to .Rd have happened, and we should think about other ones. Duncan Murdoch ______________________________________________ [email protected] mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
