Normalize Book headings to only level 2+

src/doc/trpl/crates-and-modules.md

@@ -6,7 +6,7 @@ fit them together. It's also important to have a well-defined interface, so
 that some of your functionality is private, and some is public. To facilitate
 these kinds of things, Rust has a module system.
 
-# Basic terminology: Crates and Modules
+## Basic terminology: Crates and Modules
 
 Rust has two distinct terms that relate to the module system: *crate* and
 *module*. A crate is synonymous with a *library* or *package* in other
@@ -70,7 +70,7 @@ $ tree .
 `src/lib.rs` is our crate root, corresponding to the `phrases` in our diagram
 above.
 
-# Defining Modules
+## Defining Modules
 
 To define each of our modules, we use the `mod` keyword. Let's make our
 `src/lib.rs` look like this:
@@ -124,7 +124,7 @@ deps  libphrases-a7448e02a0468eaa.rlib  native
 `libphrase-hash.rlib` is the compiled crate. Before we see how to use this
 crate from another crate, let's break it up into multiple files.
 
-# Multiple file crates
+## Multiple file crates
 
 If each crate were just one file, these files would get very large. It's often
 easier to split up crates into multiple files, and Rust supports this in two
@@ -261,7 +261,7 @@ fn goodbye() -> String {
 Now that we have our some functionality in our crate, let's try to use it from
 another crate.
 
-# Importing External Crates
+## Importing External Crates
 
 We have a library crate. Let's make an executable crate that imports and uses
 our library.
@@ -314,7 +314,7 @@ note: in expansion of format_args!
 By default, everything is private in Rust. Let's talk about this in some more
 depth.
 
-# Exporting a Public Interface
+## Exporting a Public Interface
 
 Rust allows you to precisely control which aspects of your interface are
 public, and so private is the default. To make things public, you use the `pub`
@@ -396,7 +396,7 @@ Now that our functions are public, we can use them. Great! However, typing out
 another keyword for importing names into the current scope, so that you can
 refer to them with shorter names. Let's talk about `use`.
 
-# Importing Modules with `use`
+## Importing Modules with `use`
 
 Rust has a `use` keyword, which allows us to import names into our local scope.
 Let's change our `src/main.rs` to look like this:
@@ -477,7 +477,7 @@ use phrases::english::{greetings, farewells};
 
 These two declarations are equivalent, but the second is a lot less typing.
 
-## Re-exporting with `pub use`
+### Re-exporting with `pub use`
 
 You don't just use `use` to shorten identifiers. You can also use it inside of your crate
 to re-export a function inside another module. This allows you to present an external

src/doc/trpl/error-handling.md

@@ -13,7 +13,7 @@ There are two main kinds of errors that can occur in your programs: failures,
 and panics. Let's talk about the difference between the two, and then discuss
 how to handle each. Then, we'll discuss upgrading failures to panics.
 
-# Failure vs. Panic
+## Failure vs. Panic
 
 Rust uses two terms to differentiate between two forms of error: failure, and
 panic. A *failure* is an error that can be recovered from in some way. A
@@ -116,7 +116,7 @@ We shouldn't ever hit the `_` case, so we use the `unreachable!()` macro to
 indicate this. `unreachable!()` gives a different kind of error than `Result`.
 Rust calls these sorts of errors *panics*.
 
-# Handling errors with `Option` and `Result`
+## Handling errors with `Option` and `Result`
 
 The simplest way to indicate that a function may fail is to use the `Option<T>`
 type. Remember our `from_str()` example? Here's its type signature:
@@ -178,7 +178,7 @@ match version {
 This function makes use of an enum, `ParseError`, to enumerate the various
 errors that can occur.
 
-# Non-recoverable errors with `panic!`
+## Non-recoverable errors with `panic!`
 
 In the case of an error that is unexpected and not recoverable, the `panic!`
 macro will induce a panic. This will crash the current task, and give an error:
@@ -197,7 +197,7 @@ when you run it.
 
 Because these kinds of situations are relatively rare, use panics sparingly.
 
-# Upgrading failures to panics
+## Upgrading failures to panics
 
 In certain circumstances, even though a function may fail, we may want to treat
 it as a panic instead. For example, `io::stdin().read_line()` returns an

src/doc/trpl/ffi.md

@@ -1,6 +1,6 @@
 % The Rust Foreign Function Interface Guide
 
-# Introduction
+## Introduction
 
 This guide will use the [snappy](https://github.com/google/snappy)
 compression/decompression library as an introduction to writing bindings for
@@ -68,7 +68,7 @@ extern {
 # fn main() {}
 ~~~~
 
-# Creating a safe interface
+## Creating a safe interface
 
 The raw C API needs to be wrapped to provide memory safety and make use of higher-level concepts
 like vectors. A library can choose to expose only the safe, high-level interface and hide the unsafe
@@ -164,7 +164,7 @@ pub fn uncompress(src: &[u8]) -> Option<Vec<u8>> {
 For reference, the examples used here are also available as an [library on
 GitHub](https://github.com/thestinger/rust-snappy).
 
-# Stack management
+## Stack management
 
 Rust tasks by default run on a *large stack*. This is actually implemented as a
 reserving a large segment of the address space and then lazily mapping in pages
@@ -187,13 +187,13 @@ interoperate. If, however, it is determined that a larger stack is necessary,
 there are appropriate functions in the task spawning API to control the size of
 the stack of the task which is spawned.
 
-# Destructors
+## Destructors
 
 Foreign libraries often hand off ownership of resources to the calling code.
 When this occurs, we must use Rust's destructors to provide safety and guarantee
 the release of these resources (especially in the case of panic).
 
-# Callbacks from C code to Rust functions
+## Callbacks from C code to Rust functions
 
 Some external libraries require the usage of callbacks to report back their
 current state or intermediate data to the caller.
@@ -247,7 +247,7 @@ In this example Rust's `main()` will call `trigger_callback()` in C,
 which would, in turn, call back to `callback()` in Rust.
 
 
-## Targeting callbacks to Rust objects
+### Targeting callbacks to Rust objects
 
 The former example showed how a global function can be called from C code.
 However it is often desired that the callback is targeted to a special
@@ -314,7 +314,7 @@ void trigger_callback() {
 }
 ~~~~
 
-## Asynchronous callbacks
+### Asynchronous callbacks
 
 In the previously given examples the callbacks are invoked as a direct reaction
 to a function call to the external C library.
@@ -338,7 +338,7 @@ This can be achieved by unregistering the callback in the object's
 destructor and designing the library in a way that guarantees that no
 callback will be performed after deregistration.
 
-# Linking
+## Linking
 
 The `link` attribute on `extern` blocks provides the basic building block for
 instructing rustc how it will link to native libraries. There are two accepted
@@ -385,7 +385,7 @@ A few examples of how this model can be used are:
 
 On OSX, frameworks behave with the same semantics as a dynamic library.
 
-## The `link_args` attribute
+### The `link_args` attribute
 
 There is one other way to tell rustc how to customize linking, and that is via
 the `link_args` attribute. This attribute is applied to `extern` blocks and
@@ -410,7 +410,7 @@ meaning.
 It is highly recommended to *not* use this attribute, and rather use the more
 formal `#[link(...)]` attribute on `extern` blocks instead.
 
-# Unsafe blocks
+## Unsafe blocks
 
 Some operations, like dereferencing unsafe pointers or calling functions that have been marked
 unsafe are only allowed inside unsafe blocks. Unsafe blocks isolate unsafety and are a promise to
@@ -425,7 +425,7 @@ unsafe fn kaboom(ptr: *const int) -> int { *ptr }
 
 This function can only be called from an `unsafe` block or another `unsafe` function.
 
-# Accessing foreign globals
+## Accessing foreign globals
 
 Foreign APIs often export a global variable which could do something like track
 global state. In order to access these variables, you declare them in `extern`
@@ -468,7 +468,7 @@ fn main() {
 }
 ~~~
 
-# Foreign calling conventions
+## Foreign calling conventions
 
 Most foreign code exposes a C ABI, and Rust uses the platform's C calling convention by default when
 calling foreign functions. Some foreign functions, most notably the Windows API, use other calling
@@ -507,7 +507,7 @@ however, windows uses the `C` calling convention, so `C` would be used. This
 means that in our previous example, we could have used `extern "system" { ... }`
 to define a block for all windows systems, not just x86 ones.
 
-# Interoperability with foreign code
+## Interoperability with foreign code
 
 Rust guarantees that the layout of a `struct` is compatible with the platform's
 representation in C only if the `#[repr(C)]` attribute is applied to it.
@@ -532,7 +532,7 @@ The standard library includes type aliases and function definitions for the C
 standard library in the `libc` module, and Rust links against `libc` and `libm`
 by default.
 
-# The "nullable pointer optimization"
+## The "nullable pointer optimization"
 
 Certain types are defined to not be `null`. This includes references (`&T`,
 `&mut T`), boxes (`Box<T>`), and function pointers (`extern "abi" fn()`).

src/doc/trpl/macros.md

@@ -1,6 +1,6 @@
 % The Rust Macros Guide
 
-# Introduction
+## Introduction
 
 Functions are the primary tool that programmers can use to build abstractions.
 Sometimes, however, programmers want to abstract over compile-time syntax
@@ -64,7 +64,7 @@ Macros are defined in pattern-matching style: in the above example, the text
 macro. The text on the right-hand side of the `=>`, beginning with `match
 $inp`, is the *macro transcription syntax*: what the macro expands to.
 
-# Invocation syntax
+## Invocation syntax
 
 The macro invocation syntax specifies the syntax for the arguments to the
 macro. It appears on the left-hand side of the `=>` in a macro definition. It
@@ -97,7 +97,7 @@ rules of tokenization apply,
 So `($x:ident -> (($e:expr)))`, though excessively fancy, would designate a macro
 that could be invoked like: `my_macro!(i->(( 2+2 )))`.
 
-## Invocation location
+### Invocation location
 
 A macro invocation may take the place of (and therefore expand to) an
 expression, item, statement, or pattern.  The Rust parser will parse the macro
@@ -112,7 +112,7 @@ location). Although this behavior sounds excessively dynamic, it is known to
 be useful under some circumstances.
 
 
-# Transcription syntax
+## Transcription syntax
 
 The right-hand side of the `=>` follows the same rules as the left-hand side,
 except that a `$` need only be followed by the name of the syntactic fragment
@@ -132,15 +132,15 @@ are permitted in expression, statement, and item locations. However, nothing
 else about the code is examined or executed by the macro system; execution
 still has to wait until run-time.
 
-## Interpolation location
+### Interpolation location
 
 The interpolation `$argument_name` may appear in any location consistent with
 its fragment specifier (i.e., if it is specified as `ident`, it may be used
 anywhere an identifier is permitted).
 
-# Multiplicity
+## Multiplicity
 
-## Invocation
+### Invocation
 
 Going back to the motivating example, recall that `early_return` expanded into
 a `match` that would `return` if the `match`'s scrutinee matched the
@@ -179,7 +179,7 @@ early_return!(input_2, [T::SpecialB]);
 # fn main() {}
 ~~~~
 
-### Transcription
+#### Transcription
 
 As the above example demonstrates, `$(...)*` is also valid on the right-hand
 side of a macro definition. The behavior of `*` in transcription,
@@ -191,7 +191,7 @@ of repetitions for all of the `$name`s it contains in lockstep, and (2) each
 `$name` must be under at least as many `$(...)*`s as it was matched against.
 If it is under more, it'll be repeated, as appropriate.
 
-## Parsing limitations
+### Parsing limitations
 
 
 For technical reasons, there are two limitations to the treatment of syntax
@@ -210,9 +210,9 @@ parsing `e`. Changing the invocation syntax to require a distinctive token in
 front can solve the problem. In the above example, `$(T $t:ty)* E $e:exp`
 solves the problem.
 
-# Macro argument pattern matching
+## Macro argument pattern matching
 
-## Motivation
+### Motivation
 
 Now consider code like the following:
 
@@ -295,7 +295,7 @@ pattern we want is clear:
 However, it's not possible to directly expand to nested match statements. But
 there is a solution.
 
-## The recursive approach to macro writing
+### The recursive approach to macro writing
 
 A macro may accept multiple different input grammars. The first one to
 successfully match the actual argument to a macro invocation is the one that
@@ -408,7 +408,7 @@ position (in particular, not as an argument to yet another macro invocation),
 the expander will then proceed to evaluate `m2!()` (along with any other macro
 invocations `m1!(m2!())` produced).
 
-# Hygiene
+## Hygiene
 
 To prevent clashes, rust implements
 [hygienic macros](http://en.wikipedia.org/wiki/Hygienic_macro).
@@ -438,7 +438,7 @@ fn main() {
 The two `'x` names did not clash, which would have caused the loop
 to print "I am never printed" and to run forever.
 
-# Scoping and macro import/export
+## Scoping and macro import/export
 
 Macros are expanded at an early stage in compilation, before name resolution.
 One downside is that scoping works differently for macros, compared to other
@@ -513,7 +513,7 @@ be imported.
 The Rust Reference has a [listing of macro-related
 attributes](../reference.html#macro--and-plugin-related-attributes).
 
-# The variable `$crate`
+## The variable `$crate`
 
 A further difficulty occurs when a macro is used in multiple crates.  Say that
 `mylib` defines
@@ -560,7 +560,7 @@ To keep this system simple and correct, `#[macro_use] extern crate ...` may
 only appear at the root of your crate, not inside `mod`.  This ensures that
 `$crate` is a single identifier.
 
-# A final note
+## A final note
 
 Macros, as currently implemented, are not for the faint of heart. Even
 ordinary syntax errors can be more difficult to debug when they occur inside a