diff --git a/.gitignore b/.gitignore
index e9ec3b6322f6ae6b24a95c16bef3bb85d914adee..72a16455c824de7c81988f7440c2e4fa2e907f4d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -73,6 +73,8 @@ cabal-testsuite/**/haddocks
 # python artifacts from documentation builds
 *.pyc
 .python-sphinx-virtualenv/
+venv
+.venv
 /doc/.skjold_cache/
 
 # macOS folder metadata
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index d8ced7f65a474de82afb127e8b15b9a6b1bb48d6..7add67b61eb4cd7c804a1022aacbee546639519d 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -1,8 +1,7 @@
 {% extends "!layout.html" %}
 
 {% block menu %}
-  {{ super() }}
-  <a href="cabal-projectindex.html">Reference</a>
+{{ super() }}
+  <a href="cabal-syntax-quicklinks.html">Cabal Syntax Quicklinks</a>
   <a href="genindex.html">Index</a>
 {% endblock %}
-
diff --git a/doc/bugs-and-stability.rst b/doc/bugs-and-stability.rst
deleted file mode 100644
index 81d27d3dd1af0ada912dd23f12303473a1482c32..0000000000000000000000000000000000000000
--- a/doc/bugs-and-stability.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Reporting Bugs and Stability of Cabal Interfaces
-================================================
-
-.. toctree::
-   misc
-
diff --git a/doc/intro.rst b/doc/cabal-context.rst
similarity index 98%
rename from doc/intro.rst
rename to doc/cabal-context.rst
index d2219ab32d14cc96ffa98cbd8038ba171f6cbd24..ce152cca713eced9f3bb89fb84d79af8ff763b3c 100644
--- a/doc/intro.rst
+++ b/doc/cabal-context.rst
@@ -14,8 +14,8 @@ use Hackage_ which is Haskell's central
 package archive that contains thousands of libraries and applications in
 the Cabal package format.
 
-Introduction
-============
+What Cabal does
+===============
 
 Cabal is a package system for Haskell software. The point of a package
 system is to enable software developers and users to easily distribute,
@@ -122,7 +122,7 @@ the package depends on.
 
 For full details on what goes in the ``.cabal`` and ``Setup.hs`` files,
 and for all the other features provided by the build system, see the
-section on :doc:`developing packages <developing-packages>`.
+section on :doc:`How to package Haskell code <how-to-package-haskell-code>`.
 
 Cabal featureset
 ----------------
diff --git a/doc/misc.rst b/doc/cabal-interface-stability.rst
similarity index 89%
rename from doc/misc.rst
rename to doc/cabal-interface-stability.rst
index 5d01198f0e56ec40ea2e77fe6f3f4927f5da302f..2993f8ab0ff7031ebd5b7af54f5c094ec8f943eb 100644
--- a/doc/misc.rst
+++ b/doc/cabal-interface-stability.rst
@@ -1,13 +1,3 @@
-Reporting bugs and deficiencies
-===============================
-
-Please report any flaws or feature requests in the `bug
-tracker <https://github.com/haskell/cabal/issues>`__.
-
-For general discussion or queries email the libraries mailing list
-libraries@haskell.org. There is also a development mailing list
-cabal-devel@haskell.org.
-
 Stability of Cabal interfaces
 =============================
 
diff --git a/doc/cabal-package.rst b/doc/cabal-package-description-file.rst
similarity index 99%
rename from doc/cabal-package.rst
rename to doc/cabal-package-description-file.rst
index 75ec9ff40ed5e75e20b130e0e49e050330b9a645..485389a0916e33c5f485a882e8f85594232b9210 100644
--- a/doc/cabal-package.rst
+++ b/doc/cabal-package-description-file.rst
@@ -1,6 +1,8 @@
-Package Description
-===================
+Package Description — <package>.cabal File
+==========================================
 
+The package description file, commonly known as "the Cabal file",
+describes the contents of a package.
 The Cabal package is the unit of distribution. When installed, its
 purpose is to make available:
 
diff --git a/doc/cabal-project.rst b/doc/cabal-project-description-file.rst
similarity index 99%
rename from doc/cabal-project.rst
rename to doc/cabal-project-description-file.rst
index fedf8c4e93547023032c53c33bddd3581fb27bf1..baac75e06f9846b4088a0cdbe9a2a8f49c6f106a 100644
--- a/doc/cabal-project.rst
+++ b/doc/cabal-project-description-file.rst
@@ -1,5 +1,5 @@
-cabal.project Reference
-=======================
+Project Description — cabal.project File
+========================================
 
 ``cabal.project`` files support a variety of options which configure the
 details of your build. The general syntax of a ``cabal.project`` file is
diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 19c37dea22968a5f9c33774d1799e6ae5ee2de89..2d318f8508ff967742579fcba21af540ea2303d2 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -598,9 +598,9 @@ class CabalConfigFieldXRef(CabalFieldXRef):
 #
 
 class ConfigFieldIndex(Index):
-    name = 'projectindex'
-    localname = "Cabal reference"
-    shortname = "Reference"
+    name = 'syntax-quicklinks'
+    localname = "Cabal Syntax Quicklinks"
+    shortname = "Quicklinks"
 
     class Entry(object):
         def __init__(self, typ, name, doc, anchor, meta):
diff --git a/doc/concepts-and-development.rst b/doc/concepts-and-development.rst
deleted file mode 100644
index c0e8b48135652f02136a6e470a1b9699b80e291f..0000000000000000000000000000000000000000
--- a/doc/concepts-and-development.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-Package Concepts and Development
-================================
-
-.. toctree::
-   :maxdepth: 2
-
-   developing-packages
diff --git a/doc/getting-started.rst b/doc/getting-started.rst
index 4d5ebfe810f189174f9c7df1771242ee662d6d9f..39a095a7453855781e890b47685331c568edc7a0 100644
--- a/doc/getting-started.rst
+++ b/doc/getting-started.rst
@@ -228,4 +228,4 @@ What Next?
 Now that you know how to set up a simple Haskell package using Cabal, check out
 some of the resources on the Haskell website's `documentation page
 <https://www.haskell.org/documentation/>`__ or read more about packages and
-Cabal on the :doc:`introduction <intro>` page.
+Cabal on the :doc:`What Cabal does <cabal-context>` page.
diff --git a/doc/nix-local-build-overview.rst b/doc/how-to-build-like-nix.rst
similarity index 97%
rename from doc/nix-local-build-overview.rst
rename to doc/how-to-build-like-nix.rst
index 61e59b84d76f5e9e83d425f8c628466b93c26482..0714b4b02f17175c6e780d99e9ddc362edfa1a99 100644
--- a/doc/nix-local-build-overview.rst
+++ b/doc/how-to-build-like-nix.rst
@@ -1,7 +1,7 @@
 .. _nix-style-builds:
 
-Nix-style Local Builds
-======================
+How to build locally like in Nix
+================================
 
 Nix-style local builds are a new build system implementation inspired by Nix.
 The Nix-style local build system is commonly called "v2-build" for short
diff --git a/doc/how-to-package-haskell-code.rst b/doc/how-to-package-haskell-code.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bd68681654b990de3bba24d262891664c3d1434b
--- /dev/null
+++ b/doc/how-to-package-haskell-code.rst
@@ -0,0 +1,291 @@
+How to package Haskell code
+===========================
+
+.. TIP::
+    If this is your first time using `cabal` you should check out the :doc:`Getting Started guide <getting-started>`.
+
+Starting from scratch, we're going to walk you through creating a simple
+Haskell application.
+
+**TL;DR;** ``mkdir proglet && cd proglet && cabal init --simple --exe && cabal run proglet``
+
+
+Introduction
+------------
+
+Every application needs a name, we'll call ours "proglet" and start by
+creating an empty directory.
+
+.. highlight:: console
+
+::
+
+    $ mkdir proglet
+    $ cd proglet/
+
+
+.. _init quickstart:
+
+Using ``cabal init``
+--------------------
+
+The ``cabal init`` command creates the necessary files for a Cabal package,
+it has both an ``--interactive`` (default) and ``--non-interactive``
+mode. The interactive mode will walk you through many of the package
+options and metadata, the non-interactive mode will simply pick reasonable
+defaults which is sufficient if you're just trying something out.
+
+.. highlight:: console
+
+::
+
+    $ cabal init --non-interactive
+    # You can also use -n which is the short version of --non-interactive
+
+If you want, you can also try out the interactive mode, for now chose
+"Executable" when asked what type of package you want to build.
+
+.. highlight:: console
+
+::
+
+    $ cabal init
+    ...
+    What does the package build:
+       1) Executable
+       2) Library
+       3) Library and Executable
+       4) Test suite
+    Your choice?
+
+One of the important questions is whether the package contains a library
+and/or an executable. Libraries are collections of Haskell modules that
+can be re-used by other Haskell libraries and programs, while executables
+are standalone programs. Test suites can both depend on a library or be
+standalone.
+
+For the moment these are the only choices. For more complex packages
+(e.g. a library and multiple executables) the ``.cabal``
+file can be edited afterwards.
+
+After you make your selection (executable; library; library
+and executable; or: test suite) cabal asks us a number of questions starting with
+which version of the cabal specification to use, our package's name
+(for example, "proglet"), and our package's version.
+
+::
+
+    Generating CHANGELOG.md...
+    Generating Main.hs...
+    Generating proglet.cabal...
+
+Use the ``ls`` command to see the created files:
+
+::
+
+   $ ls
+   CHANGELOG.md  Main.hs  proglet.cabal
+
+
+Running the program
+-------------------
+
+Now that we have our Haskell code and the extra files that Cabal needs, we
+can build and run our application.
+
+::
+
+   $ cabal build
+   Resolving dependencies...
+   ...
+   Linking /path/to/proglet ...
+
+   $ cabal run proglet
+   ...
+   Hello, Haskell!
+
+Since we have an executable we can use ``cabal run proglet`` which will build
+our executable (and re-build it if we've made any changes) and then run the
+binary. The ``cabal run`` command works for any ``component-name`` (tests for
+example), not just the main executable.
+
+
+About the Cabal package structure
+---------------------------------
+
+It is assumed that all the files that make up a package live under a common
+root directory (apart from external dependencies). This simple example has
+all the package files in one directory, but most packages use one or more
+subdirectories.
+
+Cabal needs one extra file in the package's root directory:
+
+-  ``proglet.cabal``: contains package metadata and build information.
+
+
+Editing the .cabal file
+-----------------------
+
+.. highlight:: cabal
+
+Load up the ``.cabal`` file in a text editor. The first part of the
+``.cabal`` file has the package metadata and towards the end of the file
+you will find the :pkg-section:`executable` or :pkg-section:`library`
+section.
+
+You will see that the fields that have yet to be filled in are commented
+out. Cabal files use "``--``" Haskell-style comment syntax.
+
+.. NOTE::
+   Comments are only allowed on lines on their own. Trailing comments on
+   other lines are not allowed because they could be confused with program
+   options.
+
+
+::
+
+    executable proglet
+      main-is: Main.hs
+      -- other-modules:
+      -- other-extensions:
+      build-depends: base >=4.11 && <4.12
+      -- hs-source-dirs:
+      default-language: Haskell2010
+
+
+If you selected earlier to create a library package then your ``.cabal``
+file will have a section that looks like this:
+
+::
+
+    library
+      exposed-modules: MyLib
+      -- other-modules:
+      -- build-depends:
+      build-depends: base >=4.11 && <4.12
+      -- hs-source-dirs:
+      default-language: Haskell2010
+
+
+The build information fields listed (but commented out) are just the few
+most important and common fields. There are many others that are covered
+later in this chapter.
+
+Most of the build information fields are the same between libraries and
+executables. The difference is that libraries have a number of "exposed"
+modules that make up the public interface of the library, while
+executables have a file containing a ``Main`` module.
+
+The name of a library always matches the name of the package, so it is
+not specified in the library section. Executables often follow the name
+of the package too, but this is not required and the name is given
+explicitly.
+
+
+Modules included in the package
+-------------------------------
+
+For an executable, ``cabal init`` creates the ``Main.hs`` file which
+contains your program's ``Main`` module. It will also fill in the
+:pkg-field:`executable:main-is` field with the file name of your program's
+``Main`` module, including the ``.hs`` (or ``.lhs``) extension. Other
+modules included in the executable should be listed in the
+:pkg-field:`other-modules` field.
+
+For a library, ``cabal init`` looks in the project directory for files
+that look like Haskell modules and adds all the modules to the
+:pkg-field:`library:exposed-modules` field. For modules that do not form part
+of your package's public interface, you can move those modules to the
+:pkg-field:`other-modules` field. Either way, all modules in the library need
+to be listed.
+
+
+Modules imported from other packages
+------------------------------------
+
+While your library or executable may include a number of modules, it
+almost certainly also imports a number of external modules from the
+standard libraries or other pre-packaged libraries. (These other
+libraries are of course just Cabal packages that contain one or more libraries.)
+
+You have to list all of the library packages that your library or
+executable imports modules from. Or to put it another way: you have to
+list all the other packages that your package depends on.
+
+For example, suppose the example ``Proglet`` module imports the module
+``Data.Map``. The ``Data.Map`` module comes from the ``containers``
+package, so we must list it:
+
+::
+
+    library
+      exposed-modules:     Proglet
+      other-modules:
+      build-depends:       containers, base >=4.11 && <4.12
+
+In addition, almost every package also depends on the ``base`` library
+package because it exports the standard ``Prelude`` module plus other
+basic modules like ``Data.List``.
+
+You will notice that we have listed ``base >=4.11 && <4.12``. This gives a
+constraint on the version of the base package that our package will work
+with. The most common kinds of constraints are:
+
+-  ``pkgname >=n``
+-  ``pkgname ^>=n``
+-  ``pkgname >=n && <m``
+-  ``pkgname ==n.*``
+
+The last is just shorthand, for example ``base ==4.*`` means exactly
+the same thing as ``base >=4 && <5``. Please refer to the documentation
+on the :pkg-field:`build-depends` field for more information.
+
+Also, you can factor out shared ``build-depends`` (and other fields such
+as ``ghc-options``) into a ``common`` stanza which you can ``import`` in
+your libraries and executable sections. For example:
+
+::
+
+    common shared-properties
+      default-language: Haskell2010
+      build-depends:
+        base == 4.*
+      ghc-options:
+        -Wall
+
+    library
+      import: shared-properties
+      exposed-modules:
+        Proglet
+
+Note that the ``import`` **must** be the first thing in the stanza. For more
+information see the :ref:`common-stanzas` section.
+
+.. _building-packages:
+
+Building the package
+--------------------
+
+For simple packages that's it! We can now try building the package,
+which also downloads and builds all required dependencies:
+
+.. code-block:: console
+
+    $ cabal build
+
+If the package contains an executable, you can run it with:
+
+.. code-block:: console
+
+   $ cabal run
+
+and the executable can also be installed for convenience:
+
+.. code-block:: console
+
+    $ cabal install
+
+When installed, the executable program lands in a special directory
+for binaries that may or may not already be on your system's ``PATH``.
+If it is, the executable can be run by typing its filename on commandline.
+For installing libraries see the :ref:`adding-libraries` section.
diff --git a/doc/how-to-report-bugs.rst b/doc/how-to-report-bugs.rst
new file mode 100644
index 0000000000000000000000000000000000000000..20910cdf1a3a8bfa01b36f3eae1d14b3cbe34152
--- /dev/null
+++ b/doc/how-to-report-bugs.rst
@@ -0,0 +1,9 @@
+How to report Cabal bugs and feature requests
+=============================================
+
+Please report any flaws or feature requests in the `bug
+tracker <https://github.com/haskell/cabal/issues>`__.
+
+For general discussion or queries email the libraries mailing list
+libraries@haskell.org. There is also a development mailing list
+cabal-devel@haskell.org.
diff --git a/doc/index.rst b/doc/index.rst
index faaa3bac6286822f42ecb440a8837a7d803fe5aa..ed882247ea747822a044b677350a0db1c0a048c1 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,21 +1,40 @@
-
 Welcome to the Cabal User Guide
 ===============================
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Getting Started
    :numbered:
+   :maxdepth: 2
 
    getting-started
-   intro
-   concepts-and-development
-   nix-local-build-overview
+
+.. toctree::
+   :caption: Cabal Guide
+   :numbered:
+   :maxdepth: 2
+
+   how-to-package-haskell-code
+   how-to-build-like-nix
+   how-to-report-bugs
+
+.. toctree::
+   :caption: Cabal Reference
+   :numbered:
+   :maxdepth: 2
+
+   cabal-package-description-file
+   cabal-project-description-file
    cabal-config-and-commands
-   cabal-package
-   cabal-project
+   external-commands
    setup-commands
    file-format-changelog
    buildinfo-fields-reference
-   bugs-and-stability
-   nix-integration
-   external-commands
+
+.. toctree::
+   :caption: Cabal Explanation
+   :numbered:
+   :maxdepth: 2
+
+   cabal-context
+   package-concepts
+   cabal-interface-stability
diff --git a/doc/nix-integration.rst b/doc/nix-integration.rst
deleted file mode 100644
index 5d4fa695cd41b2a7f76e141cc3b01af8c9dd06e8..0000000000000000000000000000000000000000
--- a/doc/nix-integration.rst
+++ /dev/null
@@ -1,64 +0,0 @@
-Nix Integration
-===============
-
-.. warning::
-
-    Nix integration has been deprecated and will be removed in a future release.
-
-    The original mechanism can still be easily replicated with the following commands:
-
-    - for a ``shell.nix``: ``nix-shell --run "cabal ..."``
-    - for a ``flake.nix``: ``nix develop -c cabal ...``
-
-.. note::
-
-    This functionality doesn't work with nix-style builds.
-    Nix-style builds are not related to Nix integration.
-
-`Nix <http://nixos.org/nix/>`_ is a package manager popular with some Haskell developers due to its focus on reliability and reproducibility. ``cabal`` now has the ability to integrate with Nix for dependency management during local package development.
-
-Enabling Nix Integration
-------------------------
-
-To enable Nix integration, simply pass the ``--enable-nix`` global option when you call ``cabal`` (eg. ``cabal --enable-nix v1-build``).
-To use this option everywhere, edit your :ref:`global configuration file<config-file-discovery>` (default: ``~/.config/cabal/config``) to include:
-
-.. code-block:: cabal
-
-    nix: True
-
-If the package (which must be locally unpacked) provides a ``shell.nix`` or ``default.nix`` file, this flag will cause ``cabal`` to run most commands through ``nix-shell``. If both expressions are present, ``shell.nix`` is preferred. The following commands are affected:
-
-- ``cabal v1-configure``
-- ``cabal v1-build``
-- ``cabal v1-repl``
-- ``cabal v1-install`` (only if installing into a sandbox)
-- ``cabal v1-haddock``
-- ``cabal v1-freeze``
-- ``cabal v1-gen-bounds``
-- ``cabal v1-run``
-
-If the package does not provide a Nix expression, ``cabal`` runs normally.
-
-Creating Nix Expressions
-------------------------
-
-The Nix package manager is based on a lazy, pure, functional programming language; packages are defined by expressions in this language. The fastest way to create a Nix expression for a Cabal package is with the `cabal2nix <https://github.com/NixOS/cabal2nix>`_ tool. To create a ``shell.nix`` expression for the package in the current directory, run this command:
-
-.. code-block:: console
-
-    $ cabal2nix --shell ./. >shell.nix
-
-Nix Expression Evaluation
--------------------------
-
-(This section describes for advanced users how Nix expressions are evaluated.)
-
-First, the Nix expression (``shell.nix`` or ``default.nix``) is instantiated with ``nix-instantiate``. The ``--add-root`` and ``--indirect`` options are used to create an indirect root in the Cabal build directory, preventing Nix from garbage collecting the derivation while in use. The ``IN_NIX_SHELL`` environment variable is set so that ``builtins.getEnv`` works as it would in ``nix-shell``.
-
-Next, the commands above are run through ``nix-shell`` using the instantiated derivation. Again, ``--add-root`` and ``--indirect`` are used to prevent Nix from garbage collecting the packages in the environment. The child ``cabal`` process reads the ``CABAL_IN_NIX_SHELL`` environment variable to prevent it from spawning additional child shells.
-
-Further Reading
-----------------
-
-The `Nix manual <http://nixos.org/nix/manual/#chap-writing-nix-expressions>`_ provides further instructions for writing Nix expressions. The `Nixpkgs manual <http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure>`_ describes the infrastructure provided for Haskell packages.
diff --git a/doc/nix-local-build.rst b/doc/nix-local-build.rst
index c086f642d2421995e7db797f79d4584a30fca9c3..7a47dacc9234872aa692d202e31a19ba093590c2 100644
--- a/doc/nix-local-build.rst
+++ b/doc/nix-local-build.rst
@@ -5,7 +5,7 @@ Quickstart
 
 Suppose that you are in a directory containing a single Cabal package
 which you wish to build (if you haven't set up a package yet check
-out :doc:`developing packages <developing-packages>` for
+out :doc:`How to package Haskell code <how-to-package-haskell-code>` for
 instructions). You can configure and build it using Nix-style
 local builds with this command (configuring is not necessary):
 
diff --git a/doc/developing-packages.rst b/doc/package-concepts.rst
similarity index 56%
rename from doc/developing-packages.rst
rename to doc/package-concepts.rst
index 28f2c7847df6251950718324a2ab27f296d154bb..25cfeb13fbac2f40a0a65a2a51ca66451d1e4563 100644
--- a/doc/developing-packages.rst
+++ b/doc/package-concepts.rst
@@ -1,308 +1,3 @@
-Quickstart
-==========
-
-.. TIP::
-    If this is your first time using `cabal` you should check out the :doc:`Getting Started guide <getting-started>`.
-
-Starting from scratch, we're going to walk you through creating a simple
-Haskell application.
-
-**TL;DR;** ``mkdir proglet && cd proglet && cabal init --simple --exe && cabal run proglet``
-
-
-Introduction
-------------
-
-Every application needs a name, we'll call ours "proglet" and start by
-creating an empty directory.
-
-.. highlight:: console
-
-::
-
-    $ mkdir proglet
-    $ cd proglet/
-
-
-.. _init quickstart:
-
-Using ``cabal init``
---------------------
-
-The ``cabal init`` command creates the necessary files for a Cabal package,
-it has both an ``--interactive`` (default) and ``--non-interactive``
-mode. The interactive mode will walk you through many of the package
-options and metadata, the non-interactive mode will simply pick reasonable
-defaults which is sufficient if you're just trying something out.
-
-.. highlight:: console
-
-::
-
-    $ cabal init --non-interactive
-    # You can also use -n which is the short version of --non-interactive
-
-If you want, you can also try out the interactive mode, for now chose
-"Executable" when asked what type of package you want to build.
-
-.. highlight:: console
-
-::
-
-    $ cabal init
-    ...
-    What does the package build:
-       1) Executable
-       2) Library
-       3) Library and Executable
-       4) Test suite
-    Your choice?
-
-One of the important questions is whether the package contains a library
-and/or an executable. Libraries are collections of Haskell modules that
-can be re-used by other Haskell libraries and programs, while executables
-are standalone programs. Test suites can both depend on a library or be
-standalonely generated.
-
-For the moment these are the only choices. For more complex packages
-(e.g. a library and multiple executables) the ``.cabal``
-file can be edited afterwards.
-
-After you make your selection (executable; library; library
-and executable; or: test suite) cabal asks us a number of questions starting with
-which version of the cabal specification to use, our package's name
-(for example, "proglet"), and our package's version.
-
-::
-
-    Generating CHANGELOG.md...
-    Generating Main.hs...
-    Generating proglet.cabal...
-
-Use the ``ls`` command to see the created files:
-
-::
-
-   $ ls
-   CHANGELOG.md  Main.hs  proglet.cabal
-
-
-Running the program
--------------------
-
-Now that we have our Haskell code and the extra files that Cabal needs we
-can build and run our application.
-
-::
-
-   $ cabal build
-   Resolving dependencies...
-   ...
-   Linking /path/to/proglet ...
-
-   $ cabal run proglet
-   ...
-   Hello, Haskell!
-
-Since we have an executable we can use ``cabal run proglet`` which will build
-our executable (and re-build it if we've made any changes) and then run the
-binary. The ``cabal run`` command works for any ``component-name`` (tests for
-example), not just the main executable.
-
-
-About the Cabal package structure
----------------------------------
-
-It is assumed that all the files that make up a package live under a common
-root directory (apart from external dependencies). This simple example has
-all the package files in one directory, but most packages use one or more
-subdirectories.
-
-Cabal needs one extra file in the package's root directory:
-
--  ``proglet.cabal``: contains package metadata and build information.
-
-
-Editing the .cabal file
------------------------
-
-.. highlight:: cabal
-
-Load up the ``.cabal`` file in a text editor. The first part of the
-``.cabal`` file has the package metadata and towards the end of the file
-you will find the :pkg-section:`executable` or :pkg-section:`library`
-section.
-
-You will see that the fields that have yet to be filled in are commented
-out. Cabal files use "``--``" Haskell-style comment syntax.
-
-.. NOTE::
-   Comments are only allowed on lines on their own. Trailing comments on
-   other lines are not allowed because they could be confused with program
-   options.
-
-
-::
-
-    executable proglet
-      main-is: Main.hs
-      -- other-modules:
-      -- other-extensions:
-      build-depends: base >=4.11 && <4.12
-      -- hs-source-dirs:
-      default-language: Haskell2010
-
-
-If you selected earlier to create a library package then your ``.cabal``
-file will have a section that looks like this:
-
-::
-
-    library
-      exposed-modules: MyLib
-      -- other-modules:
-      -- build-depends:
-      build-depends: base >=4.11 && <4.12
-      -- hs-source-dirs:
-      default-language: Haskell2010
-
-
-The build information fields listed (but commented out) are just the few
-most important and common fields. There are many others that are covered
-later in this chapter.
-
-Most of the build information fields are the same between libraries and
-executables. The difference is that libraries have a number of "exposed"
-modules that make up the public interface of the library, while
-executables have a file containing a ``Main`` module.
-
-The name of a library always matches the name of the package, so it is
-not specified in the library section. Executables often follow the name
-of the package too, but this is not required and the name is given
-explicitly.
-
-
-Modules included in the package
--------------------------------
-
-For an executable, ``cabal init`` creates the ``Main.hs`` file which
-contains your program's ``Main`` module. It will also fill in the
-:pkg-field:`executable:main-is` field with the file name of your program's
-``Main`` module, including the ``.hs`` (or ``.lhs``) extension. Other
-modules included in the executable should be listed in the
-:pkg-field:`other-modules` field.
-
-For a library, ``cabal init`` looks in the project directory for files
-that look like Haskell modules and adds all the modules to the
-:pkg-field:`library:exposed-modules` field. For modules that do not form part
-of your package's public interface, you can move those modules to the
-:pkg-field:`other-modules` field. Either way, all modules in the library need
-to be listed.
-
-
-Modules imported from other packages
-------------------------------------
-
-While your library or executable may include a number of modules, it
-almost certainly also imports a number of external modules from the
-standard libraries or other pre-packaged libraries. (These other
-libraries are of course just Cabal packages that contain a library.)
-
-You have to list all of the library packages that your library or
-executable imports modules from. Or to put it another way: you have to
-list all the other packages that your package depends on.
-
-For example, suppose the example ``Proglet`` module imports the module
-``Data.Map``. The ``Data.Map`` module comes from the ``containers``
-package, so we must list it:
-
-::
-
-    library
-      exposed-modules:     Proglet
-      other-modules:
-      build-depends:       containers, base >=4.11 && <4.12
-
-In addition, almost every package also depends on the ``base`` library
-package because it exports the standard ``Prelude`` module plus other
-basic modules like ``Data.List``.
-
-You will notice that we have listed ``base >=4.11 && <4.12``. This gives a
-constraint on the version of the base package that our package will work
-with. The most common kinds of constraints are:
-
--  ``pkgname >=n``
--  ``pkgname ^>=n`` (since Cabal 2.0)
--  ``pkgname >=n && <m``
--  ``pkgname ==n.*`` (since Cabal 1.6)
-
-The last is just shorthand, for example ``base ==4.*`` means exactly
-the same thing as ``base >=4 && <5``. Please refer to the documentation
-on the :pkg-field:`build-depends` field for more information.
-
-Also, you can factor out shared ``build-depends`` (and other fields such
-as ``ghc-options``) into a ``common`` stanza which you can ``import`` in
-your libraries and executable sections. For example:
-
-::
-
-    common shared-properties
-      default-language: Haskell2010
-      build-depends:
-        base == 4.*
-      ghc-options:
-        -Wall
-
-    library
-      import: shared-properties
-      exposed-modules:
-        Proglet
-
-Note that the ``import`` **must** be the first thing in the stanza. For more
-information see the :ref:`common-stanzas` section.
-
-.. _building-packages:
-
-Building the package
---------------------
-
-For simple packages that's it! We can now try building the package,
-which also downloads and builds all required dependencies:
-
-.. code-block:: console
-
-    $ cabal build
-
-If the package contains an executable, you can run it with:
-
-.. code-block:: console
-
-   $ cabal run
-
-and the executable can also be installed for convenience:
-
-.. code-block:: console
-
-    $ cabal install
-
-When installed, the executable program lands in a special directory
-for binaries that may or may not already be on your system's ``PATH``.
-If it is, the executable can be run by typing its filename on commandline.
-For installing libraries see the :ref:`adding-libraries` section.
-
-Next steps
-----------
-
-What we have covered so far should be enough for very simple packages
-that you use on your own system.
-
-The next few sections cover more details needed for more complex
-packages and details needed for distributing packages to other people.
-
-The previous chapter covers building and installing packages -- your own
-packages or ones developed by other people.
-
-
 Package concepts
 ================