From 17ae578a001a637d29f5827b53094243b87127e5 Mon Sep 17 00:00:00 2001
From: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Date: Sat, 8 Jul 2023 16:17:28 -0400
Subject: [PATCH 1/3] facelift bootstrap/README.md

---
 bootstrap/README.md | 47 ++++++++++++++++++++++++++-------------------
 1 file changed, 27 insertions(+), 20 deletions(-)

diff --git a/bootstrap/README.md b/bootstrap/README.md
index 80cc8a463a3..9716712d142 100644
--- a/bootstrap/README.md
+++ b/bootstrap/README.md
@@ -1,42 +1,49 @@
 # Bootstrapping cabal-install
 
-This utility is only intended for use in building cabal-install
-on a new platform. If you already have a functional (if dated) cabal-install
-please rather run `cabal v2-install`.
+This utility is only intended for use in building `cabal-install`
+on a new platform. If you already have a functional (if dated) `cabal-install`,
+please, rather run `cabal install cabal-install`.
 
-The typical usage is porting to a new linux architecture,
-then the `linux-{ghc-ver}.json` file is available in the `bootstrap/` folder:
+## Bootstrapping on Linux
 
-On a (linux) system you are bootstrapping, run
+The typical use case is porting to a new Linux architecture. In that case,
+a `linux-${GHCVER}.json` file is available in the `bootstrap/` folder:
 
-   ./bootstrap/bootstrap.py -d ./bootstrap/linux-ghcver.json -w /path/to-ghc
+On a Linux system you are bootstrapping, run
+
+    ./bootstrap/bootstrap.py -d ./bootstrap/linux-${GHCVER}.json -w /path/to-ghc
 
 from the top directory of the source checkout.
 
+### Offline build
+
 For offline builds, you can first run
 
-   ./bootstrap/bootstrap.py -d ./bootstrap/linux-ghcver.json -w /path/to-ghc fetch
+    ./bootstrap/bootstrap.py -d ./bootstrap/linux-${GHCVER}.json -w /path/to-ghc fetch
 
 to fetch tarballs for all the dependencies. These can then be used by a further
 bootstrap command by way of the `--bootstrap-sources` argument:
 
-   ./bootstrap/bootstrap.py -w /path/to-ghc --bootstrap-sources bootstrap-sources.tar.gz
+    ./bootstrap/bootstrap.py -w /path/to-ghc --bootstrap-sources bootstrap-sources.tar.gz
 
-To generate the `platform-{ghc-ver}` files for other platforms, do:
+## Bootstrapping on other (non-Linux) platforms
 
-  1. On a system with functional cabal-install, install the same GHC version
-     as you will use to bootstrap on the host system.
+You will need to generate a `${PLATFORM}-${GHCVER}.json` file for other platforms and then use it
+in the same way as it is shown for Linux above. On a system with functional `cabal-install`, do:
 
-  2. Build a dependency description file (`$PLATFORM-$GHCVER.json`, e.g. `linux-8.8.4.json`) by running:
+1. Install the same GHC version as you will use to bootstrap on the host system.
 
-       ```sh
-       cabal v2-build --with-compiler=/path/to/ghc --dry-run cabal-install:exe:cabal
-       cp dist-newstyle/cache/plan.json bootstrap/$PLATFORM-$GHCVER.plan.json
-       cd bootstrap
-       cabal v2-run -v0 cabal-bootstrap-gen -- $PLATFORM-$GHCVER.plan.json | tee $PLATFORM-$GHCVER.json
-       ```
+2. Build a dependency description file (`$PLATFORM-$GHCVER.json`, e.g. `macosx-8.8.4.json`) by running:
 
-  3. You may need to tweak `bootstrap/$PLATFORM-$GHCVER.json` file manually,
+   ```sh
+   cabal build --with-compiler=/path/to/ghc --dry-run cabal-install:exe:cabal
+   cp dist-newstyle/cache/plan.json bootstrap/$PLATFORM-$GHCVER.plan.json
+   cd bootstrap
+   cabal run -v0 cabal-bootstrap-gen -- $PLATFORM-$GHCVER.plan.json | tee $PLATFORM-$GHCVER.json
+   ```
+
+3. You may need to tweak `bootstrap/$PLATFORM-$GHCVER.json` file manually,
      for example toggle flags.
 
 There are rules in the top-level `Makefile` for generation of these files.
+

From 67c466683638860f960b2171a9dc129505593d48 Mon Sep 17 00:00:00 2001
From: brandon s allbery kf8nh <allbery.b@gmail.com>
Date: Sat, 8 Jul 2023 17:05:17 -0400
Subject: [PATCH 2/3] fixup! facelift bootstrap/README.md

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
---
 bootstrap/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/bootstrap/README.md b/bootstrap/README.md
index 9716712d142..65ecc9af65b 100644
--- a/bootstrap/README.md
+++ b/bootstrap/README.md
@@ -1,8 +1,8 @@
 # Bootstrapping cabal-install
 
 This utility is only intended for use in building `cabal-install`
-on a new platform. If you already have a functional (if dated) `cabal-install`,
-please, rather run `cabal install cabal-install`.
+on a new platform. If you already have a functional cabal-install, however old, then
+please instead run `cabal install cabal-install`.
 
 ## Bootstrapping on Linux
 

From 25cf8aed1e2b1f1194d321b07398156788242d27 Mon Sep 17 00:00:00 2001
From: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Date: Sat, 8 Jul 2023 17:20:26 -0400
Subject: [PATCH 3/3] Update bootstrap/README.md

---
 bootstrap/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bootstrap/README.md b/bootstrap/README.md
index 65ecc9af65b..1325bcefe48 100644
--- a/bootstrap/README.md
+++ b/bootstrap/README.md
@@ -43,7 +43,7 @@ in the same way as it is shown for Linux above. On a system with functional `cab
    ```
 
 3. You may need to tweak `bootstrap/$PLATFORM-$GHCVER.json` file manually,
-     for example toggle flags.
+     for example, to toggle flags.
 
 There are rules in the top-level `Makefile` for generation of these files.