From b2fddde55413f8381f6ee49be1be14fb2c42df9a Mon Sep 17 00:00:00 2001
From: mark <markm@cs.wisc.edu>
Date: Fri, 18 Jan 2019 15:16:13 -0600
Subject: [PATCH] Reorganize the book into 3 parts

---
 src/SUMMARY.md          | 27 +++++++++++++++++----------
 src/about-this-guide.md |  5 +++++
 src/part-1-intro.md     |  7 +++++++
 src/part-2-intro.md     | 12 ++++++++++++
 4 files changed, 41 insertions(+), 10 deletions(-)
 create mode 100644 src/part-1-intro.md
 create mode 100644 src/part-2-intro.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 9bdf8927..a17a3c6a 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -1,21 +1,28 @@
 # Summary
 
-- [About this guide](./about-this-guide.md)
+[About this guide](./about-this-guide.md)
+
+---
+
+- [Part 1 Intro](./part-1-intro.md)
 - [About the compiler team](./compiler-team.md)
 - [How to build the compiler and run what you built](./how-to-build-and-run.md)
     - [Build and Install distribution artifacts](./build-install-distribution-artifacts.md)
     - [Documenting Compiler](./compiler-documenting.md)
-- [Coding conventions](./conventions.md)
-- [Stabilizing Features](./stabilization_guide.md)
-- [Walkthrough: a typical contribution](./walkthrough.md)
 - [The compiler testing framework](./tests/intro.md)
     - [Running tests](./tests/running.md)
     - [Adding new tests](./tests/adding.md)
-    - [Using `compiletest` + commands to control test
-      execution](./compiletest.md)
+    - [Using `compiletest` + commands to control test execution](./compiletest.md)
+- [Walkthrough: a typical contribution](./walkthrough.md)
+- [Stabilizing Features](./stabilization_guide.md)
 - [Debugging the Compiler](./compiler-debugging.md)
 - [Profiling the compiler](./profiling.md)
     - [with the linux perf tool](./profiling/with_perf.md)
+- [Coding conventions](./conventions.md)
+
+---
+
+- [Part 2 Intro](./part-2-intro.md)
 - [High-level overview of the compiler source](./high-level-overview.md)
 - [The Rustc Driver](./rustc-driver.md)
     - [Rustdoc](./rustdoc.md)
@@ -71,7 +78,7 @@
 
 ---
 
-- [Appendix A: Stupid Stats](./appendix/stupid-stats.md)
-- [Appendix B: Background material](./appendix/background.md)
-- [Appendix C: Glossary](./appendix/glossary.md)
-- [Appendix D: Code Index](./appendix/code-index.md)
+[Appendix A: Stupid Stats](./appendix/stupid-stats.md)
+[Appendix B: Background material](./appendix/background.md)
+[Appendix C: Glossary](./appendix/glossary.md)
+[Appendix D: Code Index](./appendix/code-index.md)
diff --git a/src/about-this-guide.md b/src/about-this-guide.md
index 56f0b753..30a3b887 100644
--- a/src/about-this-guide.md
+++ b/src/about-this-guide.md
@@ -6,6 +6,11 @@ development. It is not meant to replace code documentation – each
 chapter gives only high-level details – the kinds of things that
 (ideally) don't change frequently.
 
+There are three parts to this guide. Part 1 contains information that should
+be useful no matter how you are contributing. Part 2 contains information
+about how the compiler works. Finally, there are some appendices at the
+end with useful reference information.
+
 The guide itself is of course open-source as well, and the sources can
 be found at the [GitHub repository]. If you find any mistakes in the
 guide, please file an issue about it, or even better, open a PR
diff --git a/src/part-1-intro.md b/src/part-1-intro.md
new file mode 100644
index 00000000..c829f8c3
--- /dev/null
+++ b/src/part-1-intro.md
@@ -0,0 +1,7 @@
+# Part 1: General Knowledge
+
+This section of the rustc-guide contains knowledge that should be useful to you
+regardless of what part of the compiler you are working on. This includes both
+technical info and tips (e.g. how to compile and debug the compiler) and info
+about processes in the Rust project (e.g. stabilization and info about the
+compiler team).
diff --git a/src/part-2-intro.md b/src/part-2-intro.md
new file mode 100644
index 00000000..6dd26f44
--- /dev/null
+++ b/src/part-2-intro.md
@@ -0,0 +1,12 @@
+# Part 2: How rustc works
+
+This part of the guide describes how the compiler works. It goes through
+everything from high-level structure of the compiler to how each stage of
+compilation works.
+
+This section should be friendly to both readers interested in the end-to-end
+process of compilation _and_ readers interested in learning about a specific
+system they wish to contribute to. If anything is unclear, feel free to file
+an issue on the [rustc-guide repo](https://github.com/rust-lang/rustc-guide)
+or contact the compiler team, as detailed in [this chapter from Part
+1](./compiler-team.md).