Merge remote-tracking branch 'upstream/release-18.03' into meta-check…

…-18.03

doc/.gitignore

@@ -0,0 +1,6 @@
+*.chapter.xml
+*.section.xml
+.version
+out
+manual-full.xml
+highlightjs

doc/Makefile

@@ -0,0 +1,96 @@
+MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))
+
+.PHONY: all
+all: validate out/html/index.html out/epub/manual.epub
+
+.PHONY: debug
+debug:
+	nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
+
+.PHONY: clean
+clean:
+	rm -f ${MD_TARGETS} .version manual-full.xml
+	rm -rf ./out/ ./highlightjs
+
+.PHONY: validate
+validate: manual-full.xml
+	jing "$$RNG" manual-full.xml
+
+out/html/index.html: manual-full.xml style.css highlightjs
+	mkdir -p out/html
+	xsltproc ${xsltFlags} \
+		--nonet --xinclude \
+		--output $@ \
+		"$$XSL/docbook/xhtml/docbook.xsl" \
+		./manual-full.xml
+
+	mkdir -p out/html/highlightjs/
+	echo "document.onreadystatechange = function () { \
+	  var listings = document.querySelectorAll('.programlisting, .screen'); \
+	  for (i = 0; i < listings.length; ++i) { \
+	     hljs.highlightBlock(listings[i]); \
+	  } \
+	} " > out/html/highlightjs/loader.js
+
+	cp -r highlightjs out/html/
+
+	cp ./overrides.css out/html/
+	cp ./style.css out/html/style.css
+
+	mkdir -p out/html/images/callouts
+	cp "$$XSL/docbook/images/callouts/"*.svg out/html/images/callouts/
+	chmod u+w -R out/html/
+
+out/epub/manual.epub: manual-full.xml
+	mkdir -p out/epub/scratch
+	xsltproc ${xsltFlags} --nonet \
+		--output out/epub/scratch/ \
+		"$$XSL/docbook/epub/docbook.xsl" \
+		./manual-full.xml
+
+	cp ./overrides.css out/epub/scratch/OEBPS
+	cp ./style.css out/epub/scratch/OEBPS
+	mkdir -p out/epub/scratch/OEBPS/images/callouts/
+	cp "$$XSL/docbook/images/callouts/"*.svg out/epub/scratch/OEBPS/images/callouts/
+	echo "application/epub+zip" > mimetype
+	zip -0Xq "out/epub/manual.epub" mimetype
+	rm mimetype
+	cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" *
+	rm -rf "out/epub/scratch/"
+
+highlightjs:
+	mkdir -p highlightjs
+	cp -r "$$HIGHLIGHTJS/highlight.pack.js" highlightjs/
+	cp -r "$$HIGHLIGHTJS/LICENSE" highlightjs/
+	cp -r "$$HIGHLIGHTJS/mono-blue.css" highlightjs/
+
+
+manual-full.xml: ${MD_TARGETS} .version *.xml
+	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
+
+.version:
+	nix-instantiate --eval \
+		-E '(import ../lib).nixpkgsVersion' > .version
+
+%.section.xml: %.section.md
+	pandoc $^ -w docbook+smart \
+		-f markdown+smart \
+	  | 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|\(<[^ ]* \)|\1xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" |' \
+	| cat  > $@
+
+%.chapter.xml: %.chapter.md
+	pandoc $^ -w docbook+smart \
+		--top-level-division=chapter \
+		-f markdown+smart \
+	  | 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|' \
+	| cat  > $@

doc/contributing.xml

@@ -6,12 +6,27 @@
 
 <para>The DocBook sources of the Nixpkgs manual are in the <filename
 xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
-subdirectory of the Nixpkgs repository. If you make modifications to
-the manual, it's important to build it before committing. You can do that as follows:
+subdirectory of the Nixpkgs repository.</para>
+
+<para>You can quickly check your edits with <command>make</command>:</para>
+
+<screen>
+  $ cd /path/to/nixpkgs/doc
+  $ nix-shell
+  [nix-shell]$ make
+</screen>
+
+<para>If you experience problems, run <command>make debug</command>
+to help understand the docbook errors.</para>
+
+<para>After making modifications to the manual, it's important to
+build it before committing. You can do that as follows:
 
 <screen>
-$ cd /path/to/nixpkgs
-$ nix-build doc
+  $ cd /path/to/nixpkgs/doc
+  $ nix-shell
+  [nix-shell]$ make clean
+  [nix-shell]$ nix-build .
 </screen>
 
 If the build succeeds, the manual will be in

doc/default.nix

@@ -7,112 +7,41 @@ in
 pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
-
-  buildInputs = with pkgs; [ pandoc libxml2 libxslt zip ];
-
-  xsltFlags = ''
-    --param section.autolabel 1
-    --param section.label.includes.component.label 1
-    --param html.stylesheet 'style.css'
-    --param xref.with.number.and.title 1
-    --param toc.section.depth 3
-    --param admon.style '''
-    --param callout.graphics.extension '.gif'
-  '';
-
-
-  buildCommand = let toDocbook = { useChapters ? false, inputFile, outputFile }:
-    let
-      extraHeader = lib.optionalString (!useChapters)
-        ''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" '';
-    in ''
-      {
-        pandoc '${inputFile}' -w docbook+smart ${lib.optionalString useChapters "--top-level-division=chapter"} \
-          -f markdown+smart \
-          | 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 = ./introduction.md;
-      outputFile = "introduction.xml";
-      useChapters = true;
-    }
-  + toDocbook {
-      inputFile = ./shell.md;
-      outputFile = "shell.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/python.md;
-      outputFile = "./languages-frameworks/python.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/haskell.md;
-      outputFile = "./languages-frameworks/haskell.xml";
-    }
-  + toDocbook {
-      inputFile = ../pkgs/development/idris-modules/README.md;
-      outputFile = "languages-frameworks/idris.xml";
-    }
-  + toDocbook {
-      inputFile = ../pkgs/development/node-packages/README.md;
-      outputFile = "languages-frameworks/node.xml";
-    }
-  + toDocbook {
-      inputFile = ../pkgs/development/r-modules/README.md;
-      outputFile = "languages-frameworks/r.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/rust.md;
-      outputFile = "./languages-frameworks/rust.xml";
-    }
-  + toDocbook {
-      inputFile = ./languages-frameworks/vim.md;
-      outputFile = "./languages-frameworks/vim.xml";
-    }
-  + ''
+  buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing ];
+
+  src = ./.;
+
+  # Hacking on these variables? Make sure to close and open
+  # nix-shell between each test, maybe even:
+  # $ nix-shell --run "make clean all"
+  # otherwise they won't reapply :)
+  HIGHLIGHTJS = pkgs.documentation-highlighter;
+  XSL = "${pkgs.docbook5_xsl}/xml/xsl";
+  RNG = "${pkgs.docbook5}/xml/rng/docbook/docbook.rng";
+  xsltFlags = lib.concatStringsSep " " [
+    "--param section.autolabel 1"
+    "--param section.label.includes.component.label 1"
+    "--stringparam html.stylesheet 'style.css overrides.css highlightjs/mono-blue.css'"
+    "--stringparam html.script './highlightjs/highlight.pack.js ./highlightjs/loader.js'"
+    "--param xref.with.number.and.title 1"
+    "--param toc.section.depth 3"
+    "--stringparam admon.style ''"
+    "--stringparam callout.graphics.extension .svg"
+  ];
+
+  postPatch = ''
     echo ${lib.nixpkgsVersion} > .version
+  '';
 
-    # validate against relaxng schema
-    xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
-    ${pkgs.jing}/bin/jing ${pkgs.docbook5}/xml/rng/docbook/docbook.rng manual-full.xml
-
-    dst=$out/share/doc/nixpkgs
-    mkdir -p $dst
-    xsltproc $xsltFlags --nonet --xinclude \
-      --output $dst/manual.html \
-      ${pkgs.docbook5_xsl}/xml/xsl/docbook/xhtml/docbook.xsl \
-      ./manual.xml
-
-    cp ${./style.css} $dst/style.css
-
-    mkdir -p $dst/images/callouts
-    cp "${pkgs.docbook5_xsl}/xml/xsl/docbook/images/callouts/"*.gif $dst/images/callouts/
-
-    mkdir -p $out/nix-support
-    echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products
+  installPhase = ''
+    dest="$out/share/doc/nixpkgs"
+    mkdir -p "$(dirname "$dest")"
+    mv out/html "$dest"
+    mv "$dest/index.html" "$dest/manual.html"
 
-    xsltproc $xsltFlags --nonet --xinclude \
-      --output $dst/epub/ \
-      ${pkgs.docbook5_xsl}/xml/xsl/docbook/epub/docbook.xsl \
-      ./manual.xml
+    mv out/epub/manual.epub "$dest/nixpkgs-manual.epub"
 
-    cp -r $dst/images $dst/epub/OEBPS
-    echo "application/epub+zip" > mimetype
-    manual="$dst/nixpkgs-manual.epub"
-    zip -0Xq "$manual" mimetype
-    cd $dst/epub && zip -Xr9D "$manual" *
-    rm -rf $dst/epub
+    mkdir -p $out/nix-support/
+    echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
   '';
 }

doc/languages-frameworks/idris.section.md

@@ -0,0 +1,39 @@
+Idris packages
+==============
+
+This directory contains build rules for idris packages. In addition,
+it contains several functions to build and compose those packages.
+Everything is exposed to the user via the `idrisPackages` attribute.
+
+callPackage
+------------
+
+This is like the normal nixpkgs callPackage function, specialized to
+idris packages.
+
+builtins
+---------
+
+This is a list of all of the libraries that come packaged with Idris
+itself.
+
+build-idris-package
+--------------------
+
+A function to build an idris package. Its sole argument is a set like
+you might pass to `stdenv.mkDerivation`, except `build-idris-package`
+sets several attributes for you. See `build-idris-package.nix` for
+details.
+
+build-builtin-package
+----------------------
+
+A version of `build-idris-package` specialized to builtin libraries.
+Mostly for internal use.
+
+with-packages
+-------------
+
+Bundle idris together with a list of packages. Because idris currently
+only supports a single directory in its library path, you must include
+all desired libraries here, including `prelude` and `base`.

doc/languages-frameworks/index.xml

@@ -17,19 +17,18 @@ such as Perl or Haskell.  These are described in this chapter.</para>
 <xi:include href="bower.xml" />
 <xi:include href="coq.xml" />
 <xi:include href="go.xml" />
-<xi:include href="haskell.xml" />
-<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md  -->
+<xi:include href="haskell.section.xml" />
+<xi:include href="idris.section.xml" />
 <xi:include href="java.xml" />
 <xi:include href="lua.xml" />
-<xi:include href="node.xml" /> <!-- generated from ../../pkgs/development/node-packages/README.md  -->
+<xi:include href="node.section.xml" />
 <xi:include href="perl.xml" />
-<xi:include href="python.xml" />
+<xi:include href="python.section.xml" />
 <xi:include href="qt.xml" />
-<xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md  -->
+<xi:include href="r.section.xml" />
 <xi:include href="ruby.xml" />
-<xi:include href="rust.xml" />
+<xi:include href="rust.section.xml" />
 <xi:include href="texlive.xml" />
-<xi:include href="vim.xml" />
-
+<xi:include href="vim.section.xml" />
 
 </chapter>