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
> On 06 Jul 2015, at 23:19 , Duncan Murdoch <murdoch.duncan at 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. -pd -- Peter Dalgaard, Professor, Center for Statistics, Copenhagen Business School Solbjerg Plads 3, 2000 Frederiksberg, Denmark Phone: (+45)38153501 Email: pd.mes at cbs.dk Priv: PDalgd at gmail.com
Dear Peter, I think that the grammatical term you're looking for is "verb phrase." Best, John On Tue, 7 Jul 2015 00:12:25 +0200 peter dalgaard <pdalgd at gmail.com> wrote:> > > On 06 Jul 2015, at 23:19 , Duncan Murdoch <murdoch.duncan at 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. > > -pd > -- > Peter Dalgaard, Professor, > Center for Statistics, Copenhagen Business School > Solbjerg Plads 3, 2000 Frederiksberg, Denmark > Phone: (+45)38153501 > Email: pd.mes at cbs.dk Priv: PDalgd at gmail.com > > ______________________________________________ > R-help at 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.
> On 7 Jul 2015, at 01:12, peter dalgaard <pdalgd at gmail.com> wrote: > > >> On 06 Jul 2015, at 23:19 , Duncan Murdoch <murdoch.duncan at 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.mes at cbs.dk Priv: PDalgd at 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.calboli at helsinki.fi