doc: prepare for commonmark

We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.

Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist

While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.

6 files changed, 24 insertions, 21 deletions

diff --git a/doc/builders/packages/cataclysm-dda.section.md b/doc/builders/packages/cataclysm-dda.section.md
index 0f908cb7590..bfeacb47fef 100644
--- a/doc/builders/packages/cataclysm-dda.section.md
+++ b/doc/builders/packages/cataclysm-dda.section.md
@@ -1,6 +1,6 @@
 # Cataclysm: Dark Days Ahead {#cataclysm-dark-days-ahead}
 
-## How to install Cataclysm DDA
+## How to install Cataclysm DDA {#how-to-install-cataclysm-dda}
 
 To install the latest stable release of Cataclysm DDA to your profile, execute
 `nix-env -f "<nixpkgs>" -iA cataclysm-dda`. For the curses build (build
@@ -34,7 +34,7 @@ cataclysm-dda.override {
 }
 ```
 
-## Important note for overriding packages
+## Important note for overriding packages {#important-note-for-overriding-packages}
 
 After applying `overrideAttrs`, you need to fix `passthru.pkgs` and
 `passthru.withMods` attributes either manually or by using `attachPkgs`:
@@ -69,7 +69,7 @@ in
 goodExample2.withMods (_: [])    # parallel building enabled
 ```
 
-## Customizing with mods
+## Customizing with mods {#customizing-with-mods}
 
 To install Cataclysm DDA with mods of your choice, you can use `withMods`
 attribute:
diff --git a/doc/builders/packages/elm.section.md b/doc/builders/packages/elm.section.md
index 53087c0e9de..ae223c802da 100644
--- a/doc/builders/packages/elm.section.md
+++ b/doc/builders/packages/elm.section.md
@@ -6,6 +6,6 @@ To start a development environment do
 nix-shell -p elmPackages.elm elmPackages.elm-format
 ```
 
-To update the Elm compiler, see <filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>.
+To update the Elm compiler, see `nixpkgs/pkgs/development/compilers/elm/README.md`.
 
 To package Elm applications, [read about elm2nix](https://github.com/hercules-ci/elm2nix#elm2nix).
diff --git a/doc/builders/packages/firefox.section.md b/doc/builders/packages/firefox.section.md
index acf31e188c3..b7c430db232 100644
--- a/doc/builders/packages/firefox.section.md
+++ b/doc/builders/packages/firefox.section.md
@@ -1,6 +1,6 @@
 # Firefox {#sec-firefox}
 
-## Build wrapped Firefox with extensions and policies
+## Build wrapped Firefox with extensions and policies {#build-wrapped-firefox-with-extensions-and-policies}
 
 The `wrapFirefox` function allows to pass policies, preferences and extension that are available to firefox. With the help of `fetchFirefoxAddon` this allows build a firefox version that already comes with addons pre-installed:
 
diff --git a/doc/builders/packages/opengl.section.md b/doc/builders/packages/opengl.section.md
index 6866bf89221..ee7f3af98cf 100644
--- a/doc/builders/packages/opengl.section.md
+++ b/doc/builders/packages/opengl.section.md
@@ -4,11 +4,11 @@ OpenGL support varies depending on which hardware is used and which drivers are
 
 Broadly, we support both GL vendors: Mesa and NVIDIA.
 
-## NixOS Desktop
+## NixOS Desktop {#nixos-desktop}
 
 The NixOS desktop or other non-headless configurations are the primary target for OpenGL libraries and applications. The current solution for discovering which drivers are available is based on [libglvnd](https://gitlab.freedesktop.org/glvnd/libglvnd). `libglvnd` performs "vendor-neutral dispatch", trying a variety of techniques to find the system's GL implementation. In practice, this will be either via standard GLX for X11 users or EGL for Wayland users, and supporting either NVIDIA or Mesa extensions.
 
-## Nix on GNU/Linux
+## Nix on GNU/Linux {#nix-on-gnulinux}
 
 If you are using a non-NixOS GNU/Linux/X11 desktop with free software video drivers, consider launching OpenGL-dependent programs from Nixpkgs with Nixpkgs versions of `libglvnd` and `mesa.drivers` in `LD_LIBRARY_PATH`. For Mesa drivers, the Linux kernel version doesn't have to match nixpkgs.
 
diff --git a/doc/builders/packages/steam.section.md b/doc/builders/packages/steam.section.md
index e33f1192f7c..d7bb6e69d7d 100644
--- a/doc/builders/packages/steam.section.md
+++ b/doc/builders/packages/steam.section.md
@@ -20,6 +20,7 @@ Use `programs.steam.enable = true;` if you want to add steam to systemPackages a
 ## Troubleshooting {#sec-steam-troub}
 
 - **Steam fails to start. What do I do?**
+
   Try to run
 
   ```ShellSession
@@ -32,24 +33,26 @@ Use `programs.steam.enable = true;` if you want to add steam to systemPackages a
 
   - The `newStdcpp` parameter was removed since NixOS 17.09 and should not be needed anymore.
   - Steam ships statically linked with a version of libcrypto that conflics with the one dynamically loaded by radeonsi_dri.so. If you get the error
+
     ```
     steam.sh: line 713: 7842 Segmentation fault (core dumped)
     ```
+
     have a look at [this pull request](https://github.com/NixOS/nixpkgs/pull/20269).
 
 - **Java**
 
   1. There is no java in steam chrootenv by default. If you get a message like
 
-  ```
-  /home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found
-  ```
+    ```
+    /home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found
+    ```
 
-  You need to add
+    you need to add
 
-  ```nix
-  steam.override { withJava = true; };
-  ```
+    ```nix
+    steam.override { withJava = true; };
+    ```
 
 ## steam-run {#sec-steam-run}
 
@@ -57,9 +60,9 @@ The FHS-compatible chroot used for steam can also be used to run other linux gam
 
 ```nix
 pkgs.steam.override ({
-          nativeOnly = true;
-          newStdcpp = true;
-        }).run
+  nativeOnly = true;
+  newStdcpp = true;
+}).run
 ```
 
 to your configuration, rebuild, and run the game with
diff --git a/doc/builders/packages/xorg.section.md b/doc/builders/packages/xorg.section.md
index be220a25404..ae885f92346 100644
--- a/doc/builders/packages/xorg.section.md
+++ b/doc/builders/packages/xorg.section.md
@@ -2,7 +2,7 @@
 
 The Nix expressions for the X.org packages reside in `pkgs/servers/x11/xorg/default.nix`. This file is automatically generated from lists of tarballs in an X.org release. As such it should not be modified directly; rather, you should modify the lists, the generator script or the file `pkgs/servers/x11/xorg/overrides.nix`, in which you can override or add to the derivations produced by the generator.
 
-## Katamari Tarballs
+## Katamari Tarballs {#katamari-tarballs}
 
 X.org upstream releases used to include [katamari](https://en.wiktionary.org/wiki/%E3%81%8B%E3%81%9F%E3%81%BE%E3%82%8A) releases, which included a holistic recommended version for each tarball, up until 7.7. To create a list of tarballs in a katamari release:
 
@@ -14,11 +14,11 @@ cat $(PRINT_PATH=1 nix-prefetch-url $url | tail -n 1) \
   | sort > "tarballs-$release.list"
 ```
 
-## Individual Tarballs
+## Individual Tarballs {#individual-tarballs}
 
 The upstream release process for [X11R7.8](https://x.org/wiki/Releases/7.8/) does not include a planned katamari. Instead, each component of X.org is released as its own tarball. We maintain `pkgs/servers/x11/xorg/tarballs.list` as a list of tarballs for each individual package. This list includes X.org core libraries and protocol descriptions, extra newer X11 interface libraries, like `xorg.libxcb`, and classic utilities which are largely unused but still available if needed, like `xorg.imake`.
 
-## Generating Nix Expressions
+## Generating Nix Expressions {#generating-nix-expressions}
 
 The generator is invoked as follows:
 
@@ -29,6 +29,6 @@ cd pkgs/servers/x11/xorg
 
 For each of the tarballs in the `.list` files, the script downloads it, unpacks it, and searches its `configure.ac` and `*.pc.in` files for dependencies. This information is used to generate `default.nix`. The generator caches downloaded tarballs between runs. Pay close attention to the `NOT FOUND: $NAME` messages at the end of the run, since they may indicate missing dependencies. (Some might be optional dependencies, however.)
 
-## Overriding the Generator
+## Overriding the Generator {#overriding-the-generator}
 
 If the expression for a package requires derivation attributes that the generator cannot figure out automatically (say, `patches` or a `postInstall` hook), you should modify `pkgs/servers/x11/xorg/overrides.nix`.