Merge pull request #5806 from commercialhaskell/stable

Stable

Author: mpilgrem

CONTRIBUTING.md

@@ -116,24 +116,36 @@ confirmation and we will close it.
 
 ## Documentation
 
-If you would like to help with documentation, please note that for most cases
-the Wiki has been deprecated in favor of markdown files placed in a new `/doc`
-subdirectory of the repository itself. Please submit a
+The files which make up Stack's documentation are located in the `doc`
+directory of the repository. They are formatted in the
+[Markdown syntax](https://daringfireball.net/projects/markdown/), with some
+extensions.
+
+Those files are rendered on [haskellstack.org](http://haskellstack.org) by
+[Read the Docs](https://readthedocs.org/) using
+[MkDocs](https://www.mkdocs.org/). The `stable` branch of the repository
+provides the 'stable' version of the online documentation. The `master` branch
+provides the 'latest' version of the documentation.
+
+The 'stable' version of the online documentation is intended to be applicable to
+the latest released version of Stack. If you would like to help with that
+documentation, please submit a
 [pull request](https://help.github.com/articles/using-pull-requests/) with your
 changes/additions based off the
-[the stable branch](https://github.com/commercialhaskell/stack/tree/stable).
+[stable branch](https://github.com/commercialhaskell/stack/tree/stable).
 
-The documentation is rendered on [haskellstack.org](http://haskellstack.org) by
-readthedocs.org using Sphinx and CommonMark. Since links and formatting vary
-from GFM, please check the documentation there before submitting a PR to fix
-those.
+The specific versions of the online documentation (eg `v: v2.7.5`) are generated
+from the content of files at the point in the responsitory's history specified
+by the corresponding release tag. Consequently, that content is fixed once
+released.
 
-If your changes move or rename files, or subsume Wiki content, please continue
-to leave a file/page in the old location temporarily, in addition to the new
-location. This will allow users time to update any shared links to the old
-location. Please also update any links in other files, or on the Wiki, to point
-to the new file location.
+The Markdown syntax supported by MkDocs can differ from the GitHub Flavored
+Markdown ([GFM](https://github.github.com/gfm/)) supported for content on
+GitHub.com. Please refer to the
+[MkDocs documentation](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown) 
+to ensure your pull request will achieve the desired rendering.
 
+The configuration file for MkDocs is `mkdocs.yml`.
 
 ## Code
 

doc/GUIDE.md

@@ -1146,7 +1146,7 @@ We've already used `stack exec` multiple times in this guide. As you've likely
 already guessed, it allows you to run executables, but with a slightly modified
 environment. In particular: `stack exec` looks for executables on Stack's bin
 paths, and sets a few additional environment variables (like adding those paths
-to `PATH`, and setting `GHC_PACKAGE_PATH`, which tells GHC which package
+to the PATH, and setting `GHC_PACKAGE_PATH`, which tells GHC which package
 databases to use).
 
 If you want to see exactly what the modified environment looks like, try:
@@ -1830,7 +1830,6 @@ There are lots of resources available for learning more about Stack:
 * The [home page](http://haskellstack.org)
 * The [Stack mailing list](https://groups.google.com/d/forum/haskell-stack)
 * The [FAQ](faq.md)
-* The [Stack wiki](https://github.com/commercialhaskell/stack/wiki)
 * The [haskell-stack tag on Stack Overflow](http://stackoverflow.com/questions/tagged/haskell-stack)
 * [Another getting started with Stack tutorial](http://seanhess.github.io/2015/08/04/practical-haskell-getting-started.html)
 * [Why is Stack not Cabal?](https://www.fpcomplete.com/blog/2015/06/why-is-stack-not-cabal)

doc/developing_on_windows.md

@@ -19,53 +19,51 @@ commands](https://github.com/msys2/msys2/wiki/Using-packages) that work with
 tools — should be started with `stack exec -- pacman`.
 
 The Stack-supplied MSYS2 can itself be updated with the Stack-supplied `pacman`.
-See the MSYS2 guide ['III. Updating packages'](https://www.msys2.org/wiki/MSYS2-installation/). If the Stack-supplied `pacman` has a version that is
-5.0.1.6403 or greater (see `stack exec -- pacman --version`) then the command to
-update is simply:
+See the MSYS2 guide
+['III. Updating packages'](https://www.msys2.org/wiki/MSYS2-installation/). If
+the Stack-supplied `pacman` has a version that is 5.0.1.6403 or greater (see
+`stack exec -- pacman --version`) then the command to update is simply:
 
     stack exec -- pacman -Syuu
 
-This command may need to be run more than once, until everything is reported by `pacman` as 'up to date' and 'nothing to do'.
+This command may need to be run more than once, until everything is reported by
+`pacman` as 'up to date' and 'nothing to do'.
 
 ## Setup.hs ##
 
-`Setup.hs` is automatically run inside the stack environment. So when
-you need to launch another tool you don't need to prefix the command
-with `stack exec --` within the custom `Setup.hs` file.
+`Setup.hs` is automatically run inside the Stack environment. So when you need
+to launch another tool you don't need to prefix the command with `stack exec --`
+within the custom `Setup.hs` file.
 
 ## Pacman packages to install for common Haskell packages ##
 
-The following lists MSYS2 packages known to allow the installation of
-some common Haskell packages on Windows. Feel free to submit
-additional entries via a pull request.
+The following lists MSYS2 packages known to allow the installation of some
+common Haskell packages on Windows. Feel free to submit additional entries via a
+pull request.
 
-* For [text-icu](https://github.com/bos/text-icu) install `mingw64/mingw-w64-x86_64-icu`
+* For [text-icu](https://github.com/bos/text-icu) install
+  `mingw64/mingw-w64-x86_64-icu`
 
-## Cmake ##
+## CMake ##
 
-Cmake has trouble finding other tools even if they are available on
-the `PATH`. Likely this is not a cmake problem but one of the
-environment not fully integrating. For example GHC comes with a copy
-of GCC which is not installed by MSYS2 itself. If you want to use this
-GCC you can provide a full path to it, or find it first with
-`System.Directory.findExecutable` if you want to launch GCC from a
-Haskell file such as `Setup.hs`.
+CMake has trouble finding other tools even if they are available on the PATH.
+Likely this is not a CMake problem but one of the environment not fully
+integrating. For example GHC comes with a copy of GCC which is not installed by
+MSYS2 itself. If you want to use this GCC you can provide a full path to it, or
+find it first with `System.Directory.findExecutable` if you want to launch GCC
+from a Haskell file such as `Setup.hs`.
 
-Experience tells that the `mingw-w64` versions of make and cmake are
-most likely to work. Though there are other versions available through
-pacman, so have a look to see what works for you. Both tools can be
-installed with the commands:
+Experience tells that the `mingw-w64` versions of Make and CMake are most
+likely to work. Though there are other versions available through `pacman`, so
+have a look to see what works for you. Both tools can be installed with the
+commands:
 
-```
-stack exec -- pacman -S mingw-w64-x86_64-make
-stack exec -- pacman -S mingw-w64-x86_64-cmake
-```
+    stack exec -- pacman -S mingw-w64-x86_64-make
+    stack exec -- pacman -S mingw-w64-x86_64-cmake
 
-Even though make and cmake are then both installed into the same
-environment. Cmake still seems to have trouble to find make. To help
-cmake find GCC and make supply the following flags:
+Even though Make and CMake are then both installed into the same environment,
+CMake still seems to have trouble to find Make. To help CMake find GCC and Make
+supply the following flags:
 
-```
--DCMAKE_C_COMPILER=path
--DCMAKE_MAKE_PROGRAM=path
-```
+    -DCMAKE_C_COMPILER=path
+    -DCMAKE_MAKE_PROGRAM=path

doc/faq.md

@@ -196,41 +196,40 @@ the following line to your .cabal file:
 
 You could also use the [`--custom-preprocessor-extensions` flag](yaml_configuration.md#custom-preprocessor-extensions)
 
-## I already have GHC installed, can I still use stack?
+## I already have GHC installed, can I still use Stack?
 
-Yes. In its default configuration, stack will simply ignore any system GHC
-installation and use a sandboxed GHC that it has installed itself (typically
-via the `stack setup` command). You can find these sandboxed GHC installations
-in `~/.stack/programs/$platform/ghc-$version/`.
+Yes. In its default configuration, Stack will simply ignore any system GHC
+installation and use a sandboxed GHC that it has installed itself. You can find
+these sandboxed GHC installations in the `ghc-*` directories in the
+`stack path --programs` directory.
 
-If you would like stack to use your system GHC installation, use the
+If you would like Stack to use your system GHC installation, use the
 [`--system-ghc` flag](yaml_configuration.md#system-ghc) or run
-`stack config set system-ghc --global true` to make stack check your
-`PATH` for a suitable GHC by default.
+`stack config set system-ghc --global true` to make Stack check your PATH for a
+suitable GHC by default.
 
-Note that stack can only use a system GHC installation if its version is
-compatible with the configuration of the current project, particularly the
-[`resolver` setting](yaml_configuration.md#resolver).
+Stack can only use a system GHC installation if its version is compatible with
+the configuration of the current project, particularly the
+[`resolver` or `snapshot` setting](yaml_configuration.md#resolver).
 
-Note that GHC installation doesn't work for all OSes, so in some cases you
+GHC installation doesn't work for all operating systems, so in some cases you
 will need to use `system-ghc` and install GHC yourself.
 
-## How does stack determine what GHC to use?
+## How does Stack determine what GHC to use?
 
-In its default configuration, stack determines from the current project which
-GHC version, architecture etc. it needs. It then looks in
-`~/.stack/programs/$platform/ghc-$version/` for a compatible GHC, requesting
-to install one via `stack setup` if none is found.
+In its default configuration, Stack determines from the current project which
+GHC version, architecture etc it needs. It then looks in the `ghc-<version>`
+subdirectory of the `stack path --programs` directory for a compatible GHC,
+requesting to install one via `stack setup` if none is found.
 
 If you are using the [`--system-ghc` flag](yaml_configuration.md/#system-ghc) or
-have configured `system-ghc: true` either in the project `stack.yaml`
-or the global `~/.stack/config.yaml`, stack will use the first GHC that it finds
-on your `PATH`, falling back on its sandboxed installations only if the found GHC
-doesn't comply with the various requirements (version, architecture) that your
-project needs.
+have configured `system-ghc: true` either in the project `stack.yaml` or the
+global `config.yaml`, Stack will use the first GHC that it finds on your PATH,
+falling back on its sandboxed installations only if the found GHC doesn't comply
+with the various requirements (version, architecture) that your project needs.
 
 See [this issue](https://github.com/commercialhaskell/stack/issues/420) for a
-detailed discussion of stack's behavior when `system-ghc` is enabled.
+detailed discussion of Stack's behavior when `system-ghc` is enabled.
 
 ## How do I upgrade to GHC 7.10.2 with stack?
 
@@ -563,12 +562,12 @@ Yes:
 
 ## How do I resolve linker errors when running `stack setup` or `stack build` on macOS?
 
-This is likely to be caused by having a LLVM installation and default Apple
-Clang compiler both under the `PATH`. The symptom of this issue is a linker
-error "bad relocation (Invalid pointer diff)". The compiler picks up
-inconsistent versions of binaries and the mysterious error occurs.
+This is likely to be caused by having both a LLVM installation and default Apple
+Clang compiler on the PATH. The symptom of this issue is a linker error "bad
+relocation (Invalid pointer diff)". The compiler picks up inconsistent versions
+of binaries and the mysterious error occurs.
 
-The workaround is to remove LLVM binaries from the `PATH`.
+The workaround is to remove LLVM binaries from the PATH.
 
 ## How do I suppress `'-nopie'` warnings with `stack build` on macOS?
 

doc/glossary.md

@@ -9,6 +9,7 @@ The following terms are used in Stack's documentation.
 |Cabal              |The Haskell Common Architecture for Building Applications and Libraries, provided by the [`Cabal` package](https://hackage.haskell.org/package/Cabal). Also referred to as Cabal (the library) to distinguish it from Cabal (the tool).|
 |Cabal file|A file containing a [package description](https://cabal.readthedocs.io/en/stable/cabal-package.html) used by Cabal, named `<package_name>.cabal`.|
 |Cabal (the tool)|The Haskell build tool provided by the [`cabal-install` package](https://hackage.haskell.org/package/cabal-install).|
+|CMake              |A [system](https://cmake.org/) for managing build processes.|
 |`config.yaml`      |A non-project-specific configuration file used by Stack.  |
 |Docker             |A [platform](https://www.docker.com/) for developing,  shipping, and running applications. It can package and run an application in a loosely isolated environment called a _container_.|
 |Emacs              |[GNU Emacs](https://www.gnu.org/software/emacs/), an extensible, customisable text editor.|
@@ -21,11 +22,14 @@ The following terms are used in Stack's documentation.
 |GHCup              |An [installer](https://www.haskell.org/ghcup/) for Haskell.
 |Git                |A [distributed version control system](https://git-scm.com/).|
 |Hackage            |The [Haskell Package Repository](https://hackage.haskell.org/).
+|Haddock            |The [document generation tool](https://hackage.haskell.org/package/haddock) for Haskell libraries.|
 |'Haskell' extension|The ['Haskell' extension]() for VS Code.                  |
 |HLS                |[Haskell Language Server](https://haskell-language-server.readthedocs.io/en/latest/), an implementation of the Language Server Protocol for Haskell.|
+|Homebrew           |A [package manager](https://brew.sh/) for macOS or Linux, or its executable `brew`.|
 |Hpack              |A [format](https://github.com/sol/hpack) for Haskell packages or the executable `hpack` that produces a Cabal file from `package.yaml`.|
 |Linux              |A family of operating systems based on the Linux kernal.  |
 |macOS              |The primary operating system for Apple's Mac computers. Previously known as Mac OS X or OS X.|
+|Make               |A [build automation tool](https://www.gnu.org/software/make/).|
 |MSYS2              |The [MSYS2](https://www.msys2.org/) software distribution and building platform for Windows.|
 |Nix                |A purely functional [package manager](https://nixos.org/), available for Linux and macOS.|
 |`package.yaml`     |A file that describes a package in the Hpack format.      |