[Rd] 'CanMakeUseOf' field
Duncan Murdoch
murdoch at stats.uwo.ca
Tue Aug 29 22:21:33 CEST 2006
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}}
More information about the R-devel
mailing list