[R] Documentation: Was -- identical() versus sapply()

[Duncan Murdoch]

On 12/04/2016 12:44 PM, David Winsemius wrote:
> > On Apr 12, 2016, at 8:31 AM, Sarah Goslee <sarah.goslee at gmail.com> wrote:
> >
> > I am very interested in such a distributed documentation editing
> > project, and have some thoughts on how to make it workable for both
> > volunteers and core members who would need to review.
> >
> > I'm willing to lead or colead such a project, if someone stepping up
> > would be a useful first step, and I'm also willing to host a wiki,
> > although I think something like GitHub is probably the best place.
> > I've been contemplating for a while how I can get more involved in the
> > main R efforts, and have contributed to the documentation before, in
> > tiny ways. I think those of us who have participated in R-help for a
> > while have an idea of the main stumbling blocks in the documentation
> > (besides, of course, getting people to read it in the first place).
> >
> > I don't think R-help is the right place to continue discussion; should
> > this be moved to R-devel, or somewhere else entirely?
>
> I'm in. My personal experience with R's documentation has been mostly satisfactory, once I learned to pay careful attention to the words 'list', 'name', and 'expression'.  I'm not an experienced C programmer or package author, so the requirement that I submit a "diff" file to an existing document is a hurdle that I cannot not yet clear while running, but I can probably muscle my way over. I remember taking a big step up in learning R when I built a Powerpoint deck to teach basic R, so I would probably learn quite a bit from such a process.
>
> My nomination for an improvement 'target' is the `?reshape` page. I've never been able to understand it, despite years of trying, and I've seen many others report a similar experience. Opinion: Its Details section needs to be expanded into two distinct subsections: a 'wide'-direction subsection and a 'long'-direction subsection. Each subsection would outline the minimum number of supplied arguments for an error-free execution. There need to be more worked examples, but those could easily be mined from problems submitted as recorded in the R-help Archives and StackOverFlow.

I'd suggest something different -- that one sounds hard.  The revision 
history for the last 13 years is shown below.  Though my name appears, 
it's for trivial changes, and I wouldn't consider myself to be an 
author, and I do not offer to participate in the revision.

Duncan

------------------------------------------------------------------------
r68948 | ripley | 2015-08-09 10:51:17 -0400 (Sun, 09 Aug 2015) | 1 line

use https
------------------------------------------------------------------------
r68070 | hornik | 2015-03-24 03:32:16 -0400 (Tue, 24 Mar 2015) | 1 line

Spelling.
------------------------------------------------------------------------
r68059 | ripley | 2015-03-21 18:14:23 -0400 (Sat, 21 Mar 2015) | 1 line

faulty svn merge, one more partial match
------------------------------------------------------------------------
r68055 | ripley | 2015-03-21 16:08:08 -0400 (Sat, 21 Mar 2015) | 1 line

document where use of match.arg allows partial matching
------------------------------------------------------------------------
r61521 | ripley | 2013-01-02 10:09:27 -0500 (Wed, 02 Jan 2013) | 1 line

correction
------------------------------------------------------------------------
r61433 | ripley | 2012-12-25 07:19:50 -0500 (Tue, 25 Dec 2012) | 1 line

remove trailing spaces
------------------------------------------------------------------------
r59039 | ripley | 2012-04-15 06:32:41 -0400 (Sun, 15 Apr 2012) | 1 line

use preferred form of 'R Core Team'
------------------------------------------------------------------------
r57816 | ripley | 2011-12-05 03:08:17 -0500 (Mon, 05 Dec 2011) | 1 line

more tidying up
------------------------------------------------------------------------
r57814 | ripley | 2011-12-05 02:42:30 -0500 (Mon, 05 Dec 2011) | 1 line

add note about duplicate records
------------------------------------------------------------------------
r57094 | maechler | 2011-09-27 11:32:03 -0400 (Tue, 27 Sep 2011) | 1 line

white space only
------------------------------------------------------------------------
r56186 | murdoch | 2011-06-19 21:51:45 -0400 (Sun, 19 Jun 2011) | 1 line

Revert r56184 and r56185
------------------------------------------------------------------------
r56184 | murdoch | 2011-06-19 19:58:46 -0400 (Sun, 19 Jun 2011) | 1 line

Remove redundant \alias entries from man pages
------------------------------------------------------------------------
r53637 | ripley | 2010-11-19 18:13:25 -0500 (Fri, 19 Nov 2010) | 1 line

revise documentation for PR#14435
------------------------------------------------------------------------
r50263 | ripley | 2009-10-30 13:52:33 -0400 (Fri, 30 Oct 2009) | 3 lines

spell 'indices' consistently
add an example of CJK fonts for quartz devices (borrowed from Ei-Ji Nakama)

------------------------------------------------------------------------
r49566 | ripley | 2009-09-04 17:41:50 -0400 (Fri, 04 Sep 2009) | 2 lines

remove unnecessay use of \link[]{} form

------------------------------------------------------------------------
r47616 | ripley | 2009-01-15 17:59:26 -0500 (Thu, 15 Jan 2009) | 2 lines

expand tabs in help files, which were often not rendering as intended

------------------------------------------------------------------------
r47077 | ripley | 2008-12-05 10:59:56 -0500 (Fri, 05 Dec 2008) | 1 line

invalid space
------------------------------------------------------------------------
r42961 | ripley | 2007-09-24 08:43:45 -0400 (Mon, 24 Sep 2007) | 2 lines

try to use \dQuote for actual quotes, and \emph or \sQuote or \code otherwis

------------------------------------------------------------------------
r42667 | pd | 2007-08-27 10:09:08 -0400 (Mon, 27 Aug 2007) | 1 line

reshape revamped, bug in split<-.data.frame
------------------------------------------------------------------------
r42555 | maechler | 2007-08-18 16:11:40 -0400 (Sat, 18 Aug 2007) | 1 line

more \seealso entries (long overdue)
------------------------------------------------------------------------
r42333 | ripley | 2007-07-27 06:16:22 -0400 (Fri, 27 Jul 2007) | 3 lines

add copyright/licence header
remove CVS-style $Id fields

------------------------------------------------------------------------
r41600 | ripley | 2007-05-17 01:08:32 -0400 (Thu, 17 May 2007) | 2 lines

avoid unnecessary/confusing abbrevation of arguments

------------------------------------------------------------------------
r41461 | ripley | 2007-05-07 07:08:51 -0400 (Mon, 07 May 2007) | 1 line

typo
------------------------------------------------------------------------
r41446 | ripley | 2007-05-05 09:17:30 -0400 (Sat, 05 May 2007) | 2 lines

corrections to the handling of \ in Rd files

------------------------------------------------------------------------
r40814 | murdoch | 2007-03-05 12:47:13 -0500 (Mon, 05 Mar 2007) | 1 line

Typos
------------------------------------------------------------------------
r36816 | ripley | 2005-12-20 06:38:29 -0500 (Tue, 20 Dec 2005) | 2 lines

tweaks, usually over-long lines

------------------------------------------------------------------------
r30549 | tlumley | 2004-08-06 16:27:33 -0400 (Fri, 06 Aug 2004) | 2 lines

allow multiple id variables in reshape

------------------------------------------------------------------------
r30449 | ripley | 2004-08-02 10:03:44 -0400 (Mon, 02 Aug 2004) | 2 lines

more removal of unneeded data() statements

------------------------------------------------------------------------
r27501 | ripley | 2003-12-11 03:24:12 -0500 (Thu, 11 Dec 2003) | 2 lines

nls, ts -> stubs

------------------------------------------------------------------------
r27442 | ripley | 2003-12-09 02:24:25 -0500 (Tue, 09 Dec 2003) | 2 lines

split from base