Display instruction defined by more elegantly when the confition is s…

…imple

backends/common_templates/adoc/inst.adoc.erb

@@ -81,4 +81,14 @@ Operation::
 
 Included in::
 
+<%- if inst.defined_by_condition.flat? -%>
+|===
+| Extension | Version
+
+<%- inst.defined_by_condition.flat_versions.each do |r| -%>
+| *<%= r.name %>* | <%= r.requirement_specs_to_s %>
+<%- end -%>
+|===
+<%- else -%>
 <%= inst.defined_by_condition.to_asciidoc %>
+<%- end -%>

backends/ext_pdf_doc/templates/ext_pdf.adoc.erb

@@ -182,6 +182,22 @@ Requires::
 --
 <%- end -%>
 
+<<<
+== Conventions
+
+Version requirements are specified as conditions using the following operators:
+
+[cols="1,2"]
+|===
+| Operator | Meaning
+
+| `~> VERSION` | Accepts any version that is _compatible_ with `VERSION`. By default, a version A is compatible with a version B if A's version number is greater than or equal to version B. If that default assumption is ever broken, it will be noted in the list of extension versions.
+| `= VERSION` | Accepts only version `VERSION`.
+| `>= VERSION` | Accepts any version greater than or equal to `VERSION`.
+| `\<= VERSION` | Accepts any version less than or equal to `VERSION`.
+| `> VERSION` | Accepts any version greater than `VERSION`.
+| `< VERSION` | Accepts any version less than `VERSION`.
+|===
 
 <<<
 == Extension description

lib/arch_obj_models/obj.rb

@@ -413,6 +413,66 @@ def is_a_version_requirement(ver)
     end
   end
 
+  # @return [Boolean] True if the condition is a join of N terms over the same operator
+  #
+  #  A or B or C   #=> true
+  #  A and B       #=> true
+  #  A or B and C  #=> false
+  def flat?
+    case @hsh
+    when String
+      true
+    when Hash
+      @hsh.key?("name") || @hsh[@hsh.keys.first].all? { |child| child.is_a?(String) || (child.is_a?(Hash) && child.key?("name")) }
+    else
+      raise "unexpected"
+    end
+  end
+
+  # @return [:or, :and] The operator for a flat condition
+  #                     Only valid if #flat? is true
+  def flat_op
+    case @hsh
+    when String
+      :or
+    when Hash
+      @hsh.key?("name") ? :or : { "allOf" => :and, "anyOf" => :or }[@hsh.keys.first]
+    else
+      raise "unexpected"
+    end
+  end
+
+  # @return [Array<ExtensionRequirement>] The elements of the flat join
+  #                                       Only valid if #flat? is true
+  def flat_versions
+    case @hsh
+    when String
+      [ExtensionRequirement.new(@hsh, arch: @arch)]
+    when Hash
+      if @hsh.key?("name")
+        if @hsh.key?("version").nil?
+          [ExtensionRequirement.new(@hsh["name"], arch: @arch)]
+        else
+          [ExtensionRequirement.new(@hsh["name"], @hsh["version"], arch: @arch)]
+        end
+      else
+        @hsh[@hsh.keys.first].map do |r|
+          if r.is_a?(String)
+            ExtensionRequirement.new(r, arch: @arch)
+          else
+            if r.key?("version").nil?
+              ExtensionRequirement.new(r["name"], arch: @arch)
+            else
+              ExtensionRequirement.new(r["name"], r["version"], arch: @arch)
+            end
+          end
+        end
+      end
+    else
+      raise "unexpected"
+    end
+  end
+
   def to_asciidoc(cond = @hsh, indent = 0)
     case cond
     when String
@@ -616,6 +676,8 @@ def satisfied_by? = true
 
   def empty? = true
 
+  def flat? = false
+
   def to_h = {}
   def minimize = {}
 end