Chapter 15 Other components

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.

15.1 Demos

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 demo():

  • Show all available demos: demo().
  • 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. demo/my-demo.R becomes my-demo.

By default the demo asks for human input for each plot: “Hit to see next plot:”. This behaviour can be overridden by adding 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.