[R-pkg-devel] Fwd: R CMD check and strange ## Not run strings

[Tomas Hudik]

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.boshnakov at 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-bounces at r-project.org] On
> Behalf Of Tomas Hudik
> Sent: 18 December 2017 13:38
> To: r-package-devel at 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 at r-project.org mailing list https://stat.ethz.ch/mailman/
> listinfo/r-package-devel
>

	[[alternative HTML version deleted]]