From maechler at stat.math.ethz.ch  Fri May  5 17:40:06 2006
From: maechler at stat.math.ethz.ch (Martin Maechler)
Date: Fri, 5 May 2006 17:40:06 +0200
Subject: [Rd] Including a single function from a package
In-Reply-To: <m23bfoed19.fsf@ziti.local>
References: <445B4845.6010804@Indiana.Edu>
	<Pine.LNX.4.64.0605051350530.613@gannet.stats.ox.ac.uk>
	<445B5AED.7090108@Indiana.Edu>
	<Pine.LNX.4.64.0605051509060.3432@gannet.stats.ox.ac.uk>
	<m23bfoed19.fsf@ziti.local>
Message-ID: <17499.29142.172707.782147@stat.math.ethz.ch>

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



[Rd] Including a single function from a package
Martin Maechler