forked from hadley/r-pkgs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
misc.Rmd
133 lines (89 loc) · 6.24 KB
/
misc.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
# Other components {#sec-misc}
```{r, echo = FALSE}
source("common.R")
status("restructuring")
```
## Introduction
There are five other directories that are valid top-level directories.
They are rarely used:
- `inst/`: for arbitrary additional files that you want include in your package.
This includes a few special files, like the `CITATION`, described below.
- `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](https://cran.rstudio.com/doc/manuals/r-devel/R-exts.html#Internationalization) chapter of "R extensions" for more details.
- `tools/`: auxiliary files needed during configuration, or for sources that need to generate scripts.
## Installed files {#inst}
When a package is installed, everything in `inst/` is copied into the top-level package directory.
In some sense `inst/` is the opposite of `.Rbuildignore` - where `.Rbuildignore` lets you remove arbitrary files and directories from the top level, `inst/` lets you add them.
You are free to put anything you like in `inst/` with one caution: because `inst/` is copied into the top-level directory, you should never use a subdirectory with the same name as an existing directory.
This means that you should avoid `inst/build`, `inst/data`, `inst/demo`, `inst/exec`, `inst/help`, `inst/html`, `inst/inst`, `inst/libs`, `inst/Meta`, `inst/man`, `inst/po`, `inst/R`, `inst/src`, `inst/tests`, `inst/tools` and `inst/vignettes`.
This chapter discusses the most common files found in `inst/`:
- `inst/AUTHOR` and `inst/COPYRIGHT`.
If the copyright and authorship of a package is particularly complex, you can use plain text files, `inst/COPYRIGHTS` and `inst/AUTHORS`, to provide more information.
- `inst/CITATION`: how to cite the package, see below for details.
- `inst/docs`: This is an older convention for vignettes, and should be avoided in modern packages.
- `inst/extdata`: additional external data for examples and vignettes.
See @sec-data-extdata for more detail.
- `inst/java`, `inst/python` etc.
See below.
To find a file in `inst/` from code use `system.file()`.
For example, to find `inst/extdata/mydata.csv`, you'd call `system.file("extdata", "mydata.csv", package = "mypackage")`.
Note that you omit the `inst/` directory from the path.
This will work if the package is installed, or if it's been loaded with `devtools::load_all()`.
### Package citation {#inst-citation}
The `CITATION` file lives in the `inst` directory and is intimately connected to the `citation()` function which tells you how to cite R and R packages.
Calling `citation()` without any arguments tells you how to cite base R:
```{r}
citation()
```
Calling it with a package name tells you how to cite that package:
```{r}
citation("lubridate")
```
To customise the citation for your package, add a `inst/CITATION` that looks like this:
```{r, echo = FALSE, comment = ""}
citation <- readLines(system.file("CITATION", package = "lubridate"))
cat(citation, sep = "\n")
```
You need to create `inst/CITATION`.
As you can see, it's pretty simple: you only need to learn one new function, `citEntry()`.
The most important arguments are:
- `entry`: the type of citation, "Article", "Book", "PhDThesis" etc.
- The standard bibliographic information like `title`, `author` (which should be a `personList()`), `year`, `journal`, `volume`, `issue`, `pages`, ...
A complete list of arguments can be found in `?bibentry`.
Use `citHeader()` and `citFooter()` to add additional exhortations.
### Other languages {#sec-inst-other-langs}
Sometimes a package contains useful supplementary scripts in other programming languages.
Generally, you should avoid these, because it adds an additional extra dependency, but it may be useful when wrapping substantial amounts of code from another language.
For example, [gdata](https://cran.r-project.org/web/packages/gdata/index.html) wraps the Perl module [Spreadsheet::ParseExcel](https://search.cpan.org/~dougw/Spreadsheet-ParseExcel-0.65/) to read excel files into R.
The convention is to put scripts of this nature into a subdirectory of `inst/`, `inst/python`, `inst/perl`, `inst/ruby` etc.
If these scripts are essential to your package, make sure you also add the appropriate programming language to the `SystemRequirements` field in the `DESCRIPTION`.
(This field is for human reading so don't worry about exactly how you specify it.)
Java is a special case and the best place to learn more is the documentation of the rJava package (<http://www.rforge.net/rJava/>).
## 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.