From 3e4035695c9c969675de66ca1b63e13ef57e5bd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20=C4=8Cun=C3=A1t?= Date: Mon, 21 Dec 2015 10:50:37 +0100 Subject: [PATCH] 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. --- doc/default.nix | 46 +++++++++++++++++++----------- doc/haskell-users-guide.md | 36 ++++++++++++----------- doc/languages-frameworks/index.xml | 1 + 3 files changed, 49 insertions(+), 34 deletions(-) diff --git a/doc/default.nix b/doc/default.nix index cca68014b0d..7e41380d635 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -20,27 +20,39 @@ stdenv.mkDerivation { --param callout.graphics.extension '.gif' ''; - buildCommand = '' - { - echo "" - echo "" - echo "User's Guide to the Haskell Infrastructure" - echo "" - pandoc ${./haskell-users-guide.md} -w docbook | \ - sed -e 's|||' \ - -e 's|||' - echo "" - echo "" - } >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|||' \ + -e 's|||' \ + -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 446f08eb697..b11e4cf09f8 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 "" -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 9fd79877e83..743a1b70be7 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. +