Auto merge of #39855 - steveklabnik:mdbook-reference, r=GuillaumeGomez

Port the reference to mdbook

Part of #39588.

This is only a work in progress. Still left to do:

- [x] double check contents weren't duplicated/lost with the move to individual pages (I'm going to do this)
- [x] fix up links [and footnotes](#39855 (comment)) (@frewsxcv has volunteered to help with this)
- [x] change `src/doc/reference.md` to redirect to the book
- [x] move the reference on the doc index to be part of the bookshelf

Author: bors

src/bootstrap/doc.rs

@@ -115,10 +115,6 @@ pub fn standalone(build: &Build, target: &str) {
            .arg("-o").arg(&out)
            .arg(&path);
 
-        if filename == "reference.md" {
-           cmd.arg("--html-in-header").arg(&full_toc);
-        }
-
         if filename == "not_found.md" {
             cmd.arg("--markdown-no-toc")
                .arg("--markdown-css")

src/bootstrap/step.rs

@@ -568,6 +568,15 @@ pub fn build_rules<'a>(build: &'a Build) -> Rules {
          })
          .default(build.config.docs)
          .run(move |s| doc::rustbook(build, s.target, "nomicon"));
+    rules.doc("doc-reference", "src/doc/reference")
+         .dep(move |s| {
+             s.name("tool-rustbook")
+              .host(&build.config.build)
+              .target(&build.config.build)
+              .stage(0)
+         })
+         .default(build.config.docs)
+         .run(move |s| doc::rustbook(build, s.target, "reference"));
     rules.doc("doc-standalone", "src/doc")
          .dep(move |s| {
              s.name("rustc")

src/doc/book/src/attributes.md

@@ -67,4 +67,4 @@ Rust attributes are used for a number of different things. There is a full list
 of attributes [in the reference][reference]. Currently, you are not allowed to
 create your own attributes, the Rust compiler defines them.
 
-[reference]: ../reference.html#attributes
+[reference]: ../reference/attributes.html

src/doc/book/src/compiler-plugins.md

@@ -119,7 +119,7 @@ The advantages over a simple `fn(&str) -> u32` are:
   a way to define new literal syntax for any data type.
 
 In addition to procedural macros, you can define new
-[`derive`](../reference.html#derive)-like attributes and other kinds of
+[`derive`](../reference/attributes.html#derive)-like attributes and other kinds of
 extensions.  See `Registry::register_syntax_extension` and the `SyntaxExtension`
 enum.  For a more involved macro example, see
 [`regex_macros`](https://github.com/rust-lang/regex/blob/master/regex_macros/src/lib.rs).
@@ -165,8 +165,8 @@ quasiquote as an ordinary plugin library.
 # Lint plugins
 
 Plugins can extend [Rust's lint
-infrastructure](../reference.html#lint-check-attributes) with additional checks for
-code style, safety, etc. Now let's write a plugin
+infrastructure](../reference/attributes.html#lint-check-attributes) with
+additional checks for code style, safety, etc. Now let's write a plugin
 [`lint_plugin_test.rs`](https://github.com/rust-lang/rust/blob/master/src/test/run-pass-fulldeps/auxiliary/lint_plugin_test.rs)
 that warns about any item named `lintme`.
 
@@ -244,9 +244,10 @@ 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
-`-A test-lint`. These identifiers are derived from the first argument to
-`declare_lint!`, with appropriate case and punctuation conversion.
+flags](../reference/attributes.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.
 
 You can run `rustc -W help foo.rs` to see a list of lints known to `rustc`,
 including those provided by plugins loaded by `foo.rs`.

src/doc/book/src/macros.md

@@ -101,7 +101,7 @@ trees, at compile time. The semicolon is optional on the last (here, only)
 case. The "pattern" on the left-hand side of `=>` is known as a ‘matcher’.
 These have [their own little grammar] within the language.
 
-[their own little grammar]: ../reference.html#macros
+[their own little grammar]: ../reference/macros.html
 
 The matcher `$x:expr` will match any Rust expression, binding that syntax tree
 to the ‘metavariable’ `$x`. The identifier `expr` is a ‘fragment specifier’;
@@ -363,7 +363,7 @@ fn main() {
 }
 ```
 
-[items]: ../reference.html#items
+[items]: ../reference/items.html
 
 # Recursive macros
 
@@ -490,7 +490,7 @@ be forced to choose between parsing `$i` and parsing `$e`. Changing the
 invocation syntax to put a distinctive token in front can solve the problem. In
 this case, you can write `$(I $i:ident)* E $e:expr`.
 
-[item]: ../reference.html#items
+[item]: ../reference/items.html
 
 # Scoping and macro import/export
 
@@ -565,7 +565,7 @@ When this library is loaded with `#[macro_use] extern crate`, only `m2` will
 be imported.
 
 The Rust Reference has a [listing of macro-related
-attributes](../reference.html#macro-related-attributes).
+attributes](../reference/attributes.html#macro-related-attributes).
 
 # The variable `$crate`
 

src/doc/book/src/syntax-index.md

@@ -235,10 +235,10 @@
 [Primitive Types (Tuple Indexing)]: primitive-types.html#tuple-indexing
 [Primitive Types (Tuples)]: primitive-types.html#tuples
 [Raw Pointers]: raw-pointers.html
-[Reference (Byte String Literals)]: ../reference.html#byte-string-literals
-[Reference (Integer literals)]: ../reference.html#integer-literals
-[Reference (Raw Byte String Literals)]: ../reference.html#raw-byte-string-literals
-[Reference (Raw String Literals)]: ../reference.html#raw-string-literals
+[Reference (Byte String Literals)]: ../reference/tokens.html/#byte-string-literals
+[Reference (Integer literals)]: ../reference/tokens.html#integer-literals
+[Reference (Raw Byte String Literals)]: ../reference/tokens.html#raw-byte-string-literals
+[Reference (Raw String Literals)]: ../reference/tokens.html#raw-string-literals
 [References and Borrowing]: references-and-borrowing.html
 [Strings]: strings.html
 [Structs (Update syntax)]: structs.html#update-syntax

src/doc/grammar.md

@@ -187,7 +187,7 @@ literal : [ string_lit | char_lit | byte_string_lit | byte_lit | num_lit | bool_
 The optional `lit_suffix` production is only used for certain numeric literals,
 but is reserved for future extension. That is, the above gives the lexical
 grammar, but a Rust parser will reject everything but the 12 special cases
-mentioned in [Number literals](reference.html#number-literals) in the
+mentioned in [Number literals](reference/tokens.html#number-literals) in the
 reference.
 
 #### Character and string literals

src/doc/index.md

@@ -16,14 +16,6 @@ builds documentation for individual Rust packages.
 Rust provides a standard library with a number of features; [we host its
 documentation here][api].
 
-## Reference Documentation
-
-Rust does not yet have a formal specification, but we have [a reference document
-][ref]. It is guaranteed to be accurate, but not complete. We now have a
-policy that all new features must be included in the reference before
-stabilization; however, we are still back-filling things that landed before
-then. That work is being tracked [here][38643].
-
 ## Extended Error Documentation
 
 Many of Rust's errors come with error codes, and you can request extended
@@ -37,11 +29,17 @@ nicknamed 'The Rust Bookshelf.'
 
 * [The Rust Programming Language][book] teaches you how to program in Rust.
 * [The Rustonomicon][nomicon] is your guidebook to the dark arts of unsafe Rust.
+* [The Reference][ref] is not a formal spec, but is more detailed and comprehensive than the book.
+
+Another few words about the reference: it is guaranteed to be accurate, but not
+complete. We now have a policy that all new features must be included in the
+reference before stabilization; however, we are still back-filling things that
+landed before then. That work is being tracked [here][38643].
 
 [Rust Learning]: https://github.com/ctjhoa/rust-learning
 [Docs.rs]: https://docs.rs/
 [api]: std/index.html
-[ref]: reference.html
+[ref]: reference/index.html
 [38643]: https://github.com/rust-lang/rust/issues/38643
 [err]: error-index.html
 [book]: book/index.html