[Rd] Posting Guide - help.request() function?
Dr Heather Turner
Heather.Turner at warwick.ac.uk
Mon Jun 9 18:21:17 CEST 2008
Thanks for the helpful tips and suggestions, I'll work them in. You get
local versions of the documents on Unix too - RShowDoc() will do the trick.
I'll post an updated version in due course,
Heather
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
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
More information about the R-devel
mailing list