R devel - Apr 2022 - documentation

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

If you're worried about follow-up on bug reports, I'd suggest posting to
the R bug tracker ( you can request access if you don't already have it)

On Sat, Apr 16, 2022, 11:27 AM Frederick Eaton <frederik at ofb.net>
wrote:
> 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
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
	[[alternative HTML version deleted]]