Reorganize some chapters

README.md

@@ -19,22 +19,22 @@ order to write correct Unsafe Rust programs. Due to the nature of this problem,
 it may lead to unleashing untold horrors that shatter your psyche into a billion
 infinitesimal fragments of despair.
 
-### Requirements
+## Requirements
 
 Building the Nomicon requires [mdBook]. To get it:
 
 [mdBook]: https://github.com/rust-lang/mdBook
 
 ```bash
-$ cargo install mdbook
+cargo install mdbook
 ```
 
 ### `mdbook` usage
 
 To build the Nomicon use the `build` sub-command:
 
 ```bash
-$ mdbook build
+mdbook build
 ```
 
 The output will be placed in the `book` subdirectory. To check it out, open the
@@ -43,13 +43,23 @@ build` and it'll open the index page in your default browser (if the process is
 successful) just like with `cargo doc --open`:
 
 ```bash
-$ mdbook build --open
+mdbook build --open
 ```
 
 There is also a `test` sub-command to test all code samples contained in the book:
 
 ```bash
-$ mdbook test
+mdbook test
+```
+
+### `linkcheck`
+
+We use the `linkcheck` tool to find broken links.
+To run it locally:
+
+```sh
+curl -sSLo linkcheck.sh https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
+sh linkcheck.sh --all nomicon
 ```
 
 ## Contributing

book.toml

@@ -6,5 +6,29 @@ description = "The Dark Arts of Advanced and Unsafe Rust Programming"
 [output.html]
 git-repository-url = "https://github.com/rust-lang/nomicon"
 
+[output.html.redirect]
+# Vec-related chapters.
+"./vec-alloc.html" = "./vec/vec-alloc.html"
+"./vec-dealloc.html" = "./vec/vec-dealloc.html"
+"./vec-deref.html" = "./vec/vec-deref.html"
+"./vec-drain.html" = "./vec/vec-drain.html"
+"./vec-final.html" = "./vec/vec-final.html"
+"./vec-insert-remove.html" = "./vec/vec-insert-remove.html"
+"./vec-into-iter.html" = "./vec/vec-into-iter.html"
+"./vec-layout.html" = "./vec/vec-layout.html"
+"./vec-push-pop.html" = "./vec/vec-push-pop.html"
+"./vec-raw.html" = "./vec/vec-raw.html"
+"./vec-zsts.html" = "./vec/vec-zsts.html"
+"./vec.html" = "./vec/vec.html"
+
+# Arc and Mutex related chapters.
+"./arc-and-mutex.html" = "./arc-mutex/arc-and-mutex.html"
+"./arc-base.html" = "./arc-mutex/arc-base.html"
+"./arc-clone.html" = "./arc-mutex/arc-clone.html"
+"./arc-drop.html" = "./arc-mutex/arc-drop.html"
+"./arc-final.html" = "./arc-mutex/arc-final.html"
+"./arc-layout.html" = "./arc-mutex/arc-layout.html"
+"./arc.html" = "./arc-mutex/arc.html"
+
 [rust]
 edition = "2018"

src/SUMMARY.md

@@ -1,6 +1,6 @@
 # Summary
 
-[Introduction](README.md)
+[Introduction](intro.md)
 
 * [Meet Safe and Unsafe](meet-safe-and-unsafe.md)
   * [How Safe and Unsafe Interact](safe-unsafe-meaning.md)
@@ -42,25 +42,25 @@
   * [Races](races.md)
   * [Send and Sync](send-and-sync.md)
   * [Atomics](atomics.md)
-* [Implementing Vec](vec.md)
-  * [Layout](vec-layout.md)
-  * [Allocating](vec-alloc.md)
-  * [Push and Pop](vec-push-pop.md)
-  * [Deallocating](vec-dealloc.md)
-  * [Deref](vec-deref.md)
-  * [Insert and Remove](vec-insert-remove.md)
-  * [IntoIter](vec-into-iter.md)
-  * [RawVec](vec-raw.md)
-  * [Drain](vec-drain.md)
-  * [Handling Zero-Sized Types](vec-zsts.md)
-  * [Final Code](vec-final.md)
-* [Implementing Arc and Mutex](arc-and-mutex.md)
-  * [Arc](arc.md)
-    * [Layout](arc-layout.md)
-    * [Base Code](arc-base.md)
-    * [Cloning](arc-clone.md)
-    * [Dropping](arc-drop.md)
-    * [Final Code](arc-final.md)
+* [Implementing Vec](./vec/vec.md)
+  * [Layout](./vec/vec-layout.md)
+  * [Allocating](./vec/vec-alloc.md)
+  * [Push and Pop](./vec/vec-push-pop.md)
+  * [Deallocating](./vec/vec-dealloc.md)
+  * [Deref](./vec/vec-deref.md)
+  * [Insert and Remove](./vec/vec-insert-remove.md)
+  * [IntoIter](./vec/vec-into-iter.md)
+  * [RawVec](./vec/vec-raw.md)
+  * [Drain](./vec/vec-drain.md)
+  * [Handling Zero-Sized Types](./vec/vec-zsts.md)
+  * [Final Code](./vec/vec-final.md)
+* [Implementing Arc and Mutex](./arc-mutex/arc-and-mutex.md)
+  * [Arc](./arc-mutex/arc.md)
+    * [Layout](./arc-mutex/arc-layout.md)
+    * [Base Code](./arc-mutex/arc-base.md)
+    * [Cloning](./arc-mutex/arc-clone.md)
+    * [Dropping](./arc-mutex/arc-drop.md)
+    * [Final Code](./arc-mutex/arc-final.md)
 * [FFI](ffi.md)
 * [Beneath `std`](beneath-std.md)
   * [#[panic_handler]](panic-handler.md)

src/arc-and-mutex.md → src/arc-mutex/arc-and-mutex.md

@@ -2,6 +2,6 @@
 
 Knowing the theory is all fine and good, but the *best* way to understand
 something is to use it. To better understand atomics and interior mutability,
-we'll be implementing versions of the standard library's Arc and Mutex types.
+we'll be implementing versions of the standard library's `Arc` and `Mutex` types.
 
-TODO: Mutex
+TODO: Write `Mutex` chapters.

src/arc-base.md → src/arc-mutex/arc-base.md

@@ -34,7 +34,7 @@ impl<T> Arc<T> {
 Since we're building a concurrency primitive, we'll need to be able to send it
 across threads. Thus, we can implement the `Send` and `Sync` marker traits. For
 more information on these, see [the section on `Send` and
-`Sync`](send-and-sync.md).
+`Sync`](../send-and-sync.md).
 
 This is okay because:
 * You can only get a mutable reference to the value inside an `Arc` if and only

src/arc-clone.md → src/arc-mutex/arc-clone.md

@@ -26,7 +26,7 @@ happens-before relationship but is atomic. When `Drop`ping the Arc, however,
 we'll need to atomically synchronize when decrementing the reference count. This
 is described more in [the section on the `Drop` implementation for
 `Arc`](arc-drop.md). For more information on atomic relationships and Relaxed
-ordering, see [the section on atomics](atomics.md).
+ordering, see [the section on atomics](../atomics.md).
 
 Thus, the code becomes this:
 

src/arc-layout.md → src/arc-mutex/arc-layout.md

@@ -41,7 +41,7 @@ be used where an `Arc<&'a str>` was expected. More importantly, it will give
 incorrect ownership information to the drop checker, as it will assume we don't
 own any values of type `T`. As this is a structure providing shared ownership of
 a value, at some point there will be an instance of this structure that entirely
-owns its data. See [the chapter on ownership and lifetimes](ownership.md) for
+owns its data. See [the chapter on ownership and lifetimes](../ownership.md) for
 all the details on variance and drop check.
 
 To fix the first problem, we can use `NonNull<T>`. Note that `NonNull<T>` is a

src/arc.md → src/arc-mutex/arc.md

@@ -1,7 +1,7 @@
 # Implementing Arc
 
 In this section, we'll be implementing a simpler version of `std::sync::Arc`.
-Similarly to [the implementation of `Vec` we made earlier](vec.md), we won't be
+Similarly to [the implementation of `Vec` we made earlier](../vec/vec.md), we won't be
 taking advantage of as many optimizations, intrinsics, or unstable code as the
 standard library may.
 

src/intro.md

@@ -0,0 +1,32 @@
+# The Rustonomicon
+
+## The Dark Arts of Unsafe Rust
+
+> THE KNOWLEDGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF UNLEASHING INDESCRIBABLE HORRORS THAT SHATTER YOUR PSYCHE AND SET YOUR MIND ADRIFT IN THE UNKNOWABLY INFINITE COSMOS.
+
+The Rustonomicon digs into all the awful details that you need to understand when writing Unsafe Rust programs.
+
+Should you wish a long and happy career of writing Rust programs, you should turn back now and forget you ever saw this book.
+It is not necessary.
+However if you intend to write unsafe code — or just want to dig into the guts of the language — this book contains lots of useful information.
+
+Unlike *[The Rust Programming Language][trpl]*, we will be assuming considerable prior knowledge.
+In particular, you should be comfortable with basic systems programming and Rust.
+If you don't feel comfortable with these topics, you should consider reading [The Book][trpl] first.
+That said, we won't assume you have read it, and we will take care to occasionally give a refresher on the basics where appropriate.
+You can skip straight to this book if you want; just know that we won't be explaining everything from the ground up.
+
+This book exists primarily as a high-level companion to [The Reference][ref].
+Where The Reference exists to detail the syntax and semantics of every part of the language, The Rustonomicon exists to describe how to use those pieces together, and the issues that you will have in doing so.
+
+The Reference will tell you the syntax and semantics of references, destructors, and unwinding, but it won't tell you how combining them can lead to exception-safety issues, or how to deal with those issues.
+
+It should be noted that we haven't synced The Rustnomicon and The Reference well, so they may have a duplicate content.
+In general, if the two documents disagree, The Reference should be assumed to be correct (it isn't yet considered normative, it's just better maintained).
+
+Topics that are within the scope of this book include: the meaning of (un)safety, unsafe primitives provided by the language and standard library, techniques for creating safe abstractions with those unsafe primitives, subtyping and variance, exception-safety (panic/unwind-safety), working with uninitialized memory, type punning, concurrency, interoperating with other languages (FFI), optimization tricks, how constructs lower to compiler/OS/hardware primitives, how to **not** make the memory model people angry, how you're **going** to make the memory model people angry, and more.
+
+The Rustonomicon is not a place to exhaustively describe the semantics and guarantees of every single API in the standard library, nor is it a place to exhaustively describe every feature of Rust.
+
+[trpl]: ../book/index.html
+[ref]: ../reference/index.html

src/vec-alloc.md → src/vec/vec-alloc.md

@@ -202,9 +202,9 @@ impl<T> Vec<T> {
 # fn main() {}
 ```
 
-[Global]: ../std/alloc/struct.Global.html
-[handle_alloc_error]: ../alloc/alloc/fn.handle_alloc_error.html
-[alloc]: ../alloc/alloc/fn.alloc.html
-[realloc]: ../alloc/alloc/fn.realloc.html
-[dealloc]: ../alloc/alloc/fn.dealloc.html
-[std_alloc]: ../alloc/alloc/index.html
+[Global]: ../../std/alloc/struct.Global.html
+[handle_alloc_error]: ../../alloc/alloc/fn.handle_alloc_error.html
+[alloc]: ../../alloc/alloc/fn.alloc.html
+[realloc]: ../../alloc/alloc/fn.realloc.html
+[dealloc]: ../../alloc/alloc/fn.dealloc.html
+[std_alloc]: ../../alloc/alloc/index.html

src/vec-drain.md → src/vec/vec-drain.md

@@ -149,4 +149,4 @@ impl<T> Vec<T> {
 For more details on the `mem::forget` problem, see the
 [section on leaks][leaks].
 
-[leaks]: leaking.html
+[leaks]: ../leaking.html

src/vec-layout.md → src/vec/vec-layout.md

@@ -56,5 +56,5 @@ unsafe impl<T: Sync> Sync for Vec<T> {}
 # fn main() {}
 ```
 
-[ownership]: ownership.html
-[NonNull]: ../std/ptr/struct.NonNull.html
+[ownership]: ../ownership.html
+[NonNull]: ../../std/ptr/struct.NonNull.html