[Rd] Flat documentation?

[John Fox]

Dear Paul, Duncan, et al.,

I too like the package-construction tools in R, and find it easier to 
assemble R packages than S-PLUS libraries.

I wonder, however, whether the following simple suggestion might prove 
useful: Suppose that help(foo) and ?foo first look for standard 
documentation. If such documentation exists, it would be processed as at 
present. If there is no standard documentation on foo, then help and ? 
would look for a "doc" attribute of foo (or for initial comment lines in 
the function definition, if foo is a function), and, if this exists, 
display the contents in a pager.

John

At 10:17 AM 12/11/2002 -0500, Paul Gilbert wrote:
>I am a bit concerned about the direction of some of this discussion. 
>!!Please!!
>do not consider gutting the R package Quality Assurance system and start a 
>slide
>back to the chaos of Statlib. There has to be a mechanism that weeds out code
>that no longer works or is inadequately documented. Do you realize how 
>much time
>people have wasted trying to make poorly documented "casual" Statlib code 
>work?
>There is nothing that prevents non CRAN distribution of code and casual
>documentation. Posting of an r-help message with a web site link does make 
>this
>fairly easily accessible to anyone who searches the help archives, and 
>there is
>no need for the code or documentation to be in any special format. CRAN 
>also has
>a devel area for packages that are not yet in good enough shape for the 
>regular
>area.
>
> >In fact, one of my colleagues has chosen to use S-PLUS instead of R
> >partly because it's easier to document the stuff he's written.
>
>I have mostly gone the other way, largely because of the QA tools (which in
>large part are possible because of the Rd format). It is worth pointing out to
>your colleagues that there is short term pain for long term gain. The fact 
>that
>code and documentation arguments are matched, and examples are checked, means
>that documentation does not need to be manually checked all the time as your
>code evolves. Changes that require changes in the documentation tend to be
>pointed out automatically.

____________________________
John Fox
Department of Sociology
McMaster University
email: jfox@mcmaster.ca
web: http://www.socsci.mcmaster.ca/jfox