Re: [Rd] Posting Guide - help.request() function?
Okay, here's the update. I've created a new function create.post() (with Windows and Unix versions) which would be the internal function that creates the post template ready to edit and optionally send. In the Windows version I've added an experimental method == mailto option, which will open the post template in the default mailer (e.g. Outlook) ready to edit and post. Maybe a Unix version would also be nice, e.g. browseURL(mailto:[EMAIL PROTECTED] bugbody=%0Ainsert bug report here%0A%0A%0A%0A--please do not edit the information below--%0A%0AVersion:%0A platform = x86_64-unknown-linux-gnu%0A ...) would open the post template in e.g. Thunderbird, but has the side effect of opening an empty page in the web browser. I don't know if there's a neater solution? The create.post() function is basically the old bug.report() with two extra arguments: 'description' (e.g. bug report) and 'instructions' (e.g. \\nType your message here\\n) for customization. It could be used directly e.g to post to R-devel with session information. The new bug.report() simply calls create.post() with the appropriate arguments. The improved help-request() function calls create.post() after running through the checks described before. In response to Gabor's comments, help.request(): - now checks packages are up-to-date and gives option to update on-the-fly (user may not know whether involved in query, so check all) - keeps default mailing options as in old bug.report() but create.post() gives clearer message (Email the post now?\n (yes/no)) requiring definite response (yes vs y) - still uses online documents because some are only available online (R Site Search, posting guide), it ensures the most up-to-date documentation is used, and it allows direction to global FAQ page, avoiding need to check whether user is on Windows/Mac - uses more robust method of checking R version is up-to-date I've also written a help file for help.request() which includes the method=mailto option. The help file for bug.report would need updating if this option was kept. Best wishes, Heather Martin Maechler wrote: HT == Heather Turner [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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
Re: [Rd] Posting Guide - help.request() function?
HT == Heather Turner [EMAIL PROTECTED]
on Wed, 11 Jun 2008 12:50:49 +0100 writes:
HT Okay, here's the update.
HT I've created a new function create.post() (with Windows and Unix
HT versions) which would be the internal function that creates the post
HT template ready to edit and optionally send. In the Windows version I've
HT added an experimental method == mailto option, which will open the
HT post template in the default mailer (e.g. Outlook) ready to edit and
HT post. Maybe a Unix version would also be nice, e.g.
HT browseURL(mailto:[EMAIL PROTECTED] bugbody=%0Ainsert
HT bug report here%0A%0A%0A%0A--please do not edit the information
HT below--%0A%0AVersion:%0A platform = x86_64-unknown-linux-gnu%0A ...)
HT would open the post template in e.g. Thunderbird, but has the side
HT effect of opening an empty page in the web browser. I don't know if
HT there's a neater solution?
Well, the current solution {for bug.report()} seems quite
desirable to me on unix.
HT The create.post() function is basically the old bug.report() with two
HT extra arguments: 'description' (e.g. bug report) and 'instructions'
HT (e.g. \\nType your message here\\n) for customization. It could
be
HT used directly e.g to post to R-devel with session information.
HT The new bug.report() simply calls create.post() with the appropriate
HT arguments.
Thank you; that's a really nice example of code reuse!
HT The improved help-request() function calls create.post() after running
HT through the checks described before.
HT In response to Gabor's comments, help.request():
HT - now checks packages are up-to-date and gives option to update
HT on-the-fly (user may not know whether involved in query, so check all)
This is a bit problematic as now.
E.g., we have about 1500 packages installed, and inspite of automatic
updating, never all are current, and the updating should typically
not happen on a user (but a site-wide) level anyway.
Also, the call to old.packages() takes minutes (the
first time in an R session) if you have so many packages in a
dozen libraries.
This should really not interfere with an e-mail for help,
rather I think that the packages-up-to-date check
should only happen for those non-standard packages that are
currently in use as from sessionInfo().
Unfortunately, that functionality to do that is not yet there
in old.packages(), but I am about to add that option to R-devel
as well.
No need to send me a new version of your code, BTW, since I have
already worked on it in several places.
HT - keeps default mailing options as in old bug.report() but
HT create.post() gives clearer message (Email the post now?\n (yes/no))
HT requiring definite response (yes vs y)
ok.
HT - still uses online documents because some are only available online
HT (R Site Search, posting guide), it ensures the most up-to-date
HT documentation is used, and it allows direction to global FAQ page,
HT avoiding need to check whether user is on Windows/Mac
HT - uses more robust method of checking R version is up-to-date
HT I've also written a help file for help.request() which includes the
HT method=mailto option.
ok {it did need some correction}.
HT The help file for bug.report would need updating
HT if this option was kept.
I think this is mainly a windows feature (but maybe not).
I'd definitely like to get some feedback from Windows users
about this.
HT Best wishes,
HT Heather
Thanks again, Heather, for this.
This is becoming a very nice new feature!
Martin
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Posting Guide - help.request() function?
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 = [EMAIL PROTECTED],
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 [EMAIL PROTECTED] 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(\\nWrite your query here, using your example code
to illustrate,
\\nEnd 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 =
Re: [Rd] Posting Guide - help.request() function?
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
[EMAIL PROTECTED] 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 = [EMAIL PROTECTED],
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 [EMAIL PROTECTED] directly. ,
\nOtherwise prepare some example code
Re: [Rd] Posting Guide - help.request() function?
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
[EMAIL PROTECTED] 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 = [EMAIL PROTECTED],
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
Re: [Rd] Posting Guide - help.request() function?
HT == Heather Turner [EMAIL PROTECTED]
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
[EMAIL PROTECTED] 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 = [EMAIL PROTECTED], 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))) } }
