From bc0421c4cf18c431ece8d6a19f723159316f55ff Mon Sep 17 00:00:00 2001 From: Samuel Dionne-Riel Date: Thu, 31 May 2018 20:26:27 -0400 Subject: [PATCH] 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 --- doc/Makefile | 5 ++ doc/shell.nix | 2 +- nixos/doc/manual/Makefile | 5 ++ nixos/doc/manual/shell.nix | 2 +- nixos/doc/varlistentry-fixer.rb | 124 ++++++++++++++++++++++++++++++++ 5 files changed, 136 insertions(+), 2 deletions(-) create mode 100755 nixos/doc/varlistentry-fixer.rb 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. +# +# +# types.separatedStringsep <---- +# +# ... +# +# Generates: types.separatedStringsep +# ^^^^ +# +# +# +# makeWrapperexecutablewrapperfileargs <---- +# +# +# Generates: makeWrapperexecutablewrapperfileargs +# ^^^^ ^^^^ ^^ ^^ +# +# +# namevalue <----- +# +# +# 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 + + + +# +# nixos-option +# +# path <------ +# +# +# 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 + +# +# +# +# +# +# +# +# +# +# +# name <---- +# +# +# 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