Add part openers

Fixes hadley#415

action.Rmd

@@ -1 +1,23 @@
-# (PART\*) Shiny in action {-}
+# (PART\*) Shiny in action {.unnumbered}
+
+# Introduction {#action-intro .unnumbered}
+
+The following chapters give you a grab bag of useful techniques.
+I think everyone should start with Chapter \@ref(workflow), because it gives you important tools for developing and debugging apps, and getting help when you're stuck.
+
+After that, there's no prescribed order and relatively few connections between the chapters: I'd suggest quickly skimming to get the lay of the land (and so you might remember these tools if related problems crop up in the future), and otherwise only deeply reading the bits that you currently need.
+Here's a quick run down of the main topics:
+
+-   Chapter \@ref(action-graphics) shows you how to add direct interaction to your plot and how to display images generated in other ways.
+
+-   Chapter \@ref(action-feedback) covers a family of techniques (including inline errors, notifications, progress bars, and dialog boxes) for giving feedback to your users while you app runs.
+
+-   Chapter \@ref(action-transfer) discusses how to transfer files to and from your app.
+
+-   Chapter \@ref(action-dynamic) shows you how to dynamic modify your apps user interface while it runs.
+
+-   Chapter \@ref(action-bookmark) shows how to record app state in such a way that your users can bookmark it.
+
+-   Chapter \@ref(action-tidy) shows you how to allow users to select variables when working with tidyverse packages.
+
+Let's begin by working on your workflow for developing apps.

basic.Rmd

@@ -1,2 +1,8 @@
-# (PART\*) Getting started {-}
+# (PART\*) Getting started {.unnumbered}
 
+# Introduction {#basic-intro .unnumbered}
+
+The goal of the next four chapters is to get you writing Shiny apps as quickly as possible.
+In Chapter \@ref(basic-app), I'll start small, but complete, showing you all the major pieces of an app and how they fit together.
+Then in Chapters \@ref(basic-ui) and \@ref(basic-reactivity) you'll start to get into the details of the two major parts of a Shiny app: the frontend (what the user sees in the browser) and the backend (the code that makes it all work).
+We'll finish up in Chapter \@ref(basic-case-study) with a case study to help cement the concepts you've learned so far.

reactivity-motivation.Rmd

@@ -1,4 +1,4 @@
-# Why reactivity?
+# Why reactivity? {#reactive-motivation}
 
 ```{r setup, include=FALSE}
 source("common.R")
@@ -16,20 +16,9 @@ As Tom Dale said of his Ember.js JavaScript framework: "We do a lot of magic, bu
 When you peel back the layers of reactive programming, you won't find a pile of heuristics, special cases, and hacks; instead you'll find a clever, but ultimately fairly straightforward mechanism.
 Once you've formed an accurate mental model of reactivity, you'll see that there's nothing up Shiny's sleeves: the magic comes from simple concepts combined in consistent ways.
 
-In this part of the book, you'll dive into the theory of reactivity that underlies the magic of Shiny:
+In this chapter, we'll motivate reactive programming by trying to do without it and then give a brief history of reactivity as it pertains to Shiny.
 
--   In this chapter, you'll learn why the reactivity programming model is needed, and a little bit about the history of reactive programming outside of R.
-
--   In Chapter \@ref(reactive-graph), you'll learn the full details of the reactive graph, which determines exactly when reactive components are updated.
-
--   In Chapter \@ref(reactivity-objects), you'll learn about the underlying building blocks, particularly observers and timed invalidation.
-
--   In Chapter \@ref(reactivity-components), you'll learn how to escape the constraints of the reactive graph using `reactiveVal()` and `observe()`.
-
-You certainly don't need to understand all these details for routine development of Shiny apps.
-But improving your understanding will help you write correct apps from the get go, and when something behaves unexpectedly you can more quickly narrow in on the underlying issue.
-
-## Why reactive programming? {#motivation}
+## Why do we need reactive programming? {#motivation}
 
 Reactive programming is a style of programming that focuses on values that change over time, and calculations and actions that depend on those values.
 Reactivity is important for Shiny apps because they're interactive: users change input controls (dragging sliders, typing in textboxes, checking checkboxes, ...) which causes logic to run on the server (reading CSVs, subsetting data, fitting models, ...) ultimately resulting in outputs updating (plots redrawing, tables updating, ...).
@@ -223,8 +212,7 @@ Spreadsheets are closely related to reactive programming: you declare the relati
 So you've probably already done a bunch of reactive programming without knowing it!
 
 While the ideas of reactivity have been around for a long time, it wasn't until the late 1990s that they were seriously studied in academic computer science.
-Research in reactive programming was kicked off by FRAN [@fran], **f**unctional **r**eactive **an**imation, a novel system for incorporating changes over time and user input into a functional programming language.
-This spawned a rich literature [@rp-survey], but had little impact on the practice of programming.
+Research in reactive programming was kicked off by FRAN [@fran], **f**unctional **r**eactive **an**imation, a novel system for incorporating changes over time and user input into a functional programming language. This spawned a rich literature [@rp-survey], but had little impact on the practice of programming.
 
 It wasn't until the 2010s that reactive programming roared into the programming mainstream through the fast-paced world of JavaScript UI frameworks.
 Pioneering frameworks like [Knockout](https://knockoutjs.com/), [Ember](https://emberjs.com/), and [Meteor](https://www.meteor.com) (Joe Cheng's personal inspiration for Shiny) demonstrated that reactive programming could make UI programming dramatically easier.

reactivity.Rmd

@@ -1 +1,17 @@
-# (PART\*) Mastering reactivity {-}
+# (PART\*) Mastering reactivity {.unnumbered}
+
+# Introduction {#reactivity-intro .unnumbered}
+
+You now have a bundle of useful techniques under your belt, giving you the ability to create a wide range of useful apps.
+Next we'll turn our attention to the theory of reactivity that underlies the magic of Shiny:
+
+-   In Chapter \@ref(reactive-motivation) you'll learn why the reactivity programming model is needed, and a little bit about the history of reactive programming outside of R.
+
+-   In Chapter \@ref(reactive-graph), you'll learn the full details of the reactive graph, which determines exactly when reactive components are updated.
+
+-   In Chapter \@ref(reactivity-objects), you'll learn about the underlying building blocks, particularly observers and timed invalidation.
+
+-   In Chapter \@ref(reactivity-components), you'll learn how to escape the constraints of the reactive graph using `reactiveVal()` and `observe()`.
+
+You certainly don't need to understand all these details for routine development of Shiny apps.
+But improving your understanding will help you write correct apps from the get go, and when something behaves unexpectedly you can more quickly narrow in on the underlying issue.

scaling-general.Rmd

@@ -1,23 +1,9 @@
 # General guidelines {#best-practices}
 
-(Thanks to my colleague Jeff Allen for contributing the bulk of this chapter)
-
-When you start using Shiny, it'll take you a long time to make even small apps, because you have to learn the fundamentals.
-Over time, however, you'll become more comfortable with the basic interface of the package and the key ideas of reactivity, and you'll be able to create larger, more complex applications.
-As you start to write larger apps, you'll encounter a new set of challenges: keeping a complex and growing code-base organized, stable, and maintainable.
-This will include problems like:
-
--   "I can't find the code I'm looking for in this huge file."
-
--   "I haven't worked on this code in 6 months and I'm afraid I'm going to break it if I make any changes."
+## Introduction
 
--   "Someone else started working with me on the application and we keep standing on each others toes."
-
--   "The app works on my computer but doesn't work on my collaborator's or in production."
-
-In this, the "best practices", part of the book, you'll learn some key concepts and tools from software engineering that will help you overcome these challenges.
-Below, I'll briefly introduce you to the big ideas, and then dive into the details in subsequent chapters.
-Of course you can't learn everything about software engineering in one part of one book, so I'll also point you to good places to learn more.
+This chapter introduces the most important software engineering skills you'll need when writing Shiny apps: code organisation, testing, dependency management, source code control, continuous integration, and code reviews.
+These skills are not specific to Shiny apps, but you'll need to learn a bit about all of them if you want to write complex apps that get easier to maintain over time, not harder.
 
 Improving your software engineering skills is a lifelong journey.
 Expect to have frustrations as you start learning them, but understand that everyone experiences the same issues, and if you persevere you'll get past them.
@@ -26,7 +12,9 @@ It takes time and practice to get to the final stage.
 
 I recommend setting aside some time each week to practice your software development skills.
 During this time, try to avoid touching the behaviour or appearance of your app, but instead focus your efforts on making the app easier to understand and develop.
-This will make your app easier to change in the future, and as you improve your software development your first attempt at an app will also become higher quality.
+This will make your app easier to change in the future, and as you improve your software development skills your first attempt at an app will also become higher quality.
+
+(Thanks to my colleague Jeff Allen for contributing the bulk of this chapter)
 
 ## Code organization
 

scaling.Rmd

@@ -1 +1,32 @@
-# (PART\*) Best practices {-}
+# (PART\*) Best practices {.unnumbered}
+
+# Introduction {#scaling-intro .unnumbered}
+
+When you start using Shiny, it'll take you a long time to make even small apps, because you have to learn the fundamentals.
+Over time, however, you'll become more comfortable with the basic interface of the package and the key ideas of reactivity, and you'll be able to create larger, more complex applications.
+As you start to write larger apps, you'll encounter a new set of challenges: keeping a complex and growing code-base organized, stable, and maintainable.
+This will include problems like:
+
+-   "I can't find the code I'm looking for in this huge file."
+
+-   "I haven't worked on this code in 6 months and I'm afraid I'm going to break it if I make any changes."
+
+-   "Someone else started working with me on the application and we keep standing on each others toes."
+
+-   "The app works on my computer but doesn't work on my collaborator's or in production."
+
+In this, the "best practices", part of the book, you'll learn some key concepts and tools from software engineering that will help you overcome these challenges:
+
+-   In Chapter \@ref(best-practices), I'll briefly introduce you to the big ideas of software engineering.
+
+-   In Chapter \@ref(scaling-functions), I'll show you how to extract code out of your Shiny app in to independent apps, and discuss why you might want to do so.
+
+-   In Chapter \@ref(scaling-modules), you'll learn about Shiny's module system, which allows you to extract coupled UI and server code into isolated and reusable components.
+
+-   In Chapter \@ref(scaling-packaging), I'll show you how to turn your app in R package, and motivate why that investment will pay off for bigger apps.
+
+-   In Chapter \@ref(scaling-testing), you'll learn how to turn your existing informal tests into automated test that can easily be re-run whenever your app changes.
+
+-   In Chapter \@ref(performance), you'll learn how to identify and resolve performance bottlenecks in your apps, ensuring they remain speedy even when used by hundreds of users.
+
+Of course you can't learn everything about software engineering in one part of one book, so I'll also point you to good places to learn more.