Tidy up REPL environment documentation

Author: mpilgrem

doc/GUIDE.md

@@ -1343,17 +1343,20 @@ stack exec ghci
 ~~~
 
 But that won't load up locally written modules for access. For that, use the
-`stack ghci` command or its synonym `stack repl`. To then load modules from your
-project, use the `:m` command (for "module") followed by the module name.
+`stack ghci` or `stack repl` commands, which are equivalent. To then load
+modules from your project in GHCi, use the `:module` command (`:m` for short)
+followed by the module name.
 
 !!! note
 
-    If you have added upstream packages to your project please make sure to mark
-    them as *dependency package*s for faster and reliable usage of `stack ghci`.
-    Otherwise GHCi may have trouble due to conflicts of compilation flags or
-    having to unnecessarily interpret too many modules. See
-    [stack.yaml documentation](yaml_configuration.md#packages) to learn how to
-    mark a package as a *dependency package*.
+    If you have added packages to your project please make sure to mark them as
+    extra deps for faster and reliable usage of `stack ghci`. Otherwise GHCi may
+    have trouble due to conflicts of compilation flags or having to
+    unnecessarily interpret too many modules. See Stack's project-level
+    [configuration](yaml_configuration.md#extra-deps) to learn how to
+    configure a package as an extra-dep.
+
+For further information, see the [REPL environment](ghci.md) documentation.
 
 ## The `stack ghc` and `stack runghc` commands
 

doc/build_command.md

@@ -264,6 +264,12 @@ Unset the flag to disable this behaviour. When disabled:
   console noise. If you would like to see this content instead, you can use
   the `dump-logs` option.
 
+### The `stack build --pedantic` flag
+
+Pass the flag to build your project with the GHC options `-Wall` and `-Werror`.
+`-Wall` turns on all warning options that indicate potentially suspicious code.
+`-Werror` makes any warning into a fatal error.
+
 ### The `stack build --watch-all` flag
 
 Pass the flag to rebuild your project every time any local file changes (from

doc/ghci.md

@@ -1,84 +1,108 @@
 <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# GHCi
-
-`stack ghci` allows you to load components and files of your project into
-`ghci`. It uses the same TARGET syntax as `stack build`, and can also take
-options like `--test`, `--bench`, and `--flag`.  Similarly to `stack build`, the
-default is to load up ghci with all libraries and executables in the project.
-
-In order to load multiple components, `stack ghci` combines all of the ghc options
-together.  This doesn't work in the general case, but when the packages being
-loaded share similar conventions, it should work out.  A common source of issues
-is when one component defines default extensions which aren't assumed by another
-component.  For example, specifying `NoImplicitPrelude` in one component but
-not another is quite likely to cause failures.  `ghci` will be run with
+# REPL environment
+
+A read–evaluate–print loop (REPL) environment takes single user inputs, executes
+them, and returns the result to the user. GHCi is GHC's interactive environment.
+The `stack ghci` or `stack repl` commands, which are equivalent, allow you to
+load components and files of your project into GHCi.
+
+The command uses the same TARGET syntax as `stack build`. It can also take flags
+like `--test` and `--bench` and options like `--flag`. Similarly to
+`stack build`, the default is to load up GHCi with all libraries and executables
+in the project.
+
+In order to load multiple components, `stack ghci` combines all of the GHC
+options together. This doesn't work in the general case, but when the packages
+being loaded share similar conventions, it should work out. A common source of
+issues is when one component defines default extensions which aren't assumed by
+another component. For example, specifying `NoImplicitPrelude` in one component
+but not another is quite likely to cause failures. GHCi will be run with
 `-XNoImplicitPrelude`, but it is likely that modules in the other component
-assume that the Prelude is implicitly imported.
+assume that the `Prelude` is implicitly imported.
 
 ## Selecting Main module
 
 When loading multiple packages, there may be multiple definitions for the `Main`
-module.  You can specify which Main module to load by passing in the
-`--main-is TARGET` flag.  If no selection is made and there are multiple `Main`
-modules, you will be asked to select from a list of options.
+module. You can specify which `Main` module to load with the
+`--main-is <target>` option. If no selection is made and there are multiple
+`Main` modules, you will be asked to select from a list of options.
 
 ## Speeding up initial load
 
-There are two ways to speed up the initial startup of ghci:
+There are two ways to speed up the initial startup of GHCi:
 
-* `--no-build`, to skip an initial build step.  This only works if the
-  dependencies have already been built.
+1.  Pass the `--no-build` flag, to skip an initial build step. This works only
+    if the dependencies have already been built.
 
-* `--no-load`, to skip loading all defined modules into ghci.  You can then
-  directly use `:load MyModule` to load a specific module in your project.
+2.  Pass the `--no-load` flag, to skip loading all defined modules into GHCi.
+    You can then directly use `:load MyModule` in GHCi to load a specific module
+    in your project.
 
 ## Loading just the main module
 
 By default, `stack ghci` loads and imports all of the modules in the package.
-This allows you to easily use anything exported by your package.  This is
-usually quite convenient, but in some cases it makes sense to only load one
-module, or no modules at all.  The `--only-main` flag allows this.  It specifies
-that only the main module will be loaded, if any.  This is particularly useful
-in the following circumstances:
-
-1. You're loading the project in order to run it in ghci (e.g. via `main`), and
-   you intend to reload while developing.  Without the `--only-main` flag, you
-   will need to quit and restart ghci whenever a module gets deleted.  With the
+This allows you to easily use anything exported by your package. This is usually
+quite convenient, but in some cases it makes sense to only load one module, or
+no modules at all. The `--only-main` flag allows this. It specifies that only
+the main module will be loaded, if any. This is particularly useful in the
+following circumstances:
+
+1. You're loading the project in order to run it in GHCi (e.g. via `main`), and
+   you intend to reload while developing. Without the `--only-main` flag, you
+   will need to quit and restart GHCi whenever a module gets deleted. With the
    flag, reloading should work fine in this case.
 
-2. If many of your modules have exports named the same thing, then you'll need to
-   refer to them using qualified names.  To avoid this, it may be easier to use
-   `--only-main` to start with a blank slate and just import the modules you are
-   interested in.
+2. If many of your modules have exports named the same thing, then you'll need
+   to refer to them using qualified names. To avoid this, it may be easier to
+   use the `--only-main` flag to start with a blank slate and just import the
+   modules you are interested in.
 
 ## Loading a filepath directly
 
-Instead of the `TARGET` syntax, it is also possible to directly run
-`stack ghci src/MyFile.hs`.  This will figure out which component the file is
-associated with, and use the options from that component.
+Instead of the `TARGET` syntax, it is also possible to command directly, for
+example:
 
-## Specifying extra packages to build / depend on
+~~~text
+stack ghci src/MyFile.hs
+~~~
 
-Sometimes you want to load ghci with an additional package, that isn't a direct
-dependency of your components.  This can be achieved by using the `--package` flag.
-For example, if I want to experiment with the lens library, I can run
-`stack ghci --package lens`.
+This will figure out which component the file is associated with, and use the
+options from that component.
 
-## Running plain ghci
+## Specifying extra packages to build or depend on
 
-`stack ghci` always runs ghci configured to load code from packages in your
-project.  In particular, this means it passes in flags like `-hide-all-packages`
-and `-package-id=` in order to configure which packages are visible to ghci.
+Sometimes you want to load GHCi with an additional package, that isn't a direct
+dependency of your components. This can be achieved by using the `--package`
+option. For example, if I want to experiment with the `lens` library, I can
+command:
+
+~~~text
+stack ghci --package lens
+~~~
+
+## Running plain GHCi
+
+`stack ghci` always runs GHCi configured to load code from packages in your
+project. In particular, this means it passes in flags like `-hide-all-packages`
+and `-package-id=` in order to configure which packages are visible to GHCi.
 
 For doing experiments which just involve packages installed in your databases,
-it may be useful to run ghci plainly like `stack exec ghci`. This will run a
-plain `ghci` in an environment which includes `GHC_PACKAGE_PATH`, and so will
-have access to your databases.
-
-*Note*: Running `stack ghci` on a pristine copy of the code doesn't currently
-build libraries
-([#2790](https://github.com/commercialhaskell/stack/issues/2790)) or internal
-libraries ([#4148](https://github.com/commercialhaskell/stack/issues/4148)).
-It is recommended to always run a `stack build` before running `stack ghci`,
-until these two issues are closed.
+it may be useful to run GHCi plainly like:
+
+~~~text
+stack exec ghci
+~~~
+
+This will run a plain GHCi in an environment which includes `GHC_PACKAGE_PATH`,
+and so will have access to your databases.
+
+!!! note
+
+    Running `stack ghci` on a pristine copy of the code doesn't currently build
+    libraries
+    (issue [#2790](https://github.com/commercialhaskell/stack/issues/2790)) or
+    internal libraries
+    (issue [#4148](https://github.com/commercialhaskell/stack/issues/4148)). It
+    is recommended to always use `stack build` before using `stack ghci`, until
+    these two issues are closed.

doc/ghcjs.md

@@ -35,16 +35,16 @@ nav:
   - stack.yaml vs a Cabal file: stack_yaml_vs_cabal_package_file.md
   - Build command: build_command.md
   - Code coverage: coverage.md
-  - Stack and Visual Studio Code: Stack_and_VS_Code.md
-  - Developing on Windows: developing_on_windows.md
+  - REPL environment: ghci.md
   - Dependency visualization: dependency_visualization.md
   - Docker integration: docker_integration.md
   - Nix integration: nix_integration.md
   - Non-standard project initialization: nonstandard_project_init.md
+  - Stack and Visual Studio Code: Stack_and_VS_Code.md
+  - Developing on Windows: developing_on_windows.md
   - Shell auto-completion: shell_autocompletion.md
   - Travis CI: travis_ci.md
   - Azure CI: azure_ci.md
-  - GHCi: ghci.md
   - Lock files: lock_files.md
 - Advanced documentation:
   - Build overview: build_overview.md