[R] Contributing to the R Extensions documentation

[Martin Maechler]

>>>>> "Ross" == Ross Boylan <ross at biostat.ucsf.edu>
>>>>>     on Wed, 05 Nov 2003 12:31:28 -0800 writes:

    Ross> On Wed, 2003-11-05 at 12:06, Prof Brian Ripley wrote:
    >> A list is just a vector of type VECSXP.  There IS a
    >> section called `Handling lists'.
    >> 
    >> I don't think the gap is in the `Writing R Extensions'
    >> document, maybe in your reading of it.
    >> 
    Ross> That section discusses reading lists, not making them.

    Ross> It also includes no explicit statement that the names
    Ross> of list items are in the R_NamesSymbol attribute, nor
    Ross> instructions on how to create the value that goes in
    Ross> that attribute (i.e., it should be a character vector
    Ross> and its elements made with mkChar()).  (I'm also not
    Ross> sure how deep one needs to use PROTECT, though that's
    Ross> a more general issue.)

    Ross> There is no explicit statement that the elements of
    Ross> the list are arbitrary SEXP's.

    Ross> I also had the list[i] vs list[[i]] lurking in my
    Ross> mind, wondering how that mapped to the C level
    Ross> constructs.  That is less central.

    Ross> I'm not saying the clues aren't there; after all, I
    Ross> did work it out, I think correctly.  I am saying that
    Ross> certain information would be better stated explicitly
    Ross> rather than simply being open to inference from an
    Ross> example.  And I am saying that an explicit example of
    Ross> constructing and returning a list (with named members)
    Ross> would be useful, since that's a common scenario.

I tend to agree.
I assume most people will read that manual electronically --- as
opposed to "on paper", because you can search quickly ---
and such a proposed addition would be quite helpful.

Alternatively, and sometimes even more usefully,
one could consider providing these more extended examples as
files (*.c, *.R, Makefile, .. or even better, as an R package
(with a vignette !) which would have an almost purely didactical
aim.   As an R package --- source only, no binaries! --- it had
the advantage of providing "provably" (via R CMD check) working
code.

Martin Maechler <maechler at stat.math.ethz.ch>	http://stat.ethz.ch/~maechler/
Seminar fuer Statistik, ETH-Zentrum  LEO C16	Leonhardstr. 27
ETH (Federal Inst. Technology)	8092 Zurich	SWITZERLAND
phone: x-41-1-632-3408		fax: ...-1228			<><

    >> On Wed, 5 Nov 2003, Ross Boylan wrote:
    >> 
    >> I thought there were some gaps in the R Extensions
    >> document; in particular, I was left wondering how to
    >> create a list.  I think a paragraph on it would be
    >> useful.
    >> 
    >> I would be happy to contribute the paragraph, but I'm
    >> not sure if there's interest or what the procedure is.
    >> Can anyone advise me?
    >> 
    >> Though I was looking at the 1.7.0 version, I just
    >> checked 1.8.0 and the relevant section seems the same.
    >> 
    >> My ulterior motive is to discover if my understanding
    >> of lists is actually correct :)