[Rd] Posting Guide - help.request() function?
Martin Maechler
maechler at stat.math.ethz.ch
Mon Jun 9 22:45:23 CEST 2008
>>>>> "HT" == Heather Turner <Heather.Turner at warwick.ac.uk>
>>>>> on Mon, 09 Jun 2008 17:21:17 +0100 writes:
HT> Thanks for the helpful tips and suggestions, I'll work
HT> them in. You get local versions of the documents on Unix
HT> too - RShowDoc() will do the trick.
HT> I'll post an updated version in due course,
Thank you, Heather and Gabor (and the other contributors).
Indeed, I too like the idea of providing a new R function for
this.
Ideally, Heather, you'd try to "factor out" some of the common
functionality of bug.report() and help.request() into a few
utils-namespace hidden auxiliary functions.
Ideally, you'd attach text/plain attachments (base64 encoded) so
there won't be line wrap arounds.
Martin
HT> Gabor Grothendieck wrote:
>> That's an excellent idea.
>>
>> One other item that could be checkable would be if the
>> user has the most recent versions of the packages
>> involved in the query. Perhaps it could display the
>> unupdated packages and ask the user if any of those are
>> involved in the query.
>>
>> Probably needs to give fair warning that it is sending
>> off an email so people don't wind up sending out emails
>> when they are really just trying out the system.
>> Probably "none" should be the default for email so that
>> its not regarded as obnoxious.
>>
>> Might be nice if it used local versions of documents if
>> they exist locally. On Windows they do.
>>
>> Check out ?getRversion
>>
>> On Mon, Jun 9, 2008 at 10:35 AM, Dr Heather Turner
>> <Heather.Turner at warwick.ac.uk> wrote:
>>> Whilst it is a good idea to improve the posting guide,
>>> it seems to me that it would be useful to have a
>>> function along the lines of bug.report(), to help a
>>> potential questioner make sure they have done their
>>> homework and have the relevant information to put into a
>>> post to R-help.
>>>
>>> Even those of us who know what ought to go into a post
>>> can sometimes forget to check something obvious - I
>>> recently got caught out by not checking an error was
>>> reproducible in the patched version for example.
>>>
>>> So I have written a help.request() function (see below),
>>> which - prompts the user to check the relevant
>>> resources, stopping and opening the relevant url where
>>> necessary - checks their R version is up-to-date (in a
>>> rather messy way - please suggest improvements!) -
>>> prompts them to prepare appropriate example code and
>>> test it in a fresh R session - prompts them to give a
>>> meaningful subject line - automatically adds system info
>>> to the post (as in bug.report) - sends the message for
>>> them (ensuring a fresh thread is started)
>>>
>>> Is this an idea worth taking further? I would be happy
>>> to make improvements as suggested and write a help file
>>> if so.
>>>
>>> Heather
>>>
>>> ------------------------------------------------------------
>>>
>>> help.request <- function (subject = "", ccaddress =
>>> Sys.getenv("USER"), method = getOption("mailer"),
>>> address = "r-help at R-project.org", file =
>>> "R.help.request") { no <- function(answer) answer == "n"
>>> yes <- function(answer) answer == "y" go <-
>>> function(url) { cat("Please do this first - the site has
>>> been loaded in your web browser\n") browseURL(url) }
>>> cat("Checklist:\n") post <- readline("Have you read the
>>> posting guide? (y/n) ") if (no(post))
>>> return(go("http://www.r-project.org/posting-guide.html"))
>>> FAQ <- readline("Have you checked the FAQ? (y/n) ") if
>>> (no(FAQ))
>>> return(go("http://cran.r-project.org/faqs.html")) intro
>>> <- readline("Have you checked An Introduction to R?
>>> (y/n) ") if (no(intro))
>>> return(go("http://cran.r-project.org/doc/manuals/R-intro.html"))
>>> NEWS <- readline("Have you checked the NEWS of the
>>> latest development release? (y/n) ") if (no(NEWS))
>>> return(go("https://svn.r-project.org/R/trunk/NEWS"))
>>> rsitesearch <- readline("Have you looked on RSiteSearch?
>>> (y/n) ") if (no(rsitesearch)) { cat("Please do this
>>> first - the site has been loaded in your web browser\n")
>>> return(RSiteSearch(subject)) } inf <- sessionInfo() if
>>> ("otherPkgs" %in% names(inf)){ other <- readline("You
>>> have packages other than the base packages loaded.",
>>> "\nIf your query relates to one of these, have you ",
>>> "checked any corresponding books/manuals \nand ",
>>> "considered contacting the package maintainer? (y/n/NA)
>>> ") if(no(other)) return("Please do this first.") }
>>>
>>> man <- url("http://cran.r-project.org/manuals.html") ver
>>> <- scan(man, what = character(0), sep = "\n", skip = 13,
>>> nlines = 1, quiet = TRUE) major <-
>>> as.numeric(substr(ver, start = 18, stop = 18)) minor <-
>>> as.numeric(substr(ver, start = 20, stop = 22)) if (major
>>> < as.numeric(R.Version()$major) || minor <
>>> as.numeric(R.Version()$major)) { update <-
>>> readline("Your R version is out-of-date, would you like
>>> to update now? (y/n) ") if (yes(update)) {
>>> return(go(getOption("repos"))) } } ## To get long
>>> prompt! cat("Have you written example code that is\n",
>>> "- minimal\n - reproducible\n - self-contained\n -
>>> commented", "\nusing data that is either\n", "-
>>> constructed by the code\n - loaded by data()\n", "-
>>> reproduced using dump(\"mydata\", file = \"\")\n") code
>>> <- readline(paste("have you checked this code in a fresh
>>> R session", "\n(invoking R with the --vanilla option if
>>> possible)", "\nand is this code copied to the clipboard?
>>> (y/n) ")) if (no(code)) return(cat("\nIf your query is
>>> not directly related to code", "(e.g. a general query
>>> \nabout R's capabilities),", "email R-help at r-project.org
>>> directly. ", "\nOtherwise prepare some example code
>>> first.\n")) change <- readline(paste("Would you like to
>>> change your subject line:\n", subject, "\nto something
>>> more meaningful? (y/n) ")) if (yes(change)) subject <-
>>> readline("Enter subject: \n")
>>>
>>> methods <- c("mailx", "gnudoit", "none", "ess") method
>>> <- if (is.null(method)) "none" else
>>> methods[pmatch(method, methods)] body <-
>>> paste("\\n<<Write your query here, using your example
>>> code to
illustrate> ",
>>> "\\n<<End with your name and affiliation>>\\n\\n\\n\\n",
>>> "--please do not edit the information below--\\n\\n",
>>> "Version:\\n ", paste(names(R.version), R.version, sep =
>>> " = ", collapse = "\\n "), if
>>> (nzchar(Sys.getenv("R_GUI_APP_VERSION")))
>>> paste("\\n\\nGUI:\\n R-GUI ",
>>> Sys.getenv("R_GUI_APP_VERSION"), " (",
>>> Sys.getenv("R_GUI_APP_REVISION"), ")", sep = "") else
>>> "", "\\n\\n", "Locale:\\n", Sys.getlocale(), "\\n\\n",
>>> "Search Path:\\n ", paste(search(), collapse = ", "),
>>> "\\n", sep = "", collapse = "") if (method == "gnudoit")
>>> { cmd <- paste("gnudoit -q '", "(mail nil \"", address,
>>> "\")", "(insert \"", body, "\")", "(search-backward
>>> \"Subject:\")", "(end-of-line)'", sep = "") system(cmd)
>>> } else if (method == "none") { disclaimer <- paste("#
>>> Your mailer is set to \"none\" (default on Windows),\n",
>>> "# hence we cannot send the help request directly from
>>> R.\n", "# Please copy the help request (after finishing
>>> it) to\n", "# your favorite email program and send it
>>> to\n#\n", "# ", address, "\n#\n",
>>> "######################################################\n",
>>> "\n\n", sep = "") cat(disclaimer, file = file) body <-
>>> gsub("\\\\n", "\n", body) cat(body, file = file, append
>>> = TRUE) cat("Please edit the help request.\n")
>>> system(paste(getOption("editor"), file)) cat("The unsent
>>> help request can be found in file", file, "\n") } else
>>> if (method == "mailx") { if (missing(subject))
>>> stop("'subject' missing") body <- gsub("\\\\n", "\n",
>>> body) cat(body, file = file, append = FALSE) cat("Please
>>> edit the help request.\n")
>>> system(paste(getOption("editor"), file)) if
>>> (is.character(ccaddress) && nzchar(ccaddress)) { cmdargs
>>> <- paste("-s '", subject, "' -c", ccaddress, address,
>>> "<", file, "2>/dev/null") } else cmdargs <- paste("-s
>>> '", subject, "'", address, "<", file, "2>/dev/null")
>>> status <- 1 cat("Submit the help request? ") answer <-
>>> readline() answer <- grep("y", answer, ignore.case =
>>> TRUE) if (length(answer) > 0) { cat("Sending email
>>> ...\n") status <- system(paste("mailx", cmdargs)) if
>>> (status > 0) status <- system(paste("Mail", cmdargs)) if
>>> (status > 0) status <- system(paste("/usr/ucb/mail",
>>> cmdargs)) if (status == 0) unlink(file) else {
>>> cat("Sending email failed!\n") cat("The unsent help
>>> request can be found in file", file, "\n") } } else
>>> cat("The unsent help request can be found in file",
>>> file, "\n") } else if (method == "ess") { body <-
>>> gsub("\\\\n", "\n", body) cat(body) } }
>>>
>>> -----------------------------------------------------------------------
>>>
>>> Gabor Grothendieck wrote:
>>>> Here is another update. I have added the following:
>>>>
>>>> - info about using a fresh R session. (In that case
>>>> ls() output is less essential; however, the developers
>>>> of sessionInfo() might consider adding that as a
>>>> default or as an option.)
>>>>
>>>> - questioner should consider use of functions.
>>>>
>>>> - for data use dump(x, file = "") to reproducibly
>>>> display data or use builtin datasets listed by data()
>>>>
>>>> - minimal versions of slow code should be presented in
>>>> cases where questioner is looking for faster code.
>>>>
>>>> - we still need to add links to illustrative sample
>>>> questions in r-help
>>>>
>>>> The following were not added for the reason cited:
>>>>
>>>> - guide is not just for questioners. Important to
>>>> distinguish roles of questioner, responder and reader.
>>>>
>>>> - what is to be provided ought to be given a name to
>>>> make it easier to refer to. An unlabelled set of
>>>> points is too vague. Test framework seems
>>>> appropriately descriptive. By giving it a name one can
>>>> request that a questioner "provide a test framework as
>>>> defined in the posting guide summary".
>>>>
>>>> - self contained is not implied by reproducible.
>>>> Reproducible only means that info is available
>>>> somewhere -- not that its all available right in the
>>>> questioner's post and all in a manner that is readily
>>>> accessible.
>>>>
>>>> - focus should be on making data minimal. Don't like
>>>> attachments since responder must save them and read
>>>> them in. It encourages use of large rather than
>>>> minimal data sets.
>>>>
>>>> Summary
>>>>
>>>> Surprisingly, the main problem for responders is not to
>>>> answer the question but to quickly figure out what the
>>>> question is, reproduce it in their own R session and
>>>> test their answer.
>>>>
>>>> Test Framework. To faciliate this provide a test
>>>> framework of:
>>>>
>>>> (1) minimal reproducible self-contained commented code
>>>> and data that has been run in a fresh R session. That
>>>> means code and data have been cut down as far as
>>>> possible to the essentials needed to illustrate the
>>>> problem and were run are just after starting up R.
>>>> Also it means that its possible for responders to just
>>>> copy the code and data section from the questioner's
>>>> post to the clipboard and paste it into their session
>>>> to see the same output without having to enter even one
>>>> R command. In some cases there may be an advantage to
>>>> present the code as a function and in the case of
>>>> needing a speedup be sure to post a minimal version of
>>>> the slow code. Use builtin data sets such as those
>>>> listed by data() to illustrate problem or reduce your
>>>> data to a minimum and present it reproducibly by using:
>>>> dump("mydata", file = "")
>>>>
>>>> (2) comments/explanation of what the code is intended
>>>> to produce -- Don't assume its obvious!
>>>>
>>>> (3) versions of all software used, e.g. sessionInfo(),
>>>> or R.version.string; packageDescription("zoo")$Version
>>>>
>>>> Without self-contained reproducible code the responder
>>>> must not only understand the question but must also
>>>> create a test framework and that typically takes more
>>>> time than answering the question! Its not fair to ask
>>>> the responder to provide all that on top of answering
>>>> the question. Do NOT assume the problem is so simple
>>>> that it is not necessary.
>>>>
>>>> Effort. The effort taken to reduce the problem to its
>>>> essentials and produce a test framework often solves
>>>> the problem avoiding the need for a post in the first
>>>> place. It at the least shows that the questioner tried
>>>> to solve it themself.
>>>>
>>>> Subscribers. The questioner should ensure that the
>>>> thread is complete and that it has an appropriate
>>>> Subject. The purpose of the post is not only to help
>>>> the questioner but also the other list subscribers and
>>>> those later searching the archives.
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> On Sat, Jun 7, 2008 at 9:38 AM, Gabor Grothendieck
>>>> <ggrothendieck at gmail.com> wrote:
>>>>> Here is a second version of the summary. Its been
>>>>> rearranged to place most important info at top. Also
>>>>> shortened it a bit.
>>>>>
>>>>> It still needs links to example posts, as suggested.
>>>>> Anyone?
>>>>>
>>>>> Summary
>>>>>
>>>>> Surprisingly, the main problem for responders is not
>>>>> to answer the posted questions but to quickly figure
>>>>> out what the question is, reproduce it in their own R
>>>>> session and test their answer.
>>>>>
>>>>> Test Framework. To faciliate that provide a test
>>>>> framework of:
>>>>>
>>>>> (1) reproducible self-contained minimal code and data.
>>>>> That means responders can copy it from the
>>>>> questioner's post and paste it into their session to
>>>>> see the same output without having to enter even one R
>>>>> command. NB. dput(mydata) produces mydata in
>>>>> reproducible form. (2) comments/explanations of what
>>>>> the code is intended to produce and (3) versions of
>>>>> all software used, e.g. sessionInfo().
>>>>>
>>>>> Without self-contained reproducible code the responder
>>>>> must not only understand the question but must also
>>>>> create a test framework and that typically takes more
>>>>> time than answering the question! Its not fair to ask
>>>>> the responder to provide all that on top of answering
>>>>> the question. Do NOT assume the problem is so simple
>>>>> that it is not necessary.
>>>>>
>>>>> Effort. The effort taken to reduce the problem to its
>>>>> essentials and produce a test framework often solves
>>>>> the problem avoiding the need for a post in the first
>>>>> place. It at the least shows that the questioner
>>>>> tried to solve it themself.
>>>>>
>>>>> Subscribers. The questioner should ensure that the
>>>>> thread is complete and that it has an appropriate
>>>>> Subject. The purpose of the post is not only to help
>>>>> the questioner but also the other list subscribers and
>>>>> those later searching the archives.
>>>>>
>>>>>
>>>>>
>>>>> On Fri, Jun 6, 2008 at 1:30 PM, Gabor Grothendieck
>>>>> <ggrothendieck at gmail.com> wrote:
>>>>> People read the posting guide yet they are still unable to
>>>>> create an
>>>>> acceptable
>>>>> post. e.g.
>>>>> https://stat.ethz.ch/pipermail/r-help/2008-June/164092.html
>>>>>>
>>>>> I think the problem is that the guide is not clear or
>>>>>> concise enough.
>>>>> I suggest we add a summary at the beginning which gets to
>>>>>> the heart
>>>>> of what a poster is expected to provide:
>>>>>>
>>>>> Summary
>>>>>>
>>>>> To maximize your change of getting a response when posting
>>>>>> provide (1)
>>>>> commented,
>>>>> (2) minimal, (3) self-contained and (4) reproducible code.
>>>>>> (This one
>>>>> line summary
>>>>> also appears at the end of each message to r-help.)
>>>>>>
>>>>> "Self-contained" and "reproducible" mean that a responder
>>>>>> can copy the
>>>>> questioner's code to
>>>>> the clipboard, paste it into their R session and see the
>>>>>> same problem
>>>>> you as the questioner
>>>>> see. Note that dput(mydata) will display mydata in a
>>>>>> reproducible way.
>>>>> Self-contained and reproducible are needed because:
>>>>> (1) Self-Effort. It shows that the questioner tried to
>>>>>> solve the
>>>>> problem by themself first.
>>>>> (2) Test framework. Often the responder needs to play with
>>>>>> the code a
>>>>> bit in order to respond
>>>>> or at least to give the best answer. They can't do that
>>>>>> without a
>>>>> test framework that includes
>>>>> the data and the code to run it and its not fair to ask
>>>>>> them to not
>>>>> only answer the question but
>>>>> also to come up with test data and to complete incomplete
>>>>>> code.
>>>>> (3) Archives. Questions and answers go into the archives
>>>>>> so they are
>>>>> not only for the benefit of
>>>>> of the questioner but also for the benefit of all future
>>>>>> searchers of
>>>>> the archive. That means
>>>>> that its not finished if you have solved the problem for
>>>>>> yourself.
>>>>> You still need to ensure that
>>>>> the thread has a complete solution. (For that reason its
>>>>>> also
>>>>> important to give a meaningful
>>>>> subject to each post.)
>>>>>>
>>>>> "Commented" and "minimal" also reduce the time it takes to
>>>>>> understand
>>>>> the problem.
>>>>> Don't just dump your code as is into the message since you
>>>>>> are just
>>>>> wasting your own
>>>>> time. Its not likely anyone will answer a message if the
>>>>>> questioner
>>>>> has not taken the
>>>>> time to reduce it to its essential elements.
>>>>>> Surprisingly, quite
>>>>> often understanding what
>>>>> the problem is takes the responder most of the time -- not
>>>>>> solving the
>>>>> problem. Once the
>>>>> question is actually understood its often quite fast to
>>>>>> answer. Thus
>>>>> in addition to posting
>>>>> it in a minimal form, comment on it sufficiently so that
>>>>>> the responder
>>>>> knows what the code
>>>>> does and is intended to produce. It may be obvious to the
>>>>>> questioner
>>>>> who is embroiled in
>>>>> the problem but that does not mean its obvious to others.
>>>>>>
>>>>> Introduction
>>>>>>
>>>>> .... rest of posting guide ...
>>>>>>
>>>> ______________________________________________
>>>> R-devel at r-project.org mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>> --
>>> Dr H Turner Research Fellow Dept. of Statistics The
>>> University of Warwick Coventry CV4 7AL
>>>
>>> Tel: 024 76575870 Fax: 024 76524532 Url:
>>> www.warwick.ac.uk/go/heatherturner
>>>
--
Dr H Turner
HT> Research Fellow Dept. of Statistics The University of
HT> Warwick Coventry CV4 7AL
HT> Tel: 024 76575870 Fax: 024 76524532 Url:
HT> www.warwick.ac.uk/go/heatherturner
HT> ______________________________________________
HT> R-devel at r-project.org mailing list
HT> https://stat.ethz.ch/mailman/listinfo/r-devel
More information about the R-devel
mailing list