[R] what constitutes a 'complete sentence'?

Tue Jul 7 17:51:15 CEST 2015

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