Document how RUST_LOG works

Author: brson

doc/rust.texi

@@ -3626,30 +3626,51 @@ communication facilities.
 
 The runtime contains a system for directing logging expressions to a logging
 console and/or internal logging buffers. @xref{Ref.Expr.Log}.  Logging
-expressions can be enabled or disabled via a two-dimensional filtering process:
+expressions can be enabled per module.
+
+Logging output is enabled by setting the @code{RUST_LOG} environment variable.
+@code{RUST_LOG} accepts a logging specification that is a comma-separated list
+of paths. For each module containing log statements, if @code{RUST_LOG}
+contains the path to that module or a parent of that module, then its logs
+will be output to the console. The path to an module consists of the crate
+name, any parent modules, then the module itself, all separated by double
+colons (@code{::}).
+
+As an example, to see all the logs generated by the compiler, you would set
+@code{RUST_LOG} to @code{rustc}, which is the crate name (as specified in its
+@code{link} attribute).  @xref{Ref.Comp.Crate}. To narrow down the logs to
+just crate resolution, you would set it to @code{rustc::metadata::creader}.
+
+Note that when compiling either .rs or .rc files that don't specifiy a crate
+name the crate is given a default name that matches the source file, sans
+extension. In that case, to turn on logging for a program compiled from, e.g.
+helloworld.rs, @code{RUST_LOG} should be set to @code{helloworld}.
+
+As a convenience, the logging spec can also be set to a special psuedo-crate,
+@code{::help}. In this case, when the application starts, the runtime will
+simply output a list of loaded modules containing log statements, then exit.
+
+The Rust runtime itself generates logging information. The runtime's logs are
+generated for a number of artificial modules in the @code{::rt} psuedo-crate,
+and can be enabled just like the logs for any standard module. The full list
+of runtime logging modules follows.
 
 @itemize
-
-@sp 1
-@item
-By Item
-
-Each @emph{item} (module, function, iterator, object, type) in Rust has a
-static path within its crate module, and can have logging enabled or
-disabled on a path-prefix basis.
-
-@sp 1
-@item
-By Task
-
-Each @emph{task} in a running Rust program has a unique ownership relation
-through the task ownership tree, and can have logging enabled or disabled on
-an ownership-ancestry basis.
+@item @code{::rt::mem} Memory management
+@item @code{::rt::comm} Messaging and task communication
+@item @code{::rt::task} Task management
+@item @code{::rt::dom} Task scheduling
+@item @code{::rt::trace} Unused
+@item @code{::rt::cache} Type descriptor cache
+@item @code{::rt::upcall} Compiler-generated runtime calls
+@item @code{::rt::timer} The scheduler timer
+@item @code{::rt::gc} Garbage collection
+@item @code{::rt::stdlib} Functions used directly by the standard library
+@item @code{::rt::kern} The runtime kernel
+@item @code{::rt::backtrace} Unused
+@item @code{::rt::callback} Unused
 @end itemize
 
-Logging is integrated into the language for efficiency reasons, as well as the
-need to filter logs based on these two built-in dimensions.
-
 @node       Ref.Run.Sig
 @subsection Ref.Run.Sig
 @c * Ref.Run.Sig::               Runtime signal handler.