[Rd] Title case in DESCRIPTION for package where a word is a function namei

[Henrik Bengtsson]

On Apr 25, 2015 05:07, "Prof J C Nash (U30A)" <nashjc at uottawa.ca> wrote:
>
> How about allowing underscore? (I believe WRE is silent on this, and I
> have not tried submitting a package with underscore in the title.) As I
> pointed out in my OP, _optim()_ works. And we have the advantage that we
> can distinguish package from function.

Backticks also works (and also happens to be what Markdown use for inline code);

> title <- "A Replacement and Extension of the `optim()` Function"
> title == tools::toTitleCase(title)
[1] TRUE

Henrik

>
> The purpose of consistent editing is surely to provide the affordances
> that save us from needing extra documentation, as per Donald Norman's
> excellent discussions on Design of Everyday Things, or Turn Signals are
> the Facial Expressions of Automobiles. Changing the name of a function
> in a case-sensitive computing language may not be a bug, but it is
> asking for trouble.
>
> JN
>
> On 15-04-25 07:57 AM, peter dalgaard wrote:
> >
> >> On 25 Apr 2015, at 13:11 , Prof J C Nash (U30A) <nashjc at uottawa.ca> wrote:
> >>
> >> Hendrik pointed out it was the parentheses that gave the complaint.
> >> Single quotes and no parentheses seem to satisfy R CMD check. Perhaps
> >> that needs to be in the WRE.
> >
> > Well, it is in ?toTitleCase:
> >
> >      ...However, unknown
> >      technical terms will be capitalized unless they are single words
> >      enclosed in single quotes: names of packages and libraries should
> >      be quoted in titles.
> >
> > ..and it is the "single word" bit that gets you. AFAICT, the issue is that it splits the text into words and then looks for words that begin and end with a single quote. And parentheses count as word separators, so the quotes of 'optim()' end up in two different words.
> >
> > It's one of those things that aren't easy to fix: Presumably you do want capitalization within parentheses so we can't just not let them be separators, and we can't just look for sets of single quotes with arbitrary content because they get used inside ordinary text (e.g. the beginning of this paragraph contains 's one of those things that aren'). So either we need more heuristics, like only counting () as separators when preceded by or preceding a space, or some sort of explicit escape mechanism, like BibTeX's {foo}.
> >
> >>
> >> However, I have for some time used the parentheses to distinguish
> >> functions from packages. optim() is a function, optimx a package.
> >> Is this something CRAN should be thinking about? I would argue greater
> >> benefit to users than title case.
> >>
> >> JN
> >>
> >>
> >> On 15-04-24 06:17 PM, Uwe Ligges wrote:
> >>>
> >>>
> >>> On 24.04.2015 22:44, Ben Bolker wrote:
> >>>> Prof J C Nash (U30A <nashjc <at> uottawa.ca> writes:
> >>>>
> >>>>>
> >>>>> I was preparing a fix for a minor glitch in my optimx package and R CMD
> >>>>> check gave an error that the title was not in title case.
> >>>>
> >>>>   [snip] to make Gmane happy ...
> >>>>
> >>>>> I have found
> >>>>>
> >>>>> A Replacement and Extension of the _optim()_ Function
> >>>>>
> >>>>> does not get the complaint, but I'm not sure the underscore is allowed.
> >>>>>
> >>>>> Given that I've obeyed the RTFM rule, I'm wondering what to do now.
> >>>>
> >>>>   Presumably you should ask the CRAN maintainers?  That seems to
> >>>> be the only possible answer -- I don't think anyone else can guess
> >>>> very accurately ...
> >>>
> >>> From WRE:
> >>>
> >>> "Refer to other packages and external software in single quotes, and to
> >>> book titles (and similar) in double quotes."
> >>>
> >>> Other non-English usage (as documented for the Description field; this
> >>> inlcudes function names) can also be used in single quotes.
> >>>
> >>> Best,
> >>> Uwe Ligges
> >>>
> >>>
> >>>>
> >>>>   Ben Bolker
> >>>>
> >>>> ______________________________________________
> >>>> R-devel at r-project.org mailing list
> >>>> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>>>
> >>
> >> ______________________________________________
> >> R-devel at r-project.org mailing list
> >> https://stat.ethz.ch/mailman/listinfo/r-devel
> >
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel