[06 of 10]: docs: clarify default enabled/disabled log level behavior

The "Enabling logging" section of the crate-level docs are here
updated to clarify the default behavior as it pertains to the
logging level.

Previously, the first paragraph stated that all logging is disabled
except for the default level, but the third paragraph stated that if
no log level was specified then /all/ logging was enabled.

It turns out that the third paragraph was really intended as a
continuation of the second paragraph, the applicable context of
which is limited to those scenarios in which a logging directive has
been supplied.

This changeset reworks the paragraph structure slightly to make the
intent more clear, and also to make it easy to quickly identify the
most important aspects:

    A. Old para 1 split into two separate paras:
        - first states clearly the default behavior (now in bold)
        - second introduces 'RUST_LOG' and logging directives

    B. Old para 3 split into two separate paras:
        - first now qualifies the statement with "When specifying
          the crate name or a module path..."
        - second introduces log level names

    C. The existing statement that describes the behavior when only
       a log level is provided (it sets the global log level) is
       now in bold markdown.

It might make sense to refine this further at some point so that the
flow of the text answers in order the user's questions:

    1. "What is the default behavior?"  (Already first; good.)

    2. "How do I set the log level for the entire app?"

    3. "How do I set the log level more surgically?"

Our current flow is: (1), (3), (2)

Author: salewski

src/lib.rs

@@ -89,11 +89,12 @@
 //!
 //! ## Enabling logging
 //!
-//! Log levels are controlled on a per-module basis, and by default all logging
-//! is disabled except for `error!`. Logging is controlled via the **`RUST_LOG`**
-//! environment variable. The value of this environment variable is a
-//! comma-separated list of logging directives. A logging directive is of the
-//! form:
+//! Log levels are controlled on a per-module basis, and **by default all
+//! logging is disabled except for the `error` level**.
+//!
+//! Logging is controlled via the **`RUST_LOG`** environment variable. The
+//! value of this environment variable is a comma-separated list of logging
+//! directives. A logging directive is of the form:
 //!
 //! ```text
 //! path::to::module=level
@@ -105,15 +106,18 @@
 //! Furthermore, this path is a prefix-search, so all modules nested in the
 //! specified module will also have logging enabled.
 //!
-//! The actual `level` is optional to specify. If omitted, all logging will
-//! be enabled. If specified, it must be one of the strings `debug`, `error`,
-//! `info`, `warn`, or `trace`. The letter case is not significant for the
-//! logging level names; e.g., `debug`, `DEBUG`, and `dEbuG` all represent the
-//! same logging level.
+//! When providing the crate name or a module path, explicitly specifying the
+//! log level is optional. If omitted, all logging for the item (and its
+//! children) will be enabled.
+//!
+//! When specifying a logging level, the name provided must be one of the
+//! strings `debug`, `error`, `info`, `warn`, or `trace`. The letter case is
+//! not significant for the logging level names; e.g., `debug`, `DEBUG`, and
+//! `dEbuG` all represent the same logging level.
 //!
 //! As the log level for a module is optional, the module to enable logging for
-//! is also optional. If only a `level` is provided, then the global log
-//! level for all modules is set to this value.
+//! is also optional. **If only a level is provided, then the global log
+//! level for all modules is set to this value.**
 //!
 //! Some examples of valid values of `RUST_LOG` are:
 //!