Further document output options

Author: mpilgrem

doc/build_command.md

@@ -285,13 +285,15 @@ package is targetted in a multi-package project (for example, using
 * **One target package:** The build output for the target package is sent to the
   console as it happens.
 
-* **More than one target package:** The build output from GHC
-  (as opposed to from Stack) for each target package is sent to a log file for
-  that package, unless it contains warnings or errors. At the end of the build,
-  the location of the directory containing the log files is reported. To also
-  output the contents of the log files to the console at the end of the build,
-  use Stack's `dump-logs` option. For further information about that option, see
-  the [YAML configuration](yaml_configuration.md#dump-logs) documentation.
+* **More than one target package:** The build output from GHC (as opposed to
+  from Stack) for each target package is sent to a log file for that package,
+  unless an error occurs. At the end of the build, the location of the directory
+  containing the log files is reported. To also output the contents of the log
+  files to the console at the end of the build, use Stack's `dump-logs` option.
+  For further information about that option, see the
+  [YAML configuration](yaml_configuration.md#dump-logs) documentation. The
+  default `dump-logs` mode is to output the contents of the log files that are
+  warnings.
 
 ### The `stack build --pedantic` flag
 

doc/yaml_configuration.md

@@ -620,17 +620,24 @@ Default: `warning`
 
 Command line equivalent (takes precedence): `--[no-]dump-logs` flag
 
-Control which log output from local non-dependency packages to print to the
-console. By default, Stack will only do this when building a single target
-package or if the log contains warnings, to avoid generating unnecessarily
-verbose output.
+In the case of *non-interleaved* output and *more than one* target package,
+Stack sends the build output from GHC for each target package to a log file,
+unless an error occurs. For further information, see the
+[`stack build --[no-\]interleaved-output` flag](build_command.md#the-stack-build---no-interleaved-output-flag)
+documentation.
+
+The value of the `dump-logs` key controls what, if any, log file content is sent
+('dumped') to the console at the end of the build. Possible values are:
 
 ~~~yaml
-dump-logs: none      # don't dump logs even if they contain warnings
-dump-logs: warning   # dump logs that contain warnings
-dump-logs: all       # dump all logs for local non-dependency packages
+dump-logs: none      # don't dump the content of any log files
+dump-logs: warning   # dump the content of log files that are warnings
+dump-logs: all       # dump all of the content of log files
 ~~~
 
+At the command line, `--no-dump-logs` is equivalent to `dump-logs: none` and
+`--dump-logs` is equivalent to `dump-logs: all`.
+
 ### extra-include-dirs
 
 Default: `[]`