std: Refining crate docs

Yet another attempt to make the prose on the std crate page
clearer and more informative.

This does a lot of things: tightens up the opening, adds useful links
(including a link to the search bar), offers guidance on how to use
the docs, and expands the prelude docs as a useful newbie entrypoint.

src/libstd/lib.rs

@@ -10,29 +10,122 @@
 
 //! # The Rust Standard Library
 //!
-//! The Rust Standard Library provides the essential runtime
-//! functionality for building portable Rust software.
+//! The Rust Standard Library is the foundation of portable Rust
+//! software, a set of minimal and battle-tested shared abstractions
+//! for the [broader Rust ecosystem](https://crates.io). It offers
+//! core types (e.g. [`Vec`](vec/index.html)
+//! and[`Option`](option/index.html)), library-defined [operations on
+//! language primitives](#primitive) (e.g. [`u32`](u32/index.html) and
+//! [`str`](str/index.html)), [standard macros](#macros),
+//! [I/O](io/index.html) and [multithreading](thread/index.html), among
+//! [many other lovely
+//! things](#what-is-in-the-standard-library-documentation?).
 //!
-//! The Rust Standard Library is available to all Rust crates by
-//! default, just as if contained an `extern crate std` import at the
-//! crate root. Therefore the standard library can be accessed in
-//! `use` statements through the path `std`, as in `use std::thread`,
-//! or in expressions through the absolute path `::std`, as in
-//! `::std::thread::sleep_ms(100)`.
+//! `std` is available to all Rust crates by default, just as if each
+//! one contained an `extern crate std` import at the [crate
+//! root][book-crate-root]. Therefore the standard library can be
+//! accessed in [`use`][book-use] statements through the path `std`,
+//! as in [`use std::env`](env/index.html), or in expressions
+//! through the absolute path `::std`, as in
+//! [`::std::env::args()`](env/fn.args.html).
+//!
+//! [book-crate-root]: file:///home/brian/dev/rust2/build/doc/book/crates-and-modules.html#basic-terminology:-crates-and-modules
+//! [book-use]: ../book/crates-and-modules.html#importing-modules-with-use
 //!
 //! Furthermore, the standard library defines [The Rust
 //! Prelude](prelude/index.html), a small collection of items, mostly
-//! traits, that are imported into and available in every module.
+//! traits, that are imported into every module and through trait
+//! resolution provide Rust with much of its *standard flavor*.
 //!
-//! ## What is in the standard library
+//! # How to read this documentation
 //!
-//! The standard library is a set of minimal, battle-tested
-//! core types and shared abstractions for the [broader Rust
-//! ecosystem](https://crates.io) to build on.
+//! If you already know the name of what you are looking for the
+//! fastest way to find it is to use the <a href="#"
+//! onclick="document.getElementsByName('search')[0].focus();">search
+//! bar</a> at the top of the page.
 //!
-//! The [primitive types](#primitives), though not defined in the
-//! standard library, are documented here, as are the predefined
-//! [macros](#macros).
+//! Otherwise, you may want to jump to one of these useful sections:
+//!
+//! * [`std::*` modules](#modules)
+//! * [Primitive types](#primitives)
+//! * [Standard macros](#macros)
+//! * [The Rust Prelude](prelude/index.html)
+//!
+//! If this is your first time, the documentation for the standard
+//! library is written to be casually perused and clicking on
+//! interesting things should generally lead you to interesting
+//! places. Still, there are important bits you don't want to miss, so
+//! read on for a tour of the standard library and its documentation.
+//!
+//! Once you are familiar with the contents of the standard library
+//! you may begin to find the verbosity of the prose distracting. At
+//! this stage in your development you may want to press the **[-]**
+//! button near the top of the page to collapse it into a more
+//! skimmable view.
+//!
+//! While you are looking at that **[-]** button also notice the
+//! **[src]** button. Rust's API documentation comes with the source
+//! code and you are encouraged to read it. The standard library
+//! source is generally high quality and a peek behind the curtains is
+//! often enlightening.
+//!
+//! # What is in the standard library documentation?
+//!
+//! Lots of stuff. Well, broadly four things actually.
+//!
+//! First of all, The Rust Standard Library is divided into a number
+//! of focused modules, [all listed further down this page](#modules).
+//! These modules are the bedrock upon which all of Rust is forged,
+//! and they have mighty names like [`std::slice`](slice/index.html)
+//! and [`std::cmp`](cmp/index.html). Modules' documentation typically
+//! includes an overview of the module along with examples, and are
+//! a smart place to start familiarizing yourself with the library.
+//!
+//! Secondly, implicit methods on [primitive
+//! types](../book/primitive-types.html) are documented here. This can
+//! be a source of confusion for two reasons:
+//!
+//! 1. While primitives are implemented by the compiler, the standard
+//!    library implements methods directly on the primitive types (and
+//!    it is the only library that does so), which are [documented in
+//!    the section on primitives](#primitives).
+//! 2. The standard library exports many modules *with the same name
+//!    as primitive types*. These define additional items related
+//!    to the primitive type, but not the all-important methods.
+//!
+//! So for example there is a [page for the primitive type
+//! `i32`](primitive.i32.html) that lists all the methods that can be
+//! called on 32-bit integers (mega useful), and there is a [page for
+//! the module `std::i32`](i32/index.html) that documents the constant
+//! values `MIN` and `MAX` (rarely useful).
+//!
+//! Note the documentation for the primitives
+//! [`str`](primitive.str.html) and [`[T]`](primitive.slice.html)
+//! (also called 'slice'). Many method calls on
+//! [`String`](string/struct.String.html) and
+//! [`Vec`](vec/struct.Vec.html) are actually calls to methods on
+//! `str` and `[T]` respectively, via [deref
+//! coercions](../book/deref-coercions.html). *Accepting that
+//! primitive types are documented on their own pages will bring you a
+//! deep inner wisdom. Embrace it now before proceeding.*
+//!
+//! Thirdly, the standard library defines [The Rust
+//! Prelude](prelude/index.html), a small collection of items - mostly
+//! traits - that are imported into every module. The traits in the
+//! prelude are pervasive, making the prelude documentation a good
+//! entry point to learning about the library.
+//!
+//! And lastly, the standard library exports a number of standard
+//! macros, and [lists them on this page](#macros) (technically, not
+//! all of the standard macros are defined by the standard library -
+//! some are defined by the compiler - but they are documented here
+//! the same).  Like the prelude, the standard macros are imported by
+//! default into all crates.
+//!
+//! # A Tour of The Rust Standard Library
+//!
+//! The rest of this crate documentation is dedicated to pointing
+//! out notable features of The Rust Standard Library.
 //!
 //! ## Containers and collections
 //!
@@ -43,17 +136,18 @@
 //! [`Iterator`](iter/trait.Iterator.html), which works with the `for`
 //! loop to access collections.
 //!
-//! The common container type, `Vec`, a growable vector backed by an array,
-//! lives in the [`vec`](vec/index.html) module. Contiguous, unsized regions
-//! of memory, `[T]`, commonly called "slices", and their borrowed versions,
-//! `&[T]`, commonly called "borrowed slices", are built-in types for which the
-//! [`slice`](slice/index.html) module defines many methods.
+//! The common container type, `Vec`, a growable vector backed by an
+//! array, lives in the [`vec`](vec/index.html) module. Contiguous,
+//! unsized regions of memory, `[T]`, commonly called "slices", and
+//! their borrowed versions, `&[T]`, commonly called "borrowed
+//! slices", are primitive types [with many implicit
+//! methods](primitive.slice.html) defined by the standard library.
 //!
-//! `&str`, a UTF-8 string, is a built-in type, and the standard library
-//! defines methods for it on a variety of traits in the
-//! [`str`](str/index.html) module. Rust strings are immutable;
-//! use the `String` type defined in [`string`](string/index.html)
-//! for a mutable string builder.
+//! `str`, a UTF-8 string, is a primitive type, and the standard
+//! library defines [many methods for it](primitive.str.html).
+//! Rust `str`s are immutable; use the owned `String` type
+//! defined in [`string`](string/index.html) for building and mutating
+//! strings.
 //!
 //! For converting to strings use the [`format!`](fmt/index.html)
 //! macro, and for converting from strings use the
@@ -88,6 +182,7 @@
 //! [`atomic`](sync/atomic/index.html) and
 //! [`mpsc`](sync/mpsc/index.html), which contains the channel types
 //! for message passing.
+//!
 
 // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364)
 #![cfg_attr(stage0, feature(custom_attribute))]