Tweaking rmarkdown intro

rmarkdown-demos/1-example.Rmd

@@ -3,7 +3,7 @@ title: "Viridis Demo"
 output: html_document
 ---
 
-```{r include = FALSE}
+```{r setup, include = FALSE}
 library(viridis)
 ```
 

rmarkdown-demos/rmarkdown-demos.Rproj

@@ -0,0 +1,16 @@
+Version: 1.0
+
+RestoreWorkspace: Default
+SaveWorkspace: Default
+AlwaysSaveHistory: Default
+
+EnableCodeIndexing: Yes
+UseSpacesForTab: Yes
+NumSpacesForTab: 2
+Encoding: UTF-8
+
+RnwWeave: knitr
+LaTeX: XeLaTeX
+
+AutoAppendNewline: Yes
+StripTrailingWhitespace: Yes

rmarkdown.Rmd

@@ -2,21 +2,26 @@
 
 ## Introduction
 
-R Markdown provides an unified authoring framework for data science. R Markdown documents are fully reproducible and support dozens of output formats, like PDFs, Word files, slideshows, and more. They also provide a useful notebook interface for R and are easy to track with version control software like git.
+R Markdown provides an unified authoring framework for data science, combining your code, its results, and your prose commentary. R Markdown documents are fully reproducible and support dozens of output formats, like PDFs, Word files, slideshows, and more. RMarkdown files are designed to be used in two ways:
 
-R Markdown documents rely on several technologies that go beyond R functions. To help you navigate these, the developers of RStudio have placed three R Markdown references in the RStudio IDE.
+1.  To produce a final report that you can share with others.
 
-* Go to *File > Help > Cheatsheets > R Markdown Cheat Sheet* to open the main *[R Markdown Cheat Sheet](http://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)*.
+1.  As a notebook, which allows yout to mingle prose, code, and output during 
+    your own analyses.
 
-* Go to *File > Help > Cheatsheets > R Markdown Reference Guide* to open the main *[R Markdown Reference Guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf)*.
+The name R Markdown is slightly misleading because you can use it with other languages, not just R. R Markdown has recently added support for Python and SQL, and that support will improve over time. To use a different language in code chunk, just replace the `r` in  ```` ```{r} ```` with `python` or `sql`. We'll focus on R here, for obvious reasons!
 
-* Go to *File > Help > Markdown Quick Reference* to open the *Markdown Quick Reference* in your help pane.
+R Markdown integrates a number of R packages and external tools. This means that helps is, by-and-large, not available through `?`. Instead, as you work through chapter, and use R Markdown in the future, keep these resouces close to hand:
 
-(Note that the name RMarkdown is slightly misleading because you can use it with other languages, not just R. RMarkdown has recently added support for Python and SQL, and that support will improve over time. To use a different language in code chunk, just replace the `r` in  ```` ```{r} ```` with `python` or `sql`.)
+* R Markdown Cheat Sheet: *File > Help > Cheatsheets > R Markdown Cheat Sheet*,
+* R Markdown Reference Guide: *File > Help > Cheatsheets > R Markdown Reference Guide*.
+* Markdown Quick Reference: *File > Help > Markdown Quick Reference*.
+
+You can also download these from <http://rstudio.com/cheatsheets>.
 
 ### Prerequisites
 
-You will need the __rmarkdown__ package, but RStudio will automatically install it for you, and load it when needed.
+You need the __rmarkdown__ package, but you don't need to explicit install it or load it, as RStudio automatically does both when needed.
 
 ```{r setup, include = FALSE}
 chunk <- "```"
@@ -30,47 +35,33 @@ This is an R Markdown file, a plain text file that has the extension `.Rmd`:
 cat(htmltools::includeText("rmarkdown-demos/1-example.Rmd"))
 ```
 
-It contains three types of content: 
+It contains three important types of content:
 
 1.  An (optional) __YAML header__ surrounded by `---`s.
 1.  __Chunks__ of R code surrounded by ```` ``` ````.
 1.  Text mixed with simple text formatting like `##` and .
 
-RMarkdown files are designed to be used in two ways:
-
-1.  In __notebook__ mode, to provide a convenient way to mingle prose, 
-    code, and output during an analysis.
-    
-1.  To produce a final report by __rendering__ the document to produce a HTML,
-    PDF, or word file.
-
 When you open an `.Rmd` you get a notebook interface for R. You can run each code chunk by clicking the Run icon (it looks like a play button at the top of the chunk), or by pressing Cmd/Ctrl + Shift + Enter. RStudio executes the code and displays the results inline with your file.
 
 ```{r, echo = FALSE, out.width = "100%"}
-knitr::include_graphics("images/how-1-file.png")
+knitr::include_graphics("screenshots/rmarkdown-notebook.png")
 ```
 
-To generate a report from an R Markdown file, run the `render()` command:
-
-```{r eval = FALSE}
-rmarkdown::render("1-example.Rmd")
-```
-
-Or better, use the "Knit" button in the RStudio IDE to render the file and preview the output with a single click or keyboard shortcut (Cmd/Ctrl + Shift + K). This will generates an output file that intermingles prose, code, and results.
+To produce a complete report containing all text, code, and results click "Knit" or press Cmd/Ctrl + Shift + K.  You can also do programmatically with `rmarkdown::render("1-example.Rmd")`. For the `.Rmd` above, this creates:
 
 ```{r, echo = FALSE, out.width = "100%"}
-knitr::include_graphics("images/how-2-chunk.png")
+knitr::include_graphics("screenshots/rmarkdown-report.png")
 ```
 
-When you run `render()`, R Markdown feeds the .Rmd file to [knitr](http://yihui.name/knitr/), which executes all of the code chunks and creates a new markdown (.md) document which includes the code and its output. The markdown file generated by knitr is then processed by [pandoc](http://pandoc.org/) which is responsible for creating the finished format.
+When you __knit__ the document R Markdown sends the .Rmd file to [knitr](http://yihui.name/knitr/), which executes all of the code chunks and creates a new markdown (.md) document which includes the code and its output. The markdown file generated by knitr is then processed by [pandoc](http://pandoc.org/) which is responsible for creating the finished format. The big advantage of this two step workflow is that you can create a very wide range of output formats, as you'll learn about in XYZ.
 
 ```{r, echo = FALSE, out.width = "100%"}
 knitr::include_graphics("images/RMarkdownFlow.png")
 ```
 
-This may sound complicated, but R Markdown makes it extremely simple by encapsulating all of the above processing into a single `render()` function.
+To get started with your own `.Rmd` file, select *File > New File > R Markdown...* in the menubar. RStudio will launch a wizard that you can use to pre-populate your file with useful content thatreminds you how the key features of R Markdown work. 
 
-To get started with your own `.Rmd` file, select *File > New File > R Markdown...* in the menubar. RStudio will launch a wizard that you can use to pre-populate your file with useful content that reminds you how the key features of R markdown work. 
+The following sections dives into the three components of an R Markdown document in more details: the code chunks, the text, and the YAML header.
 
 ## Code chunks
 
@@ -208,7 +199,15 @@ To ensure that caching works properly in this situation, give each chunk a chunk
 
 `dependson` should contain a character vector of *every* chunk that the cached chunk depends on. Knitr will update the results for the cached chunk whenever it detects that one of its dependencies have changed.
 
-## Inline code
+## Text formatting
+
+Format the text in your R Markdown files with Markdown, a set of markup annotations for plain text files. When you render your file, Pandoc transforms the marked up text into formatted text in your final file format.  Markdown is designed to be easy to read and easy to write. It is also very easy to learn. The guide below shows how to use Pandoc's Markdown, a slightly extended version of Markdown that R Markdown understands.
+
+```{r, echo = FALSE, comment = ""}
+cat(readr::read_file("rmarkdown-demos/markdown.Rmd"))
+```
+
+### Inline code
 
 Code results can be inserted directly into the *text* of a .Rmd file by enclosing the code with `` `r `  ``. The [file below](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/3-inline.Rmd) uses `` `r `  `` twice to call `colorFunc`, which returns "heat.colors." This makes it easy to update the report to refer to another function. 
 
@@ -219,14 +218,6 @@ knitr::include_graphics("images/inline-1-heat.png")
 Inline expressions do not take knitr options. When processing inline code, R Markdown will always display the results of inline code, but not the code, and apply relevant text formatting to the results. As a result, inline output is indistinguishable from the surrounding text. 
 
 
-## Text formatting
-
-Format the text in your R Markdown files with Markdown, a set of markup annotations for plain text files. When you render your file, Pandoc transforms the marked up text into formatted text in your final file format.  Markdown is designed to be easy to read and easy to write. It is also very easy to learn. The guide below shows how to use Pandoc's Markdown, a slightly extended version of Markdown that R Markdown understands.
-
-```{r, echo = FALSE, comment = ""}
-cat(readr::read_file("rmarkdown-demos/markdown.Rmd"))
-```
-
 ## YAML header
 
 ### Parameters