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.

doc/languages-frameworks/emscripten.section.md

@@ -27,16 +27,14 @@ Modes of use of `emscripten`:
     * dev-shell for zlib implementation hacking:
         * `nix-shell -A emscriptenPackages.zlib`
 
-
-## Imperative usage
+## Imperative usage {#imperative-usage}
 
 A few things to note:
 
 * `export EMCC_DEBUG=2` is nice for debugging
 * `~/.emscripten`, the build artifact cache sometimes creates issues and needs to be removed from time to time
 
-
-## Declarative usage
+## Declarative usage {#declarative-usage}
 
 Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:
 
@@ -50,7 +48,7 @@ A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = tru
 * Use `export EMCC_DEBUG=2` from within a emscriptenPackage's `phase` to get more detailed debug output what is going wrong.
 * ~/.emscripten cache is requiring us to set `HOME=$TMPDIR` in individual phases. This makes compilation slower but also makes it more deterministic.
 
-### Usage 1: pkgs.zlib.override
+### Usage 1: pkgs.zlib.override {#usage-1-pkgs.zlib.override}
 
 This example uses `zlib` from nixpkgs but instead of compiling **C** to **ELF** it compiles **C** to **JS** since we were using `pkgs.zlib.override` and changed stdenv to `pkgs.emscriptenStdenv`. A few adaptions and hacks were set in place to make it working. One advantage is that when `pkgs.zlib` is updated, it will automatically update this package as well. However, this can also be the downside...
 
@@ -110,7 +108,7 @@ See the `zlib` example:
       '';
     });
 
-### Usage 2: pkgs.buildEmscriptenPackage
+### Usage 2: pkgs.buildEmscriptenPackage {#usage-2-pkgs.buildemscriptenpackage}
 
 This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.
 
@@ -165,7 +163,7 @@ This `xmlmirror` example features a emscriptenPackage which is defined completel
       '';
     };
 
-### Declarative debugging
+### Declarative debugging {#declarative-debugging}
 
 Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from there you can go trough the individual steps. This makes it easy to build a good `unit test` or list the files of the project.
 
@@ -177,7 +175,7 @@ Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from
 6. `buildPhase`
 7. ... happy hacking...
 
-## Summary
+## Summary {#summary}
 
 Using this toolchain makes it easy to leverage `nix` from NixOS, MacOSX or even Windows (WSL+ubuntu+nix). This toolchain is reproducible, behaves like the rest of the packages from nixpkgs and contains a set of well working examples to learn and adapt from.