doc: Adds xml fixing script. (see previous and next commits)

This script is used to automatically fix issues within xml documentation
files.

The script is *for now* intended to be used ad-hoc, and the commits to
be examined.

A future discussion will define whether:

  * This commit and scripts are kept.
  * The script is extended for common use.

The biggest issue right now with the script is that it *could* in theory
destroy a valid space-less varlistentry.

The script could, in practical use, be changed and extended to normalize
some parts of the XML files, mainly:

  * A common quoting style for attributes
  * Fix-up some weird formatting automatically that xmlformat doesn't
    catch

5 files changed, 136 insertions, 2 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 8a4612e95f1..ba77be6678c 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -12,6 +12,11 @@ format:
 	find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
 		xmlformat --config-file "$$XMLFORMAT_CONFIG" -i {}
 
+.PHONY: fix-misc-xml
+fix-misc-xml:
+	find . -iname '*.xml' -type f \
+		-exec ../nixos/doc/varlistentry-fixer.rb {} ';'
+
 .PHONY: clean
 clean:
 	rm -f ${MD_TARGETS} .version manual-full.xml
diff --git a/doc/shell.nix b/doc/shell.nix
index e8da2eaf16b..24fe20e8105 100644
--- a/doc/shell.nix
+++ b/doc/shell.nix
@@ -1,5 +1,5 @@
 { pkgs ? import ../. {} }:
 (import ./default.nix).overrideAttrs (x: {
-  buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ];
+  buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ];
 
 })
diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile
index 2e2322d5fb5..5cbbf140869 100644
--- a/nixos/doc/manual/Makefile
+++ b/nixos/doc/manual/Makefile
@@ -14,6 +14,11 @@ format:
 	find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
 		xmlformat --config-file "../xmlformat.conf" -i {}
 
+.PHONY: fix-misc-xml
+fix-misc-xml:
+	find . -iname '*.xml' -type f \
+		-exec ../varlistentry-fixer.rb {} ';'
+
 .PHONY: clean
 clean:
 	rm -f manual-combined.xml generated
diff --git a/nixos/doc/manual/shell.nix b/nixos/doc/manual/shell.nix
index 7f8422b4ec1..cc3609d750e 100644
--- a/nixos/doc/manual/shell.nix
+++ b/nixos/doc/manual/shell.nix
@@ -4,5 +4,5 @@ in
 pkgs.mkShell {
   name = "nixos-manual";
 
-  buildInputs = with pkgs; [ xmlformat jing xmloscopy ];
+  buildInputs = with pkgs; [ xmlformat jing xmloscopy ruby ];
 }
diff --git a/nixos/doc/varlistentry-fixer.rb b/nixos/doc/varlistentry-fixer.rb
new file mode 100755
index 00000000000..6c7cc1e6439
--- /dev/null
+++ b/nixos/doc/varlistentry-fixer.rb
@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+
+# This script is written intended as a living, evolving tooling
+# to fix oopsies within the docbook documentation.
+#
+# This is *not* a formatter. It, instead, handles some known cases
+# where something bad happened, and fixing it manually is tedious.
+#
+# Read the code to see the different cases it handles.
+#
+# ALWAYS `make format` after fixing with this!
+# ALWAYS read the changes, this tool isn't yet proven to be always right.
+
+require "rexml/document"
+include REXML
+
+if ARGV.length < 1 then
+	$stderr.puts "Needs a filename."
+	exit 1
+end
+
+filename = ARGV.shift
+doc = Document.new(File.open(filename))
+
+$touched = false
+
+# Fixing varnames having a sibling element without spacing.
+# This is to fix an initial `xmlformat` issue where `term`
+# would mangle as spaces.
+#
+#   <varlistentry>
+#    <term><varname>types.separatedString</varname><replaceable>sep</replaceable> <----
+#    </term>
+#    ...
+#
+# Generates: types.separatedStringsep
+#                               ^^^^
+#
+# <varlistentry xml:id='fun-makeWrapper'>
+#  <term>
+#   <function>makeWrapper</function><replaceable>executable</replaceable><replaceable>wrapperfile</replaceable><replaceable>args</replaceable>  <----
+#  </term>
+#
+# Generates: makeWrapperexecutablewrapperfileargs
+#                     ^^^^      ^^^^    ^^  ^^
+#
+#    <term>
+#     <option>--option</option><replaceable>name</replaceable><replaceable>value</replaceable> <-----
+#    </term>
+#
+# Generates: --optionnamevalue
+#                   ^^  ^^
+doc.elements.each("//varlistentry/term") do |term|
+	["varname", "function", "option", "replaceable"].each do |prev_name|
+		term.elements.each(prev_name) do |el|
+			if el.next_element and
+					el.next_element.name == "replaceable" and
+					el.next_sibling_node.class == Element
+				then
+				$touched = true
+				term.insert_after(el, Text.new(" "))
+			end
+		end
+	end
+end
+
+
+
+#  <cmdsynopsis>
+#   <command>nixos-option</command>
+#   <arg>
+#    <option>-I</option><replaceable>path</replaceable>        <------
+#   </arg>
+#
+# Generates: -Ipath
+#             ^^
+doc.elements.each("//cmdsynopsis/arg") do |term|
+	["option", "replaceable"].each do |prev_name|
+		term.elements.each(prev_name) do |el|
+			if el.next_element and
+				el.next_element.name == "replaceable" and
+				el.next_sibling_node.class == Element
+			then
+				$touched = true
+				term.insert_after(el, Text.new(" "))
+			end
+		end
+	end
+end
+
+#  <cmdsynopsis>
+#   <arg>
+#    <group choice='req'>
+#    <arg choice='plain'>
+#     <option>--profile-name</option>
+#    </arg>
+#
+#    <arg choice='plain'>
+#     <option>-p</option>
+#    </arg>
+#     </group><replaceable>name</replaceable>   <----
+#   </arg>
+#
+# Generates: [{--profile-name | -p }name]
+#                                   ^^^^
+doc.elements.each("//cmdsynopsis/arg") do |term|
+	["group"].each do |prev_name|
+		term.elements.each(prev_name) do |el|
+			if el.next_element and
+				el.next_element.name == "replaceable" and
+				el.next_sibling_node.class == Element
+			then
+				$touched = true
+				term.insert_after(el, Text.new(" "))
+			end
+		end
+	end
+end
+
+
+if $touched then
+	doc.context[:attribute_quote] = :quote
+	doc.write(output: File.open(filename, "w"))
+end