[Rd] 'CanMakeUseOf' field

[Duncan Murdoch]

On 8/30/2006 4:44 AM, Martin Maechler wrote:
>>>>>> "FrL" == friedrich leisch <friedrich.leisch at stat.uni-muenchen.de>
>>>>>>     on Wed, 30 Aug 2006 09:34:13 +0200 (MEST) writes:
> 
>     >> Duncan Murdoch <murdoch at stats.uwo.ca> writes:
>     >>> I think we need an option to R CMD check rather than a new field in the
>     >>> DESCRIPTION.  Currently a package could be mentioned for any of these
>     >>> reasons:
>     >>> 
>     >>> 1.  To make functions, examples or vignettes work
>     >>> 2.  To allow optional functionality in functions, examples or vignettes.
>     >>> 3.  Because it contains complementary functions.
>     >>> 
>     >>> I don't think we really need to worry about 3:  it should be contained
>     >>> in 1 or 2, if reasonably complete examples are given.
>     >>> 
>     >>> Case 1 is handled by Depends.
>     >> 
>     >> I think there is an important distinction between a dependency needed
>     >> for the package to function and a dependency needed to demonstrate
>     >> said functionality via an example or vignette.  The former is what
>     >> Depends is about, the latter is something else (Suggests).
> 
>     FrL> Sorry to join in late, I am at the Compstat conference and have limited
>     FrL> email access. What Seth describes in the above paragraph is exactly what I
>     FrL> had in mind when splitting the single Depends field we had into Depends
>     FrL> and Suggests: Depends are a necessity to run the package, Suggests is nice
>     FrL> to have but not necessary. If you know how to use a package you may the
>     FrL> decide not to install a package that is only suggested, but
> 
>     FrL> * may not be interested to execute the examples,
>     FrL> * know that you never need the extra functionality
>     FrL> * ...
> 
>     FrL> so it should not be auto-installed unless you ask for
>     FrL> it (the default could also be the other way round, the
>     FrL> point is that it should be possible to have package foo
>     FrL> but not the packages it only suggests). On CRAN we
>     FrL> check with all suggestions to test all bits and pieces,
>     FrL> having an option in R CMD check to test only with
>     FrL> suggests may be nice, if there is use for it.
> 
> Yes.
> However, I see two (related) problems with the current 'Suggests'
> and that's why I opened this thread proposing to have a 
> (what I now would want to simply call)  'canUse' :
> 
> 1) For 'R CMD check' (and hence CRAN checking),
>    Packages in 'Suggests' must be require()able, and
>    hence all testing only happens *with* the suggested packages
>    being there, and not without.
> 
> 2) "Suggests"  suggests to the human reader of DESCRIPTION that
>    the package authors suggest to also install the packages listed
>    there.
>    Now there are cases, I (as package author) want to show some
>    stuff, or even provide compatibility functionality for some
>    packages that are related to mine, but which I really do not ``suggest''
>    to also be installed, e.g., because the other packages do
>    similar stuff as mine, but I believe my package to be
>    superior.  In such a case, I may, e.g., want to provide 
>    functions for porting the other package classes to my package's.
> 
> Duncan Murdoch has proposed to take care of "1)" by
> still only use 'Suggests' but adding another option to 'R CMD
> check', let's say   --no-suggests  which would run all the
> checks without having the suggested packages available  
> --- something not quite easy to implement, BTW:
> Imagine the typical windows users who (AFAICS) always only use
> one library into which they install all packages.
> How do you want the 
>     if( require(<my_suggested_package>) ) {
>        ...
>     }
> clause *not* to be triggered in such a case ?

I would expect require to return FALSE.  This could be done by check 
installing a new version of require() (as it installs new T and F), or 
by the standard require() being modified to check a stop list before 
acting (I'd prefer this, because it would make it easier for developers 
to experiment with functions in different environments), or by playing 
around with the names of things in the library (probably not workable on 
Windows), etc.

I think the default check behaviour on CRAN should be my middle case: 
test based on what is currently installed, don't require packages listed 
in Suggests to be installed.  I'm not sure if that should be the default 
behaviour for R CMD check at the command line:  as Kurt said, usually a 
developer wants to check all of the code.

> I do agree quite a bit that such a '--no-suggests' option would
> be very useful for 'R CMD check' -- in addition to my proposal.

I think the other extreme (which I think is there now as 
_R_CHECK_FORCE_SUGGESTS_) is also important.

> 
> Further, I think "2)" above is not taken care of anyway.
> After all the interesting statements and alternative proposals,
> I'm still proposing to introduce a  'canUse'  field for DESCRIPTION
> which
>   a) has a "human-readable intent" of being weaker than 'Suggests'
>   b) will not require its packages to be available for R CMD check
>   c) conveys extra information about the package's context, to humans, and
>   d) will potentially be used in automated or semi-manual 
>      ``R package database management''

I think d) is important, but I think there are too many variations on a) 
and c) to hope that this would be used consistently.  As Fritz said, the 
thing he can remember (and what I would remember) is whether a package 
is mandatory or optional.  Fine variations within "optional" are just 
too hard to define clearly in a two-level classification.

On the other hand, they are relatively easy to convey in clearly written 
documentation.  So I'd still recommend that we stay with just Depends 
and Suggests, but encourage authors to document what they mean by 
"Suggests".

Duncan Murdoch

> 
> Martin
> 
>     FrL> Ad the wording in the manual: obviously that is not
>     FrL> optimal (otherwise no need for parts of this email
>     FrL> thread), perhaps somebody else than the original author
>     FrL> (=me) could try to improve it for 2.4 after this
>     FrL> clarifications?  Otherwise I will give it a shot next
>     FrL> week after I return from Rome.
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel