[Rd] 'CanMakeUseOf' field

[Duncan Murdoch]

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