Renamed appendices and added @nrc's guide

Author: Michael-F-Bryan

src/SUMMARY.md

@@ -46,6 +46,10 @@
     - [miri const evaluator](./miri.md)
 - [Parameter Environments](./param_env.md)
 - [Generating LLVM IR](./trans.md)
-- [Background material](./background.md)
-- [Glossary](./glossary.md)
-- [Code Index](./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)

src/background.md renamed to src/appendix-background.md

@@ -1,4 +1,4 @@
-# Background topics
+# Appendix B: Background topics
 
 This section covers a numbers of common compiler terms that arise in
 this guide. We try to give the general definition while providing some

src/code-index.md renamed to src/appendix-code-index.md

@@ -1,4 +1,4 @@
-# Code Index
+# Appendix D: Code Index
 
 rustc has a lot of important data structures. This is an attempt to give some
 guidance on where to learn more about some of the key data structures of the

src/glossary.md renamed to src/appendix-glossary.md

@@ -1,21 +1,20 @@
-Glossary
---------
+# Appendix C: Glossary
 
 The compiler uses a number of...idiosyncratic abbreviations and things. This glossary attempts to list them and give you a few pointers for understanding them better.
 
 Term                    | Meaning
 ------------------------|--------
 AST                     |  the abstract syntax tree produced by the syntax crate; reflects user syntax very closely.
-binder                  |  a "binder" is a place where a variable or type is declared; for example, the `<T>` is a binder for the generic type parameter `T` in `fn foo<T>(..)`, and \|`a`\|` ...` is a binder for the parameter `a`. See [the background chapter for more](./background.html#free-vs-bound)
-bound variable          |  a "bound variable" is one that is declared within an expression/term. For example, the variable `a` is bound within the closure expession \|`a`\|` a * 2`. See [the background chapter for more](./background.html#free-vs-bound)
+binder                  |  a "binder" is a place where a variable or type is declared; for example, the `<T>` is a binder for the generic type parameter `T` in `fn foo<T>(..)`, and \|`a`\|` ...` is a binder for the parameter `a`. See [the background chapter for more](./appendix-background.html#free-vs-bound)
+bound variable          |  a "bound variable" is one that is declared within an expression/term. For example, the variable `a` is bound within the closure expession \|`a`\|` a * 2`. See [the background chapter for more](./appendix-background.html#free-vs-bound)
 codegen unit            |  when we produce LLVM IR, we group the Rust code into a number of codegen units. Each of these units is processed by LLVM independently from one another, enabling parallelism. They are also the unit of incremental re-use.
 completeness            |  completeness is a technical term in type theory. Completeness means that every type-safe program also type-checks. Having both soundness and completeness is very hard, and usually soundness is more important. (see "soundness").
-control-flow graph      |  a representation of the control-flow of a program; see [the background chapter for more](./background.html#cfg)  
+control-flow graph      |  a representation of the control-flow of a program; see [the background chapter for more](./appendix-background.html#cfg)  
 cx                      |  we tend to use "cx" as an abbrevation for context. See also `tcx`, `infcx`, etc.
 DAG                     |  a directed acyclic graph is used during compilation to keep track of dependencies between queries. ([see more](incremental-compilation.html))
-data-flow analysis      |  a static analysis that figures out what properties are true at each point in the control-flow of a program; see [the background chapter for more](./background.html#dataflow)  
+data-flow analysis      |  a static analysis that figures out what properties are true at each point in the control-flow of a program; see [the background chapter for more](./appendix-background.html#dataflow)  
 DefId                   |  an index identifying a definition (see `librustc/hir/def_id.rs`). Uniquely identifies a `DefPath`.
-free variable           |  a "free variable" is one that is not bound within an expression or term; see [the background chapter for more](./background.html#free-vs-bound)
+free variable           |  a "free variable" is one that is not bound within an expression or term; see [the background chapter for more](./appendix-background.html#free-vs-bound)
 'gcx                    |  the lifetime of the global arena ([see more](ty.html))
 generics                |  the set of generic type parameters defined on a type or item
 HIR                     |  the High-level IR, created by lowering and desugaring the AST ([see more](hir.html))
@@ -39,7 +38,7 @@ obligation              |  something that must be proven by the trait system ([s
 projection              |  a general term for a "relative path", e.g. `x.f` is a "field projection", and `T::Item` is an ["associated type projection"](./traits-goals-and-clauses.html#trait-ref)
 promoted constants      |  constants extracted from a function and lifted to static scope; see [this section](./mir.html#promoted) for more details.
 provider                |  the function that executes a query ([see more](query.html))
-quantified              |  in math or logic, existential and universal quantification are used to ask questions like "is there any type T for which is true?" or "is this true for all types T?"; see [the background chapter for more](./background.html#quantified)  
+quantified              |  in math or logic, existential and universal quantification are used to ask questions like "is there any type T for which is true?" or "is this true for all types T?"; see [the background chapter for more](./appendix-background.html#quantified)  
 query                   |  perhaps some sub-computation during compilation ([see more](query.html))
 region                  |  another term for "lifetime" often used in the literature and in the borrow checker.
 sess                    |  the compiler session, which stores global data used throughout compilation
@@ -57,7 +56,7 @@ token                   |  the smallest unit of parsing. Tokens are produced aft
 trans                   |  the code to translate MIR into LLVM IR.
 trait reference         |  a trait and values for its type parameters ([see more](ty.html)).
 ty                      |  the internal representation of a type ([see more](ty.html)).
-variance                |  variance determines how changes to a generic type/lifetime parameter affect subtyping; for example, if `T` is a subtype of `U`, then `Vec<T>` is a subtype `Vec<U>` because `Vec` is *covariant* in its generic parameter. See [the background chapter for more](./background.html#variance).
+variance                |  variance determines how changes to a generic type/lifetime parameter affect subtyping; for example, if `T` is a subtype of `U`, then `Vec<T>` is a subtype `Vec<U>` because `Vec` is *covariant* in its generic parameter. See [the background chapter for more](./appendix-background.html#variance).
 
 [LLVM]: https://llvm.org/
 [lto]: https://llvm.org/docs/LinkTimeOptimization.html