nixpkgs manual: add idris docs generated from *.md

I also modified the nesting approach in haskell docs
to allow more uniform handling of markdown -> docbook conversions.
/cc #11308.

3 files changed, 49 insertions, 34 deletions

diff --git a/doc/default.nix b/doc/default.nix
index cca68014b0d1..7e41380d6358 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -20,27 +20,39 @@ stdenv.mkDerivation {
     --param callout.graphics.extension '.gif'
   '';
 
-  buildCommand = ''
-    {
-      echo "<chapter xmlns=\"http://docbook.org/ns/docbook\""
-      echo "         xmlns:xlink=\"http://www.w3.org/1999/xlink\""
-      echo "         xml:id=\"users-guide-to-the-haskell-infrastructure\">"
-      echo ""
-      echo "<title>User's Guide to the Haskell Infrastructure</title>"
-      echo ""
-      pandoc ${./haskell-users-guide.md} -w docbook | \
-        sed -e 's|<ulink url=|<link xlink:href=|' \
-            -e 's|</ulink>|</link>|' \
-            -e 's|<sect. id=|<section xml:id=|' \
-            -e 's|</sect[0-9]>|</section>|'
-      echo ""
-      echo "</chapter>"
-    } >haskell-users-guide.xml
 
+  buildCommand = let toDocbook = { useChapters ? false, inputFile, outputFile }:
+    let
+      extraHeader = ''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" '';
+    in ''
+      {
+        pandoc '${inputFile}' -w docbook ${optionalString useChapters "--chapters"} \
+          | sed -e 's|<ulink url=|<link xlink:href=|' \
+              -e 's|</ulink>|</link>|' \
+              -e 's|<sect. id=|<section xml:id=|' \
+              -e 's|</sect[0-9]>|</section>|' \
+              -e '1s| id=| xml:id=|' \
+              -e '1s|\(<[^ ]* \)|\1${extraHeader}|'
+      } > '${outputFile}'
+    '';
+  in
+
+  ''
     ln -s '${sources}/'*.xml .
     mkdir ./languages-frameworks
     cp -s '${sources-langs}'/* ./languages-frameworks
-
+  ''
+  + toDocbook {
+      inputFile = ./haskell-users-guide.md;
+      outputFile = "haskell-users-guide.xml";
+      useChapters = true;
+    }
+  + toDocbook {
+      inputFile = ./../pkgs/development/idris-modules/README.md;
+      outputFile = "languages-frameworks/idris.xml";
+    }
+  + ''
+    cat languages-frameworks/idris.xml
     echo ${nixpkgsVersion} > .version
 
     xmllint --noout --nonet --xinclude --noxincludenode \
diff --git a/doc/haskell-users-guide.md b/doc/haskell-users-guide.md
index 446f08eb697c..b11e4cf09f84 100644
--- a/doc/haskell-users-guide.md
+++ b/doc/haskell-users-guide.md
@@ -3,8 +3,10 @@ title: User's Guide for Haskell in Nixpkgs
 author: Peter Simons
 date: 2015-06-01
 ---
+# User's Guide to the Haskell Infrastructure
 
-# How to install Haskell packages
+
+## How to install Haskell packages
 
 Nixpkgs distributes build instructions for all Haskell packages registered on
 [Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package
@@ -111,9 +113,9 @@ version of GHC listed above, there exists a package set based on that compiler.
 Also, the attributes `haskell.compiler.ghcXYC` and
 `haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
 
-# How to create a development environment
+## How to create a development environment
 
-## How to install a compiler
+### How to install a compiler
 
 A simple development environment consists of a Haskell compiler and the tool
 `cabal-install`, and we saw in section [How to install Haskell packages] how
@@ -162,7 +164,7 @@ anymore once `nix-shell` has terminated. If you find that your Haskell builds
 no longer work after garbage collection, then you'll have to re-run `cabal
 configure` inside of a new `nix-shell` environment.
 
-## How to install a compiler with libraries
+### How to install a compiler with libraries
 
 GHC expects to find all installed libraries inside of its own `lib` directory.
 This approach works fine on traditional Unix systems, but it doesn't work for
@@ -257,7 +259,7 @@ environment in your profile:
       export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
     fi
 
-## How to install a compiler with libraries, hoogle and documentation indexes
+### How to install a compiler with libraries, hoogle and documentation indexes
 
 If you plan to use your environment for interactive programming, not just
 compiling random Haskell code, you might want to replace `ghcWithPackages` in
@@ -319,7 +321,7 @@ page](http://kb.mozillazine.org/Links_to_local_pages_do_not_work) for
 workarounds.
 
 
-## How to create ad hoc environments for `nix-shell`
+### How to create ad hoc environments for `nix-shell`
 
 The easiest way to create an ad hoc development environment is to run
 `nix-shell` with the appropriate GHC environment given on the command-line:
@@ -369,14 +371,14 @@ development commands. Note that you need `cabal-install` installed in your
 `$PATH` already to use it here --- the `nix-shell` environment does not provide
 it.
 
-# How to create Nix builds for your own private Haskell packages
+## How to create Nix builds for your own private Haskell packages
 
 If your own Haskell packages have build instructions for Cabal, then you can
 convert those automatically into build instructions for Nix using the
 `cabal2nix` utility, which you can install into your profile by running
 `nix-env -i cabal2nix`.
 
-## How to build a stand-alone project
+### How to build a stand-alone project
 
 For example, let's assume that you're working on a private project called
 `foo`. To generate a Nix build expression for it, change into the project's
@@ -433,7 +435,7 @@ You can even use that generated file to run `nix-build`, too:
 
     $ nix-build shell.nix
 
-## How to build projects that depend on each other
+### How to build projects that depend on each other
 
 If you have multiple private Haskell packages that depend on each other, then
 you'll have to register those packages in the Nixpkgs set to make them visible
@@ -468,9 +470,9 @@ or enter an interactive shell environment suitable for building them:
 
     $ nix-shell "<nixpkgs>" -A haskellPackages.bar.env
 
-# Miscellaneous Topics
+## Miscellaneous Topics
 
-## How to build with profiling enabled
+### How to build with profiling enabled
 
 Every Haskell package set takes a function called `overrides` that you can use
 to manipulate the package as much as you please. One useful application of this
@@ -494,7 +496,7 @@ following snippet in your `~/.nixpkgs/config.nix` file:
 Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
 `default.nix` or `shell.nix` files with `profiledHaskellPackages`.
 
-## How to override package versions in a compiler-specific package set
+### How to override package versions in a compiler-specific package set
 
 Nixpkgs provides the latest version of
 [`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
@@ -560,7 +562,7 @@ prefer one built with GHC 7.8.x in the first place. However, for users who
 cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
 older version might be useful.
 
-## How to recover from GHC's infamous non-deterministic library ID bug
+### How to recover from GHC's infamous non-deterministic library ID bug
 
 GHC and distributed build farms don't get along well:
 
@@ -586,7 +588,7 @@ command, i.e. by running:
     rm /nix/var/nix/manifests/*
     rm /nix/var/nix/channel-cache/*
 
-## Builds on Darwin fail with `math.h` not found
+### Builds on Darwin fail with `math.h` not found
 
 Users of GHC on Darwin have occasionally reported that builds fail, because the
 compiler complains about a missing include file:
@@ -603,7 +605,7 @@ can configure the environment variables
 
 in their `~/.bashrc` file to avoid the compiler error.
 
-## Using Stack together with Nix
+### Using Stack together with Nix
 
     --  While building package zlib-0.5.4.2 using:
       runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
@@ -666,7 +668,7 @@ to find out the store path of the system's zlib library. Now, you can
    The same thing applies to `cabal configure`, of course, if you're
    building with `cabal-install` instead of Stack.
 
-## Creating statically linked binaries
+### Creating statically linked binaries
 
 There are two levels of static linking. The first option is to configure the
 build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions,
@@ -688,7 +690,7 @@ as shared libraries only, i.e. there is just no static library available that
 Cabal could link!
 
 
-# Other resources
+## Other resources
 
 - The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
   provides an introduction into Haskell NG aimed at beginners. The slides are
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 9fd79877e835..743a1b70be7c 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -20,6 +20,7 @@ such as Perl or Haskell.  These are described in this chapter.</para>
 <xi:include href="java.xml" />
 <xi:include href="lua.xml" />
 <xi:include href="coq.xml" />
+<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md  -->
 <xi:include href="qt.xml" />