NixOS · May 1, 2018 · May 1, 2018 · May 1, 2018 · May 1, 2018 · May 1, 2018
diff --git a/doc/Makefile b/doc/Makefile
@@ -1,12 +1,17 @@
 MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))
 
 .PHONY: all
-all: validate out/html/index.html out/epub/manual.epub
+all: validate format out/html/index.html out/epub/manual.epub
 
 .PHONY: debug
 debug:
 	nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
 
+.PHONY: format
+format:
+	find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
+		xmlformat --config-file "$$XMLFORMAT_CONFIG" -i {}
+
 .PHONY: clean
 clean:
 	rm -f ${MD_TARGETS} .version manual-full.xml

diff --git a/doc/default.nix b/doc/default.nix
@@ -7,7 +7,7 @@ in
 pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
-  buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing ];
+  buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing  xmlformat ];
 
   src = ./.;
 
@@ -18,6 +18,7 @@ pkgs.stdenv.mkDerivation {
   HIGHLIGHTJS = pkgs.documentation-highlighter;
   XSL = "${pkgs.docbook5_xsl}/xml/xsl";
   RNG = "${pkgs.docbook5}/xml/rng/docbook/docbook.rng";
+  XMLFORMAT_CONFIG = ../nixos/doc/xmlformat.conf;
   xsltFlags = lib.concatStringsSep " " [
     "--param section.autolabel 1"
     "--param section.label.includes.component.label 1"

diff --git a/doc/shell.nix b/doc/shell.nix
@@ -1,4 +1,5 @@
 { pkgs ? import ../. {} }:
 (import ./default.nix).overrideAttrs (x: {
   buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ];
+
 })
diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile
@@ -0,0 +1,24 @@
+.PHONY: all
+all: manual-combined.xml format
+
+.PHONY: debug
+debug: generated manual-combined.xml
+
+manual-combined.xml: generated *.xml
+	rm -f ./manual-combined.xml
+	nix-shell --packages xmloscopy \
+		--run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml"
+
+.PHONY: format
+format:
+	find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
+		xmlformat --config-file "../xmlformat.conf" -i {}
+
+.PHONY: clean
+clean:
+	rm -f manual-combined.xml generated
+
+generated: ./options-to-docbook.xsl
+	nix-build ../../release.nix \
+		--attr manualGeneratedSources.x86_64-linux \
+		--out-link ./generated
diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
@@ -25,9 +25,8 @@ effect after you run <command>nixos-rebuild</command>.</para>
 <xi:include href="networking.xml" />
 <xi:include href="linux-kernel.xml" />
 
-<xi:include href="modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
+<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
 
 <!-- Apache; libvirtd virtualisation -->
 
 </part>
-
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
@@ -102,13 +102,18 @@ let
     </section>
   '';
 
+  generatedSources = runCommand "generated-docbook" {} ''
+    mkdir $out
+    ln -s ${modulesDoc} $out/modules.xml
+    ln -s ${optionsDocBook} $out/options-db.xml
+    printf "%s" "${version}" > $out/version
+  '';
+
   copySources =
     ''
       cp -prd $sources/* . # */
+      ln -s ${generatedSources} ./generated
       chmod -R u+w .
-      ln -s ${modulesDoc} configuration/modules.xml
-      ln -s ${optionsDocBook} options-db.xml
-      printf "%s" "${version}" > version
     '';
 
   toc = builtins.toFile "toc.xml"
@@ -224,6 +229,7 @@ let
     '';
 
 in rec {
+  inherit generatedSources;
 
   # The NixOS options in JSON format.
   optionsJSON = runCommand "options-json"

diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml
@@ -18,13 +18,25 @@
 <para>
   The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
   <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
-  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>
 
-  <screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
+<para>
+  You can quickly validate your edits with <command>make</command>:
 </para>
 
+<screen>
+  $ cd /path/to/nixpkgs/nixos/doc/manual
+  $ make
+</screen>
+
+<para>
+  Once you are done making modifications to the manual, it's important
+  to build it before committing. You can do that as follows:
+</para>
+
+<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
+
 <para>
   When this command successfully finishes, it will tell you where the
   manual got generated. The HTML will be accessible through the

diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml
@@ -31,7 +31,8 @@ therein.</para>
 <para>You can use the following options in
 <filename>configuration.nix</filename>.</para>
 
-<xi:include href="options-db.xml" />
+<xi:include href="./generated/options-db.xml"
+            xpointer="configuration-variable-list" />
 
 </refsection>
 

diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml
@@ -6,7 +6,7 @@
 
   <info>
     <title>NixOS Manual</title>
-    <subtitle>Version <xi:include href="version" parse="text" /></subtitle>
+    <subtitle>Version <xi:include href="./generated/version" parse="text" /></subtitle>
   </info>
 
   <preface>
@@ -39,7 +39,8 @@
 
   <appendix xml:id="ch-options">
     <title>Configuration Options</title>
-    <xi:include href="options-db.xml" />
+    <xi:include href="./generated/options-db.xml"
+                xpointer="configuration-variable-list" />
   </appendix>
 
   <xi:include href="release-notes/release-notes.xml" />

diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl
@@ -15,9 +15,9 @@
 
 
   <xsl:template match="/expr/list">
-
-      <variablelist>
-
+    <appendix>
+      <title>Configuration Options</title>
+      <variablelist xml:id="configuration-variable-list">
         <xsl:for-each select="attrs">
           <xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '&lt;', '_'), '>', '_'), '?', '_'))" />
           <varlistentry>
@@ -100,7 +100,7 @@
         </xsl:for-each>
 
       </variablelist>
-
+    </appendix>
   </xsl:template>
 
 

diff --git a/nixos/doc/manual/shell.nix b/nixos/doc/manual/shell.nix
@@ -0,0 +1,8 @@
+let
+  pkgs = import ../../.. { };
+in
+pkgs.mkShell {
+  name = "nixos-manual";
+
+  buildInputs = with pkgs; [ xmlformat jing xmloscopy ];
+}
diff --git a/nixos/doc/xmlformat.conf b/nixos/doc/xmlformat.conf
@@ -0,0 +1,72 @@
+#
+# DocBook Configuration file for "xmlformat"
+# see http://www.kitebird.com/software/xmlformat/
+# 10 Sept. 2004
+#
+
+# Only block elements
+ackno address appendix article biblioentry bibliography bibliomixed \
+biblioset blockquote book bridgehead callout calloutlist caption caution \
+chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \
+constructorsynopsis dedication destructorsynopsis entry epigraph equation example \
+figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \
+glosssee glossseealso graphic graphicco highlights imageobjectco important \
+index indexdiv indexentry indexinfo info informalequation informalexample \
+informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \
+mediaobjectco msgmain msgset note orderedlist para part preface primaryie \
+procedure qandadiv qandaentry qandaset refentry refentrytitle reference \
+refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \
+sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \
+simplesect step substeps synopfragment synopsis table term title \
+toc variablelist varlistentry warning itemizedlist listitem \
+footnote colspec partintro row simplelist subtitle tbody tgroup thead tip
+  format      block
+  normalize   no
+
+
+#appendix bibliography chapter glossary preface reference
+#  element-break   3
+
+sect1 section
+  element-break   2
+
+
+#
+para abstract
+  format       block
+  entry-break  1
+  exit-break   1
+  normalize    yes
+  wrap-length  79
+
+title
+  format       block
+  normalize = yes
+  entry-break = 0
+  exit-break = 0
+
+# Inline elements
+abbrev accel acronym action application citation citebiblioid citerefentry citetitle \
+classname co code command computeroutput constant country database date email emphasis \
+envar errorcode errorname errortext errortype exceptionname fax filename \
+firstname firstterm footnoteref foreignphrase funcdef funcparams function \
+glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \
+hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \
+interface interfacename \
+keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \
+menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \
+oointerface option optional otheraddr othername package paramdef parameter personname \
+phrase pob postcode productname prompt property quote refpurpose replaceable \
+returnvalue revnumber sgmltag state street structfield structname subscript \
+superscript surname symbol systemitem token trademark type ulink userinput \
+uri varargs varname void wordasword xref year mathphrase member tag
+  format       inline
+
+programlisting screen
+  format       verbatim
+  entry-break = 0
+  exit-break = 0
+
+
+#term
+#  format       inline
diff --git a/nixos/release.nix b/nixos/release.nix
@@ -123,14 +123,14 @@ let
         preferLocalBuild = true;
       };
 
-
 in rec {
 
   channel = import lib/make-channel.nix { inherit pkgs nixpkgs version versionSuffix; };
 
   manual = buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.manual);
   manualEpub = (buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.manualEpub));
   manpages = buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.manpages);
+  manualGeneratedSources = buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.generatedSources);
   options = (buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.optionsJSON)).x86_64-linux;