Merge pull request #5816 from mpilgrem/hpack

Fix #5498 Clarify that `package.yaml` is an Hpack file format

Author: mpilgrem

doc/GUIDE.md

@@ -217,11 +217,11 @@ multi-package projects, which we'll elaborate on as this guide progresses.
 
 Another file important to the build is `package.yaml`.
 
-The `package.yaml` file is the preferred package format that is provided
-built-in by Stack through the [hpack tool](https://github.com/sol/hpack). The
-default behaviour is to generate the Cabal file (here named `helloworld.cabal`)
-from this `package.yaml` file, and accordingly you should **not** modify the
-Cabal file.
+The `package.yaml` file describes the package in the
+[Hpack](https://github.com/sol/hpack) format. Stack has in-built Hpack
+functionality and this is its preferred package format. The default behaviour is
+to generate the Cabal file (here named `helloworld.cabal`) from this
+`package.yaml` file, and accordingly you should **not** modify the Cabal file.
 
 It is also important to remember that Stack is built on top of the Cabal build
 system. Therefore, an understanding of the moving parts in Cabal are necessary.
@@ -233,7 +233,7 @@ language pragmas, and so on.
 
 In this guide, we'll discuss the bare minimum necessary to understand how to
 modify a `package.yaml` file. You can see a full list of the available options
-at the [hpack documentation](https://github.com/sol/hpack#quick-reference). The
+at the [Hpack documentation](https://github.com/sol/hpack#quick-reference). The
 Cabal User Guide the definitive reference for the
 [Cabal file format](https://cabal.readthedocs.io/en/stable/cabal-package.html).
 

doc/faq.md

@@ -556,9 +556,15 @@ Unfortunately `stack build` does not have an obvious equivalent to `cabal build
 
 Yes:
 
-* If a package directory contains an Hpack `package.yaml` file, then Stack will use it to generate a `.cabal` file when building the package.
-* You can run `stack init` to initialize a `stack.yaml` file regardless of whether your packages are declared with `.cabal` files or with Hpack `package.yaml` files.
-* You can use the `with-hpack` configuration option to specify an Hpack executable to use instead of the Hpack bundled with Stack.
+* If a package directory contains an [Hpack](https://github.com/sol/hpack)
+  `package.yaml` file, then Stack will use it to generate a Cabal file when
+  building the package.
+* You can run `stack init` to initialize a `stack.yaml` file regardless of
+  whether your packages are declared with Cabal files or with Hpack
+  `package.yaml` files.
+* You can use the `with-hpack` YAML configuration or command line option to
+  specify an Hpack executable to use instead of Stack's in-built Hpack
+  functionality.
 
 ## How do I resolve linker errors when running `stack setup` or `stack build` on macOS?
 

doc/stack_yaml_vs_cabal_package_file.md

@@ -1,18 +1,18 @@
 <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>
 
-# stack.yaml vs cabal package file
+# stack.yaml vs Cabal package file
 
 Due to their apparent overlap, the purpose of the following three files can be
 unclear:
 
 * `stack.yaml`
-* A cabal package file, e.g. `my-package.cabal`
+* A Cabal package file, e.g. `my-package.cabal`
 * `package.yaml`
 
 The last two are easy to explain: `package.yaml` is a file format supported by
-[hpack](https://github.com/sol/hpack#readme). It adds some niceties on top of
-cabal. For example, hpack has YAML syntax support and will automatically
-generate of `exposed-modules` lists. However, it's just a frontend to cabal
+[Hpack](https://github.com/sol/hpack#readme). It adds some niceties on top of
+Cabal. For example, Hpack has YAML syntax support and will automatically
+generate of `exposed-modules` lists. However, it's just a frontend to Cabal
 package files. So for this document, we're instead going to focus on the first
 two and try to answer:
 
@@ -26,12 +26,12 @@ _package_. A package has:
 * A name and version
 * 0 or 1 libraries
 * 0 or more executables
-* A cabal file (or, as mentioned above, an hpack `package.yaml` that
-  generates a cabal file)
+* A Cabal file (or, as mentioned above, an [Hpack](https://github.com/sol/hpack)
+  `package.yaml` file that generates a Cabal file)
 * And a bunch more
 
 The second to last bullet bears repeating: there's a 1-to-1 correspondence between
-packages and cabal files. 
+packages and cabal files.
 
 Stack is a build tool that works on top of the Cabal build system, and defines
 a new concept called a _project_. A project has:

doc/yaml_configuration.md

@@ -1344,8 +1344,8 @@ with-gcc: /usr/local/bin/gcc-5
 
 ### with-hpack
 
-Use an Hpack executable, rather than the version the Hpack library built into
-Stack.
+Use an [Hpack](https://github.com/sol/hpack) executable, rather than Stack's
+in-built version of the Hpack functionality.
 
 ```yaml
 with-hpack: /usr/local/bin/hpack