[R] Demo files in R packages

[Duncan Murdoch]

On 2026-01-25 4:39 p.m., Michael L Friendly wrote:
> One thing I'd like to do is to use `demo(package="mypkg")` in the 
> README.Rmd file for `mypkg`.
> Currently, this opens up an editor window in RStudio. But I don't know 
> how to capture this for inclusion in the README. It returns an object of 
> class “packageIQR” which I’ve never heard of
> demo(package = "vcdExtra") |> class()
> [1] "packageIQR"
> demo(package="vcdExtra")

If you run `unclass(demo(package="vcdExtra"))` you can see the 
(undocumented?) structure of a packageIQR object.  It's pretty simple:
a list with a few labels, and a "results" matrix with information about 
the demos.  You could print it using

   demo(package="vcdExtra")$results

or just the interesting bits with

   demo(package="vcdExtra")$results[,3:4]

Duncan Murdoch

> -----Original Message-----
> From: Koenker, Roger W <rkoenker using illinois.edu>
> Sent: January 25, 2026 3:53 PM
> To: Michael L Friendly <friendly using yorku.ca>
> Cc: Duncan Murdoch <murdoch.duncan using gmail.com>; R-help using r-project.org
> Subject: Re: [R] Demo files in R packages
> I too find demos quite useful, particularly for my REBayes package for 
> which documented examples are useless since CRAN checking doesn’t or at 
> least didn’t have an installed Mosek capability.  I’ve taken to adding 
> references to them in the body of the roxyen2 documentation but this is 
> a bit hit or miss.  Fortunately, as Micheal says demo(package = “foo”) 
> still works provided that users are aware of it.  I would also be 
> interested in other creative solutions to make them more visible.
> Roger
>> On Jan 25, 2026, at 10:44 AM, Michael L Friendly <friendly using yorku.ca <mailto:friendly using yorku.ca>> wrote:
>> 
>> I know I can put them into a vignette, but the advantage of demo files is that you can run them using demo().
>> It just seems like the facilities for demo files were abandoned.
>> 
>> -Michael
>> 
>> 
>> 
>> -----Original Message-----
>> From: Duncan Murdoch <murdoch.duncan using gmail.com <mailto:murdoch.duncan using gmail.com>>
>> Sent: January 24, 2026 6:02 PM
>> To: Michael L Friendly <friendly using yorku.ca <mailto:friendly using yorku.ca>>; R-help using r-project.org 
> <mailto:R-help using r-project.org>
>> Subject: Re: [R] Demo files in R packages
>> 
>> On 2026-01-24 4:49 p.m., Michael L Friendly wrote:
>>> Before vignettes were established as a way to document a package, there were demos, R files in a `demo/` folder with a `demo/00-Index` file giving their contents.
>>> Used as `demo(package="...")` this gave a window with a list and titles, and `demo("example1", package="...") ran `demo/example1.R` in the console.
>>> It was also a good way to give a pointer to something more extensive than you wanted to include in the examples for a function or dataset.
>>> 
>>> This idea still works for R packages, but is not available for use in roxygen2 documentation, or pkgdown sites.
>>> I have several packages with collections of demo/ files, and am wondering if there is anything further I can do with them to make them accessible.
>> 
>> I converted most of my demo files in rgl to a single vignette.  I just 
>> added a simple paragraph
>> 
>>> This vignette holds code that was previously included as "demos" 
>>> in `rgl`.  Some of the demos require R to be running; those remain 
>>> available via `demo(package = "rgl")`.
>> 
>> As the second sentence indicates, rgl still has a few demos, mostly Shiny examples.
>> 
>> Conversion was simple:  just copy the title into a heading, and include all the code.
>> 
>> Duncan Murdoch
>> ______________________________________________
>> R-help using r-project.org <mailto:R-help using r-project.org> mailing list -- To 
> UNSUBSCRIBE and more, see
>> https://urldefense.com/v3/__https://stat.ethz.ch/mailman/listinfo/r-he 
> <https://urldefense.com/v3/__https://stat.ethz.ch/mailman/listinfo/r-he>
>> lp__;!!DZ3fjg!9JAEtHwhqq2bhNITvwUxzNd_yVeNP1ijh99HnlVKpoq55zBGZ-Qvbs1r
>> 0tjCqVsbM4Or3_Lx9QWFluvaLBYLQg$ PLEASE do read the posting guide 
>> https://urldefense.com/v3/__https://www.R-project.org/posting-guide.ht 
> <https://urldefense.com/v3/__https://www.R-project.org/posting-guide.ht>
>> ml__;!!DZ3fjg!9JAEtHwhqq2bhNITvwUxzNd_yVeNP1ijh99HnlVKpoq55zBGZ-Qvbs1r
>> 0tjCqVsbM4Or3_Lx9QWFluvwC65ABA$ and provide commented, minimal, 
>> self-contained, reproducible code.