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

> 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

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.

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
>

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