[Rd] 'CanMakeUseOf' field

[Seth Falcon]

Martin Maechler <maechler at stat.math.ethz.ch> writes:

>>>>>> "Seth" == Seth Falcon <sfalcon at fhcrc.org>
>>>>>>     on Wed, 30 Aug 2006 07:06:24 -0700 writes:
>
>     Seth> Kurt Hornik <Kurt.Hornik at wu-wien.ac.at> writes:
>     >> An internal environment variable called
>     >> 
>     >> _R_CHECK_FORCE_SUGGESTS_
>     >> 
>     >> which controls this has been in place for quite some time now.  One can
>     >> trivially add a Perl R CMD check configure variable for it.  I am a bit
>     >> hesitant to add a --force-suggests cola to R CMD check, as this
>     >> hardwires a legacy dependency model which may not be up to future needs.
>     >> 
>     >> As an aside, I have never understood whe developers have need for such
>     >> an option (as I would have assumed that they'd typically try to check
>     >> all of their code).
>
>     Seth> This is not an aside, but the heart of the issue IMHO :-)
>
>     Seth> One case in which checking Suggests does not make sense is when a
>     Seth> package provides optional functionality that is platform specific.  A
>     Seth> given Suggests entry may only be available on platform A, but it still
>     Seth> is desirable to check the package on platform B.  Similar issues can
>     Seth> arise during development when a given Suggests entry stops working
>     Seth> with R-devel.
>
>     Seth> Further, if an item in Suggests means it is optional, then one
>     Seth> _should_ test that by testing the package without the optional packge
>     Seth> being available.  There are a few ways for a true dependency to sneak
>     Seth> into the code.  So I agree that typically developers want to test all
>     Seth> of their code, but that implies being able to check a package without
>     Seth> its Suggests being available (I realize this may be hard to implement,
>     Seth> but easily having R CMD check ignore Suggests is a good start).
>
>     Seth> And lastly, Suggests is currently used to list packages used for
>     Seth> extended examples in package vignettes and being able to easily
>     Seth> perform all other checks makes sense to me.
>
> Very good points, thanks.
> I think it's clear that some R developers see a clear need for
> this and their (our) output would be enhanced by such a very
> small addition --- it would probably only be a small addition
> addition to the "Writing R Extension" manual for the moment.
>
> I don't understand why some developers have such a resistance
> to allow one other such keyword.
> Dirk mentioned 'Enhances'  --- something which I could also live
> with instead of 'CanUse' -- I just to be generous
> with myself (as package author) in my interpretation of
> "enhancing" :-)

This is my last post until we discuss this next year ;-)

The easy solution is to add a new term, but I don't think this is a
good solution at all.

A new developer would have a hard time guessing the difference between
Suggests and CanUse.  Why?  Because 'CanUse' exists because of a
disagreement about how R CMD check should operate.  The meaning of
CanUse is just that it doesn't get checked by R CMD check.

I think we should consider keeping the two levels: Depends and
Suggests and improve R CMD check to:

* Be able to check a package when any subset of Suggests
  is present.

* Be able to check a package forcing all Suggests to be unavailable.

If new terms are wanted, they should have clear semantics.  From the
discussion, here are some possibilities:

DocDepends: Needed for vignette or extended example
RelatedTo: Loose affinity for listed package

Adding DocDepends, it would make sense to modify R CMD check to know
about it.  Probably not for RelatedTo.

> Those developers who cannot remember disambiguating more than
> one field for 'optional' are well allowed to keep using just
> one, i.e., 'Suggests'. 
> But others who want to be more precise and or want to better expose
> (via DESCRIPTION) what they do anyway
> (via 'if(require(*)) { .. }') inside their code, examples, and
> or vignettes would just converge on *how* the new field should
> be baptized. 
> Since 'R CMD check' is not affected, there's no other
> consequence for any package writer.

I fail to see how adding an ambiguous term with fuzzy meaning is good
for package developers wishing to be more precise.  At the same time,
if changes to R CMD check are decided against, I would rather have an
extra term.

Bw,

+ seth