misc.rmd

---
layout: default
title: Other components
output: oldbookdown::html_chapter
---

# Other components {#misc}

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][internationalization] chapter of 
  "R extensions" for more details.

* `tools/`: auxiliary files needed during configuration, or for sources that need
  to generate scripts.

## Demos {#demo}

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 <Return> 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.


[internationalization]:http://cran.rstudio.com/doc/manuals/r-devel/R-exts.html#Internationalization