From pgilbert at bank-banque-canada.ca  Wed Aug 30 20:13:55 2006
From: pgilbert at bank-banque-canada.ca (Paul Gilbert)
Date: Wed, 30 Aug 2006 14:13:55 -0400
Subject: [Rd] 'CanMakeUseOf' field
In-Reply-To: <44F5BFD0.3040502@stats.uwo.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>	<63945.151.100.49.234.1156923253.squirrel@webmail.lrz-muenchen.de>	<17653.20470.199569.870638@stat.math.ethz.ch>	<44F5A0E9.1010309@stats.uwo.ca>
	<44F5BCB9.7030702@bank-banque-canada.ca>
	<44F5BFD0.3040502@stats.uwo.ca>
Message-ID: <44F5D563.6090601@bank-banque-canada.ca>



Duncan Murdoch wrote:
> On 8/30/2006 12:28 PM, Paul Gilbert wrote:
>> Duncan Murdoch wrote:
>>> 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".
>>
>> The problem I see here is that this is a change from the status quo, 
>> which is likely to make a real mess for some time.  
> 
> I'm not sure what your "this" refers to.  Was it my suggestion or 
> Martin's?  Must be his, I never make a real mess :-)

I was referring to 'but encourage authors to document what they mean by 
"Suggests"', which to me implies that every developer gets to define 
what Suggests means to them.  Thus, I would get to make a real mess, 
which I usually manage to do even without it being a legitimate option.:-)

> 
> Duncan Murdoch
> 
>  > The status quo is
>> that packages in Depends and Suggests are needed to check examples and 
>> vignettes. I would not change this without a very good reason.  It 
>> would be best to put other suggestions of extensions, that some users 
>> may want to use, somewhere else.  The current situation is that these 
>> suggestions are sprinkled in Rd files, vignettes, web pages, etc. This 
>> situation is not too bad, but it might be nice to have some place 
>> users would expect to find this information.  However, changing the 
>> meaning of Suggests to be developer defined does not strike me as an 
>> improvement.
>>
>> Paul Gilbert
>>>
>>> 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
>>>
>>> ______________________________________________
>>> 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 information, and 
>> the Bank of
>> Canada does not waive any related rights. Any distribution, use, or 
>> copying of this
>> email or the information it contains by other than the intended 
>> recipient is
>> unauthorized. If you received this email in error please delete it 
>> immediately from
>> your system and notify the sender promptly by email that you have done 
>> so.
>> ------------------------------------------------------------------------------------ 
>>
>>
>> Le pr?sent courriel peut contenir de l'information privil?gi?e ou 
>> confidentielle.
>> La Banque du Canada ne renonce pas aux droits qui s'y rapportent. 
>> Toute diffusion,
>> utilisation ou copie de ce courriel ou des renseignements qu'il 
>> contient par une
>> personne autre que le ou les destinataires d?sign?s est interdite. Si 
>> vous recevez
>> ce courriel par erreur, veuillez le supprimer imm?diatement et envoyer 
>> sans d?lai ?
>> l'exp?diteur un message ?lectronique pour l'aviser que vous avez 
>> ?limin? de votre
>> ordinateur toute copie du courriel re?u.
====================================================================================

La version fran?aise suit le texte anglais.

------------------------------------------------------------------------------------

This email may contain privileged and/or confidential inform...{{dropped}}




[Rd] 'CanMakeUseOf' field
Paul Gilbert