emscripten docs: reword introduction

in particular, remove mention of `nix-env`

Co-authored by: Henrik Karlsson <i97henka@gmail.com>

1 files changed, 10 insertions, 40 deletions

diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md
index 5f93dd5ff31..d1ae7e36bf5 100644
--- a/doc/languages-frameworks/emscripten.section.md
+++ b/doc/languages-frameworks/emscripten.section.md
@@ -2,37 +2,16 @@
 
 [Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler
 
-This section of the manual covers how to use `emscripten` in nixpkgs.
+If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions,
 
-Minimal requirements:
-
-* nix
-* nixpkgs
-
-Modes of use of `emscripten`:
-
-* **Imperative usage** (on the command line):
-
-   If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions you can use these commands:
-
-    * `nix-env -f "<nixpkgs>" -iA emscripten`
-    * `nix-shell -p emscripten`
-
-* **Declarative usage**:
-
-    This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`. From the root of the nixpkgs repository:
-    * build and install all packages:
-        * `nix-env -iA emscriptenPackages`
-
-    * dev-shell for zlib implementation hacking:
-        * `nix-shell -A emscriptenPackages.zlib`
-
-## Imperative usage {#imperative-usage}
+```console
+nix-shell -p emscripten
+```
 
 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
+* The build artifact cache in `~/.emscripten` sometimes creates issues and needs to be removed from time to time
 
 ## Declarative usage {#declarative-usage}
 
@@ -41,16 +20,13 @@ Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:
 * `pkgs.zlib.override`
 * `pkgs.buildEmscriptenPackage`
 
-Both are interesting concepts.
-
-A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true` is a default meaning that each emscriptenPackage requires a `checkPhase` implemented.
-
-* 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.
+A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true`.
+This means each Emscripten package requires that a [`checkPhase`](#ssec-check-phase) is implemented.
 
-### Usage 1: pkgs.zlib.override {#usage-1-pkgs.zlib.override}
+* Use `export EMCC_DEBUG=2` from within a phase to get more detailed debug output what is going wrong.
+* The cache at `~/.emscripten` requires to set `HOME=$TMPDIR` in individual phases.
+  This makes compilation slower but also more deterministic.
 
-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...
 
 See the `zlib` example:
 
@@ -174,9 +150,3 @@ Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from
 5. `configurePhase`
 6. `buildPhase`
 7. ... happy hacking...
-
-## 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.
-
-If in trouble, ask the maintainers.