From 285f60104b42a4db3e04e4d84ebb4bf42254bfb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Amy=20de=20Buitl=C3=A9ir?= Date: Tue, 13 Jun 2023 20:33:24 +0100 Subject: [PATCH] restructured repo --- index.html | 217 ++++++++---------- source/book.adoc | 20 +- source/flake-structure/main.adoc | 32 ++- source/generic-flake/main.adoc | 4 +- source/hello-flake-repo/main.adoc0 | 4 +- source/hello-flake-return/main.adoc | 4 +- source/hello-flake/main.adoc0 | 2 +- source/intro/main.adoc | 8 +- source/modify-hello-flake/main.adoc0 | 10 +- source/python-flake/main.adoc0 | 8 +- source/shebangs/bash-with-nixpkg.sh | 3 - source/shebangs/{main.adoc0 => main.adoc} | 32 +-- source/shebangs/python-with-nixpkg.sh | 11 - source/shell-recipes/main.adoc | 13 ++ source/shell-recipes/main.adoc0 | 112 --------- .../shell.nix} | 0 .../shell.nix} | 0 .../shell.nix} | 0 .../shell.nix} | 0 .../shell.nix} | 0 .../shell.nix} | 0 .../shell.nix} | 0 22 files changed, 167 insertions(+), 313 deletions(-) delete mode 100755 source/shebangs/bash-with-nixpkg.sh rename source/shebangs/{main.adoc0 => main.adoc} (52%) delete mode 100755 source/shebangs/python-with-nixpkg.sh create mode 100644 source/shell-recipes/main.adoc delete mode 100644 source/shell-recipes/main.adoc0 rename source/shell-recipes/{0350-shell-haskell-local-deps.nix => shell-haskell-local-deps/shell.nix} (100%) rename source/shell-recipes/{0300-shell-haskell-local.nix => shell-haskell-local/shell.nix} (100%) rename source/shell-recipes/{0400-shell-with-env-var.nix => shell-with-env-var/shell.nix} (100%) rename source/shell-recipes/{0250-shell-with-flake-rev.nix => shell-with-flake-rev/shell.nix} (100%) rename source/shell-recipes/{0200-shell-with-flake.nix => shell-with-flake/shell.nix} (100%) rename source/shell-recipes/{0150-shell-with-git-nix-pkg.nix => shell-with-git-nix-pkg/shell.nix} (100%) rename source/shell-recipes/{0100-shell-with-nixpkgs.nix => shell-with-nixpkgs/shell.nix} (100%) diff --git a/index.html b/index.html index 8b708c9..85a8903 100644 --- a/index.html +++ b/index.html @@ -110,8 +110,9 @@ pre.pygments .tok-il { color: #FF6600 } /* Literal.Number.Integer.Long */
  • 3. The hello-flake repo
  • 4. Flake structure
  • 5. A generic flake
    • @@ -124,22 +125,27 @@ pre.pygments .tok-il { color: #FF6600 } /* Literal.Number.Integer.Long */
  • 7.4. This all seems like a hassle!
    • -
  • 8. A new flake from scratch (Python)
    • +
  • 8. A new flake from scratch (Python) + +
  • 9. Nix shell recipes
  • 10. Nix-shell shebangs
    • @@ -467,12 +473,12 @@ Nix[ +
    -
    inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs";
-    flake-utils.url = "github:numtide/flake-utils";
-  };
    +
    inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
    @@ -528,7 +534,8 @@ flakes. The important thing to note is that the hello-flake package "inputs": { "flake-utils": "flake-utils", "nixpkgs": "nixpkgs" - } + } +. . .
    @@ -553,24 +560,27 @@ benefit of using flakes.

    The basic structure of a flake is shown below.

    -
    +
    -
    {
-  description = ... # package description
-  inputs = ... # dependencies
-  outputs = ... # what the flake producesgo
-  nixConfig = ... # advanced configuration options
-}
    +
    {
+  description = package description
+  inputs = dependencies
+  outputs = what the flake produces
+  nixConfig = advanced configuration options
+}
    +
    +

    4.1. Description

    The description part is self-explanatory; it’s just a string. You probably won’t need nixConfig unless you’re doing something fancy. I’m going to focus on what goes into the inputs and outputs sections, and highlight some of the things I found confusing when I began using flakes.

    +
    -

    4.1. Inputs

    +

    4.2. Inputs

    This section specifies the dependencies of a flake. It’s an attribute set; it maps keys to values.

    @@ -595,28 +605,28 @@ This commonly takes the following form.

    which is a large Git repository of programs and libraries that are pre-packaged for Nix. We can write that as

    -
    +
    -
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";
    +
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-version";
    -

    where NN.MM is replaced with the version number that you used to build +

    where version is replaced with the version number that you used to build the package, e.g. 22.11. Information about the latest nixpkgs releases is available at https://status.nixos.org/. You can also write the entry without the version number

    -
    +
    -
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";
    +
    nixpkgs.url = "github:NixOS/nixpkgs/nixos";

    or more simply,

    -
    +
    -
    nixpkgs.url = "nixpkgs";
    +
    nixpkgs.url = "nixpkgs";
    @@ -666,21 +676,21 @@ Reference Manual.

    Although you probably won’t need to use it, there is another syntax for flake references that you might encounter. This example

    -
    +
    -
    inputs.import-cargo = {
-  type = "github";
-  owner = "edolstra";
-  repo = "import-cargo";
-};
    +
    inputs.import-cargo = {
+  type = "github";
+  owner = "edolstra";
+  repo = "import-cargo";
+};

    is equivalent to

    -
    +
    -
    inputs.import-cargo.url = "github:edolstra/import-cargo";
    +
    inputs.import-cargo.url = "github:edolstra/import-cargo";
    @@ -694,7 +704,7 @@ input.

    -

    4.2. Outputs

    +

    4.3. Outputs

    This section is a function that essentially returns the recipe for building the flake.

    @@ -704,11 +714,11 @@ building the flake.

    list them as parameters. This example references the import-cargo dependency defined in the previous example.

    -
    +
    -
    outputs = { self, nixpkgs, import-cargo }: {
-  ... outputs ...
-};
    +
    outputs = { self, nixpkgs, import-cargo }: {
+  definitions for outputs
+};
    @@ -737,7 +747,7 @@ writing your own flakes. I’ll explain the example in some detail.

    -
    {
+
    {
   description = "brief package description";
 
   inputs = {
@@ -770,7 +780,7 @@ writing your own flakes. I’ll explain the example in some detail.
    
         };
       }
     );
-}
    
+}
    @@ -852,6 +862,7 @@ If you compare this flake definition to the colour-coded template presented in the previous section, most of it should look familiar.

    +
    flake.nix
    {
   description = "a very simple and friendly flake";
@@ -1167,7 +1178,14 @@ cowsay "Hello from your flake!"
 
    
 
    $ ./hello-flake
-./hello-flake: line 3: cowsay: command not found
    
+ ________________________
+< Hello from your flake! >
+ ------------------------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
    @@ -1312,7 +1330,7 @@ don’t need to git push the changes until we’re ready to share t 
    $ git commit hello-flake flake.nix -m 'added bovine feature'
-[main 8c8f6c7] added bovine feature
+[main 746a121] added bovine feature
  2 files changed, 7 insertions(+), 1 deletion(-)
 $ nix run
  ________________________
@@ -1417,6 +1435,8 @@ $ git init
 Initialized empty Git repository in /home/amy/codeberg/nix-book/source/python-flake/hello-python/.git/
    +
    +

    8.1. A simple Python program

    Next, we’ll create a simple Python program.

    @@ -1490,6 +1510,9 @@ $ python hello.py Hello from inside a Python program built with a Nix flake!
    +
    +
    +

    8.2. A Python builder

    Next, create a Python script to build the package. We’ll use Python’s setuptools, but you can use other build tools. For more information on @@ -1565,6 +1588,9 @@ twice. Alternatively, we could have done exit followed by the

    After a lot of output messages, the build succeeds.

    +
    +
    +

    8.3. The Nix flake

    Now we should write flake.nix. We already know how to write most of the flake from the examples we did earlier. The two parts that will be @@ -1760,7 +1786,7 @@ repo, and commit all important files.

    $ git add flake.lock
 $ git commit -a -m 'initial commit'
-[master (root-commit) a98ed14] initial commit
+[master (root-commit) b139782] initial commit
  4 files changed, 127 insertions(+)
  create mode 100644 flake.lock
  create mode 100644 flake.nix
@@ -1795,6 +1821,7 @@ Python flake.
    +

    9. Nix shell recipes

    @@ -1805,6 +1832,7 @@ Python flake.

    cowsay.

    +
    shell.nix
    1
 2
@@ -1828,12 +1856,9 @@ mkShell {
 
    
 
    
 
    $ nix-shell
-error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
 $ hello
-bash: line 19: hello: command not found
 Hello, world!
 $ cowsay "moo"
-bash: line 22: cowsay: command not found
  _____
 < moo >
  -----
@@ -1851,6 +1876,7 @@ bash: line 22: cowsay: command not found
 
    
 
    9.2. Shell with access to a package defined in a remote git repo
    
 
    
+
    shell.nix
    
 
    
 
     1
  2
@@ -1880,57 +1906,15 @@ mkShell {
 
    
 
    
 
    $ nix-shell
-error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
-$ hello-nix
-bash: line 48: hello-nix: command not found
-Hello from your nix package!
    
+$ hello
+Hello, world!
    
 
    
 
 
 
    
-
    9.3. Shell with access to a flake
    
-
    
-
    
-
     1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
    with (import <nixpkgs> {});
-let
-   hello = (builtins.getFlake git+https://codeberg.org/mhwombat/hello-flake).packages.${builtins.currentSystem}.default;
-   # For older flakes, you might need an expression like this...
-   # hello = (builtins.getFlake git+https://codeberg.org/mhwombat/hello-flake).defaultPackage.${builtins.currentSystem};
-in
-mkShell {
-  buildInputs = [
-    hello
-  ];
-}
-
    
-
    
-
    
-
    
-
    Here’s a demonstration using the shell.
    
-
    
-
    
-
    
-
    $ nix-shell
-error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
-$ hello-flake
-bash: line 65: hello-flake: command not found
-Hello from your flake!
    
-
    
-
    
-
    
-
    
-
    9.4. Shell with access to a specific revision of a flake
    
+
    9.3. Shell with access to a specific revision of a flake
    
 
    
+
    shell.nix
    
 
    
 
    1
 2
@@ -1958,20 +1942,19 @@ mkShell {
 
    
 
    
 
    $ nix-shell
-error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
-$ hello-flake
-bash: line 82: hello-flake: command not found
-Hello from your flake!
    
+$ hello
+Hello, world!
    
 
    
 
 
 
    
-
    9.5. Shell with access to a Haskell package on your local computer
    
+
    9.4. Shell with access to a Haskell package on your local computer
    
 
    
 
    This shell provides access to three Haskell packages that are on my hard
 drive.
    
 
    
 
    
+
    shell.nix
    
 
    
 
     1
  2
@@ -2005,12 +1988,13 @@ mkShell {
 
    
 
 
    
-
    9.6. Shell with access to a Haskell package on your local computer, with interdependencies
    
+
    9.5. Shell with access to a Haskell package on your local computer, with interdependencies
    
 
    
 
    This shell provides access to four Haskell packages that are on my hard
 drive. The fourth package depends on the first three to build.
    
 
    
 
    
+
    shell.nix
    
 
    
 
     1
  2
@@ -2054,11 +2038,12 @@ mkShell {
 
    
 
 
    
-
    9.7. Shell with an environment variable set
    
+
    9.6. Shell with an environment variable set
    
 
    
 
    This shell has the environment variable FOO set to “bar”
    
 
    
 
    
+
    shell.nix
    
 
    
 
    1
 2
@@ -2080,10 +2065,8 @@ mkShell {
 
    
 
    
 
    $ nix-shell
-error: getting status of '/home/amy/codeberg/nix-book/source/shell-recipes/default.nix': No such file or directory
-$ echo $FOO
-
-bar
    
+$ echo "FOO=$FOO"
+FOO=bar
    
 
    
 
 
@@ -2105,10 +2088,8 @@ interpreter and any dependencies. Here are some examples.
    
 
 
    
 
    10.1. A Bash script depending on a package in the nixpkgs repo.
    
-
    
-
    Script:
    
-
    
 
    
+
    Script
    
 
    
 
    1
 2
@@ -2118,10 +2099,8 @@ cowsay "Pretty cool, huh?"
 
    
 
    
 
    
-
    
-
    Output:
    
-
    
 
    
+
    Output
    
 
    
 
     ___________________
 < Pretty cool, huh? >
@@ -2135,11 +2114,9 @@ cowsay "Pretty cool, huh?"
 
    
 
    
 
    
-
    10.2. A Python script depending on a package in the nixpkgs repo.
    
-
    
-
    Script:
    
-
    
+
    10.2. A Bash script depending on a package in the nixpkgs repo.
    
 
    
+
    Script
    
 
    
 
     1
  2
@@ -2165,10 +2142,8 @@ print('sanitized: '
    
 
    
 
    
-
    
-
    Output:
    
-
    
 
    
+
    Output
    
 
    
 
    original:  <span style="font-weight:bold">some text</span>
 sanitized:  <strong>some text</strong>
    
diff --git a/source/book.adoc b/source/book.adoc
index 69d20c6..ca33372 100644
--- a/source/book.adoc
+++ b/source/book.adoc
@@ -8,22 +8,22 @@
 :!prewrap:
 :icons: font
 
-include::intro/main.adoc[]
+include::intro/main.adoc[leveloffset=+1]
 
-include::hello-flake/main-generated.adoc[]
+include::hello-flake/main-generated.adoc[leveloffset=+1]
 
-include::hello-flake-repo/main-generated.adoc[]
+include::hello-flake-repo/main-generated.adoc[leveloffset=+1]
 
-include::flake-structure/main.adoc[]
+include::flake-structure/main.adoc[leveloffset=+1]
 
-include::generic-flake/main.adoc[]
+include::generic-flake/main.adoc[leveloffset=+1]
 
-include::hello-flake-return/main.adoc[]
+include::hello-flake-return/main.adoc[leveloffset=+1]
 
-include::modify-hello-flake/main-generated.adoc[]
+include::modify-hello-flake/main-generated.adoc[leveloffset=+1]
 
-include::python-flake/main-generated.adoc[]
+include::python-flake/main-generated.adoc[leveloffset=+1]
 
-include::shell-recipes/main-generated.adoc[]
+include::shell-recipes/main.adoc[leveloffset=+1]
 
-include::shebangs/main-generated.adoc[]
+include::shebangs/main.adoc[leveloffset=+1]
diff --git a/source/flake-structure/main.adoc b/source/flake-structure/main.adoc
index cdaf3f8..94a61f8 100644
--- a/source/flake-structure/main.adoc
+++ b/source/flake-structure/main.adoc
@@ -1,22 +1,25 @@
-== Flake structure
+= Flake structure
 
 The basic structure of a flake is shown below.
 
+[source,nix,subs=quotes]
 ....
 {
-  description = ... # package description
-  inputs = ... # dependencies
-  outputs = ... # what the flake producesgo
-  nixConfig = ... # advanced configuration options
+  description = _package description_
+  inputs = _dependencies_
+  outputs = _what the flake produces_
+  nixConfig = _advanced configuration options_
 }
 ....
 
+== Description
+
 The `description` part is self-explanatory; it’s just a string. You
 probably won’t need `nixConfig` unless you’re doing something fancy. I’m
 going to focus on what goes into the `inputs` and `outputs` sections,
 and highlight some of the things I found confusing when I began using flakes.
 
-=== Inputs
+== Inputs
 
 This section specifies the dependencies of a flake. It’s an _attribute
 set_; it maps keys to values.
@@ -37,21 +40,24 @@ As a first example of a flake reference, all (almost all?) flakes depend on "`ni
 which is a large Git repository of programs and libraries that are
 pre-packaged for Nix. We can write that as
 
+[source,nix,subs=quotes]
 ....
-nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";
+nixpkgs.url = "github:NixOS/nixpkgs/nixos-__version__";
 ....
 
-where `NN.MM` is replaced with the version number that you used to build
+where _version_ is replaced with the version number that you used to build
 the package, e.g. `22.11`. Information about the latest nixpkgs releases
 is available at https://status.nixos.org/. You can also write the entry
 without the version number
 
+[source,nix]
 ....
-nixpkgs.url = "github:NixOS/nixpkgs/nixos-VERSION";
+nixpkgs.url = "github:NixOS/nixpkgs/nixos";
 ....
 
 or more simply,
 
+[source,nix]
 ....
 nixpkgs.url = "nixpkgs";
 ....
@@ -83,6 +89,7 @@ Reference Manual].
 Although you probably won’t need to use it, there is another syntax for
 flake references that you might encounter. This example
 
+[source,nix]
 ....
 inputs.import-cargo = {
   type = "github";
@@ -93,6 +100,7 @@ inputs.import-cargo = {
 
 is equivalent to
 
+[source,nix]
 ....
 inputs.import-cargo.url = "github:edolstra/import-cargo";
 ....
@@ -102,7 +110,7 @@ Each of the `inputs` is fetched, evaluated and passed to the `outputs`
 function as a set of attributes with the same name as the corresponding
 input.
 
-=== Outputs
+== Outputs
 
 This section is a function that essentially returns the recipe for
 building the flake.
@@ -111,10 +119,10 @@ We said above that `inputs` are passed to the `outputs`, so we need to
 list them as parameters. This example references the `import-cargo`
 dependency defined in the previous example.
 
-[subs=quotes]
+[source,nix,subs=quotes]
 ....
 outputs = { self, nixpkgs, import-cargo }: {
-  #... outputs ...#
+  #_definitions for outputs_#
 };
 ....
 
diff --git a/source/generic-flake/main.adoc b/source/generic-flake/main.adoc
index f751b00..7711bce 100644
--- a/source/generic-flake/main.adoc
+++ b/source/generic-flake/main.adoc
@@ -1,4 +1,4 @@
-== A generic flake
+= A generic flake
 
 The previous section presented a very high-level view of flakes,
 focusing on the basic structure. In this section, we will add a bit more
@@ -9,7 +9,7 @@ functional language. As with most programming languages, there are many
 ways to achieve the same result. Below is an example you can follow when
 writing your own flakes. I’ll explain the example in some detail.
 
-[subs=quotes]
+[source,subs=quotes]
 ----
 {
   description = "#_brief package description_#";
diff --git a/source/hello-flake-repo/main.adoc0 b/source/hello-flake-repo/main.adoc0
index adb9631..87bc8a5 100644
--- a/source/hello-flake-repo/main.adoc0
+++ b/source/hello-flake-repo/main.adoc0
@@ -1,4 +1,4 @@
-== The hello-flake repo
+= The hello-flake repo
 
 Let’s clone the repository and see how the flake is defined.
 
@@ -50,6 +50,7 @@ https://nixos.org/guides/nix-language.html[Nix language basics].]. Yes,
 uses. We’ll look at this in more detail shortly. For now, I’d like to
 focus on the inputs section.
 
+[source,nix]
 ....
 inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs";
@@ -70,6 +71,7 @@ Finally, let’s look at `flake.lock`, or rather, just part of it.
 .flake.lock
 ....
 $# head -n 40 flake.lock
+. . .
 ....
 
 If `flake.nix` seemed intimidating, then this file looks like an
diff --git a/source/hello-flake-return/main.adoc b/source/hello-flake-return/main.adoc
index 0780deb..8ed2052 100644
--- a/source/hello-flake-return/main.adoc
+++ b/source/hello-flake-return/main.adoc
@@ -1,4 +1,4 @@
-== Another look at hello-flake
+= Another look at hello-flake
 
 Now that we have a better understanding of the structure of `flake.nix`,
 let’s have a look at the one we saw earlier, in the `hello-flake` repo.
@@ -6,6 +6,7 @@ If you compare this flake definition to the colour-coded template
 presented in the previous section, most of it should look familiar.
 
 [subs=quotes]
+.flake.nix
 ....
 {
   description = "a very simple and friendly flake";
@@ -47,6 +48,7 @@ additional development tools.
 Now let’s look at the section I labeled `SOME UNFAMILIAR STUFF` and
 see what it does.
 
+[subs=quotes]
 ....
         packages = rec {
           hello = pkgs.stdenv.mkDerivation rec { ❶
diff --git a/source/hello-flake/main.adoc0 b/source/hello-flake/main.adoc0
index 9d3fd57..2666f59 100644
--- a/source/hello-flake/main.adoc0
+++ b/source/hello-flake/main.adoc0
@@ -1,4 +1,4 @@
-== Hello, flake!
+= Hello, flake!
 
 Before learning to write Nix flakes, let’s learn how to use them. I’ve
 created a simple example of a flake in this git
diff --git a/source/intro/main.adoc b/source/intro/main.adoc
index 8b7a889..43d3e9d 100644
--- a/source/intro/main.adoc
+++ b/source/intro/main.adoc
@@ -1,6 +1,6 @@
-== Introduction
+= Introduction
 
-=== Why Nix?
+== Why Nix?
 
 If you’ve opened this PDF, you already have your own motivation for
 learning Nix. Here’s how it helps me. As a researcher, I tend to work on
@@ -28,7 +28,7 @@ any dependencies. It automatically tracks the version of each dependency
 so that it can replicate the environment wherever and whenever it’s
 needed.
 
-=== Why _flakes_?
+== Why _flakes_?
 
 Flakes are labeled as an experimental feature, so it might seem safer to
 avoid them. However, they have been in use for years, and there is
@@ -37,7 +37,7 @@ easier to understand, and offer more features than the traditional Nix
 approach. After weighing the pros and cons, I feel it’s better to learn
 and use flakes; and this seems to be the general consensus.
 
-=== Prerequisites
+== Prerequisites
 
 To follow along with the examples in this book, you will need access to a computer
 or (virtual machine) with Nix installed and _flakes enabled_.
diff --git a/source/modify-hello-flake/main.adoc0 b/source/modify-hello-flake/main.adoc0
index daa4e4b..e1d22e9 100644
--- a/source/modify-hello-flake/main.adoc0
+++ b/source/modify-hello-flake/main.adoc0
@@ -1,6 +1,6 @@
-== Modifying the flake
+= Modifying the flake
 
-=== The Nix development shell
+== The Nix development shell
 
 Let’s make a simple modification to the script. This will give you an
 opportunity to check your understanding of flakes.
@@ -79,7 +79,7 @@ first if needed. Specifically, it runs the version in the Nix store, not
 the version in `result`.
 |===
 
-=== Introducing a dependency
+== Introducing a dependency
 
 Now we’re ready to make the flake a little more interesting.
 Instead of using the `echo` command in the script, we can use the Linux `cowsay`
@@ -165,7 +165,7 @@ $ git commit hello-flake flake.nix -m 'added bovine feature'
 $ nix run
 ....
 
-=== Development workflows
+== Development workflows
 
 If you’re getting confused about when to use the different commands,
 it’s because there’s more than one way to use Nix. I tend to think of it
@@ -203,7 +203,7 @@ executable depends on the development tools – It probably isn’t
 I generally only use `nix build` if I just want to build the package but
 not execute anything (perhaps it’s just a library).
 
-=== This all seems like a hassle!
+== This all seems like a hassle!
 
 It is a bit annoying to modify `flake.nix` and ether rebuild or reload
 the development environment every time you need another tool. However,
diff --git a/source/python-flake/main.adoc0 b/source/python-flake/main.adoc0
index 1ec39e5..d086b41 100644
--- a/source/python-flake/main.adoc0
+++ b/source/python-flake/main.adoc0
@@ -1,4 +1,4 @@
-== A new flake from scratch (Python)
+= A new flake from scratch (Python)
 
 At last we are ready to create a flake from scratch! Start with an empty
 directory and create a git repository.
@@ -9,6 +9,8 @@ $ cd hello-python
 $ git init
 ....
 
+== A simple Python program
+
 Next, we’ll create a simple Python program.
 
 ////
@@ -57,6 +59,8 @@ $# nix-shell -p python3 --command sh
 $ python hello.py
 ....
 
+== A Python builder
+
 Next, create a Python script to build the package. We’ll use Python’s
 setuptools, but you can use other build tools. For more information on
 setuptools, see the
@@ -106,6 +110,8 @@ $# python -m build > /dev/null 2>&1
 
 After a lot of output messages, the build succeeds.
 
+== The Nix flake
+
 Now we should write `flake.nix`. We already know how to write most of
 the flake from the examples we did earlier. The two parts that will be
 different are the development shell and the package builder.
diff --git a/source/shebangs/bash-with-nixpkg.sh b/source/shebangs/bash-with-nixpkg.sh
deleted file mode 100755
index aa12709..0000000
--- a/source/shebangs/bash-with-nixpkg.sh
+++ /dev/null
@@ -1,3 +0,0 @@
-#! /usr/bin/env nix-shell
-#! nix-shell -i bash -p cowsay
-cowsay "Pretty cool, huh?"
diff --git a/source/shebangs/main.adoc0 b/source/shebangs/main.adoc
similarity index 52%
rename from source/shebangs/main.adoc0
rename to source/shebangs/main.adoc
index 0c918f4..1b11096 100644
--- a/source/shebangs/main.adoc0
+++ b/source/shebangs/main.adoc
@@ -1,4 +1,4 @@
-== Nix-shell shebangs
+= Nix-shell shebangs
 
 You can use `nix-shell` to run scripts in arbitrary languages, providing
 the necessary dependencies. This is particularly convenient for
@@ -9,32 +9,6 @@ The script should start with two "`shebang`" (`#!`) commands. The first
 should invoke `nix-shell`. The second should declares the scrpt
 interpreter and any dependencies. Here are some examples.
 
-=== A Bash script depending on a package in the nixpkgs repo.
+include::bash-with-nix-pkg/main-generated.adoc[leveloffset=+1]
 
-Script:
-
-[source,bash,linenums]
-....
-include::bash-with-nixpkg.sh[]
-....
-
-Output:
-
-....
-$# ./bash-with-nixpkg.sh
-....
-
-=== A Python script depending on a package in the nixpkgs repo.
-
-Script:
-
-[source,bash,linenums]
-....
-include::python-with-nixpkg.sh[]
-....
-
-Output:
-
-....
-$# ./python-with-nixpkg.sh
-....
+include::python-with-nix-pkg/main-generated.adoc[leveloffset=+1]
diff --git a/source/shebangs/python-with-nixpkg.sh b/source/shebangs/python-with-nixpkg.sh
deleted file mode 100755
index e66531b..0000000
--- a/source/shebangs/python-with-nixpkg.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#! /usr/bin/env nix-shell
-#! nix-shell -i python3 -p python3Packages.html-sanitizer
-
-from html_sanitizer import Sanitizer
-sanitizer = Sanitizer()  # default configuration
-
-original='some text'
-print('original: ', original)
-
-sanitized=sanitizer.sanitize(original)
-print('sanitized: ', sanitized)
diff --git a/source/shell-recipes/main.adoc b/source/shell-recipes/main.adoc
new file mode 100644
index 0000000..e2e6c9c
--- /dev/null
+++ b/source/shell-recipes/main.adoc
@@ -0,0 +1,13 @@
+= Nix shell recipes
+
+include::shell-with-nixpkgs/main-generated.adoc[leveloffset=+1]
+
+include::shell-with-git-nix-pkg/main-generated.adoc[leveloffset=+1]
+
+include::shell-with-flake-rev/main-generated.adoc[leveloffset=+1]
+
+include::shell-haskell-local/main-generated.adoc[leveloffset=+1]
+
+include::shell-haskell-local-deps/main-generated.adoc[leveloffset=+1]
+
+include::shell-with-env-var/main-generated.adoc[leveloffset=+1]
diff --git a/source/shell-recipes/main.adoc0 b/source/shell-recipes/main.adoc0
deleted file mode 100644
index 855cfb6..0000000
--- a/source/shell-recipes/main.adoc0
+++ /dev/null
@@ -1,112 +0,0 @@
-== Nix shell recipes
-
-=== Shell with access to a package from the Nixpkgs/NixOS repo
-
-This shell provides access to two packages from nixpkgs: hello and
-cowsay.
-
-[source,nix,linenums]
-....
-include::0100-shell-with-nixpkgs.nix[]
-....
-
-Here’s a demonstration using the shell.
-
-....
-$ nix-shell
-$ hello
-Hello, world!
-$ cowsay "moo"
- _____
-< moo >
- -----
-        \   ^__^
-         \  (oo)\_______
-            (__)\       )\/\
-                ||----w |
-                ||     ||
-....
-
-The command-line equivalent would be `nix-shell -p hello cowsay`
-
-=== Shell with access to a package defined in a remote git repo
-
-[source,nix,linenums]
-....
-include::0150-shell-with-git-nix-pkg.nix[]
-....
-
-Here’s a demonstration using the shell.
-
-....
-$ nix-shell
-$ hello-nix
-Hello from your nix package!
-....
-
-=== Shell with access to a flake
-
-[source,nix,linenums]
-....
-include::0200-shell-with-flake.nix[]
-....
-
-Here’s a demonstration using the shell.
-
-....
-$ nix-shell
-$ hello-flake
-Hello from your flake!
-....
-
-=== Shell with access to a specific revision of a flake
-
-[source,nix,linenums]
-....
-include::0250-shell-with-flake-rev.nix[]
-....
-
-Here’s a demonstration using the shell.
-
-....
-$ nix-shell
-$ hello-flake
-Hello from your flake!
-....
-
-=== Shell with access to a Haskell package on your local computer
-
-This shell provides access to three Haskell packages that are on my hard
-drive.
-
-[source,nix,linenums]
-....
-include::0300-shell-haskell-local.nix[]
-....
-
-=== Shell with access to a Haskell package on your local computer, with interdependencies
-
-This shell provides access to four Haskell packages that are on my hard
-drive. The fourth package depends on the first three to build.
-
-[source,nix,linenums]
-....
-include::0350-shell-haskell-local-deps.nix[]
-....
-
-=== Shell with an environment variable set
-
-This shell has the environment variable FOO set to "`bar`"
-
-[source,nix,linenums]
-....
-include::0400-shell-with-env-var.nix[]
-....
-
-Here’s a demonstration using the shell.
-
-....
-$ nix-shell
-$ echo $FOO
-bar
-....
diff --git a/source/shell-recipes/0350-shell-haskell-local-deps.nix b/source/shell-recipes/shell-haskell-local-deps/shell.nix
similarity index 100%
rename from source/shell-recipes/0350-shell-haskell-local-deps.nix
rename to source/shell-recipes/shell-haskell-local-deps/shell.nix
diff --git a/source/shell-recipes/0300-shell-haskell-local.nix b/source/shell-recipes/shell-haskell-local/shell.nix
similarity index 100%
rename from source/shell-recipes/0300-shell-haskell-local.nix
rename to source/shell-recipes/shell-haskell-local/shell.nix
diff --git a/source/shell-recipes/0400-shell-with-env-var.nix b/source/shell-recipes/shell-with-env-var/shell.nix
similarity index 100%
rename from source/shell-recipes/0400-shell-with-env-var.nix
rename to source/shell-recipes/shell-with-env-var/shell.nix
diff --git a/source/shell-recipes/0250-shell-with-flake-rev.nix b/source/shell-recipes/shell-with-flake-rev/shell.nix
similarity index 100%
rename from source/shell-recipes/0250-shell-with-flake-rev.nix
rename to source/shell-recipes/shell-with-flake-rev/shell.nix
diff --git a/source/shell-recipes/0200-shell-with-flake.nix b/source/shell-recipes/shell-with-flake/shell.nix
similarity index 100%
rename from source/shell-recipes/0200-shell-with-flake.nix
rename to source/shell-recipes/shell-with-flake/shell.nix
diff --git a/source/shell-recipes/0150-shell-with-git-nix-pkg.nix b/source/shell-recipes/shell-with-git-nix-pkg/shell.nix
similarity index 100%
rename from source/shell-recipes/0150-shell-with-git-nix-pkg.nix
rename to source/shell-recipes/shell-with-git-nix-pkg/shell.nix
diff --git a/source/shell-recipes/0100-shell-with-nixpkgs.nix b/source/shell-recipes/shell-with-nixpkgs/shell.nix
similarity index 100%
rename from source/shell-recipes/0100-shell-with-nixpkgs.nix
rename to source/shell-recipes/shell-with-nixpkgs/shell.nix