[Rd] Flat documentation?

[John Fox]

Dear Duncan,

At 09:18 AM 12/12/2002 -0500, Duncan Murdoch wrote:
>On Wed, 11 Dec 2002 14:42:41 -0500, you wrote:
>
> >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.
>
>I think that would be an ideal solution, as long as there was a
>relatively easy way to import text.

One could simply supply a function to perform this task -- e.g., doc(foo, 
'file'), which returns the function or data frame foo with the contents of 
file in the doc attribute (or as initial comment lines).

>For example, if it's done with
>comments (which would be my preference), there should be a way to
>enter multi-line comments (like /* ...  */ in C).  If it's done with
>attributes there needs to be an easy way to put free-form text into
>the attribute.

I can think of several ways to store a multi-line text attribute: a vector 
of strings, a string with new-line characters, etc. It would be easiest to 
import the text from a file, and it would be up to help() to display the 
information correctly.

>As an aside, I wasn't certain that multi-line comments didn't exist,
>so I checked the language reference.  Comments aren't documented at
>all! (At least in the r-devel version...) This should probably be
>fixed. I've submitted draft text as a bug report.


Regards,
  John

-----------------------------------------------------
John Fox
Department of Sociology
McMaster University
Hamilton, Ontario, Canada L8S 4M4
email: jfox@mcmaster.ca
phone: 905-525-9140x23604
web: www.socsci.mcmaster.ca/jfox
-----------------------------------------------------