Rewrite liblog into a logging facade

.gitignore

@@ -1,2 +1,2 @@
-/target
-/Cargo.lock
+target/
+Cargo.lock

Cargo.toml

@@ -9,8 +9,5 @@ repository = "https://github.com/rust-lang/log"
 documentation = "http://doc.rust-lang.org/log"
 homepage = "https://github.com/rust-lang/log"
 description = """
-Logging macros and infrastructure for Rust
+A lightweight logging facade for Rust
 """
-
-[dependencies]
-regex = "0.1"

README.md

@@ -1,23 +1,79 @@
 log
 ===
 
-A Rust library for application logging via debug/info/warn/error macros
+A Rust library providing a lightweight logging *facade*.
 
 [![Build Status](https://travis-ci.org/rust-lang/log.svg?branch=master)](https://travis-ci.org/rust-lang/log)
 
 [Documentation](http://doc.rust-lang.org/log)
 
+A logging facade provides a single logging API that abstracts over the actual
+logging implementation. Libraries can use the logging API provided by this
+crate, and the consumer of those libraries can choose the logging
+implementation that is most suitable for its use case.
+
 ## Usage
 
-Add this to your `Cargo.toml`:
+## In libraries
+
+Libraries should link only to the `log` crate, and use the provided macros to
+log whatever information will be useful to downstream consumers:
 
 ```toml
 [dependencies]
-log = "0.1.0"
+log = "0.2"
 ```
 
-and this to your crate root:
+```rust
+#[macro_use]
+extern crate log;
+
+pub fn shave_the_yak(yak: &Yak) {
+    trace!("Commencing yak shaving");
+
+    loop {
+        match find_a_razor() {
+            Ok(razor) => {
+                info!("Razor located: {}", razor);
+                yak.shave(razor);
+                break;
+            }
+            Err(err) => {
+                warn!("Unable to locate a razor: {}, retrying", err);
+            }
+        }
+    }
+}
+```
+
+## In executables
+
+Executables should chose a logger implementation and initialize it early in the
+runtime of the program. Logger implementations will typically include a
+function to do this. Any log messages generated before the logger is
+initialized will be ignored.
+
+The executable itself may use the `log` crate to log as well.
+
+The `env_logger` crate provides a logger implementation that mirrors the
+functionality of the old revision of the `log` crate.
+
+```toml
+[dependencies]
+log = "0.2"
+env_logger = "0.1"
+```
 
 ```rust
+#[macro_use]
 extern crate log;
+extern crate env_logger;
+
+fn main() {
+    env_logger::init().unwrap();
+
+    info!("starting up");
+
+    // ...
+}
 ```

env/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "env_logger"
+version = "0.0.1"
+authors = ["The Rust Project Developers"]
+
+[dependencies.log]
+version = "0.1"
+path = ".."
+
+[dependencies]
+regex = "0.1"