From f5d5f3d119953e7ef9a6f0e55b3be8870d85c7bf Mon Sep 17 00:00:00 2001
From: Solene Rapenne <solene@perso.pw>
Date: Fri, 16 Sep 2022 10:27:28 +0200
Subject: [PATCH 01/16] add tutorial for nix-shell in shebang

---
 source/tutorials/nix-shell-in-shebang.md | 33 ++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 source/tutorials/nix-shell-in-shebang.md

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
new file mode 100644
index 000000000..98ee0e443
--- /dev/null
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -0,0 +1,33 @@
+# How to use nix-shel in a shebang
+
+The [nix
+shell](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html)
+is feature provided by the [Nix package
+manager](https://nixos.org/guides/how-nix-works.html). It allows users
+to enter into a new shell environment containing a set of packages given
+on the command line.
+
+You can nix-shell as an interpreter](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter)
+in the shebang, not only to define the interpreter, but also a list the
+dependencies required for the script file.
+
+Imagine a simple shell script downloading an XML file, running a linter
+on it and sending an email of the result. It requires `curl`, `xmllint`
+and `mail`.
+
+```shell
+#!/usr/bin/env nix-shell
+#!nix-shell -i bash -p curl libxml2 mailutils
+
+curl http://localhost.example/report.xml | xmllint -
+
+if [ $? -eq 0 ]; then
+    echo "The report is valid" | mail someone@localhost.example
+else
+    echo "The report is invalid" | mail someone@localhost.example
+fi
+```
+
+By using `nix-shell` as the shebang, you don't have any prerequisites
+steps like typing `nix-shell` or installing packages before using the
+program.

From 67d9df4d38074c50e1b334b0c886195b6d3c7a6d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene@perso.pw>
Date: Mon, 26 Sep 2022 12:13:28 +0200
Subject: [PATCH 02/16] Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 source/tutorials/nix-shell-in-shebang.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index 98ee0e443..71b3916ea 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -1,4 +1,4 @@
-# How to use nix-shel in a shebang
+# Reproducible interpreted scripts
 
 The [nix
 shell](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html)
@@ -11,13 +11,13 @@ You can nix-shell as an interpreter](https://nixos.org/manual/nix/stable/command
 in the shebang, not only to define the interpreter, but also a list the
 dependencies required for the script file.
 
-Imagine a simple shell script downloading an XML file, running a linter
-on it and sending an email of the result. It requires `curl`, `xmllint`
-and `mail`.
+The following shell script example downloads an XML file, runs a linter on it, and sends an email depending on the result.
+It requires `curl`, `xmllint`, and `mail`.
 
 ```shell
 #!/usr/bin/env nix-shell
-#!nix-shell -i bash -p curl libxml2 mailutils
+#! nix-shell -i bash -p curl libxml2 mailutils
+#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/2a601aafdc5605a5133a2ca506a34a3a73377247.tar.gz
 
 curl http://localhost.example/report.xml | xmllint -
 

From 2d35b14e0123ed2aa8153be0ecba25cf6fe313dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene@perso.pw>
Date: Mon, 26 Sep 2022 12:13:48 +0200
Subject: [PATCH 03/16] Update source/tutorials/nix-shell-in-shebang.md

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 source/tutorials/nix-shell-in-shebang.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index 71b3916ea..ccc8652d2 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -27,7 +27,3 @@ else
     echo "The report is invalid" | mail someone@localhost.example
 fi
 ```
-
-By using `nix-shell` as the shebang, you don't have any prerequisites
-steps like typing `nix-shell` or installing packages before using the
-program.

From 4aea4920ec8f01aef133c2e2ee2ad79b2dc189c3 Mon Sep 17 00:00:00 2001
From: Solene Rapenne <solene.rapenne@tweag.io>
Date: Mon, 26 Sep 2022 16:41:58 +0200
Subject: [PATCH 04/16] nix-shell in a shebang should be a tutorial

---
 source/tutorials/nix-shell-in-shebang.md | 69 +++++++++++++++++-------
 1 file changed, 49 insertions(+), 20 deletions(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index ccc8652d2..7bf57307c 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -1,29 +1,58 @@
 # Reproducible interpreted scripts
 
-The [nix
-shell](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html)
-is feature provided by the [Nix package
-manager](https://nixos.org/guides/how-nix-works.html). It allows users
-to enter into a new shell environment containing a set of packages given
-on the command line.
+In this tutorial, you will learn how to use the [nix shell] to create reproducible interpreted scripts.
+We will write a script requesting latest releases of NixOS/nixpkgs GitHub repository, convert it from XML to JSON and pretty-print the result.
 
-You can nix-shell as an interpreter](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter)
-in the shebang, not only to define the interpreter, but also a list the
-dependencies required for the script file.
+[nix shell]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html
 
-The following shell script example downloads an XML file, runs a linter on it, and sends an email depending on the result.
-It requires `curl`, `xmllint`, and `mail`.
+# Steps
+
+## Getting Nix
+
+The first step is to [install the Nix package manager].
+
+[install the Nix package manager]: https://nix.dev/tutorials/install-nix
+
+## Requirements
+
+In order to write our script, we must thinkg beforehand about which programs we will need.
+
+1. get the content of the url `https://github.com/NixOS/nixpkgs/releases.atom`
+2. convert the XML into a JSON structure
+3. display the JSON into the terminal so it's human readable
+
+For the first step, we will need the program curl, provided by the nix package `curl`.
+For the second step, we will need the program `xmljson`, provided by the nix package `python3Packages.xmljson`. As it's a python program, it's bundled at the python3 packages level.
+For the third step, we will need the program `jq`, provided by the nix package `jq`.
+
+Finally, the whole program will run in a `bash` shell, provided by the nix package `bash`.
+
+## Shebang theory
+
+The shebang is the name of the first line of an interpreted script, and it looks like `#!/bin/some_path`.
+This is a mechanism to tell which binary should be used when running an executable script.
+
+We will use the [nix-shell as an interpreter] in the shebang, not only to define the interpreter, but to also list the packages needed to provide the commands we saw in the previous section: `bash`, `python3Packages.xmljson`, `jq` and `curl`.
+
+[nix-shell as an interpreter]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter
+
+## The script
+
+We will use the shebang `#!/usr/bin/env nix-shell` in which `/usr/bin/env` means to use the `nix-shell` command found in the system path.
+
+The command `nix-shell` can take a few different parameters:
+- `-i` to indicates which program should be used to interpret the file, we want `bash`
+- `-p` to indicates a list of packages that should be provided in the current shell, we need `jq python3Packages.xmljson curl`
+- `-I` to indicates special attributes to `nix` such as `nixpkgs` to use a specific pinned version instead of using "the current version available now".
+
+Create a file named `nixpkgs-releases.sh` with the following content:
 
 ```shell
-#!/usr/bin/env nix-shell
-#! nix-shell -i bash -p curl libxml2 mailutils
+#!/usr/bin/env nix-shell 
+#! nix-shell -i bash -p curl jq python3Packages.xmljson
 #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/2a601aafdc5605a5133a2ca506a34a3a73377247.tar.gz
 
-curl http://localhost.example/report.xml | xmllint -
-
-if [ $? -eq 0 ]; then
-    echo "The report is valid" | mail someone@localhost.example
-else
-    echo "The report is invalid" | mail someone@localhost.example
-fi
+curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .
 ```
+
+Make it executable using `chmod o+x nixpkgs-releases.sh` and run it using `./nixpkgs-releases.sh`.

From e4492d1eba15bd56faa2225ba25062c346048b9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene@perso.pw>
Date: Wed, 5 Oct 2022 15:08:17 +0200
Subject: [PATCH 05/16] Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 source/tutorials/nix-shell-in-shebang.md | 56 +++++++++++++++---------
 1 file changed, 35 insertions(+), 21 deletions(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index 7bf57307c..f5b22db57 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -1,36 +1,38 @@
 # Reproducible interpreted scripts
 
 In this tutorial, you will learn how to use the [nix shell] to create reproducible interpreted scripts.
-We will write a script requesting latest releases of NixOS/nixpkgs GitHub repository, convert it from XML to JSON and pretty-print the result.
 
 [nix shell]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html
 
 # Steps
 
-## Getting Nix
+## Requirements
 
-The first step is to [install the Nix package manager].
+- A working [Nix installation](install-nix)
+- Familiarity with [Bash]
 
-[install the Nix package manager]: https://nix.dev/tutorials/install-nix
+[Bash]: https://www.gnu.org/software/bash/
 
-## Requirements
+# A trivial script with non-trivial dependencies
+
+Take the following script, which fetches the content XML of a URL, converts it to JSON, and formats it for better readability:
 
-In order to write our script, we must thinkg beforehand about which programs we will need.
+```bash
+#! /bin/bash
 
-1. get the content of the url `https://github.com/NixOS/nixpkgs/releases.atom`
-2. convert the XML into a JSON structure
-3. display the JSON into the terminal so it's human readable
+curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .
+```
 
-For the first step, we will need the program curl, provided by the nix package `curl`.
-For the second step, we will need the program `xmljson`, provided by the nix package `python3Packages.xmljson`. As it's a python program, it's bundled at the python3 packages level.
-For the third step, we will need the program `jq`, provided by the nix package `jq`.
+It requires the programs `curl`, `xml2json`, and `jq`.
+It also requires the `bash` interpreter.
+If any of these dependencies are not present on the system running the script, it will fail partially or altogether.
 
-Finally, the whole program will run in a `bash` shell, provided by the nix package `bash`.
+We will use `nix-shell` interpreter directives to declare all dependencies explicitly, and produce a script that will always run on any machine that supports Nix and the required packages from Nixpkgs.
 
-## Shebang theory
+The characters `#!` at the beginning of a script are known as a [shebang].
+This is a mechanism to tell which program should be used to interpret the following code.
 
-The shebang is the name of the first line of an interpreted script, and it looks like `#!/bin/some_path`.
-This is a mechanism to tell which binary should be used when running an executable script.
+[shebang]: https://en.m.wikipedia.org/wiki/Shebang_(Unix)
 
 We will use the [nix-shell as an interpreter] in the shebang, not only to define the interpreter, but to also list the packages needed to provide the commands we saw in the previous section: `bash`, `python3Packages.xmljson`, `jq` and `curl`.
 
@@ -38,12 +40,14 @@ We will use the [nix-shell as an interpreter] in the shebang, not only to define
 
 ## The script
 
-We will use the shebang `#!/usr/bin/env nix-shell` in which `/usr/bin/env` means to use the `nix-shell` command found in the system path.
+We will use the shebang line `#! /usr/bin/env nix-shell`.
 
-The command `nix-shell` can take a few different parameters:
+`/usr/bin/env` is a program available on most modern Unix-like operating systems. It takes a command name as argument and will run the first executable by that name it finds in the directories listed in the environment variable `$PATH`.
+
+The command `nix-shell` takes the following parameters relevant for our use case:
 - `-i` to indicates which program should be used to interpret the file, we want `bash`
-- `-p` to indicates a list of packages that should be provided in the current shell, we need `jq python3Packages.xmljson curl`
-- `-I` to indicates special attributes to `nix` such as `nixpkgs` to use a specific pinned version instead of using "the current version available now".
+- `-p` to indicates a list of packages that should be present in the interpreter's environment
+- `-I` explicitly sets the search path for packages
 
 Create a file named `nixpkgs-releases.sh` with the following content:
 
@@ -55,4 +59,14 @@ Create a file named `nixpkgs-releases.sh` with the following content:
 curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .
 ```
 
-Make it executable using `chmod o+x nixpkgs-releases.sh` and run it using `./nixpkgs-releases.sh`.
+Make it executable using
+
+ ```console
+ chmod o+x nixpkgs-releases.sh
+ ```
+ 
+and run it with
+
+```console
+./nixpkgs-releases.sh
+```

From b41f28721feedbfd2ce2d94d47641dfbe12478f9 Mon Sep 17 00:00:00 2001
From: Solene Rapenne <solene.rapenne@tweag.io>
Date: Wed, 5 Oct 2022 15:12:46 +0200
Subject: [PATCH 06/16] move the shebang information in the requirements list

---
 source/tutorials/nix-shell-in-shebang.md | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index f5b22db57..e0dbbc790 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -10,8 +10,10 @@ In this tutorial, you will learn how to use the [nix shell] to create reproducib
 
 - A working [Nix installation](install-nix)
 - Familiarity with [Bash]
+- Familiarity with the concept of [shebang]
 
 [Bash]: https://www.gnu.org/software/bash/
+[shebang]: https://en.m.wikipedia.org/wiki/Shebang_(Unix)
 
 # A trivial script with non-trivial dependencies
 
@@ -29,11 +31,6 @@ If any of these dependencies are not present on the system running the script, i
 
 We will use `nix-shell` interpreter directives to declare all dependencies explicitly, and produce a script that will always run on any machine that supports Nix and the required packages from Nixpkgs.
 
-The characters `#!` at the beginning of a script are known as a [shebang].
-This is a mechanism to tell which program should be used to interpret the following code.
-
-[shebang]: https://en.m.wikipedia.org/wiki/Shebang_(Unix)
-
 We will use the [nix-shell as an interpreter] in the shebang, not only to define the interpreter, but to also list the packages needed to provide the commands we saw in the previous section: `bash`, `python3Packages.xmljson`, `jq` and `curl`.
 
 [nix-shell as an interpreter]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter

From 44df26b89f00068a47a26f2cfbd595400f47e433 Mon Sep 17 00:00:00 2001
From: Solene Rapenne <solene.rapenne@tweag.io>
Date: Sat, 22 Oct 2022 13:30:59 +0200
Subject: [PATCH 07/16] content enhancement

---
 source/tutorials/nix-shell-in-shebang.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index e0dbbc790..1e4d16dc7 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -10,7 +10,9 @@ In this tutorial, you will learn how to use the [nix shell] to create reproducib
 
 - A working [Nix installation](install-nix)
 - Familiarity with [Bash]
-- Familiarity with the concept of [shebang]
+
+We will refer to the concept of [shebang].
+You don't need to know more that it's the first line of a script telling your shell shell which program should be used to run the script, examples: `#!/usr/bin/env bash`, `#!/usr/bin/perl`.
 
 [Bash]: https://www.gnu.org/software/bash/
 [shebang]: https://en.m.wikipedia.org/wiki/Shebang_(Unix)
@@ -56,6 +58,10 @@ Create a file named `nixpkgs-releases.sh` with the following content:
 curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .
 ```
 
+The command `xml2json` is provided by the package `python3Packages.xmljson`, while the commands `jq` and `curl` are provided by eponymous packages.
+
+The parameter of `-I` refers to a pinned nixpkgs version, which mean this script will always run with the same packages versions. If you distribute your script, it's guaranteed to run on other systems with the same binaries.
+
 Make it executable using
 
  ```console

From 71a1b09c490e77a543b79770c6dfbfbd13dee1f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene@perso.pw>
Date: Tue, 27 Dec 2022 09:37:37 +0100
Subject: [PATCH 08/16] Update source/tutorials/nix-shell-in-shebang.md

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 source/tutorials/nix-shell-in-shebang.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index 1e4d16dc7..a410e15d3 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -68,7 +68,7 @@ Make it executable using
  chmod o+x nixpkgs-releases.sh
  ```
  
-and run it with
+Run the script:
 
 ```console
 ./nixpkgs-releases.sh

From 7a17e524f67bc4f2c6136a8acf26ef58f791ae40 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene@perso.pw>
Date: Tue, 27 Dec 2022 09:39:18 +0100
Subject: [PATCH 09/16] Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 source/tutorials/nix-shell-in-shebang.md | 40 +++++++++++-------------
 1 file changed, 18 insertions(+), 22 deletions(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index a410e15d3..6499ef3cb 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -1,23 +1,13 @@
 # Reproducible interpreted scripts
 
-In this tutorial, you will learn how to use the [nix shell] to create reproducible interpreted scripts.
-
-[nix shell]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html
-
-# Steps
+In this tutorial, you will learn how to use Nix to create and run reproducible interpreted scripts.
 
 ## Requirements
 
 - A working [Nix installation](install-nix)
 - Familiarity with [Bash]
 
-We will refer to the concept of [shebang].
-You don't need to know more that it's the first line of a script telling your shell shell which program should be used to run the script, examples: `#!/usr/bin/env bash`, `#!/usr/bin/perl`.
-
-[Bash]: https://www.gnu.org/software/bash/
-[shebang]: https://en.m.wikipedia.org/wiki/Shebang_(Unix)
-
-# A trivial script with non-trivial dependencies
+## A trivial script with non-trivial dependencies
 
 Take the following script, which fetches the content XML of a URL, converts it to JSON, and formats it for better readability:
 
@@ -31,38 +21,44 @@ It requires the programs `curl`, `xml2json`, and `jq`.
 It also requires the `bash` interpreter.
 If any of these dependencies are not present on the system running the script, it will fail partially or altogether.
 
-We will use `nix-shell` interpreter directives to declare all dependencies explicitly, and produce a script that will always run on any machine that supports Nix and the required packages from Nixpkgs.
+With Nix, we can declare all dependencies explicitly, and produce a script that will always run on any machine that supports Nix and the required packages taken from Nixpkgs.
 
-We will use the [nix-shell as an interpreter] in the shebang, not only to define the interpreter, but to also list the packages needed to provide the commands we saw in the previous section: `bash`, `python3Packages.xmljson`, `jq` and `curl`.
+## The script
 
-[nix-shell as an interpreter]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter
+A [shebang] is the first line of a script starting with `#!`.
+It determines which program to use for running the script.
 
-## The script
+[Bash]: https://www.gnu.org/software/bash/
+[shebang]: https://en.m.wikipedia.org/wiki/Shebang_(Unix)
 
 We will use the shebang line `#! /usr/bin/env nix-shell`.
 
 `/usr/bin/env` is a program available on most modern Unix-like operating systems. It takes a command name as argument and will run the first executable by that name it finds in the directories listed in the environment variable `$PATH`.
 
 The command `nix-shell` takes the following parameters relevant for our use case:
-- `-i` to indicates which program should be used to interpret the file, we want `bash`
-- `-p` to indicates a list of packages that should be present in the interpreter's environment
+- `-i` tells which program to use for interpreting the rest of the file
+- `-p` lists packages that should be present in the interpreter's environment
 - `-I` explicitly sets the search path for packages
 
 Create a file named `nixpkgs-releases.sh` with the following content:
 
 ```shell
 #!/usr/bin/env nix-shell 
-#! nix-shell -i bash -p curl jq python3Packages.xmljson
+#! nix-shell -i bash
+#! nix-shell -p curl jq python3Packages.xmljson
 #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/2a601aafdc5605a5133a2ca506a34a3a73377247.tar.gz
 
 curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .
 ```
 
-The command `xml2json` is provided by the package `python3Packages.xmljson`, while the commands `jq` and `curl` are provided by eponymous packages.
+We specify `bash` as the interpreter.
+
+The command `xml2json` is provided by the package `python3Packages.xmljson`, while the commands `jq` and `curl` are provided by packages of the same name.
 
-The parameter of `-I` refers to a pinned nixpkgs version, which mean this script will always run with the same packages versions. If you distribute your script, it's guaranteed to run on other systems with the same binaries.
+The parameter of `-I` refers to a specific Git commit of the Nixpkgs repository.
+This ensures that the script will always run with the exact same packages versions, everywhere.
 
-Make it executable using
+Make the script executable:
 
  ```console
  chmod o+x nixpkgs-releases.sh

From a697acd53df11bcffea14f5f28baa25cc9d3ce32 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 10 Jan 2023 03:20:00 +0100
Subject: [PATCH 10/16] break line on each sentence

---
 source/tutorials/nix-shell-in-shebang.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index 6499ef3cb..079c4a66a 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -33,7 +33,8 @@ It determines which program to use for running the script.
 
 We will use the shebang line `#! /usr/bin/env nix-shell`.
 
-`/usr/bin/env` is a program available on most modern Unix-like operating systems. It takes a command name as argument and will run the first executable by that name it finds in the directories listed in the environment variable `$PATH`.
+`/usr/bin/env` is a program available on most modern Unix-like operating systems.
+It takes a command name as argument and will run the first executable by that name it finds in the directories listed in the environment variable `$PATH`.
 
 The command `nix-shell` takes the following parameters relevant for our use case:
 - `-i` tells which program to use for interpreting the rest of the file

From e678e4fa29590cadb6a9413c9798ed741099d3bb Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 10 Jan 2023 03:20:54 +0100
Subject: [PATCH 11/16] introduce `nix-shell` as shebang interpreter

---
 source/tutorials/nix-shell-in-shebang.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/nix-shell-in-shebang.md
index 079c4a66a..0655e57fa 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/nix-shell-in-shebang.md
@@ -36,7 +36,10 @@ We will use the shebang line `#! /usr/bin/env nix-shell`.
 `/usr/bin/env` is a program available on most modern Unix-like operating systems.
 It takes a command name as argument and will run the first executable by that name it finds in the directories listed in the environment variable `$PATH`.
 
-The command `nix-shell` takes the following parameters relevant for our use case:
+We use [`nix-shell` as a shebang interpreter].
+It takes the following parameters relevant for our use case:
+
+[`nix-shell` as a shebang interpreter]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter
 - `-i` tells which program to use for interpreting the rest of the file
 - `-p` lists packages that should be present in the interpreter's environment
 - `-I` explicitly sets the search path for packages

From ab60cd84a0e3e6b6b5e93d5e18d360c96075b558 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene.rapenne@tweag.io>
Date: Mon, 6 Feb 2023 09:48:35 +0100
Subject: [PATCH 12/16] Register reproducible scripts tutorial in TOC

---
 .../ad-hoc-developer-environments.md          | 22 +------------------
 source/tutorials/index.md                     |  1 +
 ...-in-shebang.md => reproducible-scripts.md} |  2 ++
 3 files changed, 4 insertions(+), 21 deletions(-)
 rename source/tutorials/{nix-shell-in-shebang.md => reproducible-scripts.md} (99%)

diff --git a/source/tutorials/ad-hoc-developer-environments.md b/source/tutorials/ad-hoc-developer-environments.md
index b9a20b411..3d9a5ceef 100644
--- a/source/tutorials/ad-hoc-developer-environments.md
+++ b/source/tutorials/ad-hoc-developer-environments.md
@@ -128,27 +128,6 @@ There are two things going on here:
 1. The `--pure` flag makes sure that the bash environment from your system is not inherited. That means only the `git` that Nix installed is available inside the shell. This is useful for one-liners and scripts that run, for example, within a CI environment. While developing, however, we'd like to have our editor around and a bunch of other things. Therefore we might skip the flag for development environments but use it in build ones.
 2. The `-I` flag pins the Nixpkgs revision to an **exact Git revision**, leaving no doubt about which exact version of Nix packages will be used.
 
-## Reproducible executables
-
-Finally, we can wrap scripts with Nix to provide a reproducible shell environment that we can commit to a Git repository and share with strangers online. As long as they have Nix installed, they'll be able to execute the script without worrying about manually installing (and later uninstalling) dependencies at all.
-
-```python
-#! /usr/bin/env nix-shell
-#! nix-shell --pure -i python -p "python38.withPackages (ps: [ ps.django ])"
-#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/2a601aafdc5605a5133a2ca506a34a3a73377247.tar.gz
-
-import django
-
-print(django)
-```
-
-This is essentially the same example as in the previous section, but this time declaratively source controlled! All of the required Nix commands are included as `#!` shebang headers in the script itself.
-
-:::{note}
-The multiline shebang format is a feature of [nix-shell](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter). 
-All the subsequent `#! nix-shell` lines are used to build up the shell's configuration before building the shell and executing the body of the script.
-:::
-
 ## Next steps
 
 We've only covered the bare essentials of Nix here. Once you're comfortable with these examples, take a look at:
@@ -160,3 +139,4 @@ We've only covered the bare essentials of Nix here. Once you're comfortable with
 - See `man nix-shell` for all of the options.
 - To quickly setup a Nix project read through
   [Getting started Nix template](https://github.com/nix-dot-dev/getting-started-nix-template).
+- {ref}`reproducible-scripts` to see how to use `nix-shell` as a shebang.
diff --git a/source/tutorials/index.md b/source/tutorials/index.md
index 0004ce33f..20c55fcf2 100644
--- a/source/tutorials/index.md
+++ b/source/tutorials/index.md
@@ -5,6 +5,7 @@
 
 install-nix.md
 ad-hoc-developer-environments.md
+reproducible-scripts.rst
 nix-language.md
 towards-reproducibility-pinning-nixpkgs.md
 declarative-and-reproducible-developer-environments.md
diff --git a/source/tutorials/nix-shell-in-shebang.md b/source/tutorials/reproducible-scripts.md
similarity index 99%
rename from source/tutorials/nix-shell-in-shebang.md
rename to source/tutorials/reproducible-scripts.md
index 0655e57fa..ca6c14e3a 100644
--- a/source/tutorials/nix-shell-in-shebang.md
+++ b/source/tutorials/reproducible-scripts.md
@@ -1,3 +1,5 @@
+(reproducible-scripts)=
+
 # Reproducible interpreted scripts
 
 In this tutorial, you will learn how to use Nix to create and run reproducible interpreted scripts.

From 62b93d5da0ade431c2955f7b107b37626c46b879 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene.rapenne@tweag.io>
Date: Mon, 6 Feb 2023 10:01:23 +0100
Subject: [PATCH 13/16] tutorials: chmod +x for everyone

---
 source/tutorials/reproducible-scripts.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/tutorials/reproducible-scripts.md b/source/tutorials/reproducible-scripts.md
index ca6c14e3a..10a2519ae 100644
--- a/source/tutorials/reproducible-scripts.md
+++ b/source/tutorials/reproducible-scripts.md
@@ -67,7 +67,7 @@ This ensures that the script will always run with the exact same packages versio
 Make the script executable:
 
  ```console
- chmod o+x nixpkgs-releases.sh
+ chmod +x nixpkgs-releases.sh
  ```
  
 Run the script:

From 76c988bef5a66ec85c8b7b5b7795b260c55b33ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene.rapenne@tweag.io>
Date: Mon, 6 Feb 2023 10:09:17 +0100
Subject: [PATCH 14/16] tutorials: add nix manual reference to -I

---
 source/tutorials/reproducible-scripts.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/reproducible-scripts.md b/source/tutorials/reproducible-scripts.md
index 10a2519ae..1868c77b3 100644
--- a/source/tutorials/reproducible-scripts.md
+++ b/source/tutorials/reproducible-scripts.md
@@ -41,10 +41,12 @@ It takes a command name as argument and will run the first executable by that na
 We use [`nix-shell` as a shebang interpreter].
 It takes the following parameters relevant for our use case:
 
-[`nix-shell` as a shebang interpreter]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter
 - `-i` tells which program to use for interpreting the rest of the file
 - `-p` lists packages that should be present in the interpreter's environment
-- `-I` explicitly sets the search path for packages
+- `-I` explicitly sets [the search path] for packages
+
+[`nix-shell` as a shebang interpreter]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter
+[the search path]: https://nixos.org/manual/nix/unstable/command-ref/opt-common.html#opt-I
 
 Create a file named `nixpkgs-releases.sh` with the following content:
 

From 28fbe789efdbb01640f82e43c003f1ab75faacf4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene.rapenne@tweag.io>
Date: Mon, 6 Feb 2023 10:12:08 +0100
Subject: [PATCH 15/16] tutorials: files are now in markdown

---
 source/tutorials/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/tutorials/index.md b/source/tutorials/index.md
index 20c55fcf2..7e346274e 100644
--- a/source/tutorials/index.md
+++ b/source/tutorials/index.md
@@ -5,7 +5,7 @@
 
 install-nix.md
 ad-hoc-developer-environments.md
-reproducible-scripts.rst
+reproducible-scripts.md
 nix-language.md
 towards-reproducibility-pinning-nixpkgs.md
 declarative-and-reproducible-developer-environments.md

From 18ecf6f7416fbe158dd9d4c8deb8c883a6368549 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene.rapenne@tweag.io>
Date: Mon, 6 Feb 2023 10:24:20 +0100
Subject: [PATCH 16/16] tutorials: use ref syntax to link other pages

---
 source/tutorials/nix-language.md         | 2 +-
 source/tutorials/reproducible-scripts.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/nix-language.md b/source/tutorials/nix-language.md
index ef25812de..c50879216 100644
--- a/source/tutorials/nix-language.md
+++ b/source/tutorials/nix-language.md
@@ -75,7 +75,7 @@ Read detailed explanations if you want to make sure you fully understand the exa
 
 - Familiarity with software development
 - Familiarity with Unix shell, to read command line examples <!-- TODO: link to yet-to-be instructions on "how to read command line examples" -->
-- A [Nix installation](./install-nix) to run the examples
+- A {ref}`Nix installation <install-nix>` to run the examples
 
 ### How to run the examples?
 
diff --git a/source/tutorials/reproducible-scripts.md b/source/tutorials/reproducible-scripts.md
index 1868c77b3..b40c78af4 100644
--- a/source/tutorials/reproducible-scripts.md
+++ b/source/tutorials/reproducible-scripts.md
@@ -6,7 +6,7 @@ In this tutorial, you will learn how to use Nix to create and run reproducible i
 
 ## Requirements
 
-- A working [Nix installation](install-nix)
+- A working {ref}`Nix installation <install-nix>`
 - Familiarity with [Bash]
 
 ## A trivial script with non-trivial dependencies