knit readme

README.md

@@ -24,7 +24,7 @@ You can install patchwork from github with:
 devtools::install_github("thomasp85/patchwork")
 ```
 
-## Example
+## Basic example
 
 The usage of `patchwork` is simple: just add plots together\!
 
@@ -40,7 +40,7 @@ p1 + p2
 
 ![](man/figures/README-example-1.png)<!-- -->
 
-you are of course free to also add the plots together as part of the
+You are of course free to also add the plots together as part of the
 same plotting operation:
 
 ``` r
@@ -52,9 +52,11 @@ ggplot(mtcars) +
 
 ![](man/figures/README-unnamed-chunk-2-1.png)<!-- -->
 
-layouts can be specified by adding a `plot_layout()` call to the
+## Layout and nesting
+
+Layouts can be specified by adding a `plot_layout()` call to the
 assemble. This lets you define the dimensions of the grid and how much
-space to allocate to the different rows and columns
+space to allocate to the different rows and columns.
 
 ``` r
 p1 + p2 + plot_layout(ncol = 1, heights = c(3, 1))
@@ -63,7 +65,7 @@ p1 + p2 + plot_layout(ncol = 1, heights = c(3, 1))
 ![](man/figures/README-unnamed-chunk-3-1.png)<!-- -->
 
 If you need to add a bit of space between your plots you can use
-`plot_spacer()` to fill a cell in the grid with nothing
+`plot_spacer()` to fill a cell in the grid with nothing.
 
 ``` r
 p1 + plot_spacer() + p2
@@ -72,8 +74,8 @@ p1 + plot_spacer() + p2
 ![](man/figures/README-unnamed-chunk-4-1.png)<!-- -->
 
 You can make nested plots layout by wrapping part of the plots in
-parentheses - in these cases the layout is scoped to the different
-nesting levels
+parentheses. In this case the layout is scoped to the different nesting
+levels.
 
 ``` r
 p3 <- ggplot(mtcars) + geom_smooth(aes(disp, qsec))
@@ -91,49 +93,62 @@ p4 + {
 
 ![](man/figures/README-unnamed-chunk-5-1.png)<!-- -->
 
+## Annotating Plots
+
+In many cases, one doesn’t want to just assemble plots together, but
+also **label** them or `annotate` them enabling one to easily refer to
+each piece, as well as adding titles to the whole. Enter the
+`plot_annotation` function
+
+``` r
+p1 + p2 + plot_annotation(title = "A great plot!", tag_levels = "A")
+```
+
+![](man/figures/README-unnamed-chunk-6-1.png)<!-- -->
+
 ### Advanced features
 
 In addition to adding plots and layouts together, `patchwork` defines
-some other operators that might be of interest. `-` will behave like `+`
-but put the left and right side in the same nesting level (as opposed to
-putting the right side into the left sides nesting level). Observe:
+some other operators that might be of interest. `-` behaves like `+` but
+puts the left and right side in the same nesting level (as opposed to
+putting the right side into the left side’s nesting level). Observe:
 
 ``` r
 p1 + p2 + p3 + plot_layout(ncol = 1)
 ```
 
-![](man/figures/README-unnamed-chunk-6-1.png)<!-- -->
+![](man/figures/README-unnamed-chunk-7-1.png)<!-- -->
 
-this is basically the same as without braces (just like standard math
+This is basically the same as without braces (just like standard math
 arithmetic) - the plots are added sequentially to the same nesting
-level. Now look:
+level. Now consider:
 
 ``` r
 p1 + p2 - p3 + plot_layout(ncol = 1)
 ```
 
-![](man/figures/README-unnamed-chunk-7-1.png)<!-- -->
+![](man/figures/README-unnamed-chunk-8-1.png)<!-- -->
 
-Now `p1 + p2` and `p3` is on the same level…
+Now `p1 + p2` and `p3` are on the same level…
 
-> A note on semantics. If `-` is read as *subtract* its use makes little
-> sense as we are not removing plots. Think of it as a hyphen instead…
+> A note on semantics. If `-` is read as *minus* its use makes little
+> sense as we are not removing plots. Think of it as a *hyphen* instead…
 
 Often you are interested in just putting plots besides or on top of each
 other. `patchwork` provides both `|` and `/` for horizontal and vertical
-layouts respectively. They can of course be combined for a very readable
-layout syntax:
+layouts respectively. They can, of course, be combined for a very
+readable layout syntax:
 
 ``` r
 (p1 | p2 | p3) /
       p4
 ```
 
-![](man/figures/README-unnamed-chunk-8-1.png)<!-- -->
+![](man/figures/README-unnamed-chunk-9-1.png)<!-- -->
 
 There are two additional operators that are used for a slightly
 different purpose, namely to reduce code repetition. Consider the case
-where you want to change the theme for all plots in an assemble. Instead
+where you want to change the theme for all plots in an assembly. Instead
 of modifying all plots individually you can use `&` or `*` to add
 elements to all subplots. The two differ in that `*` will only affect
 the plots on the current nesting level:
@@ -142,19 +157,19 @@ the plots on the current nesting level:
 (p1 + (p2 + p3) + p4 + plot_layout(ncol = 1)) * theme_bw()
 ```
 
-![](man/figures/README-unnamed-chunk-9-1.png)<!-- -->
+![](man/figures/README-unnamed-chunk-10-1.png)<!-- -->
 
 whereas `&` will recurse into nested levels:
 
 ``` r
 p1 + (p2 + p3) + p4 + plot_layout(ncol = 1) & theme_bw()
 ```
 
-![](man/figures/README-unnamed-chunk-10-1.png)<!-- -->
+![](man/figures/README-unnamed-chunk-11-1.png)<!-- -->
 
-> Note that parenthesis is required in the former case due to higher
-> precedence of the `*` operator. The latter case is the most common so
-> it has deserved the easiest use.
+> Note that parentheses are required in the former case due to the
+> higher precedence of the `*` operator. The latter case is the most
+> common so it deserves the easiest use.
 
-This is all it does for now, but stay tuned as more functionality is
-added, such as collapsing guides, etc…
+This is all `patchwork` does for now, but stay tuned as more
+functionality is added, such as collapsing guides, etc…