[Rd] Query: Could documentation include modernized references?

[Martin Maechler]

>>>>> Duncan Murdoch 
>>>>>     on Sun, 26 Mar 2023 12:41:03 -0400 writes:

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

(indeed!)

    > 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

Thanks a lot, Duncan, for this (as usual from you) very precise
and helpful information / explanations.

I am "happy"/willing to get involved a bit here, as I do want to
spend some time re-reading about current state of (some, notably
optim-related) optimizers.

(But I will be mostly offline for the next 60 hours or so.)


Martin

--
Martin Maechler
ETH Zurich  and  R Core team