Dear Peter, You're correct that these examples aren't verb phrases (though the second one contains a verb phrase). I don't want to make the discussion even more pedantic (moving it in this direction was my fault), but "Paragraph" isn't quite right, unless explained, because conventionally a paragraph consists of sentences. How about something like this? "One can use several complete sentences or punctuated telegraphic phrases, but only one paragraph (that is, block of continuous text with no intervening blank lines). The description should end with a full stop (period)." It would likely be helpful to add some examples of good and bad descriptions, and to explain how the check actually works. Best, John On Tue, 7 Jul 2015 12:20:38 +0200 peter dalgaard <pdalgd at gmail.com> wrote:> ...except that there is not necessarily a verb either. What we're looking for is something like "advertisement style" as in > > UGLY MUGS 7.95. > > An invaluable addition to your display cabinet. Comes in an assortment of warts and wrinkles, crafted by professional artist Foo Yung. > > However, I'm drawing blanks when searching for an established term for it. > > Could we perhaps sidestep the issue by requesting a "single descriptive paragraph, with punctuation" or thereabouts? > > ---- > > I'm still puzzled about what threw Federico's example in the first place. The actual code is > > if(strict && !is.na(val <- db["Description"]) > && !grepl("[.!?]['\")]?$", trimws(val))) > out$bad_Description <- TRUE > > and I can do this > > > strict <- TRUE > > db <- tools:::.read_description("/tmp/dd") > > if(strict && !is.na(val <- db["Description"]) > + && !grepl("[.!?]['\")]?$", trimws(val))) > + out$bad_Description <- TRUE > > out > Error: object 'out' not found > > I.e., the complaint should _not_ be triggered. I suppose that something like a non-breakable space at the end could confuse trimws(), but beyond that I'm out of ideas. > > > On 07 Jul 2015, at 03:28 , John Fox <jfox at mcmaster.ca> wrote: > > > 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. > > > > > > > > -- > Peter Dalgaard, Professor, > Center for Statistics, Copenhagen Business School > Solbjerg Plads 3, 2000 Frederiksberg, Denmark > Phone: (+45)38153501 > Office: A 4.23 > Email: pd.mes at cbs.dk Priv: PDalgd at gmail.com > > > > > > > > >------------------------------------------------ John Fox, Professor McMaster University Hamilton, Ontario, Canada http://socserv.mcmaster.ca/jfox/
On Tue, Jul 7, 2015 at 8:19 AM, John Fox <jfox at mcmaster.ca> wrote:> Dear Peter, > > You're correct that these examples aren't verb phrases (though the second > one contains a verb phrase). I don't want to make the discussion even more > pedantic (moving it in this direction was my fault), but "Paragraph" isn't > quite right, unless explained, because conventionally a paragraph consists > of sentences. > > How about something like this? "One can use several complete sentences or > punctuated telegraphic phrases, but only one paragraph (that is, block of > continuous text with no intervening blank lines). The description should > end with a full stop (period)." > >Before we start crafting better definitions of the rule, it seems important to understand what issue we are trying to solve. I don't see any place where this has been communicated. As I said previously, I usually give them the benefit of the doubt. However, this requirement is poorly implemented and we need to know more. For example, does CRAN need to parse the text and the code failed because there was no period? It seems plausible that someone could have worded that requirement in the current form, but it is poorly written (which is unusual). If the goal is to improve the quality of the description text, then that is a more difficult issue to define. and good luck coding your way into a lucid and effective set of rules. It also seems a bit over the top to me and a poor choice of where everyone should be spending their time. What are we trying to fix? It would likely be helpful to add some examples of good and bad> descriptions, and to explain how the check actually works. > > Best, > John > > On Tue, 7 Jul 2015 12:20:38 +0200 > peter dalgaard <pdalgd at gmail.com> wrote: > > ...except that there is not necessarily a verb either. What we're > looking for is something like "advertisement style" as in > > > > UGLY MUGS 7.95. > > > > An invaluable addition to your display cabinet. Comes in an assortment > of warts and wrinkles, crafted by professional artist Foo Yung. > > > > However, I'm drawing blanks when searching for an established term for > it. > > > > Could we perhaps sidestep the issue by requesting a "single descriptive > paragraph, with punctuation" or thereabouts? > > > > ---- > > > > I'm still puzzled about what threw Federico's example in the first > place. The actual code is > > > > if(strict && !is.na(val <- db["Description"]) > > && !grepl("[.!?]['\")]?$", trimws(val))) > > out$bad_Description <- TRUE > > > > and I can do this > > > > > strict <- TRUE > > > db <- tools:::.read_description("/tmp/dd") > > > if(strict && !is.na(val <- db["Description"]) > > + && !grepl("[.!?]['\")]?$", trimws(val))) > > + out$bad_Description <- TRUE > > > out > > Error: object 'out' not found > > > > I.e., the complaint should _not_ be triggered. I suppose that something > like a non-breakable space at the end could confuse trimws(), but beyond > that I'm out of ideas. > > > > > > On 07 Jul 2015, at 03:28 , John Fox <jfox at mcmaster.ca> wrote: > > > > > 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. > > > > > > > > > > > > > -- > > Peter Dalgaard, Professor, > > Center for Statistics, Copenhagen Business School > > Solbjerg Plads 3, 2000 Frederiksberg, Denmark > > Phone: (+45)38153501 > > Office: A 4.23 > > Email: pd.mes at cbs.dk Priv: PDalgd at gmail.com > > > > > > > > > > > > > > > > > > > > ------------------------------------------------ > John Fox, Professor > McMaster University > Hamilton, Ontario, Canada > http://socserv.mcmaster.ca/jfox/ > > ______________________________________________ > 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. >[[alternative HTML version deleted]]
Dear Max, I think that the object is to describe clearly what CRAN wants in the description field so that package authors don't write description fields that are unacceptable to CRAN. Clear criteria would save both package authors' and CRAN maintainers' time. Although a mechanical check can find some problems with descriptions, I doubt whether it's possible to write a mechanical check that will fully implement what CRAN wants. John> -----Original Message----- > From: R-help [mailto:r-help-bounces at r-project.org] On Behalf Of Max Kuhn > Sent: July-07-15 10:53 AM > To: John Fox > Cc: R Help; Federico Calboli; peter dalgaard > Subject: Re: [R] what constitutes a 'complete sentence'? > > On Tue, Jul 7, 2015 at 8:19 AM, John Fox <jfox at mcmaster.ca> wrote: > > > Dear Peter, > > > > You're correct that these examples aren't verb phrases (though the > second > > one contains a verb phrase). I don't want to make the discussion even > more > > pedantic (moving it in this direction was my fault), but "Paragraph" > isn't > > quite right, unless explained, because conventionally a paragraph > consists > > of sentences. > > > > How about something like this? "One can use several complete sentences > or > > punctuated telegraphic phrases, but only one paragraph (that is, block > of > > continuous text with no intervening blank lines). The description > should > > end with a full stop (period)." > > > > > Before we start crafting better definitions of the rule, it seems > important > to understand what issue we are trying to solve. I don't see any place > where this has been communicated. As I said previously, I usually give > them > the benefit of the doubt. However, this requirement is poorly > implemented > and we need to know more. > > For example, does CRAN need to parse the text and the code failed > because > there was no period? It seems plausible that someone could have worded > that > requirement in the current form, but it is poorly written (which is > unusual). > > If the goal is to improve the quality of the description text, then that > is > a more difficult issue to define. and good luck coding your way into a > lucid and effective set of rules. It also seems a bit over the top to me > and a poor choice of where everyone should be spending their time. > > What are we trying to fix? > > It would likely be helpful to add some examples of good and bad > > descriptions, and to explain how the check actually works. > > > > Best, > > John > > > > On Tue, 7 Jul 2015 12:20:38 +0200 > > peter dalgaard <pdalgd at gmail.com> wrote: > > > ...except that there is not necessarily a verb either. What we're > > looking for is something like "advertisement style" as in > > > > > > UGLY MUGS 7.95. > > > > > > An invaluable addition to your display cabinet. Comes in an > assortment > > of warts and wrinkles, crafted by professional artist Foo Yung. > > > > > > However, I'm drawing blanks when searching for an established term > for > > it. > > > > > > Could we perhaps sidestep the issue by requesting a "single > descriptive > > paragraph, with punctuation" or thereabouts? > > > > > > ---- > > > > > > I'm still puzzled about what threw Federico's example in the first > > place. The actual code is > > > > > > if(strict && !is.na(val <- db["Description"]) > > > && !grepl("[.!?]['\")]?$", trimws(val))) > > > out$bad_Description <- TRUE > > > > > > and I can do this > > > > > > > strict <- TRUE > > > > db <- tools:::.read_description("/tmp/dd") > > > > if(strict && !is.na(val <- db["Description"]) > > > + && !grepl("[.!?]['\")]?$", trimws(val))) > > > + out$bad_Description <- TRUE > > > > out > > > Error: object 'out' not found > > > > > > I.e., the complaint should _not_ be triggered. I suppose that > something > > like a non-breakable space at the end could confuse trimws(), but > beyond > > that I'm out of ideas. > > > > > > > > > On 07 Jul 2015, at 03:28 , John Fox <jfox at mcmaster.ca> wrote: > > > > > > > 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. > > > > > > > > > > > > > > > > > > -- > > > Peter Dalgaard, Professor, > > > Center for Statistics, Copenhagen Business School > > > Solbjerg Plads 3, 2000 Frederiksberg, Denmark > > > Phone: (+45)38153501 > > > Office: A 4.23 > > > Email: pd.mes at cbs.dk Priv: PDalgd at gmail.com > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > ------------------------------------------------ > > John Fox, Professor > > McMaster University > > Hamilton, Ontario, Canada > > http://socserv.mcmaster.ca/jfox/ > > > > ______________________________________________ > > 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. > > > > [[alternative HTML version deleted]] > > ______________________________________________ > 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.--- This email has been checked for viruses by Avast antivirus software. https://www.avast.com/antivirus
On 07 Jul 2015, at 16:52 , Max Kuhn <mxkuhn at gmail.com> wrote:> > What are we trying to fix? > >Two things, actually. (1) An error message that sends the package developer on a wild goose chase, because it is both out of sync both with what is wanted, and what is checked for. (2) The description in the WRE manual is somewhat self-contradicting, and could probably be improved. To my mind, the tricky one is (1). (2) should be easier because there is space to elaborate. (1) needs to be succinct, which is hard if there is no single term for what is being required. I'm beginning to think that the best we can do is along the lines of "Malformed Description field: Missing end punctuation.". If more checks are devised, add more messages. -- Peter Dalgaard, Professor, Center for Statistics, Copenhagen Business School Solbjerg Plads 3, 2000 Frederiksberg, Denmark Phone: (+45)38153501 Office: A 4.23 Email: pd.mes at cbs.dk Priv: PDalgd at gmail.com