From 490325801de7ce89ea9b2099c4565f59eac05c29 Mon Sep 17 00:00:00 2001
From: David Binder <binderd@informatik.uni-tuebingen.de>
Date: Mon, 6 Nov 2023 02:20:37 +0100
Subject: [PATCH] Improve text of package info howto

---
 doc/how-to-access-package-info.rst | 35 +++++++++++++++++-------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/doc/how-to-access-package-info.rst b/doc/how-to-access-package-info.rst
index 99a6c305ee4..4c82d472c9e 100644
--- a/doc/how-to-access-package-info.rst
+++ b/doc/how-to-access-package-info.rst
@@ -14,30 +14,34 @@ to access that kind of information from within Haskell modules.
 Accessing the auto-generated modules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To enable packages to find these files in a portable way, Cabal generates a
-module called :file:`Paths_{pkgname}` (with any hyphens in *pkgname*
-replaced by underscores) during building, so that it may be imported by
-modules of the package.
+To enable Haskell modules to use information from package descriptions, Cabal
+generates two special modules for every package: A module called :file:`Paths_<package>`
+and a module called :file:`PackageInfo_<package>`. Since the names of Haskell
+modules must not contain any hyphens, they are replaced by underscores in the
+name of the generated module. If your package is called ``my-app``, for example,
+then the two modules :file:`PackageInfo_my_app` and :file:`Paths_my_app` are
+generated.
 
 .. Note::
 
-   If you decide to import the :file:`Paths_{pkgname}` module then it
-   *must* be listed in the :pkg-field:`other-modules` field just like any other
-   module in your package and on :pkg-field:`autogen-modules` as the file is
-   autogenerated.
+   If you decide to import the :file:`PackageInfo_<package>` or :file:`Paths_<package>`
+   module then it *must* be listed in the :pkg-field:`other-modules` field just
+   like any other module in your package and on :pkg-field:`autogen-modules` as
+   the file is autogenerated.
 
-Unlike :file:`Paths_{pkgname}`,
-:file:`PackageInfo_{pkgname}` is system- and path-independent. It aims to be
-easier to work with for hash-based tools such as Nix.
+Unlike :file:`Paths_{pkgname}`, :file:`PackageInfo_{pkgname}` is system- and
+path-independent. It aims to be easier to work with for hash-based tools such as Nix.
 
-The :file:`Paths_{pkgname}` module is not platform independent, as any
-other autogenerated module, so it does not get included in the source
-tarballs generated by ``sdist``.
+.. Note::
+
+    Just like any other autogenerated module, the :file:`PackageInfo_<package>` and
+    :file:`Paths_<package>` modules do not get included in the source tarballs generated
+    by ``sdist``.
 
 The PackageInfo_<package> module
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The auto generated :file:`PackageInfo_{pkgname}` module exports the following
+The autogenerated :file:`PackageInfo_{pkgname}` module exports the following
 package-related constants:
 
 .. code-block:: haskell
@@ -48,6 +52,7 @@ package-related constants:
     copyright :: String
     homepage :: String
 
+These constants correspond to the fields of the same name in the package description.
 
 The Paths_<package> module
 ^^^^^^^^^^^^^^^^^^^^^^^^^^