[Rd] Query: Could documentation include modernized references?

[Ben Bolker]

   For one point of evidence about how much people pay attention to the 
documentation about what's outdated: Brian Ripley added a comment to 
nlminb.Rd in 2013 saying that the function was "for historical 
compatibility" 
<https://github.com/wch/r-source/commit/fd50cf2047b636e496551bcefd6bfa505f93f168> 
but it's still widely used in new code ...

  But I agree that adding appropriate warnings/links to the 
documentation couldn't hurt.

   cheers
    Ben

On 2023-03-26 12:41 p.m., Duncan Murdoch wrote:
> On 26/03/2023 11:54 a.m., J C Nash wrote:
>> A tangential email discussion with Simon U. has highlighted a 
>> long-standing
>> matter that some tools in the base R distribution are outdated, but that
>> so many examples and other tools may use them that they cannot be 
>> deprecated.
>>
>> The examples that I am most familiar with concern optimization and 
>> nonlinear
>> least squares, but other workers will surely be able to suggest cases 
>> elsewhere.
>> I was the source (in Pascal) of Nelder-Mead, BFGS and CG algorithms in 
>> optim().
>> BFGS is still mostly competitive, and Nelder-Mead is useful for 
>> initial exploration
>> of an optimization problem, but CG was never very good, right from the 
>> mid-1970s
>> well before it was interfaced to R. By contrast Rcgmin works rather well
>> considering how similar it is in nature to CG. Yet I continue to see 
>> use and
>> even recommendations of these tools in inappropriate circumstances.
>>
>> Given that it would break too many other packages and examples to drop 
>> the
>> existing tools, should we at least add short notes in the man (.Rd) 
>> pages?
>> I'm thinking of something like
>>
>>      optim() has methods that are dated. Users are urged to consider 
>> suggestions
>>      from ...
>>
>> and point to references and/or an appropriate Task View, which could, 
>> of course,
>> be in the references.
>>
>> I have no idea what steps are needed to make such edits to the man 
>> pages. Would
>> R-core need to be directly involved, or could one or two trusted R 
>> developers
>> be given privileges to seek advice on and implement such modest 
>> documentation
>> additions?  FWIW, I'm willing to participate in such an effort, which 
>> I believe
>> would help users to use appropriate and up-to-date tools.
> 
> I can answer your final paragraph:
> 
> Currently R-core would need to be directly involved, in that they are 
> the only ones with write permission on the R sources.
> 
> However, they don't need to do the work, they just need to approve of it 
> and commit it.  So I would suggest one way forward is the following:
> 
> - You fork one of the mirrors of the R sources from Github, and (perhaps 
> with help from others) edit one or two of the pages in the way you're 
> describing.  Once you think they are ready, make them available online 
> for others to review (Github or Gitlab would help doing this), and then 
> submit the changes as a patch against the svn sources on the R Bugzilla 
> site.
> 
> - Another way could be that you copy the help page sources to a dummy 
> package, instead of checking out the whole of the R sources.  You'll 
> need to be careful not to miss other changes to the originals between 
> the time you make your copy and the time you submit the patches.
> 
> Don't do too many pages, because you're probably going to have to work 
> out the details of the workflow as you go, and earn R Core's trust by 
> submitting good changes and responding to their requests.  And maybe 
> don't do any until you hear from a member of R Core that they're willing 
> to participate in this, because they certainly don't accept all 
> suggestions.
> 
> Duncan Murdoch
> 
> ______________________________________________
> R-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

-- 
Dr. Benjamin Bolker
Professor, Mathematics & Statistics and Biology, McMaster University
Director, School of Computational Science and Engineering
(Acting) Graduate chair, Mathematics & Statistics
 > E-mail is sent at my convenience; I don't expect replies outside of 
working hours.