Title case in DESCRIPTION for package where a word is a function name

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Title case in DESCRIPTION for package where a word is a function name

Prof J C Nash (U30A)
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. It is

A Replacement and Extension of the optim() Function

R CMD check suggests the incorrect form

A Replacement and Extension of the Optim() Function

'Writing R Extensions' suggests single quotes, i.e.,

A Replacement and Extension of the 'optim()' Function

which R CMD check still complains about.

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.

On a related matter, I'm finding the reverse dependency check for optimx
takes a very long time and sometimes stalls for reasons I have not yet
sorted out. I run it in virtual machines for R3.2 and R-devel. Possibly
optimx needs so many packages I'm hitting memory or disk limits. Perhaps
off-list discussion could suggest a way to set up a reverse check
server. I'd be willing to help on such a project, which might be helpful
for many developers.

JN

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Title case in DESCRIPTION for package where a word is a function name

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

  Ben Bolker

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Title case in DESCRIPTION for package where a word is a function name

Uwe Ligges-3


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
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Title case in DESCRIPTION for package where a word is a function name

bbolker
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

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Title case in DESCRIPTION for package where a word is a function name

Prof J C Nash (U30A)
In reply to this post by Uwe Ligges-3
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
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Title case in DESCRIPTION for package where a word is a function namei

Peter Dalgaard-2

> On 25 Apr 2015, at 13:11 , Prof J C Nash (U30A) <[hidden email]> 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
>>>
>>> ______________________________________________
>>> [hidden email] mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>
> ______________________________________________
> [hidden email] 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: [hidden email]  Priv: [hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Title case in DESCRIPTION for package where a word is a function namei

Prof J C Nash (U30A)
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) <[hidden email]> 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
>>>>
>>>> ______________________________________________
>>>> [hidden email] mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Title case in DESCRIPTION for package where a word is a function namei

Henrik Bengtsson-4
On Apr 25, 2015 05:07, "Prof J C Nash (U30A)" <[hidden email]> 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) <[hidden email]> 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
> >>>>
> >>>> ______________________________________________
> >>>> [hidden email] mailing list
> >>>> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>>>
> >>
> >> ______________________________________________
> >> [hidden email] mailing list
> >> https://stat.ethz.ch/mailman/listinfo/r-devel
> >
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel