Re #5566 Improve online documentation for dump-logs

Author: mpilgrem

doc/build_command.md

@@ -198,7 +198,7 @@ The same Cabal flag name can be set (or unset) for multiple packages (at the
 command line only) with:
 
 ~~~text
-stack build --flag *:[-]<flag)name>
+stack build --flag *:[-]<flag_name>
 ~~~
 
 !!! note
@@ -555,14 +555,15 @@ package is targetted in a multi-package project (for example, using
 `stack build <package_name>`).
 
 * **One target package:** The build output for the target package is sent to the
-  console as it happens.
+  standard error output stream of 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 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
+  unless an error occurs that prevents that. 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 standard error output stream of 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.

doc/yaml_configuration.md

@@ -687,12 +687,13 @@ Command line equivalent (takes precedence): `--[no-]dump-logs` flag
 
 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)
+unless an error occurs that prevents that. For further information, see the
+[`stack build --[no-]interleaved-output` flag](build_command.md#-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:
+('dumped') to the standard error output stream of the console at the end of the
+build. Possible values are:
 
 ~~~yaml
 dump-logs: none      # don't dump the content of any log files
@@ -703,6 +704,15 @@ 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`.
 
+If GHC reports an error during the build and a log file is created, that build
+output will be included in the log file. Stack will also report errors during
+building to the standard error output stream. That stream can be piped to a
+file. For example, for a file named `stderr.log`:
+
+~~~text
+stack --no-dump-logs --color always build --no-interleaved-output 2> stderr.log
+~~~
+
 ### extra-include-dirs
 
 Default: `[]`