use headings for outline structure

src/README.md

@@ -1,4 +1,4 @@
-## Outline
+# Outline
 
 The book shall be organized top-down from defining a problem domain, the solution approach Nix takes, following explanations how solutions for each specific problems are designed. Each section shall have working examples how to use the presented solution and links to relevant reference manuals.
 
@@ -8,13 +8,13 @@ Sections are ordered from generic to specific. Sections depend on insights from
 
 Software developers building their own projects may take a different path than end-users who just want to use packaged software temporarily or persistently.
 
-### Which problems Nix solves
+## Which problems Nix solves
 
 - having complete, automatic build instructions
 - avoiding dependency hell
 - hooking build results into the operating system to make them usable
 
-### How Nix works
+## How Nix works
 
 Explain high-level architecture, general mechanism, and design rationale of Nix.
 
@@ -26,82 +26,87 @@ Explain high-level architecture, general mechanism, and design rationale of Nix.
 
 Also ultimately, in a hypertext document we don't really care about order, and we can always direct the reader by noting what is to be expected from reading a certain chapter.
 
-### What Nix can do
+## What Nix can do
 
 Each section here should start out with a problem description, and explain the mechanism built on top of Nix to solve that problem. Then there should be concrete examples mapping from the explained concepts to interacting with the actual implementation.
 
-- prerequisites
-    - install Nix
-- build and run software
+### prerequisites
 
-    Show how existing build plans are used to produce working software.
+- install Nix
 
-    - find packaged software
-    - run software from existing packages
-    - set up a temporary environment
-- package management
+### build and run software
 
-    This chapter is about how to hold onto the ephemeral examples from the previous chapter, and how to create more complex environments by composing existing packages.
+Show how existing build plans are used to produce working software.
 
-    - imperative package management
+- find packaged software
+- run software from existing packages
+- set up a temporary environment
 
-        Describes a straightforward transition from temporary environments using existing packages.
+### package management
 
-        - persist packages in the file system
-        - updates, rollbacks, pinning
-        - garbage collection
+This chapter is about how to hold onto the ephemeral examples from the previous chapter, and how to create more complex environments by composing existing packages.
 
-        Imperative package management's unique feature is that it allows updating each package independently to the most recent available version without touching the rest of the system.
+#### imperative package management
 
-    - declarative package management
+Describes a straightforward transition from temporary environments using existing packages.
 
-        While imperative package management supports "generations", it does not have proper change management, "profiles" are not portable, and it is not possible to compose packages into a larger unit.
-        This section shows how to have all of that by declaring a Nix expression in a file.
+- persist packages in the file system
+- updates, rollbacks, pinning
+- garbage collection
 
-        - declare a reproducible environment
-        - compose packages
-        - adapt packages to your needs
+Imperative package management's unique feature is that it allows updating each package independently to the most recent available version without touching the rest of the system.
 
-        This chapter should have at least a reference to or a full-blown copy of a good introduction to the Nix langauge as a prerequisite for working through examples.
-        Another option would be to develop an approach to the language by motivating language features through the examples themselves, but that would probably be a lot more work.
+#### declarative package management
 
-- maintain package collection
+While imperative package management supports "generations", it does not have proper change management, "profiles" are not portable, and it is not possible to compose packages into a larger unit.
+This section shows how to have all of that by declaring a Nix expression in a file.
 
-    Explain how existing packages come into being, how their collection is organized, and show how to modify and create packages.
+- declare a reproducible environment
+- compose packages
+- adapt packages to your needs
 
-    - organization of package collection
-    - modify existing package
-    - create new package
-    - contribute to public repository
+This chapter should have at least a reference to or a full-blown copy of a good introduction to the Nix langauge as a prerequisite for working through examples.
+Another option would be to develop an approach to the language by motivating language features through the examples themselves, but that would probably be a lot more work.
 
-    Creating packages and contributing are advanced topics that require much more detail (especially langauge specifics), and are partially covered in the `nixpkgs` manual already.
-    In this context they are intended to demonstrate `nixpkgs` architecture and design, to enable readers to navigate existing code, assess pull requests, and create or maintain their own packages.
-    This should be fairly superficial, otherwise it would duplicate much of the `nixpkgs` manual.
-    Alternatively these sections could be dropped entirely, or moved to their own chapter and reference or reuse much of the `nixpkgs` manual.
+### maintain package collection
 
-    Another problem with all of the `nixpkgs` topics is that many design questions are still under debate, and implementation is a moving target, even if slowly.
-    It is not yet clear to me how to deal with this, it seems like a lot of work, and possibly `nixpkgs` is entirely out of scope of this book if we cannot gather enough humanpower to sort through all of that.
+Explain how existing packages come into being, how their collection is organized, and show how to modify and create packages.
 
-- declarative configuration management
+- organization of package collection
+- modify existing package
+- create new package
+- contribute to public repository
 
-    Show how the disconnected packages from previous examples can be wired up into a consistent and persistent user environment or operating system configuration.
+Creating packages and contributing are advanced topics that require much more detail (especially langauge specifics), and are partially covered in the `nixpkgs` manual already.
+In this context they are intended to demonstrate `nixpkgs` architecture and design, to enable readers to navigate existing code, assess pull requests, and create or maintain their own packages.
+This should be fairly superficial, otherwise it would duplicate much of the `nixpkgs` manual.
+Alternatively these sections could be dropped entirely, or moved to their own chapter and reference or reuse much of the `nixpkgs` manual.
 
-    - user environments
-    - operating system distribution
-    - service management
+Another problem with all of the `nixpkgs` topics is that many design questions are still under debate, and implementation is a moving target, even if slowly.
+It is not yet clear to me how to deal with this, it seems like a lot of work, and possibly `nixpkgs` is entirely out of scope of this book if we cannot gather enough humanpower to sort through all of that.
 
-    @thufschmitt correctly pointed out that tools like `home-manager` and `nix-darwin` are not "official" Nix projects. He uttered concern that discussing them in this book in depth may touch a political issue: Do they become "blessed" by including them?
+### declarative configuration management
 
-    My stance on this is that they are mature and widely used tools. They should be discussed right next to NixOS already on the principle that they all depend on `nixpkgs` and the way they work is almost identical, illustrating that the mechanism Nix provides is straighforward.
+Show how the disconnected packages from previous examples can be wired up into a consistent and persistent user environment or operating system configuration.
 
-    What is not as clear to me is how to determine if and how alternative contenders should be mentioned. There should be some criteria that makes an alternative approach viable enough to discuss, for example being mature enough to reliably support meaningful examples. Another instance that immediately comes to mind are NixOps and Disnix, both of which (to me) have unclear state of maturity and maintenance, but seem to be developed enough and have interesting concepts that I think are worth including.
+- user environments
+- operating system distribution
+- service management
+
+@thufschmitt correctly pointed out that tools like `home-manager` and `nix-darwin` are not "official" Nix projects. He uttered concern that discussing them in this book in depth may touch a political issue: Do they become "blessed" by including them?
+
+My stance on this is that they are mature and widely used tools. They should be discussed right next to NixOS already on the principle that they all depend on `nixpkgs` and the way they work is almost identical, illustrating that the mechanism Nix provides is straighforward.
+
+What is not as clear to me is how to determine if and how alternative contenders should be mentioned. There should be some criteria that makes an alternative approach viable enough to discuss, for example being mature enough to reliably support meaningful examples. Another instance that immediately comes to mind are NixOps and Disnix, both of which (to me) have unclear state of maturity and maintenance, but seem to be developed enough and have interesting concepts that I think are worth including.
+
+### software development
+
+- continuous integration
+- distributed builds
+- caching
+- deployment
+- cross-compilation
+- bundling build results
+    - virtual machines
+    - docker containers
 
-- software development
-    - continuous integration
-    - distributed builds
-    - caching
-    - deployment
-    - cross-compilation
-    - bundling build results
-        - virtual machines
-        - docker containers