From jfox@mcmaster.ca  Thu Dec 12 15:36:05 2002
From: jfox@mcmaster.ca (John Fox)
Date: Thu Dec 12 15:36:05 2002
Subject: [Rd] Flat documentation?
In-Reply-To: <8e3hvu4rvnimgh0bu798itlcbhhdeuv1c2@4ax.com>
References: <5.0.2.1.0.20021211143041.02872480@mcmail.cis.mcmaster.ca>
 <b5vcvu0tp8ab3r1o9r9m9c1rqv4rke2llp@4ax.com>
 <3DF7571E.20E2B822@bank-banque-canada.ca>
 <5.0.2.1.0.20021211143041.02872480@mcmail.cis.mcmaster.ca>
Message-ID: <5.1.0.14.2.20021212092533.01ddb880@mcmail.cis.mcmaster.ca>

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
-----------------------------------------------------



[Rd] Flat documentation?
John Fox