R devel - Apr 2015 - Title case in DESCRIPTION for package where a word is a function name

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
>

Uwe Ligges <ligges <at> statistik.tu-dortmund.de> writes:
> 
> 
> 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
  Does this then constitute a bug in the package-checking code?
  
  With a just-updated R-devel, for a test case I get:

The Title field should be in title case, current version then in title case:
?Support Functions and Data for "Ecological Models and Data" plus
'optim()'?
?Support Functions and Data for "Ecological Models and Data" Plus
'Optim()'?

(while I'm nit-picking, I will say that the first time I got a version
of this error a few weeks ago, it took me two or three tries to parse
what "..., current version then in title case" meant.  It is perfectly
correct, I just found it really hard to understand ...)

  cheers
    Ben Bolker

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.

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
>>

> 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
-- 
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