From murdoch at stats.uwo.ca  Tue Aug 29 22:21:33 2006
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Tue, 29 Aug 2006 16:21:33 -0400
Subject: [Rd] 'CanMakeUseOf' field
In-Reply-To: <44F49FE1.6040002@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>	<m2d5ajedon.fsf@ziti.fhcrc.org>	<44F47295.2050207@stats.uwo.ca>	<m28xl7ctt3.fsf@ziti.fhcrc.org>	<44F4865B.5010107@bank-banque-canada.ca>	<44F48E3F.6070903@stats.uwo.ca>
	<44F49FE1.6040002@bank-banque-canada.ca>
Message-ID: <44F4A1CD.50800@stats.uwo.ca>

On 8/29/2006 4:13 PM, Paul Gilbert wrote:
> 
> Duncan Murdoch wrote:
> 
>> On 8/29/2006 2:24 PM, Paul Gilbert wrote:
>>
>>> Seth Falcon wrote:
>>>
>>>> Duncan Murdoch <murdoch at stats.uwo.ca> writes:
>>>>  
>>>>
>>>>> On 8/29/2006 11:58 AM, Seth Falcon wrote:
>>>>>   
>>>>>
>>>>>> 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).
>>>>>>     
>>>>>
>>>>> Yes, that's a good point, especially with vignettes.  Only the package
>>>>> author needs to be able to run them.
>>>>>   
>>>>
>>>>
>>>> Yes, but just to keep things clear: the value of vignettes is that
>>>> users can follow along.  So the ability to programatically identify
>>>> the extra required packages is valuable.
>>>>
>>>>  
>>>>
>>>>> But maybe examples should be considered broken if they don't
>>>>> work. Users should be able to expect example(foo) not to generate an
>>>>> error.  Package authors should wrap optional examples in code like if
>>>>> (require(...)).
>>>>>   
>>>>
>>> This is a work around that is ok for the developer's testing and to 
>>> prevent failure on CRAN, and I use it. But, other than actually 
>>> reading the examples, it provides no hints to other testers or users 
>>> about things that might be installed, or installed first, to give 
>>> more complete testing and more functionality.
>>
>>
>> I'm not saying to use this instead of Suggests, I'm saying to do both. 
>> This way the Suggests entries really are suggestions:  the examples 
>> will run with or without the presence of the suggested packages.
>>
>> I think there are so many variations on when a Suggested package 
>> should be installed, that it's not reasonable to expect to be able to 
>> encode them all in a machine readable way.  They should be documented 
>> in human readable format.
>>
>>> Looking toward the future, I think it would be useful to have a 
>>> standard mechanism to indicate extensions that are available in a 
>>> package, and might be tested and used, but are not necessarily 
>>> available on CRAN. For instance, an example might access to a 
>>> purchased database or take advantage of  a computer cluster. It seems 
>>> limiting to think that all testing that cannot be done on CRAN must 
>>> be done almost exclusively by the developer.
>>
>>
>> If by "mechanism" you mean human-readable documentation, I agree with 
>> this.
> 
> Yes,  I was think of human-readable and in a standard location, like a 
> field in the DESCRIPTION file.  (You are thinking of fields in the 
> DESCRIPTION file as human-readable, are you not?)

Yes, but I don't think that's necessarily the right place for this. 
What we were going to do this summer was to make it easier to build 
foo-package.Rd files, without duplication of the information in the 
DESCRIPTION file.  I think that man page (or a man page linked from it) 
would be the right place for a detailed discussion like this.

This doesn't address the problem of someone who hasn't got the package 
installed yet, though perhaps CRAN could put a version of that man page 
(or all of them) online for browsing.  Unfortunately this hasn't 
happened yet, but maybe we'll get to it before 2.5.0.

Duncan Murdoch



> 
> Paul
> 
>>
>> Duncan Murdoch
>>
>>>
>>> Paul
>>>
>>>>
>>>> I agree.  As with vignettes, there is value in users being able to
>>>> follow along and it would be nice to have a programatic way to
>>>> identify extra package needed for fancy/involved/optional examples.
>>>>
>>>> Best,
>>>>
>>>> + seth
>>>>
>>>> ______________________________________________
>>>> R-devel at r-project.org mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>  
>>>>
>>> ==================================================================================== 
>>>
>>>
>>> La version fran?aise suit le texte anglais.
>>>
>>> ------------------------------------------------------------------------------------ 
>>>
>>>
>>> This email may contain privileged and/or confidential 
>>> inform...{{dropped}}
>>>
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
> ====================================================================================
> 
> La version fran?aise suit le texte anglais.
> 
> ------------------------------------------------------------------------------------
> 
> This email may contain privileged and/or confidential info...{{dropped}}




[Rd] 'CanMakeUseOf' field
Duncan Murdoch