[Rd] documentation

[Frederick Eaton]

Dear R Devel,

I'm sorry that I haven't had time to check the subversion logs to see
if any of these items have been addressed, but I remember notifying
the list about bugs in the documentation of 'browser()' and
'system2()' and I haven't yet received any acknowledgment that the
issues I described were understood. R is a useful language, and since
it is used in education, I wonder if we should make sure that all
documentation bugs are responded to.

Contributors might also note that documentation error reports can't be
generated automatically, like compiler errors can; and that
distributing bad documentation is an effective way to obscure the
functioning of a software project, and to make it hard for others to
verify that it is doing the right thing, or to extend its
functionality.

For a refresher, the issue with system2() is that the documentation
does not warn users that the elements of the 'args' array need to be
passed through a quoting function, and the issue with browser() is
that various limitations of the trace facilities and API are
undocumented. Have these been fixed without reporting back to the
list? Or is it that no one else uses these functions? In which case
maybe I can be given access to fix the documentation myself?

I worry that R is becoming more like an appliance, needing servicing
in cooperation with the maker, than a tool that I can recommend for
people to take home and build something with. I hope that I'm
misunderstanding the intent of the core team.

Thank you,

Frederick