There are four other directories that are valid top-level directories. They are rarely used:
demo/: for package demos. These were useful prior to the introduction of vignettes, but are no longer recommended. See below.
exec/: for executable scripts. Unlike files placed in other directories, files in
exec/are automatically flagged as executable.
po/: translations for messages. This is useful but beyond the scope of this book. See the Internationalization chapter of “R extensions” for more details.
tools/: auxiliary files needed during configuration, or for sources that need to generate scripts.
A demo is an
.R file that lives in
demo/. Demos are like examples but tend to be longer. Instead of focussing on a single function, they show how to weave together multiple functions to solve a problem.
You list and access demos with
- Show all available demos:
- Show all demos in a package:
demo(package = "httr").
- Run a specific demo:
demo("oauth1-twitter", package = "httr").
- Find a demo:
system.file("demo", "oauth1-twitter.R", package = "httr").
Each demo must be listed in
demo/00Index in the following form:
demo-name Demo description. The demo name is the name of the file without the extension, e.g.
By default the demo asks for human input for each plot: “Hit
devAskNewPage(ask = FALSE) to the demo file.
You can add pauses by adding:
readline("press any key to continue").
Generally, I do not recommend using demos. Instead, consider writing a vignette:
Demos are not automatically tested by
R CMD check. This means that they can easily break without your knowledge.
Vignettes have both input and output, so readers can see the results without having to run the code themselves.
Longer demos need to mingle code with explanation, and RMarkdown is better suited to that task than R comments.
Vignettes are listed on the CRAN package page. This makes it easier for new users to discover them.