From bbbed7428987367aaf39bf57fbdf494ad8a29487 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@gagarin.work>
Date: Thu, 5 Sep 2024 04:28:20 +0200
Subject: [PATCH] clarify side notes

---
 .../first-steps/ad-hoc-shell-environments.md  |  5 ++--
 .../first-steps/declarative-shell.md          | 25 +++++++++++++------
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/source/tutorials/first-steps/ad-hoc-shell-environments.md b/source/tutorials/first-steps/ad-hoc-shell-environments.md
index 5d48ea310..8b9fe8509 100644
--- a/source/tutorials/first-steps/ad-hoc-shell-environments.md
+++ b/source/tutorials/first-steps/ad-hoc-shell-environments.md
@@ -22,7 +22,7 @@ $ echo no chance | lolcat
 The program ‘lolcat’ is currently not installed.
 ```
 
-Use `nix-shell` with the `-p` (`--packages`) option to specify that we need the `cowsay` and `lolcat` packages.
+Use `nix-shell` with the `-p` (`--packages`) option to specify that we need the `cowsay` and `lolcat` packages:
 
 :::{note}
 The first invocation of `nix-shell` for these packages may take a while to download all dependencies.
@@ -162,6 +162,7 @@ Python 3.10.11
 
 Exit the shell as usual to return to the previous environment.
 
+(towards-reproducibility)=
 ## Towards reproducibility
 
 These shell environments are very convenient, but the examples so far are not reproducible yet.
@@ -175,7 +176,7 @@ The following example creates a fully reproducible environment.
 You can run it anywhere, anytime to obtain the exact same version of the `git`.
 
 ```shell-session
-$ nix-shell -p git --run "git --version" --pure -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/2a601aafdc5605a5133a2ca506a34a3a73377247.tar.gz
+$ nix-shell -p git --run "git --version" --pure -I nixpkgs=https://github.com/NixOS/nixpkgs/tarball/2a601aafdc5605a5133a2ca506a34a3a73377247
 ...
 git version 2.33.1
 ```
diff --git a/source/tutorials/first-steps/declarative-shell.md b/source/tutorials/first-steps/declarative-shell.md
index 8e3b68575..725200e1b 100644
--- a/source/tutorials/first-steps/declarative-shell.md
+++ b/source/tutorials/first-steps/declarative-shell.md
@@ -52,6 +52,7 @@ A better solution is to create our shell environment from a `shell.nix` file.
 
 Create a file called `shell.nix` with these contents:
 
+{lineno-start=1}
 ```nix
 let
   nixpkgs = fetchTarball "https://github.com/NixOS/nixpkgs/tarball/nixos-24.05";
@@ -67,19 +68,29 @@ pkgs.mkShellNoCC {
 ```
 
 ::::{dropdown} Detailed explanation
-We use a version of [Nixpkgs pinned to a release branch](<ref-pinning-nixpkgs>), and explicitly set configuration options and overlays to avoid them being inadvertently overridden by [global configuration](https://nixos.org/manual/nixpkgs/stable/#chap-packageconfig).
+We use a version of [Nixpkgs pinned to a release branch](<ref-pinning-nixpkgs>).
+If you followed the [](ad-hoc-envs) tutorial and don't want to to download all dependencies again, specify the exact same revision as in the section [](towards-reproducibility):
 
-`nix-shell` was originally conceived as a way to construct a shell environment containing the [tools needed to debug package builds](https://nixos.org/manual/nixpkgs/stable/#sec-tools-of-stdenv), such as Make or GCC.
-Only later it became widely used as a general way to make temporary environments for other purposes.
-`mkShellNoCC` is a function that produces such an environment, but without a compiler toolchain.
+{lineno-start=1 emphasize-lines="2"}
+```nix
+let
+  nixpkgs = fetchTarball "https://github.com/NixOS/nixpkgs/tarball/2a601aafdc5605a5133a2ca506a34a3a73377247";
+  pkgs = import nixpkgs { config = {}; overlays = []; };
+in
+```
+
+We explicitly set `config` and `overlays` to avoid them being inadvertently overridden by [global configuration](https://nixos.org/manual/nixpkgs/stable/#chap-packageconfig).
 
-`mkShellNoCC` takes as argument an attribute set.
+`mkShellNoCC` is a function that takes as argument an attribute set.
 Here we give it an attribute `packages` with a list containing two items from the `pkgs` attribute set.
 
-:::{Dropdown} Side note on `packages` and `buildInputs`
-You may encounter examples of `mkShell` or `mkShellNoCC` that add packages to the `buildInputs` or `nativeBuildInputs` attributes instead.
+:::{Dropdown} Side note on `mkShell`
 
+`nix-shell` and `mkShell` were originally conceived as a way to construct a shell environment containing the [tools needed to debug package builds](https://nixos.org/manual/nixpkgs/stable/#sec-tools-of-stdenv), such as Make or GCC.
+Only later it became widely used as a general way to make temporary environments for other purposes.
+`mkShellNoCC` is a function that produces such an environment, but without a compiler toolchain.
 
+You may encounter examples of `mkShell` or `mkShellNoCC` that add packages to the `buildInputs` or `nativeBuildInputs` attributes instead.
 `mkShellNoCC` is a [wrapper around `mkDerivation`](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell), so it takes the same arguments as `mkDerivation`, such as `buildInputs` or `nativeBuildInputs`.
 The `packages` attribute argument to `mkShellNoCC` is simply an alias for `nativeBuildInputs`.
 :::