From murdoch at stats.uwo.ca  Tue Aug 29 19:22:33 2006
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Tue, 29 Aug 2006 13:22:33 -0400
Subject: [Rd] 'CanMakeUseOf' field  [was ".. Add 'fields' argument ..]
In-Reply-To: <44F473F4.1020607@bank-banque-canada.ca>
References: <m2wt8sgyo0.fsf@ziti.fhcrc.org>	<17651.65163.240840.365787@stat.math.ethz.ch>	<44F4473D.9030203@bank-banque-canada.ca>	<17652.19292.998960.686119@stat.math.ethz.ch>	<44F46112.7060809@stats.uwo.ca>
	<44F473F4.1020607@bank-banque-canada.ca>
Message-ID: <44F477D9.7090909@stats.uwo.ca>

On 8/29/2006 1:05 PM, Paul Gilbert wrote:
> 
> Duncan Murdoch wrote:
> 
>> On 8/29/2006 10:12 AM, Martin Maechler wrote:
>>
>>>>>>>> "PaulG" == Paul Gilbert <pgilbert at bank-banque-canada.ca>
>>>>>>>>     on Tue, 29 Aug 2006 09:55:09 -0400 writes:
>>>>>>>
>>>
>>>     PaulG> Martin Maechler wrote:
>>>     >> ...
>>>     >>     >> The idea was a field related to but weaker than 
>>> 'Suggests' :
>>>     >> Something like
>>>     >> 'canMakeUseOf: <pkg1> [, <pkg2>, ... ]
>>>     >> which is *not* used in any QA/QC checking, but is purely
>>>     >> informative: If <pkg1> is require()able, then some examples may
>>>     >> look nicer, a function may provide another feature, etc, etc.
>>>     >> Alternatives to 'canMakeUseOf' would have been
>>>     >> 'isHappilyCoworkingWith' ....
>>>     >>     >> What do you (R-devel listeners) think about the idea?
>>>
>>>     PaulG> I still like this idea.  I prefer 'canMakeUseOf' to     
>>> PaulG> 'isHappilyCoworkingWith'  mainly because it seems less ambiguous.
>>>
>>> Thanks, Paul.
>>> As you may have guessed I should have put a  " :-) "  beside the
>>> 'isHappily...' .
>>>
>>> Of course, even 'CanMakeUseOf' {we should capitalize the first letter}
>>> is rather too long, but before finding the proper term, we should
>>> agree on usefulness of such a new field.
>>> Apart from the use of package authors {some could note that
>>> other packages make use of theirs, without already depending on
>>> or suggesting them}, it's one of those fields that should help
>>> in the future to explore (e.g. cluster or neighborhood-graph)
>>> the growing high-dimensional space of R packages.
>>
>>
>> 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.
> 
> Well, from "Writing R Extensions"
>    The optional  Suggests  field uses the same syntax as  Depends  and 
> lists packages that are not
>    necessarily needed. This includes packages used only in examples or 
> vignettes

Yes, Seth pointed that out too.  Rather than adding additional levels, 
I'd fix it by changing the wording:

1.  To make functions work.
2.  To make examples and vignettes work, or optional functionality in 
functions.

The point is that there are some packages that are absolutely required 
(listed in Depends), and some that are only sometimes required (listed 
in Suggests).  Gabor's suggestion of labelling how things are used could 
be helpful too, but really even there, there are multiple levels of how 
something is used.

> So case 1 is handled by the combination of Depends and Suggests, and we 
> need something to handle case 2.
> 
> The related question is whether the CRAN checks should  try to check 2, 
> or perhaps there needs to be 2a and 2b.  There are cababilities (and 
> data) that CRAN may not have, so it would be nice distinguish things 
> that should be checked on CRAN from things that should not be.

I'd suggest that CRAN do its checks using the "as currently installed" 
option proposed below.  If a package can't pass tests using what's on 
CRAN, then it should be marked as needing work.

Duncan Murdoch

> 
> Paul
> 
>>
>> An author should check case 2 both with and without the suggested 
>> package.  A user  might be satisfied with a simple check "as things 
>> currently stand", or might want a stringent check like the author 
>> wants.  The author can't know that, because it will depend on the user.
>>
>> So I don't think this is something that should be changed in 
>> DESCRIPTION.  There should be an option to R CMD check to include or 
>> exclude packages mentioned in the Suggests entry.  (I'd suggest a 3 
>> level option:  check as though they are not available, check as 
>> currently installed, require that they be available.)
>>
>> Duncan Murdoch
> ====================================================================================
> 
> La version fran?aise suit le texte anglais.
> 
> ------------------------------------------------------------------------------------
> 
> This email may contain privileged and/or confidential info...{{dropped}}




[Rd] 'CanMakeUseOf' field [was ".. Add 'fields' argument ..]
Duncan Murdoch