> On 7 Jul 2015, at 01:12, peter dalgaard <pda...@gmail.com> wrote: > > >> On 06 Jul 2015, at 23:19 , Duncan Murdoch <murdoch.dun...@gmail.com> wrote: >> >> On 06/07/2015 5:09 PM, Rolf Turner wrote: >>> On 07/07/15 07:10, William Dunlap wrote: >>> >>> [Rolf Turner wrote.] >>> >>>>> The CRAN guidelines should be rewritten so that they say what they *mean*. >>>>> If a complete sentence is not actually required --- and it seems >>>>> abundantly clear >>>>> that it is not --- then guidelines should not say so. Rather they should >>>>> say, >>>>> clearly and comprehensibly, what actually *is* required. >>>> >>>> This may be true, but also think of the user when you write the >>>> description. >>>> If you are scanning a long list of descriptions looking for a package to >>>> use, >>>> seeing a description that starts with 'A package for' just slows you down. >>>> Seeing a description that includes 'designed to' leaves you wondering if >>>> the >>>> implementation is woefully incomplete. You want to go beyond what CRAN >>>> can test for. >>> >>> All very true and sound and wise, but what has this got to do with >>> complete sentences? The package checker issues a message saying that it >>> wants a complete sentence when this has nothing to do with what it >>> *really* wants. >> >> That's false. If you haven't given a complete sentence, you might still >> pass, but if you have, you will pass. That's not "nothing to do" with >> what it really wants, it's just an imperfect test that fails to detect >> violations of the guidelines. >> >> As we've seen, it sometimes also makes mistakes in the other direction. >> I'd say those are more serious. >> >> Duncan Murdoch >> > > Ackchewly.... > > I don't think what we want is what we say that we want. A quick check > suggests that many/most packages use "headline speech", as in "Provides > functions for analysis of foo, with special emphasis on bar.", which seems > perfectly ok. As others have indicated, prefixing with "This package" would > be rather useless. However, I'm at a loss as to how to describe what it is > that we want, much less how to translate it to a dozen other languages.
You are hitting the nail on the head — R asks for a *description* without defining any grammatical rule for it aside from the nebulous ‘complete sentence’ (nebulous because of how it is enforced) and ’this package': "The mandatory ‘Description’ field should give a comprehensive description of what the package does. One can use several (complete) sentences, but only one paragraph. It should be intelligible to all the intended readership (e.g. for a CRAN package to all CRAN users). It is good practice not to start with the package name, ‘This package’ or similar." I am puzzled by the idea that people that deal with stats, maths and computers should define what is a grammatically acceptable description, as opposed to a description. If I describe my package poorly it might not be used as much, and thus it might represent a wasted effort for *me*. Incidentally, not being able to use ‘pkgname' or ‘this package’ decreases the chances of successfully deploying a subject-verb-object sentence. BW F > > -pd > -- > Peter Dalgaard, Professor, > Center for Statistics, Copenhagen Business School > Solbjerg Plads 3, 2000 Frederiksberg, Denmark > Phone: (+45)38153501 > Email: pd....@cbs.dk Priv: pda...@gmail.com > > > > > > > > -- Federico Calboli Ecological Genetics Research Unit Department of Biosciences PO Box 65 (Biocenter 3, Viikinkaari 1) FIN-00014 University of Helsinki Finland federico.calb...@helsinki.fi ______________________________________________ R-help@r-project.org mailing list -- To UNSUBSCRIBE and more, see https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
