Book: Add section on logging

cf. #68

For now, suggests using env_logger, as it's pretty popular, but notes
that there are alternatives to consider.

Might mention convey when it covers logging, too.

Cargo.toml

@@ -32,11 +32,17 @@ path = "src/tutorial/errors-exit.rs"
 name = "output-progressbar"
 path = "src/tutorial/output-progressbar.rs"
 
+[[bin]]
+name = "output-log"
+path = "src/tutorial/output-log.rs"
+
 [dependencies]
 structopt = "0.2.10"
 failure = "0.1.3"
 exitfailure = "0.5.1"
 indicatif = "0.10.1"
+log = "0.4.6"
+env_logger = "0.6.0"
 
 [dev-dependencies]
 assert_cmd = "0.10"

src/tutorial/output-log.rs

@@ -0,0 +1,7 @@
+use log::{info, warn};
+
+fn main() {
+    env_logger::init();
+    info!("starting up");
+    warn!("oops, nothing implemented!");
+}

src/tutorial/output.md

@@ -189,33 +189,75 @@ To make it easier to understand what is happening in our program,
 we might want to add some log statements.
 This is usually easy while writing your application.
 But it will become super helpful when running this program again in half a year.
+In some regard,
+logging is the same as using `println`,
+except that you can specify the importance of a message.
+The levels you can usually use are use _error_, _warn_, _info_, _debug_, and _trace_
+(_error_ has the highest priority, _trace_ the lowest).
+
+To add simple logging to your application,
+you'll need two things:
+The [log] crate (this contains)
+and an _adapter_ that actually writes the log output somewhere useful.
+Having the ability to use log adapters is very flexible:
+You can, for example, use them to write logs not only to the terminal
+but also to _syslog_, or to a central log server.
+
+Since we are right now only concerned with writing a CLI application,
+an easy adapter to use is [env_logger].
+It's called "env" logger because you can
+use an environment variable to specify which parts of your application
+you want to log
+(and at which level you want to log them).
+It will prefix your log messages with a timestamp
+and the module where the log messages comes from.
+Since libraries can also use `log`,
+you easily configure their log output, too.
+
+[log]: https://crates.io/crates/log
+[env_logger]: https://crates.io/crates/env_logger
 
-<aside class="todo">
+Here's a quick example:
 
-**TODO:**
-`log` crate: macros with similar syntax to `println`
-[Issue #68](https://github.com/rust-lang-nursery/cli-wg/issues/68)
+```rust,ignore
+{{#include output-log.rs}}
+```
 
-</aside>
+Assuming you have this as a `src/bin/output-log.rs`,
+you can run it like this:
 
-<aside class="todo">
+```console
+$ env RUST_LOG=output_log=info cargo run --bin output-log
+    Finished dev [unoptimized + debuginfo] target(s) in 0.17s
+     Running `target/debug/output-log`
+[2018-11-30T20:25:52Z INFO  output_log] starting up
+[2018-11-30T20:25:52Z WARN  output_log] oops, nothing implemented!
+```
 
-**TODO:**
-crate for actual log output – which one?
-env_logger?
-Link to `../in-depth/human-communication.html`
-[Issue #68](https://github.com/rust-lang-nursery/cli-wg/issues/68)
+`RUST_LOG` is the name of the environment variable
+you can use to set your log settings.
+`env_logger` also contains a builder
+so you can programmatically adjust these settings,
+and, for example, also show _info_ level messages by default.
 
-</aside>
+There are a lot of alternative logging adapters out there,
+and also alternatives or extension to `log`.
+If you know your application will have a lot to log,
+make sure to review them,
+and make your users' life easier.
 
 <aside>
 
-**Aside:**
+**Tip:**
 Experience has shown that even mildly useful CLI programs can end up being used for years to come.
 (Especially if they were meant as a temporary solution.)
 If your application doesn't work
 and someone (e.g., you, in the future) needs to figure out why,
 being able to pass `--verbose` to get additional log output
 can make the difference between minutes and hours of debugging.
+The [clap-verbosity-flag] crate contains a quick way
+to add a `--verbose` to a project using `structopt`.
+
+[clap-verbosity-flag]: https://crates.io/crates/clap-verbosity-flag
 
 </aside>