From 4cff4130549abf65eb17242a373eb98953252895 Mon Sep 17 00:00:00 2001
From: John Chapman <thestar@fussycoder.id.au>
Date: Sat, 9 Oct 2021 12:03:34 +1100
Subject: [PATCH 1/2] Clarify that not all nix packages will use the default
 build phases

---
 doc/manual/src/command-ref/nix-shell.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index 72f6730f1..8bcad85e1 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -117,6 +117,12 @@ $ nix-shell '<nixpkgs>' -A pan
 [nix-shell]$ ./pan/gui/pan
 ```
 
+Note: Other packages may override these phases (the unpackPhase,
+configurePhase, buildPhase, etc).
+For those, it may be required to do something like
+`eval "$configurePhase-configurePhase"` or `eval "$configurePhase"`
+depending on how that package's nix files have been written.
+
 To clear the environment first, and do some additional automatic
 initialisation of the interactive shell:
 

From ffeec5f283464744fc0ba850622671eb1e91e4c7 Mon Sep 17 00:00:00 2001
From: John Chapman <thestar@fussycoder.id.au>
Date: Sun, 17 Oct 2021 15:24:22 +1100
Subject: [PATCH 2/2] Clarify that not all nix packages will use the default
 build phases

---
 doc/manual/src/command-ref/nix-shell.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index 8bcad85e1..0bd54b955 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -110,18 +110,18 @@ shell in which to build it:
 
 ```console
 $ nix-shell '<nixpkgs>' -A pan
-[nix-shell]$ unpackPhase
+[nix-shell]$ eval ${unpackPhase:-unpackPhase}
 [nix-shell]$ cd pan-*
-[nix-shell]$ configurePhase
-[nix-shell]$ buildPhase
+[nix-shell]$ eval ${configurePhase:-configurePhase}
+[nix-shell]$ eval ${buildPhase:-buildPhase}
 [nix-shell]$ ./pan/gui/pan
 ```
 
-Note: Other packages may override these phases (the unpackPhase,
-configurePhase, buildPhase, etc).
-For those, it may be required to do something like
-`eval "$configurePhase-configurePhase"` or `eval "$configurePhase"`
-depending on how that package's nix files have been written.
+The reason we use form `eval ${configurePhase:-configurePhase}` here is because
+those packages that override these phases do so by exporting the overridden
+values in the environment variable of the same name.
+Here bash is being told to either evaluate the contents of 'configurePhase',
+if it exists as a variable, otherwise evaluate the configurePhase function.
 
 To clear the environment first, and do some additional automatic
 initialisation of the interactive shell: