[R] Suggestion for posting guide

[Martin Maechler]

>>>>> "Tony" == Tony Plate <tplate at blackmesacapital.com>
>>>>>     on Fri, 20 Aug 2004 10:05:28 -0600 writes:

    Tony> When I originally compiled the posting guide many
    Tony> people felt that it should be kept as concise as
    Tony> possible, so that its length would not discourage
    Tony> people from reading it.  (It probably ended up too
    Tony> long anyway.)  So I wouldn't really recommend adding a
    Tony> section of this length too it.

I agree

    Tony> That said, a question posted with a good example that
    Tony> can be cut and pasted directly into R is far easier to
    Tony> respond to, so it does seem like a good idea to help
    Tony> people create such things.  If someone (Gabor?) wanted
    Tony> to create a page on how to provide good examples in
    Tony> posts, the people who control what gets put on the
    Tony> R-project site might be willing to put it up there,
    Tony> and a link to it from the posting guide would seem
    Tony> like a good idea.

indeed!
    Tony> Tony Plate

read on :

    Tony> At Thursday 07:17 AM 8/19/2004, Gabor Grothendieck wrote:

    >> I have a suggestion for the posting guide.  One problem
    >> with some posts is that they do not provide an example
    >> that can be reproduced.  I think that many people just do
    >> not know how to easily specify some data and some
    >> technical assistance should be provided in the posting
    >> guide.  If the problem depends on specific data they
    >> should be made aware, in the posting guide, of:

    >> dput(x)

Rereading the posting guide (which *really* is rather too long
already for beginners), I see that we already have an 'Examples:' section.
[Have you seen that, Gabor, and not found useful enough?]

And just below that, we say

  PGuide> When providing examples, it is best to give an R command that
  PGuide> constructs the data, as in the matrix() expression above. For
  PGuide> more complicated data structures, dump("x", file=stdout())
  PGuide> will print an expression that will recreate the object x.

I tend to think that
	dump("x", file=stdout())
should probably be replaced with 
        dput(x)

even though they are not quite the same now (and even more
different in R-devel i.e. 2.0.0-to-be).

    >> since that outputs object x as R code which can then be
    >> easily copied from the post and pasted into a session.

(yes,  but that's already in there!).

    >> If its not dependent on particular data they can generate
    >> patterned or random data IF THEY KNOW HOW but many might
    >> find it easier to just use one of the included datasets
    >> so some guidance should be provided on the contents of a
    >> few of them, e.g.
    >> 
    >> R comes with built in data sets.  data() will list them, data(iris) will
    >> attach data set iris and ?iris, str(iris), summary(iris), head(iris)
    >> and dput(iris) will give more information on iris (after attaching it).
    >> The following are a few of the datasets that come with R:
    >> 
    >> iris - data frame with 4 numeric columns and one 3 level factor
    >> nhtemp - a ts class time series
    >> faithful - data frame with two numeric columns
    >> warpbreaks - data with a numeric column, a 2-level factor & a 3-level 
    >> factor
    >> 
    >> Also letters, LETTERS, month.abb and month.name are built
    >> in character vectors that do not require a data statement
    >> to access.

Thank you for the suggestions, Gabor.

If you have proposals for improvement, I'd mostly appreciate to
get a "diff -u" output from the current and your modified
posting-guide.html files -- 
probably only sent to Tony Plate and me (unless other people
chime in).

Martin