nixos/doc/varlistentry-fixer.rb

   1 #!/usr/bin/env ruby
   2
   3 # This script is written intended as a living, evolving tooling
   4 # to fix oopsies within the docbook documentation.
   5 #
   6 # This is *not* a formatter. It, instead, handles some known cases
   7 # where something bad happened, and fixing it manually is tedious.
   8 #
   9 # Read the code to see the different cases it handles.
  10 #
  11 # ALWAYS `make format` after fixing with this!
  12 # ALWAYS read the changes, this tool isn't yet proven to be always right.
  13
  14 require "rexml/document"
  15 include REXML
  16
  17 if ARGV.length < 1 then
  18   $stderr.puts "Needs a filename."
  19   exit 1
  20 end
  21
  22 filename = ARGV.shift
  23 doc = Document.new(File.open(filename))
  24
  25 $touched = false
  26
  27 # Fixing varnames having a sibling element without spacing.
  28 # This is to fix an initial `xmlformat` issue where `term`
  29 # would mangle as spaces.
  30 #
  31 #   <varlistentry>
  32 #    <term><varname>types.separatedString</varname><replaceable>sep</replaceable> <----
  33 #    </term>
  34 #    ...
  35 #
  36 # Generates: types.separatedStringsep
  37 #                               ^^^^
  38 #
  39 # <varlistentry xml:id='fun-makeWrapper'>
  40 #  <term>
  41 #   <function>makeWrapper</function><replaceable>executable</replaceable><replaceable>wrapperfile</replaceable><replaceable>args</replaceable>  <----
  42 #  </term>
  43 #
  44 # Generates: makeWrapperexecutablewrapperfileargs
  45 #                     ^^^^      ^^^^    ^^  ^^
  46 #
  47 #    <term>
  48 #     <option>--option</option><replaceable>name</replaceable><replaceable>value</replaceable> <-----
  49 #    </term>
  50 #
  51 # Generates: --optionnamevalue
  52 #                   ^^  ^^
  53 doc.elements.each("//varlistentry/term") do |term|
  54   ["varname", "function", "option", "replaceable"].each do |prev_name|
  55     term.elements.each(prev_name) do |el|
  56       if el.next_element and
  57           el.next_element.name == "replaceable" and
  58           el.next_sibling_node.class == Element
  59         then
  60         $touched = true
  61         term.insert_after(el, Text.new(" "))
  62       end
  63     end
  64   end
  65 end
  66
  67
  68
  69 #  <cmdsynopsis>
  70 #   <command>nixos-option</command>
  71 #   <arg>
  72 #    <option>-I</option><replaceable>path</replaceable>        <------
  73 #   </arg>
  74 #
  75 # Generates: -Ipath
  76 #             ^^
  77 doc.elements.each("//cmdsynopsis/arg") do |term|
  78   ["option", "replaceable"].each do |prev_name|
  79     term.elements.each(prev_name) do |el|
  80       if el.next_element and
  81         el.next_element.name == "replaceable" and
  82         el.next_sibling_node.class == Element
  83       then
  84         $touched = true
  85         term.insert_after(el, Text.new(" "))
  86       end
  87     end
  88   end
  89 end
  90
  91 #  <cmdsynopsis>
  92 #   <arg>
  93 #    <group choice='req'>
  94 #    <arg choice='plain'>
  95 #     <option>--profile-name</option>
  96 #    </arg>
  97 #
  98 #    <arg choice='plain'>
  99 #     <option>-p</option>
 100 #    </arg>
 101 #     </group><replaceable>name</replaceable>   <----
 102 #   </arg>
 103 #
 104 # Generates: [{--profile-name | -p }name]
 105 #                                   ^^^^
 106 doc.elements.each("//cmdsynopsis/arg") do |term|
 107   ["group"].each do |prev_name|
 108     term.elements.each(prev_name) do |el|
 109       if el.next_element and
 110         el.next_element.name == "replaceable" and
 111         el.next_sibling_node.class == Element
 112       then
 113         $touched = true
 114         term.insert_after(el, Text.new(" "))
 115       end
 116     end
 117   end
 118 end
 119
 120
 121 if $touched then
 122   doc.context[:attribute_quote] = :quote
 123   doc.write(output: File.open(filename, "w"))
 124 end