Various READMEs and docs cleanup

Noticeably closes #11428.

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 If you're just reporting a bug, please see:
 
-https://github.com/mozilla/rust/wiki/HOWTO-submit-a-Rust-bug-report
+http://static.rust-lang.org/doc/master/complement-bugreport.html
 
 ## Pull request procedure
 

README.md

@@ -7,50 +7,49 @@ documentation.
 
 ### Windows
 
-1. Download and use the [installer][win-exe].
+1. Download and use the [installer and MinGW][win-wiki].
 2. Read the [tutorial].
 2. Enjoy!
 
-> ***Note:*** Windows users should read the detailed
+> ***Note:*** Windows users can read the detailed
-> [getting started][wiki-start] notes on the wiki. Even when using
+> [getting started][wiki-start] notes on the wiki.
-> the binary installer the Windows build requires a MinGW installation,
-> the precise details of which are not discussed here.
 
 [tutorial]: http://static.rust-lang.org/doc/tutorial.html
 [wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust
-[win-exe]: http://static.rust-lang.org/dist/rust-0.9-install.exe
+[win-wiki]: https://github.com/mozilla/rust/wiki/Using-Rust-on-Windows
 
 ### Linux / OS X
 
-1. Install the prerequisites (if not already installed)
+1. Make sure you have installed the dependencies:
-    * g++ 4.4 or clang++ 3.x
+    * `g++` 4.4 or `clang++` 3.x
-    * python 2.6 or later (but not 3.x)
+    * `python` 2.6 or later (but not 3.x)
-    * perl 5.0 or later
+    * `perl` 5.0 or later
-    * gnu make 3.81 or later
+    * GNU `make` 3.81 or later
-    * curl
+    * `curl`
-2. Download and build Rust
+2. Download and build Rust:
+
     You can either download a [tarball] or build directly from the [repo].
-    
+
     To build from the [tarball] do:
-    
+
         $ curl -O http://static.rust-lang.org/dist/rust-0.9.tar.gz
         $ tar -xzf rust-0.9.tar.gz
         $ cd rust-0.9
-    
+
     Or to build from the [repo] do:
 
         $ git clone https://github.com/mozilla/rust.git
         $ cd rust
 
     Now that you have Rust's source code, you can configure and build it:
-    
+
         $ ./configure
         $ make && make install
-    
+
-    You may need to use `sudo make install` if you do not normally have
+    > ***Note:*** You may need to use `sudo make install` if you do not normally have
-    permission to modify the destination directory. The install locations can
+    > permission to modify the destination directory. The install locations can
-    be adjusted by passing a `--prefix` argument to `configure`. Various other
+    > be adjusted by passing a `--prefix` argument to `configure`. Various other
-    options are also supported, pass `--help` for more information on them.
+    > options are also supported, pass `--help` for more information on them.
 
     When complete, `make install` will place several programs into
     `/usr/local/bin`: `rustc`, the Rust compiler; `rustdoc`, the
@@ -76,17 +75,16 @@ Snapshot binaries are currently built and tested on several platforms:
 * Linux (various distributions), x86 and x86-64
 * OSX 10.6 ("Snow Leopard") or greater, x86 and x86-64
 
-You may find that other platforms work, but these are our "tier 1"
+You may find that other platforms work, but these are our officially
 supported build environments that are most likely to work.
 
-Rust currently needs about 1.8G of RAM to build without swapping; if it hits
+Rust currently needs about 1.5 GiB of RAM to build without swapping; if it hits
 swap, it will take a very long time to build.
 
-There is lots more documentation in the [wiki].
+There is a lot more documentation in the [wiki].
 
 [wiki]: https://github.com/mozilla/rust/wiki
 
-
 ## License
 
 Rust is primarily distributed under the terms of both the MIT license
@@ -94,4 +92,3 @@ and the Apache License (Version 2.0), with portions covered by various
 BSD-like licenses.
 
 See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.
-

doc/README

@@ -1,28 +0,0 @@
-Pandoc, a universal document converter, is required to generate docs as HTML
-from Rust's source code. It's available for most platforms here:
-http://johnmacfarlane.net/pandoc/installing.html
-
-Node.js (http://nodejs.org/) is also required for generating HTML from
-the Markdown docs (reference manual, tutorials, etc.) distributed with
-this git repository.
-
-To generate all the docs, run `make docs` from the root of the repository.
-This will convert the distributed Markdown docs to HTML and generate HTML doc
-for the 'std' and 'extra' libraries.
-
-To generate HTML documentation from one source file/crate, do something like:
-
-  rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs
-
-(This, of course, requires that you've built/installed the `rustdoc` tool.)
-
-To generate an HTML version of a doc from Markdown, without having Node.js
-installed, do something like:
-
-  pandoc --from=markdown --to=html5 --number-sections -o rust.html rust.md
-
-The syntax for pandoc flavored markdown can be found at:
-http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
-
-A nice quick reference (for non-pandoc markdown) is at:
-http://kramdown.rubyforge.org/quickref.html

doc/README.md

@@ -0,0 +1,40 @@
+# Dependencies
+
+[Pandoc](http://johnmacfarlane.net/pandoc/installing.html), a universal
+document converter, is required to generate docs as HTML from Rust's
+source code.
+
+[Node.js](http://nodejs.org/) is also required for generating HTML from
+the Markdown docs (reference manual, tutorials, etc.) distributed with
+this git repository.
+
+# Building
+
+To generate all the docs, just run `make docs` from the root of the repository.
+This will convert the distributed Markdown docs to HTML and generate HTML doc
+for the 'std' and 'extra' libraries.
+
+To generate HTML documentation from one source file/crate, do something like:
+
+~~~~
+rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs
+~~~~
+
+(This, of course, requires a working build of the `rustdoc` tool.)
+
+# Additional notes
+
+To generate an HTML version of a doc from Markdown without having Node.js
+installed, you can do something like:
+
+~~~~
+pandoc --from=markdown --to=html5 --number-sections -o rust.html rust.md
+~~~~
+
+(rust.md being the Rust Reference Manual.)
+
+The syntax for pandoc flavored markdown can be found at:
+http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
+
+A nice quick reference (for non-pandoc markdown) is at:
+http://kramdown.rubyforge.org/quickref.html

doc/complement-bugreport.md

@@ -1,47 +1,45 @@
-% HOWTO submit a RUST bug report
+% How to submit a Rust bug report
 
 # I think I found a bug in the compiler!
 
-   If you see this message: ''error: internal compiler error: unexpected failure'',
+If you see this message: `error: internal compiler error: unexpected failure`,
 then you have definitely found a bug in the compiler. It's also possible that
 your code is not well-typed, but if you saw this message, it's still a bug in
 error reporting.
 
-   If you see a message about an LLVM assertion failure, then you have also
+If you see a message about an LLVM assertion failure, then you have also
 definitely found a bug in the compiler. In both of these cases, it's not your
 fault and you should report a bug!
 
-   If you see a compiler error message that you think is meant for users to see,
+If you see a compiler error message that you think is meant for users to see,
 but it confuses you, *that's a bug too*. If it wasn't clear to you, then it's
 an error message we want to improve, so please report it so that we can try
 to make it better.
 
-# I don't want to waste the Rust devs' time! How do I know the bug I found isn't a bug that already exists in the issue tracker?
+# How do I know the bug I found isn't a bug that already exists in the issue tracker?
 
-   If you don't have much time, then don't worry about that. Just submit the bug.
+If you don't have enough time for a search, then don't worry about that. Just submit
-If it's a duplicate, somebody will notice that and close it. No one will laugh
+the bug. If it's a duplicate, somebody will notice that and close it during triage.
-at you, we promise (and if someone did, they would be violating the Rust
-[code of conduct](https://github.com/mozilla/rust/wiki/Note-development-policy code of conduct)).
 
-   If you have more time, it's very helpful if you can type the text of the error
+If you have the time for it, it would be useful to type the text of the error
 message you got [into the issue tracker search box](https://github.com/mozilla/rust/issues)
 to see if there's an existing bug that resembles your problem. If there is,
-and it's an open bug, you can comment on that issue and say you ran into it too.
+and it's an open bug, you can comment on that issue and say you are also affected.
-This will encourage devs to fix it. But again, don't let this stop you from
+This will encourage the devs to fix it. But again, don't let this stop you from
 submitting a bug. We'd rather have to do the work of closing duplicates than
 miss out on valid bug reports.
 
 # What information should I include in a bug report?
 
-    It's helpful to include your specific OS (for example: Mac OS X 10.8.3,
+It generally helps our diagnosis to include your specific OS (for example: Mac OS X 10.8.3,
-Windows 7, Ubuntu 12.0.4) and your hardware architecture (for example: i686, x86_64).
+Windows 7, Ubuntu 12.04) and your hardware architecture (for example: i686, x86_64).
 It's also helpful to copy/paste the output of re-running the erroneous rustc
-commmand with the `-v` flag. Finally, if you can run the offending command under gdb,
+command with the `-v` flag. Finally, if you can run the offending command under gdb,
-pasting a stack trace can be useful; to do so, you will need to set a breakpoint on `rust_begin_unwind`.
+pasting a stack trace can be useful; to do so, you will need to set a breakpoint on `rust_fail`.
 
-# I submitted a bug, but nobody has commented on it! I'm sad.
+# I submitted a bug, but nobody has commented on it!
 
-   This is sad, but does happen sometimes, since we're short-staffed. If you
+This is sad, but does happen sometimes, since we're short-staffed. If you
 submit a bug and you haven't received a comment on it within 3 business days,
 it's entirely reasonable to either ask on the #rust IRC channel,
 or post on the [rust-dev mailing list](https://mail.mozilla.org/listinfo/rust-dev)

doc/complement-lang-faq.md

@@ -236,7 +236,7 @@ They start small (ideally in the hundreds of bytes) and expand dynamically by ca
 
 * Requiring explicit bounds means that the compiler can type-check the code at the point where the type-parametric item is *defined*, rather than delaying to when its type parameters are instantiated.  You know that *any* set of type parameters fulfilling the bounds listed in the API will compile. It's an enforced minimal level of documentation, and results in very clean error messages.
 
-* Scoping of methods is also a problem.  C++ needs [Koenig (argument dependent) lookup](http://en.wikipedia.org/wiki/Argument-dependent_name_lookup), which comes with its own host of problems. Explicit bounds avoid this issue: traits are explicitly imported and then used as bounds on type parameters, so there is a clear mapping from the method to its implementation (via the trait and the instantiated type).  
+* Scoping of methods is also a problem.  C++ needs [Koenig (argument dependent) lookup](http://en.wikipedia.org/wiki/Argument-dependent_name_lookup), which comes with its own host of problems. Explicit bounds avoid this issue: traits are explicitly imported and then used as bounds on type parameters, so there is a clear mapping from the method to its implementation (via the trait and the instantiated type).
 
   * Related to the above point: since a parameter explicitly names its trait bounds, a single type is able to implement traits whose sets of method names overlap, cleanly and unambiguously.
 

doc/complement-project-faq.md

@@ -15,7 +15,7 @@ Existing languages at this level of abstraction and efficiency are unsatisfactor
 # What are some non-goals?
 
 * To employ any particularly cutting-edge technologies. Old, established techniques are better.
-* To prize expressiveness, minimalism or elegance above other goals. These are desirable but subordinate goals. 
+* To prize expressiveness, minimalism or elegance above other goals. These are desirable but subordinate goals.
 * To cover the "systems language" part all the way down to "writing an OS kernel".
 * To cover the complete feature-set of C++, or any other language. It should provide majority-case features.
 * To be 100% static, 100% safe, 100% reflective, or too dogmatic in any other sense. Trade-offs exist.

doc/complement-usage-faq.md

@@ -20,16 +20,12 @@ If you aren't sure which paths you need, try setting RUST_LOG to `::help` and ru
 
 This is much like the answer for `log` statements, except that you also need to compile your program in debug mode (that is, pass `--cfg debug` to `rustc`).  Note that if you want to see the instrumentation of the `debug!` statements within `rustc` itself, you need a debug version of `rustc`; you can get one by invoking `configure` with the `--enable-debug` option.
 
-# What does it mean when a program exits with `leaked memory in rust main loop (2 objects)' failed, rt/memory_region.cpp:99 2 objects`?
+# What does it mean when a program exits with `leaked memory`?
+
+The error looks like this: `leaked memory in rust main loop (2 objects)' failed, rt/memory_region.cpp:99 2 objects`.
 
 This message indicates a memory leak, and is mostly likely to happen on rarely exercised failure paths. Note that failure unwinding is not yet implemented on windows so this is expected. If you see this on Linux or Mac it's a compiler bug; please report it.
 
-# Why do gdb backtraces end with the error 'previous frame inner to this frame (corrupt stack?)'?
-
-**Short answer** your gdb is too old to understand our hip new stacks. Upgrade to a newer version (7.3.1 is known to work).
-
-**Long answer** Rust uses 'spaghetti stacks' (a linked list of stacks) to allow tasks to start very small but recurse arbitrarily deep when necessary. As a result, new frames don't always decrease the stack pointer like gdb expects but instead may jump around the heap to different stack segments. Newer versions of gdb recognize that the special function called __morestack may change the stack pointer to a different stack.
-
 # Why did my build create a bunch of zero-length files in my lib directory?
 
 This is a normal part of the Rust build process. The build system uses these zero-length files for dependency tracking, as the actual names of the Rust libraries contain hashes that can't be guessed easily by the Makefiles.

doc/index.md

@@ -6,44 +6,46 @@
 .header-section-number { display: none; }
 </style>
 
-[The Rust tutorial](tutorial.html)  
+[The Rust tutorial](tutorial.html)  ([PDF](tutorial.pdf))
-[The Rust reference manual](rust.html) ([PDF](rust.pdf))  
+[The Rust reference manual](rust.html) ([PDF](rust.pdf))
 
 # Guides
 
-[Pointers](guide-pointers.html)  
+[Pointers](guide-pointers.html)
-[References and Lifetimes](guide-lifetimes.html)  
+[References and Lifetimes](guide-lifetimes.html)
-[Containers and Iterators](guide-container.html)  
+[Containers and Iterators](guide-container.html)
-[Tasks and Communication](guide-tasks.html)  
+[Tasks and Communication](guide-tasks.html)
-[Foreign Function Interface](guide-ffi.html)  
+[Foreign Function Interface](guide-ffi.html)
-[Macros](guide-macros.html)  
+[Macros](guide-macros.html)
-[Packaging](guide-rustpkg.html)  
+[Packaging](guide-rustpkg.html)
-[Testing](guide-testing.html)  
+[Testing](guide-testing.html)
-[Conditions](guide-conditions.html)  
+[Conditions](guide-conditions.html)
 
 # Libraries
 
-[std](std/index.html)  
+[The standard library, `libstd`](std/index.html)
-[extra](extra/index.html)  
+[The extra library, `libextra`](extra/index.html)
-[green](green/index.html)  
+
-[native](native/index.html)  
+[The M:N runtime library, `libgreen`](green/index.html)
-[syntax](syntax/index.html)  
+[The 1:1 runtime library, `libnative`](native/index.html)
-[rustc](rustc/index.html)  
+
+[The Rust parser, `libsyntax`](syntax/index.html)
+[The Rust compiler, `librustc`](rustc/index.html)
 
 # Tooling
 
-[The rustpkg manual](rustpkg.html)  
+[The `rustpkg` manual](rustpkg.html)
 
 # FAQs
 
-[Language FAQ](complement-lang-faq.html)  
+[Language FAQ](complement-lang-faq.html)
-[Project FAQ](complement-project-faq.html)  
+[Project FAQ](complement-project-faq.html)
-[Usage FAQ](complement-usage-faq.html)  
+[Usage FAQ](complement-usage-faq.html)
-[Code cheatsheet](complement-cheatsheet.html) - "How do I do X?"  
+[Code cheatsheet](complement-cheatsheet.html) - "How do I do X?"
-[HOWTO submit a bug report](complement-bugreport.html)  
+[How to submit a bug report](complement-bugreport.html)
 
 # External resources
 
-The Rust [IRC channel](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) - #rust on irc.mozilla.org  
+The Rust [IRC channel](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) - `#rust` on irc.mozilla.org
-The Rust community on [Reddit](http://reddit.com/r/rust)  
+The Rust community on [Reddit](http://reddit.com/r/rust)
-The Rust [wiki](http://github.com/mozilla/rust/wiki)  
+The Rust [wiki](http://github.com/mozilla/rust/wiki)

src/README.md

@@ -0,0 +1,43 @@
+This is a preliminary version of the Rust compiler, libraries and tools.
+
+Source layout:
+
+| `librustc/`         | The self-hosted compiler                                  |
+| `libstd/`           | The standard library (imported and linked by default)     |
+| `libextra/`         | The "extras" library (slightly more peripheral code)      |
+| `libsyntax/`        | The Rust parser and pretty-printer                        |
+| ------------------- | --------------------------------------------------------- |
+| `rt/`               | The runtime system                                        |
+| `rt/rust_*.c`       | - The majority of the runtime services                    |
+| `rt/isaac`          | - The PRNG used for pseudo-random choices in the runtime  |
+| `rt/bigint`         | - The bigint library used for the 'big' type              |
+| `rt/uthash`         | - Small hashtable-and-list library for C, used in runtime |
+| `rt/sync`           | - Concurrency utils                                       |
+| `rt/util`           | - Small utility classes for the runtime.                  |
+| `rt/vg`             | - Valgrind headers                                        |
+| `rt/msvc`           | - MSVC support                                            |
+| ------------------- | --------------------------------------------------------- |
+| `test/`             | Testsuite                                                 |
+| `test/compile-fail` | - Tests that should fail to compile                       |
+| `test/run-fail`     | - Tests that should compile, run and fail                 |
+| `test/run-pass`     | - Tests that should compile, run and succeed              |
+| `test/bench`        | - Benchmarks and miscellaneous                            |
+| `test/pretty`       | - Pretty-printer tests                                    |
+| `test/auxiliary`    | - Dependencies of tests                                   |
+| ------------------- | --------------------------------------------------------- |
+| `compiletest/`      | The test runner                                           |
+| ------------------- | --------------------------------------------------------- |
+| `librustpkg/`       | The package manager and build system                      |
+| ------------------- | --------------------------------------------------------- |
+| `librustdoc/`       | The Rust API documentation tool                           |
+| ------------------- | --------------------------------------------------------- |
+| `llvm/`             | The LLVM submodule                                        |
+| ------------------- | --------------------------------------------------------- |
+| `libuv/`            | The libuv submodule                                       |
+| ------------------- | --------------------------------------------------------- |
+| `rustllvm/`         | LLVM support code                                         |
+| ------------------- | --------------------------------------------------------- |
+| `libfuzzer/`        | A collection of fuzz testers                              |
+| ------------------- | --------------------------------------------------------- |
+| `etc/`              | Scripts, editors support, misc                            |
+

src/README.txt

@@ -1,43 +0,0 @@
-This is a preliminary version of the Rust compiler, libraries and tools
-
-Source layout:
-
-librustc/          The self-hosted compiler
-
-libstd/            The standard library (imported and linked by default)
-libextra/          The "extras" library (slightly more peripheral code)
-libsyntax/         The Rust parser and pretty-printer
-
-rt/                The runtime system
-rt/rust_*.cpp      - The majority of the runtime services
-rt/isaac           - The PRNG used for pseudo-random choices in the runtime
-rt/bigint          - The bigint library used for the 'big' type
-rt/uthash          - Small hashtable-and-list library for C, used in runtime
-rt/sync            - Concurrency utils
-rt/util            - Small utility classes for the runtime.
-rt/vg              - Valgrind headers
-rt/msvc            - MSVC support
-
-test/              Testsuite
-test/compile-fail  - Tests that should fail to compile
-test/run-fail      - Tests that should compile, run and fail
-test/run-pass      - Tests that should compile, run and succeed
-test/bench         - Benchmarks and miscellanea
-test/pretty        - Pretty-printer tests
-test/auxiliary     - Dependencies of tests
-
-compiletest/       The test runner
-
-librustpkg/        The package manager and build system
-
-librustdoc/        The Rust API documentation tool
-
-llvm/              The LLVM submodule
-
-libuv/             The libuv submodule
-
-rustllvm/          LLVM support code
-
-libfuzzer/         A collection of fuzz testers
-
-etc/               Scripts, editor support, misc

src/libsyntax/diagnostic.rs

@@ -18,7 +18,7 @@ use std::local_data;
 use extra::term;
 
 static BUG_REPORT_URL: &'static str =
-    "https://github.com/mozilla/rust/wiki/HOWTO-submit-a-Rust-bug-report";
+    "http://static.rust-lang.org/doc/master/complement-bugreport.html";
 
 pub trait Emitter {
     fn emit(&self,