demo.rmd

---
layout: default
title: Demos
output: bookdown::html_chapter
---

## Demos {#demo}

A demo is an `.R` file that lives in `demo/`. Demos are like examples, but tend to be longer, and instead of focussing on a single function, 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 form: `demo-name  Demo description`. The demo name is the name of the file without extension, e.g. `demo/my-demo.R` becomes `my-demo`.

By default the demo ask for human input for each plot: "Hit <Return> to see next plot: " . 
This behaviour can be overwritten by adding `devAskNewPage(ask=F)` to the demo file.
You can then add pauses by adding lines like: `readline("press any key to continue")`.


Generally, I do not recommend using demos. Instead write a vignette:

* Demos are not automatically run by `R CMD check`. This means that they're
  not tested automatically, so can easily break without you realising.

* Vignettes have both input and output, so readers can see the results 
  without running the code themselves.

* Longer demos need to mingle code with explanation, and RMarkdown is a better
  tool for that than R comments.

* Vignettes are listed on the CRAN package page. That makes it easier for 
  new users to find out about them.