rollup merge of #18903: steveklabnik/error_handling_guide

Now that we've done `fail` -> `panic`, I feel bringing back the error handling guide is a good idea. We had one long ago, but it was removed when conditions were removed.

This doesn't cover the new FromError stuff, but I feel like it's already useful in this state, so I'm sending this PR now.

diff --combined src/libcore/result.rs
index 0dc4fb839659dc8e6c8b95eae769a93bebb877ee,e2f739457970f5227c95400fa7ed5987c628af1a..16798c039bac603cd49cfbf269c447844c5a195c
--- 1/src/libcore/result.rs
--- 2/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@@ -38,8 -38,8 +38,8 @@@
  //!         return Err("invalid header length");
  //!     }
  //!     match header[0] {
 -//!         1 => Ok(Version1),
 -//!         2 => Ok(Version2),
 +//!         1 => Ok(Version::Version1),
 +//!         2 => Ok(Version::Version2),
  //!         _ => Err("invalid version")
  //!     }
  //! }
@@@ -227,57 -227,9 +227,11 @@@
  //! ```
  //!
  //! `try!` is imported by the prelude, and is available everywhere.
- //!
- //! # `Result` and `Option`
- //!
- //! The `Result` and [`Option`](../option/index.html) types are
- //! similar and complementary: they are often employed to indicate a
- //! lack of a return value; and they are trivially converted between
- //! each other, so `Result`s are often handled by first converting to
- //! `Option` with the [`ok`](type.Result.html#method.ok) and
- //! [`err`](type.Result.html#method.ok) methods.
- //!
- //! Whereas `Option` only indicates the lack of a value, `Result` is
- //! specifically for error reporting, and carries with it an error
- //! value.  Sometimes `Option` is used for indicating errors, but this
- //! is only for simple cases and is generally discouraged. Even when
- //! there is no useful error value to return, prefer `Result<T, ()>`.
- //!
- //! Converting to an `Option` with `ok()` to handle an error:
- //!
- //! ```
- //! use std::io::Timer;
- //! let mut t = Timer::new().ok().expect("failed to create timer!");
- //! ```
- //!
- //! # `Result` vs. `panic!`
- //!
- //! `Result` is for recoverable errors; `panic!` is for unrecoverable
- //! errors. Callers should always be able to avoid panics if they
- //! take the proper precautions, for example, calling `is_some()`
- //! on an `Option` type before calling `unwrap`.
- //!
- //! The suitability of `panic!` as an error handling mechanism is
- //! limited by Rust's lack of any way to "catch" and resume execution
- //! from a thrown exception. Therefore using panics for error
- //! handling requires encapsulating code that may panic in a task.
- //! Calling the `panic!` macro, or invoking `panic!` indirectly should be
- //! avoided as an error reporting strategy. Panics is only for
- //! unrecoverable errors and a panicking task is typically the sign of
- //! a bug.
- //!
- //! A module that instead returns `Results` is alerting the caller
- //! that failure is possible, and providing precise control over how
- //! it is handled.
- //!
- //! Furthermore, panics may not be recoverable at all, depending on
- //! the context. The caller of `panic!` should assume that execution
- //! will not resume after the panic, that a panic is catastrophic.
  
  #![stable]
  
 +pub use self::Result::*;
 +
  use std::fmt::Show;
  use slice;
  use slice::AsSlice;