[Rd] Including a single function from a package

[Martin Maechler]

>>>>> "Seth" == Seth Falcon <sfalcon at fhcrc.org>
>>>>>     on Fri, 05 May 2006 07:56:02 -0700 writes:

    Seth> Prof Brian Ripley <ripley at stats.ox.ac.uk> writes:
    >> On Fri, 5 May 2006, Ken Kelley wrote:
    >> 
    >>> Thank you both very much for your quick and helpful
    >>> responses.
    >>> 
    >>> I added "Imports: MASS, gsl" to the DESCRIPTION file and
    >>> that took care of loading in the desired functions just
    >>> fine. I went back and took another look at the
    >>> "Specifying imports and exports" section (section 1.6.1)
    >>> of the Writing R Extensions manual and I do not see
    >>> anything about including an "Imports:" line in the
    >>> DESCRIPTION file when including an "importFrom" in the
    >>> NAMESPACE file. Perhaps including this information in a
    >>> future update should be considered.
    >>  Well, no, it described under the DESCRIPTION file:
    >> 
    >> The optional @samp{Imports} field lists packages whose
    >> namespaces are imported from but which do not need to be
    >> attached.
    >> 
    >> Note that caveat which complicates the issue and I think
    >> makes in inappropriate for that section.

    Seth> I think it would be an improvement to mention in the
    Seth> namespace documentation that imported package must
    Seth> appear in either Depends or Imports in the DESCRIPTION
    Seth> file as well as being mentioned in the NAMESPACE file.
    Seth> The requirment that this information be repeated is
    Seth> not obvious to many.  That is, one might reasonably
    Seth> imagine that specifying imports with an importsFrom
    Seth> directive in the NAMESPACE file is enough.

I do have to agree with Seth;
I've helped several people now all of whom had problems with the
above when they were told to follow work along the documentation
in "Writing R Extensions".
The typical package writer will start with

DESCRIPTION, R/*.R, then, man/*.Rd, etc  
and at some point learn about NAMESPACE and read in the manual
about things related to the "new NAMESPACE".  It's very natural
*not* go back and reread the docu about DESCRIPTION as well.

Martin