Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
Hi,
thank you guys for fast replies - good ideas and points! They completely
makes sense.
@Georgi - yes, the rendering is the issue. I personally find \dontrun{}
better understandable then rendered ## Not Run.
Maybe even better would be to have rendered "r-markdown kind" where you can
click on a small triangle icon(
http://rmarkdown.rstudio.com/r_notebooks.html#executing_code) and the
example would run for you. So user can:
1. run the code when he wants
2. wont have to think whether ## Not run is a comment or some kind of
escape or special command (my case 3 days before)
I understand "r-markdown kind" rendering would be possible in GUI apps only
(Rstudio). The question is how to do it on R core (command line) level.
what do you think?
best, Tomas
On Tue, Dec 19, 2017 at 11:20 PM, Georgi Boshnakov <
georgi.boshna...@manchester.ac.uk> wrote:
> Sure, but \dontrun's function is to prevent the R tools from running the
> enclosed code.
>
> How it is rendered is a completely separate matter. The code in \dontrun
> is not required to be executable (or even valid R code), so surely there
> should be some sort of visual clue in the rendered page. I don't argue
> whether it should be the one shown now or should be left entirely to the
> package author, although the current one seems reasonable to me.
>
> Georgi
>
>
> -Original Message-
> From: Hadley Wickham [mailto:h.wick...@gmail.com]
> Sent: 19 December 2017 19:22
> To: Georgi Boshnakov
> Cc: Tomas Hudik; r-package-devel@r-project.org
> Subject: Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
>
> > This actually is not about Rd format. Indeed, you are using 'roxygen'
> syntax.
>
> This is unrelated to roxygen. \dontrun{} is Rd formatting.
>
> Hadley
>
> --
> http://hadley.nz
>
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
On 19/12/2017 5:20 PM, Georgi Boshnakov wrote:
Sure, but \dontrun's function is to prevent the R tools from running the
enclosed code.
How it is rendered is a completely separate matter. The code in \dontrun is
not required to be executable (or even valid R code), so surely there should be
some sort of visual clue in the rendered page. I don't argue whether it should
be the one shown now or should be left entirely to the package author, although
the current one seems reasonable to me.
What you say in no way contradicts what Hadley said. He's complaining
about your earlier message blaming roxygen for this. He's right, this
isn't a roxygen issue, it's a general R help page issue. However:
I'm finding it quite amazing that this thread has gone on as long as it
has. I think you suggested that package authors should add comments to
their code explaining why they asked not to run some lines. That's such
a sensible suggestion that it should have ended the thread.
Duncan Murdoch
Georgi
-Original Message-
From: Hadley Wickham [mailto:h.wick...@gmail.com]
Sent: 19 December 2017 19:22
To: Georgi Boshnakov
Cc: Tomas Hudik; r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
This actually is not about Rd format. Indeed, you are using 'roxygen' syntax.
This is unrelated to roxygen. \dontrun{} is Rd formatting.
Hadley
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
Sure, but \dontrun's function is to prevent the R tools from running the
enclosed code.
How it is rendered is a completely separate matter. The code in \dontrun is
not required to be executable (or even valid R code), so surely there should be
some sort of visual clue in the rendered page. I don't argue whether it should
be the one shown now or should be left entirely to the package author, although
the current one seems reasonable to me.
Georgi
-Original Message-
From: Hadley Wickham [mailto:h.wick...@gmail.com]
Sent: 19 December 2017 19:22
To: Georgi Boshnakov
Cc: Tomas Hudik; r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
> This actually is not about Rd format. Indeed, you are using 'roxygen'
> syntax.
This is unrelated to roxygen. \dontrun{} is Rd formatting.
Hadley
--
http://hadley.nz
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
> This actually is not about Rd format. Indeed, you are using 'roxygen'
> syntax.
This is unrelated to roxygen. \dontrun{} is Rd formatting.
Hadley
--
http://hadley.nz
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
… and my point was that it is not a matter of syntax, but that the user would
better be alerted.
A user would be more confused and even irritated if they run an example and get
surprises (such as having to wait a long time) or not getting any wiser.
The example you cite falls into the category of ‘template examples’ - it is
not really meant to be run as is.
You almost certainly will never encounter message 12345, for example. In
fact, it would probably give error. This is a nice illustration of the
usefulness of ‘Not run’ to give a sort of warning.
I bet that the package you have taken it from contains similar examples in
other places, so a user will become aware of this.
Merry Christmas,
Georgi
From: Tomas Hudik [mailto:xhu...@gmail.com]
Sent: 19 December 2017 16:02
To: Georgi Boshnakov
Cc: r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
Yes, I used oxygen. My point was that a majority of users is not familiar
Rd/oxygen and if somebody sees something like:
```
Examples
## Not run:
modify_message(12345, add_labels='label_1')
modify_message(12345, remove_labels='label_1')
#add and remove at the same time
modify_message(12345, add_labels='label_2', remove_labels='label_1')
## End(Not run)
```
he will be pretty much confused and will not get that it is because of a
special example that couldnt run for any reason.
Whether example run during package compilation might be important for package
creator but not so much for a regular user.
Therefore I think the question is whether a standard user needs to know whether
some code in help page run during the package compilation.
my 2c, Tomas
On Mon, Dec 18, 2017 at 8:07 PM, Georgi Boshnakov
<georgi.boshna...@manchester.ac.uk<mailto:georgi.boshna...@manchester.ac.uk>>
wrote:
Hi,
This actually is not about Rd format. Indeed, you are using 'roxygen' syntax.
Examples are not run when there is a good reason (long time, internet
connection required, specific local resources). This often means that the user
needs to be made aware that something is not as straightforward as usual.
A better question would probably be "Is there a better way to alert the user
that the example is somehow special?" Maybe, but it is difficult to beat "Not
run" for brevity and native English speakers would probably have come forward
with a better replacement.
Also, adding a note (in a comment before the example) as to way an example is
not run can be of benefit to both the user and the package author. Even if it
is obvious at the time of writing, it may not be so months or years later.
Kind regards,
Georgi Boshnakov
-Original Message-
From: R-package-devel
[mailto:r-package-devel-boun...@r-project.org<mailto:r-package-devel-boun...@r-project.org>]
On Behalf Of Tomas Hudik
Sent: 18 December 2017 13:38
To: r-package-devel@r-project.org<mailto:r-package-devel@r-project.org>
Subject: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
Hi there,
If I write a function with documentation (notice `\dontrun` section)
#' Print a string.
#'
#' @examples
#' \dontrun{
#' str_length(letters)
#'}
print_str <- function(str) {
print(string)
}
`roxygenize()` will create proper Rd file, however, `R CMD check .` will
generate:
```
...
## Not run:
str_length(letters)
## End(Not run)
```
If a person not familiar with Rd (majority of people) see such example, I do
think he will be confused.
Question - wouldnt be good to remove `## NOT run` strings by default (
https://github.com/wch/r-source/blob/af7f52f70101960861e5d995d3a4be
c010bc89e6/src/library/tools/R/Rd2latex.R#L238
)
E.g. see https://cran.r-project.org/web/packages/gmailr/gmailr.pdf - and go
through example sections. There is not many people who would know what those
cryptic `## Not Run` strings mean.
thanks, Tomas
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org<mailto:R-package-devel@r-project.org> mailing
list https://stat.ethz.ch/mailman/listinfo/r-package-devel
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
Yes, I used oxygen. My point was that a majority of users is not familiar
Rd/oxygen and if somebody sees something like:
```
Examples
## Not run:
modify_message(12345, add_labels='label_1')
modify_message(12345, remove_labels='label_1')
#add and remove at the same time
modify_message(12345, add_labels='label_2', remove_labels='label_1')
## End(Not run)
```
he will be pretty much confused and will not get that it is because of a
special example that couldnt run for any reason.
Whether example run during package compilation might be important for
package creator but not so much for a regular user.
Therefore I think the question is whether a standard user needs to know
whether some code in help page run during the package compilation.
my 2c, Tomas
On Mon, Dec 18, 2017 at 8:07 PM, Georgi Boshnakov <
georgi.boshna...@manchester.ac.uk> wrote:
> Hi,
>
> This actually is not about Rd format. Indeed, you are using 'roxygen'
> syntax.
>
> Examples are not run when there is a good reason (long time, internet
> connection required, specific local resources). This often means that the
> user needs to be made aware that something is not as straightforward as
> usual.
>
> A better question would probably be "Is there a better way to alert the
> user that the example is somehow special?" Maybe, but it is difficult to
> beat "Not run" for brevity and native English speakers would probably have
> come forward with a better replacement.
>
> Also, adding a note (in a comment before the example) as to way an
> example is not run can be of benefit to both the user and the package
> author. Even if it is obvious at the time of writing, it may not be so
> months or years later.
>
> Kind regards,
> Georgi Boshnakov
>
> -Original Message-
> From: R-package-devel [mailto:r-package-devel-boun...@r-project.org] On
> Behalf Of Tomas Hudik
> Sent: 18 December 2017 13:38
> To: r-package-devel@r-project.org
> Subject: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
>
> Hi there,
>
> If I write a function with documentation (notice `\dontrun` section)
>
> #' Print a string.
> #'
> #' @examples
> #' \dontrun{
> #' str_length(letters)
> #'}
> print_str <- function(str) {
> print(string)
> }
>
> `roxygenize()` will create proper Rd file, however, `R CMD check .` will
> generate:
> ```
> ...
> ## Not run:
> str_length(letters)
> ## End(Not run)
> ```
>
> If a person not familiar with Rd (majority of people) see such example, I
> do think he will be confused.
> Question - wouldnt be good to remove `## NOT run` strings by default (
> https://github.com/wch/r-source/blob/af7f52f70101960861e5d995d3a4be
> c010bc89e6/src/library/tools/R/Rd2latex.R#L238
> )
>
> E.g. see https://cran.r-project.org/web/packages/gmailr/gmailr.pdf - and
> go through example sections. There is not many people who would know what
> those cryptic `## Not Run` strings mean.
>
>
> thanks, Tomas
>
> [[alternative HTML version deleted]]
>
> __
> R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/
> listinfo/r-package-devel
>
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
Hi,
This actually is not about Rd format. Indeed, you are using 'roxygen' syntax.
Examples are not run when there is a good reason (long time, internet
connection required, specific local resources). This often means that the user
needs to be made aware that something is not as straightforward as usual.
A better question would probably be "Is there a better way to alert the user
that the example is somehow special?" Maybe, but it is difficult to beat "Not
run" for brevity and native English speakers would probably have come forward
with a better replacement.
Also, adding a note (in a comment before the example) as to way an example is
not run can be of benefit to both the user and the package author. Even if it
is obvious at the time of writing, it may not be so months or years later.
Kind regards,
Georgi Boshnakov
-Original Message-
From: R-package-devel [mailto:r-package-devel-boun...@r-project.org] On Behalf
Of Tomas Hudik
Sent: 18 December 2017 13:38
To: r-package-devel@r-project.org
Subject: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings
Hi there,
If I write a function with documentation (notice `\dontrun` section)
#' Print a string.
#'
#' @examples
#' \dontrun{
#' str_length(letters)
#'}
print_str <- function(str) {
print(string)
}
`roxygenize()` will create proper Rd file, however, `R CMD check .` will
generate:
```
...
## Not run:
str_length(letters)
## End(Not run)
```
If a person not familiar with Rd (majority of people) see such example, I do
think he will be confused.
Question - wouldnt be good to remove `## NOT run` strings by default (
https://github.com/wch/r-source/blob/af7f52f70101960861e5d995d3a4be
c010bc89e6/src/library/tools/R/Rd2latex.R#L238
)
E.g. see https://cran.r-project.org/web/packages/gmailr/gmailr.pdf - and go
through example sections. There is not many people who would know what those
cryptic `## Not Run` strings mean.
thanks, Tomas
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
