From f67ea4a6d0b14a61af3ccd98ef1a37ce870162e1 Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Sat, 24 Mar 2018 22:10:55 -0400
Subject: [PATCH] Document shell.nix / xmloscopy / make for the nixpkgs docs

---
 doc/contributing.xml | 24 ++++++++++++++++++++----
 doc/shell.nix        |  4 ++++
 2 files changed, 24 insertions(+), 4 deletions(-)
 create mode 100644 doc/shell.nix

diff --git a/doc/contributing.xml b/doc/contributing.xml
index a83059aa36e6..8eed9c5416e8 100644
--- a/doc/contributing.xml
+++ b/doc/contributing.xml
@@ -6,12 +6,28 @@
 
 <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
-$ nix-build doc
+  $ cd /path/to/nixpkgs/doc
+  $ nix-shell
+  [nix-shell]$ make
+</screen>
+
+<para>If you experience problems, run <command>xmloscopy --docbook5
+./manual.xml ./manual-full.xml</command> inside the nix-shell 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/doc
+  $ nix-shell
+  [nix-shell]$ make clean
+  [nix-shell]$ nix-build .
 </screen>
 
 If the build succeeds, the manual will be in
diff --git a/doc/shell.nix b/doc/shell.nix
new file mode 100644
index 000000000000..22590142ee1a
--- /dev/null
+++ b/doc/shell.nix
@@ -0,0 +1,4 @@
+{ pkgs ? import ../. {} }:
+(import ./default.nix).overrideAttrs (x: {
+  buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ];
+})