[ESS] ESS, devtools, and documentation

[Martin Maechler]

>>>>> Vitalie Spinu <spinuvit at gmail.com>
>>>>>     on Sat, 18 Oct 2014 15:51:31 -0700 writes:

    >>>> Martin Maechler on Sat, 18 Oct 2014 10:30:58 +0200 wrote:
    >> it was almost fine,  ... and I think it is more flexible to keep the
    >> "global" .ess.helpFUN
 
    >> For you, Timothy, or any other working with released ESS, a nicer
    >> workaround should be to do -- once in your session -- so you could do
    >> it on the same line in your R scripts where you have
    >> require(devtools) {or library(..) if you really prefer} :

    >> .ess.helpFUN <- get("help", globalenv())

    > Due to lexical scope we are picking .ess.helpFUN from ESSR
    > environment. So the user has to assign it in ESSR.

well (in the ess-help branch) we did take it
from globalenv, as I thought your intention was.
My changes 	
   - worked in R 1.0.x
   - kept it visible in "ESSR" so users can even override .ess.helpFUN,

    > .ess.helpFUN looks like a complication to me. If we pick "help" from
    > globalenv users can assign their own "help" function in globalenv if
    > they want so.

well, .. yes, unless some other "smart tool" interferes with assigning
"help" in globalenv.  That's why the original code took it from
utils explicitly.

    > In my previous email I was particularly interested if the "glbalenv"
    > function is defined in very old version of R. Sorry for not being
    > explicit about that.

yes, I understood, and I did a small change so it did work with
old R. I have now merged that branch (in a too complicated way) into master.

    >> After all devtools wants to get the help page from the package source
    >> without attaching the package to the search() path. So, the above
    >> workaround does ensure regular help works for all packages you have
    >> in search(), it will *not* find the help pages of the "load_all(.) --
    >> pseudo attached package". Only if you additionally attach (a
    >> typically older version of) your package {using require() or
    >> library()}, you will get the (old version of) help pages for that
    >> package.

    > Devtools redefines "help" function and it makes sure that the help from
    > dev-loaded packages is accessible.

Yes, of course, I know..

    > That should not be our concern. We
    > need to make sure that help(foo), print(help(foo)), ? and C-c C-v work
    > exactly the same and the only way to achieve that is to pick help from
    > globalenv.

I never disagreed with that. I just mentioned that I did not
like the sneaky way that 'devtools' redefines 'help' and '?' etc
... but that was not related to how we should deal with it.
I'm sorry, if I was confusing there

Also -- as mentioned above -- the new scheme is not error proof either:
As soon as the user executes some code which defines a
non-functional help() function in her globalenv, things are
broken now  and they were not broken previously when took R's
version of help() irrespectively of bogous things in globalenv
or other entries in search() that come *before* package:utils
...

Martin