Fix dead links in the guide and reorganize

Author: alexcrichton

mk/docs.mk

@@ -275,9 +275,8 @@ endif
 docs: $(DOC_TARGETS)
 compiler-docs: $(COMPILER_DOC_TARGETS)
 
-trpl: tmp/trpl.ok
+trpl: doc/book/index.html
 
-tmp/trpl.ok: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md)
+doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md)
 	$(Q)rm -rf doc/book
 	$(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book
-	$(Q)touch $@

mk/tests.mk

@@ -156,8 +156,8 @@ endef
 
 $(foreach doc,$(DOCS), \
   $(eval $(call DOCTEST,md-$(doc),$(S)src/doc/$(doc).md)))
-$(foreach file,$(wildcard $(S)src/doc/trpl/src/*), \
-  $(eval $(call DOCTEST,$(file:$(S)src/doc/trpl/src/%.md=trpl-%),$(file))))
+$(foreach file,$(wildcard $(S)src/doc/trpl/*.md), \
+  $(eval $(call DOCTEST,$(file:$(S)src/doc/trpl/%.md=trpl-%),$(file))))
 
 ######################################################################
 # Main test targets

src/doc/trpl/SUMMARY.md

@@ -1,35 +1,36 @@
 # Summary
 
-* [I: The Basics](src/basic.md)
-    * [Installing Rust](src/installing-rust.md)
-    * [Hello, world!](src/hello-world.md)
-    * [Hello, Cargo!](src/hello-cargo.md)
-    * [Variable Bindings](src/variable-bindings.md)
-    * [If](src/if.md)
-    * [Functions](src/functions.md)
-    * [Comments](src/comments.md)
-    * [Compound Data Types](src/compound-data-types.md)
-    * [Match](src/match.md)
-    * [Looping](src/looping.md)
-    * [Strings](src/strings.md)
-    * [Arrays, Vectors, and Slices](src/arrays-vectors-and-slices.md)
-    * [Standard Input](src/standard-input.md)
-    * [Guessing Game](src/guessing-game.md)
-* [II: Intermedite Rust](src/intermediate.md)
-    * [Crates and Modules](src/crates-and-modules.md)
-    * [Testing](src/testing.md)
-    * [Pointers](src/pointers.md)
-    * [Patterns](src/patterns.md)
-    * [Method Syntax](src/method-syntax.md)
-    * [Closures](src/closures.md)
-    * [Iterators](src/iterators.md)
-    * [Generics](src/generics.md)
-    * [Traits](src/traits.md)
-    * [Tasks](src/tasks.md)
-    * [Error Handling](src/error-handling.md)
-* [III: Advanced Topics](src/advanced.md)
-    * [FFI](src/ffi.md)
-    * [Unsafe Code](src/unsafe.md)
-    * [Macros](src/macros.md)
-    * [Compiler Plugins](src/plugins.md)
-* [Conclusion](src/conclusion.md)
+* [I: The Basics](basic.md)
+    * [Installing Rust](installing-rust.md)
+    * [Hello, world!](hello-world.md)
+    * [Hello, Cargo!](hello-cargo.md)
+    * [Variable Bindings](variable-bindings.md)
+    * [If](if.md)
+    * [Functions](functions.md)
+    * [Comments](comments.md)
+    * [Compound Data Types](compound-data-types.md)
+    * [Match](match.md)
+    * [Looping](looping.md)
+    * [Strings](strings.md)
+    * [Arrays, Vectors, and Slices](arrays-vectors-and-slices.md)
+    * [Standard Input](standard-input.md)
+    * [Guessing Game](guessing-game.md)
+* [II: Intermediate Rust](intermediate.md)
+    * [Crates and Modules](crates-and-modules.md)
+    * [Testing](testing.md)
+    * [Pointers](pointers.md)
+    * [Ownership](ownership.md)
+    * [Patterns](patterns.md)
+    * [Method Syntax](method-syntax.md)
+    * [Closures](closures.md)
+    * [Iterators](iterators.md)
+    * [Generics](generics.md)
+    * [Traits](traits.md)
+    * [Tasks](tasks.md)
+    * [Error Handling](error-handling.md)
+* [III: Advanced Topics](advanced.md)
+    * [FFI](ffi.md)
+    * [Unsafe Code](unsafe.md)
+    * [Macros](macros.md)
+    * [Compiler Plugins](plugins.md)
+* [Conclusion](conclusion.md)

src/doc/trpl/src/advanced.md renamed to src/doc/trpl/advanced.md

@@ -1,4 +1,4 @@
-# Arrays, Vectors, and Slices
+% Arrays, Vectors, and Slices
 
 Like many programming languages, Rust has list types to represent a sequence of
 things. The most basic is the **array**, a fixed-size list of elements of the
@@ -48,7 +48,7 @@ errant access is the source of many bugs in other systems programming
 languages.
 
 A **vector** is a dynamic or "growable" array, implemented as the standard
-library type [`Vec<T>`](std/vec/) (we'll talk about what the `<T>` means
+library type [`Vec<T>`](../std/vec/) (we'll talk about what the `<T>` means
 later). Vectors are to arrays what `String` is to `&str`. You can create them
 with the `vec!` macro:
 

src/doc/trpl/src/arrays-vectors-and-slices.md renamed to src/doc/trpl/arrays-vectors-and-slices.md

@@ -1,4 +1,4 @@
-# Closures
+% Closures
 
 So far, we've made lots of functions in Rust, but we've given them all names.
 Rust also allows us to create anonymous functions. Rust's anonymous

src/doc/trpl/src/basic.md renamed to src/doc/trpl/basic.md

@@ -1,4 +1,4 @@
-# Comments
+% Comments
 
 Now that we have some functions, it's a good idea to learn about comments.
 Comments are notes that you leave to other programmers to help explain things
@@ -42,5 +42,5 @@ fn hello(name: &str) {
 When writing doc comments, adding sections for any arguments, return values,
 and providing some examples of usage is very, very helpful.
 
-You can use the [`rustdoc`](rustdoc.html) tool to generate HTML documentation
+You can use the [`rustdoc`](../rustdoc.html) tool to generate HTML documentation
 from these doc comments.

src/doc/trpl/src/closures.md renamed to src/doc/trpl/closures.md

@@ -1,4 +1,4 @@
-# Compound Data Types
+% Compound Data Types
 
 Rust, like many programming languages, has a number of different data types
 that are built-in. You've already done some simple work with integers and

src/doc/trpl/src/comments.md renamed to src/doc/trpl/comments.md

@@ -1,4 +1,4 @@
-# Functions
+% Functions
 
 You've already seen one function so far, the `main` function:
 

src/doc/trpl/src/compound-data-types.md renamed to src/doc/trpl/compound-data-types.md

@@ -1,4 +1,4 @@
-# Guessing Game
+% Guessing Game
 
 Okay! We've got the basics of Rust down. Let's write a bigger program.
 
@@ -108,12 +108,12 @@ we do know that Rust has random number generation, but we don't know how to
 use it.
 
 Enter the docs. Rust has a page specifically to document the standard library.
-You can find that page [here](std/index.html). There's a lot of information on
+You can find that page [here](../std/index.html). There's a lot of information on
 that page, but the best part is the search bar. Right up at the top, there's
 a box that you can enter in a search term. The search is pretty primitive
 right now, but is getting better all the time. If you type 'random' in that
-box, the page will update to [this one](std/index.html?search=random). The very
-first result is a link to [`std::rand::random`](std/rand/fn.random.html). If we
+box, the page will update to [this one](../std/index.html?search=random). The very
+first result is a link to [`std::rand::random`](../std/rand/fn.random.html). If we
 click on that result, we'll be taken to its documentation page.
 
 This page shows us a few things: the type signature of the function, some

src/doc/trpl/src/conclusion.md renamed to src/doc/trpl/conclusion.md

@@ -1,4 +1,4 @@
-# Hello, Cargo!
+% Hello, Cargo!
 
 [Cargo](http://crates.io) is a tool that Rustaceans use to help manage their
 Rust projects. Cargo is currently in an alpha state, just like Rust, and so it

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

@@ -1,4 +1,4 @@
-# Hello, world!
+% Hello, world!
 
 Now that you have Rust installed, let's write your first Rust program. It's
 traditional to make your first program in any new language one that prints the

src/doc/trpl/src/error-handling.md renamed to src/doc/trpl/error-handling.md

@@ -1,4 +1,4 @@
-# `if`
+% `if`
 
 Rust's take on `if` is not particularly complex, but it's much more like the
 `if` you'll find in a dynamically typed language than in a more traditional

src/doc/trpl/src/ffi.md renamed to src/doc/trpl/ffi.md

@@ -1,4 +1,4 @@
-# Installing Rust
+% Installing Rust
 
 The first step to using Rust is to install it! There are a number of ways to
 install Rust, but the easiest is to use the `rustup` script. If you're on

src/doc/trpl/src/functions.md renamed to src/doc/trpl/functions.md

@@ -336,4 +336,4 @@ can help you with. There are a number of really useful iterators, and you can
 write your own as well. Iterators provide a safe, efficient way to manipulate
 all kinds of lists. They're a little unusual at first, but if you play with
 them, you'll get hooked. For a full list of the different iterators and
-consumers, check out the [iterator module documentation](std/iter/index.html).
+consumers, check out the [iterator module documentation](../std/iter/index.html).

src/doc/trpl/src/generics.md renamed to src/doc/trpl/generics.md

@@ -1,4 +1,4 @@
-# Looping
+% Looping
 
 Looping is the last basic construct that we haven't learned yet in Rust. Rust has
 two main looping constructs: `for` and `while`.

src/doc/trpl/src/guessing-game.md renamed to src/doc/trpl/guessing-game.md

@@ -507,7 +507,7 @@ When this library is loaded with `#[use_macros] extern crate`, only `m2` will
 be imported.
 
 The Rust Reference has a [listing of macro-related
-attributes](reference.html#macro--and-plugin-related-attributes).
+attributes](../reference.html#macro--and-plugin-related-attributes).
 
 # The variable `$crate`
 
@@ -567,7 +567,7 @@ intermediate states out, and passing the flag `--pretty expanded` as a
 command-line argument to the compiler will show the result of expansion.
 
 If Rust's macro system can't do what you need, you may want to write a
-[compiler plugin](guide-plugin.html) instead. Compared to `macro_rules!`
+[compiler plugin](plugin.html) instead. Compared to `macro_rules!`
 macros, this is significantly more work, the interfaces are much less stable,
 and the warnings about debugging apply ten-fold. In exchange you get the
 flexibility of running arbitrary Rust code within the compiler. Syntax

src/doc/trpl/src/hello-cargo.md renamed to src/doc/trpl/hello-cargo.md

@@ -1,4 +1,4 @@
-# Match
+% Match
 
 Often, a simple `if`/`else` isn't enough, because you have more than two
 possible options. Also, `else` conditions can get incredibly complicated, so

src/doc/trpl/src/hello-world.md renamed to src/doc/trpl/hello-world.md

@@ -5,20 +5,20 @@
 <p>
 <b>Warning:</b> Plugins are an advanced, unstable feature! For many details,
 the only available documentation is the <a
-href="syntax/index.html"><code>libsyntax</code></a> and <a
-href="rustc/index.html"><code>librustc</code></a> API docs, or even the source
+href="../syntax/index.html"><code>libsyntax</code></a> and <a
+href="../rustc/index.html"><code>librustc</code></a> API docs, or even the source
 code itself. These internal compiler APIs are also subject to change at any
 time.
 </p>
 
 <p>
 For defining new syntax it is often much easier to use Rust's <a
-href="guide-macros.html">built-in macro system</a>.
+href="macros.html">built-in macro system</a>.
 </p>
 
 <p style="margin-bottom: 0">
 The code in this document uses language features not covered in the Rust
-Guide.  See the <a href="reference.html">Reference Manual</a> for more
+Guide.  See the <a href="../reference.html">Reference Manual</a> for more
 information.
 </p>
 
@@ -32,19 +32,19 @@ extend the compiler's behavior with new syntax extensions, lint checks, etc.
 A plugin is a dynamic library crate with a designated "registrar" function that
 registers extensions with `rustc`. Other crates can use these extensions by
 loading the plugin crate with `#[plugin] extern crate`. See the
-[`rustc::plugin`](rustc/plugin/index.html) documentation for more about the
+[`rustc::plugin`](../rustc/plugin/index.html) documentation for more about the
 mechanics of defining and loading a plugin.
 
 Arguments passed as `#[plugin=...]` or `#[plugin(...)]` are not interpreted by
 rustc itself.  They are provided to the plugin through the `Registry`'s [`args`
-method](rustc/plugin/registry/struct.Registry.html#method.args).
+method](../rustc/plugin/registry/struct.Registry.html#method.args).
 
 # Syntax extensions
 
 Plugins can extend Rust's syntax in various ways. One kind of syntax extension
 is the procedural macro. These are invoked the same way as [ordinary
-macros](guide-macros.html), but the expansion is performed by arbitrary Rust
-code that manipulates [syntax trees](syntax/ast/index.html) at
+macros](macros.html), but the expansion is performed by arbitrary Rust
+code that manipulates [syntax trees](../syntax/ast/index.html) at
 compile time.
 
 Let's write a plugin
@@ -126,14 +126,13 @@ The advantages over a simple `fn(&str) -> uint` are:
   a way to define new literal syntax for any data type.
 
 In addition to procedural macros, you can define new
-[`deriving`](reference.html#deriving)-like attributes and other kinds of
+[`deriving`](../reference.html#deriving)-like attributes and other kinds of
 extensions.  See
-[`Registry::register_syntax_extension`](rustc/plugin/registry/struct.Registry.html#method.register_syntax_extension)
+[`Registry::register_syntax_extension`](../rustc/plugin/registry/struct.Registry.html#method.register_syntax_extension)
 and the [`SyntaxExtension`
 enum](http://doc.rust-lang.org/syntax/ext/base/enum.SyntaxExtension.html).  For
 a more involved macro example, see
-[`src/libregex_macros/lib.rs`](https://github.com/rust-lang/rust/blob/master/src/libregex_macros/lib.rs)
-in the Rust distribution.
+[`regex_macros`](https://github.com/rust-lang/regex/blob/master/regex_macros/src/lib.rs).
 
 
 ## Tips and tricks
@@ -147,7 +146,7 @@ variables of the same name (but different syntax contexts) are in play
 in the same scope. In this case `--pretty expanded,hygiene` will tell
 you about the syntax contexts.
 
-You can use [`syntax::parse`](syntax/parse/index.html) to turn token trees into
+You can use [`syntax::parse`](../syntax/parse/index.html) to turn token trees into
 higher-level syntax elements like expressions:
 
 ```ignore
@@ -163,31 +162,31 @@ Looking through [`libsyntax` parser
 code](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/parser.rs)
 will give you a feel for how the parsing infrastructure works.
 
-Keep the [`Span`s](syntax/codemap/struct.Span.html) of
+Keep the [`Span`s](../syntax/codemap/struct.Span.html) of
 everything you parse, for better error reporting. You can wrap
-[`Spanned`](syntax/codemap/struct.Spanned.html) around
+[`Spanned`](../syntax/codemap/struct.Spanned.html) around
 your custom data structures.
 
 Calling
-[`ExtCtxt::span_fatal`](syntax/ext/base/struct.ExtCtxt.html#method.span_fatal)
+[`ExtCtxt::span_fatal`](../syntax/ext/base/struct.ExtCtxt.html#method.span_fatal)
 will immediately abort compilation. It's better to instead call
-[`ExtCtxt::span_err`](syntax/ext/base/struct.ExtCtxt.html#method.span_err)
+[`ExtCtxt::span_err`](../syntax/ext/base/struct.ExtCtxt.html#method.span_err)
 and return
-[`DummyResult`](syntax/ext/base/struct.DummyResult.html),
+[`DummyResult`](../syntax/ext/base/struct.DummyResult.html),
 so that the compiler can continue and find further errors.
 
 The example above produced an integer literal using
-[`AstBuilder::expr_uint`](syntax/ext/build/trait.AstBuilder.html#tymethod.expr_uint).
+[`AstBuilder::expr_uint`](../syntax/ext/build/trait.AstBuilder.html#tymethod.expr_uint).
 As an alternative to the `AstBuilder` trait, `libsyntax` provides a set of
-[quasiquote macros](syntax/ext/quote/index.html).  They are undocumented and
+[quasiquote macros](../syntax/ext/quote/index.html).  They are undocumented and
 very rough around the edges.  However, the implementation may be a good
 starting point for an improved quasiquote as an ordinary plugin library.
 
 
 # Lint plugins
 
 Plugins can extend [Rust's lint
-infrastructure](reference.html#lint-check-attributes) with additional checks for
+infrastructure](../reference.html#lint-check-attributes) with additional checks for
 code style, safety, etc. You can see
 [`src/test/auxiliary/lint_plugin_test.rs`](https://github.com/rust-lang/rust/blob/master/src/test/auxiliary/lint_plugin_test.rs)
 for a full example, the core of which is reproduced here:
@@ -236,11 +235,11 @@ foo.rs:4 fn lintme() { }
 The components of a lint plugin are:
 
 * one or more `declare_lint!` invocations, which define static
-  [`Lint`](rustc/lint/struct.Lint.html) structs;
+  [`Lint`](../rustc/lint/struct.Lint.html) structs;
 
 * a struct holding any state needed by the lint pass (here, none);
 
-* a [`LintPass`](rustc/lint/trait.LintPass.html)
+* a [`LintPass`](../rustc/lint/trait.LintPass.html)
   implementation defining how to check each syntax element. A single
   `LintPass` may call `span_lint` for several different `Lint`s, but should
   register them all through the `get_lints` method.
@@ -252,7 +251,7 @@ mostly use the same infrastructure as lint plugins, and provide examples of how
 to access type information.
 
 Lints defined by plugins are controlled by the usual [attributes and compiler
-flags](reference.html#lint-check-attributes), e.g. `#[allow(test_lint)]` or
+flags](../reference.html#lint-check-attributes), e.g. `#[allow(test_lint)]` or
 `-A test-lint`. These identifiers are derived from the first argument to
 `declare_lint!`, with appropriate case and punctuation conversion.
 

src/doc/trpl/src/if.md renamed to src/doc/trpl/if.md

@@ -409,7 +409,7 @@ test.rs:4         let y = &x;
 
 As you might guess, this kind of analysis is complex for a human, and therefore
 hard for a computer, too! There is an entire [guide devoted to references, ownership,
-and lifetimes](guide-ownership.html) that goes into this topic in
+and lifetimes](ownership.html) that goes into this topic in
 great detail, so if you want the full details, check that out.
 
 ## Best practices
@@ -542,7 +542,7 @@ with some improvements:
 4. Rust enforces that no other writeable pointers alias to this heap memory,
    which means writing to an invalid pointer is not possible.
 
-See the section on references or the [ownership guide](guide-ownership.html)
+See the section on references or the [ownership guide](ownership.html)
 for more detail on how lifetimes work.
 
 Using boxes and references together is very common. For example:
@@ -780,6 +780,6 @@ Here's a quick rundown of Rust's pointer types:
 
 # Related resources
 
-* [API documentation for Box](std/boxed/index.html)
-* [Ownership guide](guide-ownership.html)
+* [API documentation for Box](../std/boxed/index.html)
+* [Ownership guide](ownership.html)
 * [Cyclone paper on regions](http://www.cs.umd.edu/projects/cyclone/papers/cyclone-regions.pdf), which inspired Rust's lifetime system