Various READMEs and docs cleanup

Noticeably closes #11428.

Author: adrientetar

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
-> [getting started][wiki-start] notes on the wiki. Even when using
-> the binary installer the Windows build requires a MinGW installation,
-> the precise details of which are not discussed here.
+> ***Note:*** Windows users can read the detailed
+> [getting started][wiki-start] notes on the wiki.
 
 [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)
-    * g++ 4.4 or clang++ 3.x
-    * python 2.6 or later (but not 3.x)
-    * perl 5.0 or later
-    * gnu make 3.81 or later
-    * curl
-2. Download and build Rust
+1. Make sure you have installed the dependencies:
+    * `g++` 4.4 or `clang++` 3.x
+    * `python` 2.6 or later (but not 3.x)
+    * `perl` 5.0 or later
+    * GNU `make` 3.81 or later
+    * `curl`
+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
-    permission to modify the destination directory. The install locations can
-    be adjusted by passing a `--prefix` argument to `configure`. Various other
-    options are also supported, pass `--help` for more information on them.
+
+    > ***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
+    > be adjusted by passing a `--prefix` argument to `configure`. Various other
+    > 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,22 +75,20 @@ 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
 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

@@ -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/README.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 it's a duplicate, somebody will notice that and close it. No one will laugh
-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 don't have enough time for a search, then don't worry about that. Just submit
+the bug. If it's a duplicate, somebody will notice that and close it during triage.
 
-   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.
-This will encourage devs to fix it. But again, don't let this stop you from
+and it's an open bug, you can comment on that issue and say you are also affected.
+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,
-Windows 7, Ubuntu 12.0.4) and your hardware architecture (for example: i686, x86_64).
+It generally helps our diagnosis to include your specific OS (for example: Mac OS X 10.8.3,
+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,
-pasting a stack trace can be useful; to do so, you will need to set a breakpoint on `rust_begin_unwind`.
+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_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-bugreport.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-lang-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-project-faq.md

@@ -20,15 +20,11 @@ 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`?
 
-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?)'?
+The error looks like this: `leaked memory in rust main loop (2 objects)' failed, rt/memory_region.cpp:99 2 objects`.
 
-**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.
+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 did my build create a bunch of zero-length files in my lib directory?
 

doc/complement-usage-faq.md

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