Document shell.nix / xmloscopy / make for the nixpkgs docs

2018-03-25 19:52:08 -04:00
parent 7e25ff7106
commit f67ea4a6d0
2 changed files with 24 additions and 4 deletions
@@ -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