diff options
author | Samuel Dionne-Riel <samuel@dionne-riel.com> | 2018-05-31 20:26:27 -0400 |
---|---|---|
committer | Samuel Dionne-Riel <samuel@dionne-riel.com> | 2018-05-31 21:02:15 -0400 |
commit | bc0421c4cf18c431ece8d6a19f723159316f55ff (patch) | |
tree | 6c81b79df1a0ad4c24519a508f15e81fea2d5126 /nixos/doc | |
parent | aa59151c21c353923b3f003662f17f2210c63c57 (diff) |
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
Diffstat (limited to 'nixos/doc')
-rw-r--r-- | nixos/doc/manual/Makefile | 5 | ||||
-rw-r--r-- | nixos/doc/manual/shell.nix | 2 | ||||
-rwxr-xr-x | nixos/doc/varlistentry-fixer.rb | 124 |
3 files changed, 130 insertions, 1 deletions
diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile index 2e2322d5fb517..5cbbf140869a6 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 7f8422b4ec11f..cc3609d750e03 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 0000000000000..6c7cc1e6439b1 --- /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 |