openstax_kitchen 2.0.0 → 3.0.0

data/lib/kitchen/directions/bake_unit_title/main.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kitchen
+  module Directions
+    module BakeUnitTitle
+      def self.v1(book:)
+        V1.new.bake(book: book)
+      end
+    end
+  end
+end

data/lib/kitchen/directions/bake_unit_title/v1.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Kitchen::Directions::BakeUnitTitle
+  class V1
+    def bake(book:)
+      book.units.each do |unit|
+        compose_unit_title(unit: unit)
+      end
+    end
+
+    def compose_unit_title(unit:)
+      heading = unit.title
+      heading.replace_children(with:
+        <<~HTML
+          <span class="os-part-text">#{I18n.t(:unit)} </span>
+          <span class="os-number">#{unit.count_in(:book)}</span>
+          <span class="os-divider"> </span>
+          <span data-type="" itemprop="" class="os-text">#{heading.text}</span>
+        HTML
+      )
+    end
+  end
+end

data/lib/kitchen/directions/bake_unnumbered_tables.rb

@@ -1,14 +1,16 @@
+# frozen_string_literal: true
+
 module Kitchen
   module Directions
     module BakeUnnumberedTables
-
       def self.v1(book:)
-        book.tables("$.unnumbered").each do |table|
-          table.wrap(%Q(<div class="os-table">))
-          table.remove_attribute("summary")
+        book.tables('$.unnumbered').each do |table|
+          table.wrap(%(<div class="os-table">))
+          table.remove_attribute('summary')
+          table.parent.add_class('os-unstyled-container') if table.unstyled?
+          table.parent.add_class('os-column-header-container') if table.column_header?
         end
       end
-
     end
   end
 end

data/lib/kitchen/directions/move_title_text_into_span.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
+
 module Kitchen
   module Directions
     module MoveTitleTextIntoSpan
-
       def self.v1(title:)
         title.replace_children(with:
           <<~HTML
@@ -9,7 +10,6 @@ module Kitchen
           HTML
         )
       end
-
     end
   end
 end

data/lib/kitchen/document.rb

@@ -1,25 +1,56 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 
 module Kitchen
+  # Wrapper around a Nokogiri `Document`, adding search with Kitchen enumerators,
+  # clipboards, pantries, etc.
+  #
   class Document
     extend Forwardable
 
+    # @return [Element] the current element yielded from search results
     attr_accessor :location
+    # @return [Config] the configuration used in this document
     attr_reader :config
 
+    # @!method selectors
+    #   The document's selectors
+    #   @see Config#selectors
+    #   @return [Selectors::Base]
     def_delegators :config, :selectors
+
+    # @!method to_xhtml
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#to_xhtml-instance_method Nokogiri::XML::Node#to_xhtml
+    #   @return [String] the document as an XHTML string
+    # @!method to_s
+    #   Turn this node in to a string. If the document is HTML, this method returns html.
+    #   If the document is XML, this method returns XML.
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#to_s-instance_method Nokogiri::XML::Node#to_s
+    #   @return [String]
+    # @!method to_xml
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#to_xml-instance_method Nokogiri::XML::Node#to_xml
+    #   @return [String] the document as an XML string
+    # @!method to_html
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#to_html-instance_method Nokogiri::XML::Node#to_html
+    #   @return [String] the document as an HTML string
     def_delegators :@nokogiri_document, :to_xhtml, :to_s, :to_xml, :to_html
 
+    # Return a new instance of Document
+    #
+    # @param nokogiri_document [Nokogiri::XML::Document]
+    # @param config [Config]
     def initialize(nokogiri_document:, config: nil)
       @nokogiri_document = nokogiri_document
       @location = nil
-      @config = config || Config.new_default
+      @config = config || Config.new
       @next_paste_count_for_id = {}
-      @id_copy_suffix = "_copy_"
+      @id_copy_suffix = '_copy_'
     end
 
     # Returns an enumerator that iterates over all children of this document
-    # that match the provided selector or XPath arguments.
+    # that match the provided selector or XPath arguments.  Updates `location`
+    # during iteration.
     #
     # @param selector_or_xpath_args [Array<String>] CSS selectors or XPath arguments
     # @return [ElementEnumerator]
@@ -29,9 +60,11 @@ module Kitchen
 
       ElementEnumerator.new do |block|
         nokogiri_document.search(*selector_or_xpath_args).each do |inner_node|
-          element = Kitchen::Element.new(node: inner_node,
-                                         document: self,
-                                         short_type: Utils.search_path_to_type(selector_or_xpath_args))
+          element = Kitchen::Element.new(
+            node: inner_node,
+            document: self,
+            short_type: Utils.search_path_to_type(selector_or_xpath_args)
+          )
           self.location = element
           block.yield(element)
         end
@@ -92,28 +125,52 @@ module Kitchen
       )
     end
 
+    # Create a new Element from a string
+    #
+    # @param string [String] the element as a string
+    #
+    # @example
+    #   create_element_from_string("<div class='foo'>bar</div>") #=> <div class="foo">bar</div>
+    #
+    # @return [Element]
+    #
     def create_element_from_string(string)
-      Kitchen::Element.new(
-        node: @nokogiri_document.create_element("div"),
-        document: self,
-        short_type: "created_element_#{SecureRandom.hex(4)}"
-      ).element_children.first
+      children = Nokogiri::XML("<foo>#{string}</foo>").search('foo').first.element_children
+      raise('new_element must only make one top-level element') if children.many?
+
+      node = children.first
+
+      create_element(node.name, node.attributes).tap do |element|
+        element.inner_html = node.children
+      end
     end
 
+    # Keeps track that an element with the given ID has been copied.  When such
+    # elements are pasted, this information is used to give those elements unique
+    # IDs that don't duplicate the original element.
+    #
+    # @param id [String] the ID
+    #
     def record_id_copied(id)
       return if id.blank?
+
       @next_paste_count_for_id[id] ||= 1
     end
 
+    # Returns a unique ID given the ID of an element that was copied and is about
+    # to be pasted
+    #
+    # @param original_id [String]
+    #
     def modified_id_to_paste(original_id)
       return nil if original_id.nil?
-      return "" if original_id.blank?
+      return '' if original_id.blank?
 
       count = next_count_for_pasted_id(original_id)
 
       # A count of 0 means the element was cut and this is the first paste, do not
       # modify the ID; otherwise, use the uniquified ID.
-      if count == 0
+      if count.zero?
         original_id
       else
         "#{original_id}#{@id_copy_suffix}#{count}"
@@ -123,6 +180,7 @@ module Kitchen
     # Returns the underlying Nokogiri Document object
     #
     # @return [Nokogiri::XML::Document]
+    #
     def raw
       @nokogiri_document
     end
@@ -131,6 +189,7 @@ module Kitchen
 
     def next_count_for_pasted_id(id)
       return if id.blank?
+
       (@next_paste_count_for_id[id] ||= 0).tap do
         @next_paste_count_for_id[id] += 1
       end

data/lib/kitchen/element.rb

@@ -1,6 +1,17 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An one-off element that isn't one of the main elements we have dedicated classes
+  # for (like ChapterElement).  Provides a way to set an arbitrary +short_type+
+  #
   class Element < ElementBase
 
+    # Creates a new +Element+
+    #
+    # @param node [Nokogiri::XML::Node] the node this element wraps
+    # @param document [Document] this element's document
+    # @param short_type [Symbol, String] the type for this element
+    #
     def initialize(node:, document:, short_type: nil)
       super(node: node,
             document: document,

data/lib/kitchen/element_base.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 require 'securerandom'
 
 module Kitchen
-
   # Abstract base class for all elements.  If you are looking for a simple concrete
   # element class, use `Element`.
   #
@@ -10,35 +11,101 @@ module Kitchen
     extend Forwardable
     include Mixins::BlockErrorIf
 
+    # The element's document
+    # @return [Document]
     attr_reader :document
+
+    # The element's type, e.g. +:page+
+    # @return [Symbol, String]
     attr_reader :short_type
+
+    # The enumerator class for this element
+    # @return [Class]
     attr_reader :enumerator_class
-    attr_accessor :css_or_xpath_that_found_me
+
+    # The search query that located this element in the DOM
+    # @return [SearchQuery]
+    attr_accessor :search_query_that_found_me
 
     # @!method name
     #   Get the element name (the tag)
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#name-instance_method Nokogiri::XML::Node#name
+    #   @return [String]
     # @!method name=
     #   Set the element name (the tag)
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#name=-instance_method Nokogiri::XML::Node#name=
     # @!method []
     #   Get an element attribute
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#[]-instance_method Nokogiri::XML::Node#[]
+    #   @return [String]
     # @!method []=
     #   Set an element attribute
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#[]=-instance_method Nokogiri::XML::Node#[]=
     # @!method add_class
     #   Add a class to the element
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#add_class-instance_method Nokogiri::XML::Node#add_class
     # @!method remove_class
     #   Remove a class from the element
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#remove_class-instance_method Nokogiri::XML::Node#remove_class
+    # @!method text
+    #   Get the element text
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#text-instance_method Nokogiri::XML::Node#text
+    #   @return [String]
+    # @!method wrap
+    #   Add HTML around this element
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#wrap-instance_method Nokogiri::XML::Node#wrap
+    #   @return [Nokogiri::XML::Node]
+    # @!method children
+    #   Get the element's children
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#children-instance_method Nokogiri::XML::Node#children
+    #   @return [Nokogiri::XML::NodeSet]
+    # @!method to_html
+    #   Get the element as HTML
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#to_html-instance_method Nokogiri::XML::Node#to_html
+    #   @return [String]
+    # @!method remove_attribute
+    #   Removes an attribute from the element
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#remove_attribute-instance_method Nokogiri::XML::Node#remove_attribute
+    # @!method classes
+    #   Gets the element's classes
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#classes-instance_method Nokogiri::XML::Node#classes
+    #   @return [Array<String>]
+    # @!method path
+    #   Get the path for this element
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#path-instance_method Nokogiri::XML::Node#path
+    #   @return [String]
+    # @!method inner_html=
+    #   Set the inner HTML for this element
+    #   @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node#inner_html=-instance_method Nokogiri::XML::Node#inner_html=
+    #   @return Object
     def_delegators :@node, :name=, :name, :[], :[]=, :add_class, :remove_class,
-                           :text, :wrap, :children, :to_html, :remove_attribute,
-                           :classes, :path
+                   :text, :wrap, :children, :to_html, :remove_attribute,
+                   :classes, :path, :inner_html=
 
+    # @!method config
+    #   Get the config for this element's document
+    #   @return [Config]
     def_delegators :document, :config
+
+    # @!method selectors
+    #   Get the selectors for this element's document
+    #   @return [Selectors::Base]
     def_delegators :config, :selectors
 
+    # Creates a new instance
+    #
+    # @param node [Nokogiri::XML::Node] the wrapped element
+    # @param document [Document] the element's document
+    # @param enumerator_class [ElementEnumeratorBase] the enumerator that matches this element type
+    # @param short_type [Symbol, String] the type of this element
+    #
     def initialize(node:, document:, enumerator_class:, short_type: nil)
-      raise(ArgumentError, "node cannot be nil") if node.nil?
+      raise(ArgumentError, 'node cannot be nil') if node.nil?
+
       @node = node
 
-      raise(ArgumentError, "enumerator_class cannot be nil") if enumerator_class.nil?
+      raise(ArgumentError, 'enumerator_class cannot be nil') if enumerator_class.nil?
+
       @enumerator_class = enumerator_class
 
       @short_type = short_type || "unknown_type_#{SecureRandom.hex(4)}"
@@ -48,33 +115,57 @@ module Kitchen
         when Kitchen::Document
           document
         else
-          raise(ArgumentError, "`document` is not a known document type")
+          raise(ArgumentError, '`document` is not a known document type')
         end
 
       @ancestors = HashWithIndifferentAccess.new
-      @counts_in = HashWithIndifferentAccess.new
-      @css_or_xpath_that_has_been_counted = {}
+      @search_query_matches_that_have_been_counted = {}
       @is_a_clone = false
     end
 
-    def self.is_the_element_class_for?(node)
+    # Returns true if this class represents the element for the given node
+    #
+    # @param node [Nokogiri::XML::Node] the underlying node
+    # @return [Boolean]
+    #
+    def self.is_the_element_class_for?(_node)
       # override this in subclasses
       false
     end
 
+    # Returns true if this element has the given class
+    #
+    # @param klass [String] the class to test for
+    # @return [Boolean]
+    #
     def has_class?(klass)
-      (self[:class] || "").include?(klass)
+      (self[:class] || '').include?(klass)
     end
 
+    # Returns the element's ID
+    #
+    # @return [String]
+    #
     def id
       self[:id]
     end
 
+    # Sets the element's ID
+    #
+    # @param value [String] the new value for the ID
+    #
     def id=(value)
       self[:id] = value
     end
 
     # A way to set values and chain them
+    #
+    # @param property [String, Symbol] the name of the property to set
+    # @param value [String] the value to set
+    #
+    # @example
+    #   element.set(:name,"div").set("id","foo")
+    #
     def set(property, value)
       case property.to_sym
       when :name
@@ -85,18 +176,37 @@ module Kitchen
       self
     end
 
+    # Returns this element's ancestor of the given type
+    #
+    # @param type [String, Symbol] e.g. +:page+, +:term+
+    # @return [Ancestor]
+    # @raise [StandardError] if there is no ancestor of the given type
+    #
     def ancestor(type)
       @ancestors[type.to_sym]&.element || raise("No ancestor of type '#{type}'")
     end
 
+    # Returns true iff this element has an ancestor of the given type
+    #
+    # @param type [String, Symbol] e.g. +:page+, +:term+
+    # @return [Boolean]
+    #
     def has_ancestor?(type)
       @ancestors[type.to_sym].present?
     end
 
-    def ancestors
-      @ancestors
-    end
+    # Returns the element's ancestors
+    #
+    # @return [Array<Ancestor>]
+    #
+    attr_reader :ancestors
 
+    # Adds ancestors to this element, for each incrementing descendant counts for this type
+    #
+    # @param args [Array<Hash, Ancestor, Element, Document>] the ancestors
+    # @raise [StandardError] if there is already an ancestor with the one of
+    #   the given ancestors' types
+    #
     def add_ancestors(*args)
       args.each do |arg|
         case arg
@@ -112,50 +222,93 @@ module Kitchen
       end
     end
 
+    # Adds one ancestor, incrementing its descendant counts for this element type
+    #
+    # @param ancestor [Ancestor]
+    # @raise [StandardError] if there is already an ancestor with the given ancestor's type
+    #
     def add_ancestor(ancestor)
       if @ancestors[ancestor.type].present?
         raise "Trying to add an ancestor of type '#{ancestor.type}' but one of that " \
               "type is already present"
       end
 
+      ancestor.increment_descendant_count(short_type)
       @ancestors[ancestor.type] = ancestor
     end
 
+    # Return the elements in all of the ancestors
+    #
+    # @return [Array<ElementBase>]
+    #
     def ancestor_elements
       @ancestors.values.map(&:element)
     end
 
-    def count_as_descendant
-      @ancestors.each_pair do |type, ancestor|
-        @counts_in[type] = ancestor.increment_descendant_count(short_type)
-      end
-    end
-
+    # Returns the count of this element's type in the given ancestor type
+    #
+    # @param ancestor_type [String, Symbol]
+    #
     def count_in(ancestor_type)
-      @counts_in[ancestor_type] || raise("No ancestor of type '#{ancestor_type}'")
+      @ancestors[ancestor_type]&.get_descendant_count(short_type) ||
+        raise("No ancestor of type '#{ancestor_type}'")
     end
 
-    def remember_that_sub_elements_are_already_counted(css_or_xpath:, count:)
-      @css_or_xpath_that_has_been_counted[css_or_xpath] = count
-    end
-
-    def have_sub_elements_already_been_counted?(css_or_xpath)
-      number_of_sub_elements_already_counted(css_or_xpath) != 0
+    # Track that a sub element found by the given query has been counted
+    #
+    # @param search_query [SearchQuery] the search query matching the counted element
+    # @param type [String] the type of the sub element that was counted
+    #
+    def remember_that_a_sub_element_was_counted(search_query, type)
+      @search_query_matches_that_have_been_counted[search_query.to_s] ||= Hash.new(0)
+      @search_query_matches_that_have_been_counted[search_query.to_s][type] += 1
     end
 
-    def number_of_sub_elements_already_counted(css_or_xpath)
-      @css_or_xpath_that_has_been_counted[css_or_xpath] || 0
+    # Undo the counts from a prior search query (so that they can be counted again)
+    #
+    # @param search_query [SearchQuery] the prior search query whose counts need to be undone
+    #
+    def uncount(search_query)
+      @search_query_matches_that_have_been_counted.delete(search_query.to_s)&.each do |type, count|
+        ancestors.each_value do |ancestor|
+          ancestor.decrement_descendant_count(type, by: count)
+        end
+      end
     end
 
+    # Returns the search history that found this element
+    #
+    # @return [SearchHistory]
+    #
     def search_history
-      history = ancestor_elements.map(&:css_or_xpath_that_found_me) + [css_or_xpath_that_found_me]
-      history.compact.join(" ")
+      SearchHistory.new(
+        ancestor_elements.last&.search_history || SearchHistory.empty,
+        search_query_that_found_me
+      )
     end
 
-    def search(*selector_or_xpath_args)
+    # Returns an ElementEnumerator that iterates over the provided selector or xpath queries
+    #
+    # @param selector_or_xpath_args [Array<String>] Selector or XPath queries
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    # @return [ElementEnumerator]
+    #
+    def search(*selector_or_xpath_args, only: nil, except: nil)
       block_error_if(block_given?)
 
-      ElementEnumerator.factory.build_within(self, css_or_xpath: selector_or_xpath_args)
+      ElementEnumerator.factory.build_within(
+        self,
+        search_query: SearchQuery.new(
+          css_or_xpath: selector_or_xpath_args,
+          only: only,
+          except: except
+        )
+      )
     end
 
     # Yields and returns the first child element that matches the provided
@@ -185,16 +338,32 @@ module Kitchen
       end
     end
 
+    # @!method at
+    #   @see first
     alias_method :at, :first
 
-    def element_children()
+    # Returns an enumerator over the direct child elements of this element, with the
+    # specific type (e.g. +TermElement+) if such type is available.
+    #
+    # @return [TypeCastingElementEnumerator]
+    #
+    def element_children
       block_error_if(block_given?)
-      TypeCastingElementEnumerator.factory.build_within(self, css_or_xpath: "./*")
+      TypeCastingElementEnumerator.factory.build_within(
+        self,
+        search_query: SearchQuery.new(css_or_xpath: './*')
+      )
     end
 
+    # Searches for elements handled by a list of enumerator classes.  All element that
+    # matches one of those enumerator classes are iterated over.
+    #
+    # @param enumerator_classes [Array<ElementEnumeratorBase>]
+    # @return [TypeCastingElementEnumerator]
+    #
     def search_with(*enumerator_classes)
       block_error_if(block_given?)
-      raise "must supply at least one enumerator class" if enumerator_classes.empty?
+      raise 'must supply at least one enumerator class' if enumerator_classes.empty?
 
       factory = enumerator_classes[0].factory
       enumerator_classes[1..-1].each do |enumerator_class|
@@ -232,6 +401,7 @@ module Kitchen
       the_copy = clone
       the_copy.raw.traverse do |node|
         next if node.text? || node.document?
+
         document.record_id_copied(node[:id])
       end
       clipboard(to).add(the_copy) if to.present?
@@ -247,6 +417,7 @@ module Kitchen
       temp_copy = clone
       temp_copy.raw.traverse do |node|
         next if node.text? || node.document?
+
         node[:id] = document.modified_id_to_paste(node[:id]) unless node[:id].blank?
       end
       temp_copy.to_s
@@ -263,20 +434,19 @@ module Kitchen
       Element.new(node: raw.parent, document: document, short_type: "parent(#{short_type})")
     end
 
-    # TODO make it clear if all of these methods take Element, Node, or String
+    # TODO: make it clear if all of these methods take Element, Node, or String
 
     # If child argument given, prepends it before the element's current children.
     # If sibling is given, prepends it as a sibling to this element.
     #
     # @param child [String] the child to prepend
     # @param sibling [String] the sibling to prepend
+    # @raise [RecipeError] if specify other than just a child or a sibling
     #
     def prepend(child: nil, sibling: nil)
-      if child && sibling
-        raise RecipeError, "Only one of `child` or `sibling` can be specified"
-      elsif !child && !sibling
-        raise RecipeError, "One of `child` or `sibling` must be specified"
-      elsif child
+      require_one_of_child_or_sibling(child, sibling)
+
+      if child
         if node.children.empty?
           node.children = child.to_s
         else
@@ -285,6 +455,7 @@ module Kitchen
       else
         node.add_previous_sibling(sibling)
       end
+
       self
     end
 
@@ -293,13 +464,12 @@ module Kitchen
     #
     # @param child [String] the child to append
     # @param sibling [String] the sibling to append
+    # @raise [RecipeError] if specify other than just a child or a sibling
     #
     def append(child: nil, sibling: nil)
-      if child && sibling
-        raise RecipeError, "Only one of `child` or `sibling` can be specified"
-      elsif !child && !sibling
-        raise RecipeError, "One of `child` or `sibling` must be specified"
-      elsif child
+      require_one_of_child_or_sibling(child, sibling)
+
+      if child
         if node.children.empty?
           node.children = child.to_s
         else
@@ -308,6 +478,7 @@ module Kitchen
       else
         node.next = sibling
       end
+
       self
     end
 
@@ -320,7 +491,7 @@ module Kitchen
       self
     end
 
-    # TODO methods like replace_children that take string, either forbid or handle Element/Node args
+    # TODO: methods like replace_children that take string, either forbid or handle Element/Node args
 
     # Get the content of children matching the provided selector.  Mostly
     # useful when there is one child with text you want to extract.
@@ -350,11 +521,19 @@ module Kitchen
     # @return [String] the sub header tag name
     #
     def sub_header_name
-      first_header = node.search("h1, h2, h3, h4, h5, h6").first
+      first_header = node.search('h1, h2, h3, h4, h5, h6').first
+
+      if first_header.nil?
+        'h1'
+      else
+        first_header.name.gsub(/\d/) { |num| (num.to_i + 1).to_s }
+      end
+    end
 
-      first_header.nil? ?
-        "h1" :
-        first_header.name.gsub(/\d/) {|num| (num.to_i + 1).to_s}
+    # Mark the location so that if there's an error we can show the developer where.
+    #
+    def mark_as_current_location!
+      document.location = self
     end
 
     # Returns the underlying Nokogiri object
@@ -365,22 +544,40 @@ module Kitchen
       node
     end
 
+    # Returns a string version of this element
+    #
+    # @return [String]
+    #
     def inspect
       to_s
     end
 
+    # Returns a string version of this element
+    #
+    # @return [String]
+    #
     def to_s
       remove_default_namespaces_if_clone(node.to_s)
     end
 
+    # Returns a string version of this element as XML
+    #
+    # @return [String]
+    #
     def to_xml
       remove_default_namespaces_if_clone(node.to_xml)
     end
 
+    # Returns a string version of this element as XHTML
+    #
+    # @return [String]
+    #
     def to_xhtml
       remove_default_namespaces_if_clone(node.to_xhtml)
     end
 
+    # Returns a clone of this object
+    #
     def clone
       super.tap do |element|
         # When we call dup, the dup gets a bunch of default namespace stuff that
@@ -409,17 +606,32 @@ module Kitchen
 
     # @!method pages
     #   Returns a pages enumerator
-    def_delegators :as_enumerator, :pages, :chapters, :terms, :figures, :notes, :tables, :examples
+    def_delegators :as_enumerator, :pages, :chapters, :terms, :figures, :notes, :tables, :examples,
+                   :metadatas, :units
 
+    # Returns this element as an enumerator (over only one element, itself)
+    #
+    # @return [ElementEnumeratorBase] (actually returns the appropriate enumerator class for this element)
+    #
     def as_enumerator
-      enumerator_class.new(css_or_xpath: css_or_xpath_that_found_me) {|block| block.yield(self)}
+      enumerator_class.new(search_query: search_query_that_found_me) { |block| block.yield(self) }
     end
 
     protected
 
+    # The wrapped Nokogiri node
+    # @return [Nokogiri::XML::Node] the node
     attr_accessor :node
+
+    # If this element is a clone
+    # @return [Boolean]
     attr_accessor :is_a_clone
 
+    # Return a clipboard
+    #
+    # @param name_or_object [String, Clipboard] the name of the clipboard or the clipboard itself
+    # @return [Clipboard]
+    #
     def clipboard(name_or_object)
       case name_or_object
       when Symbol
@@ -427,18 +639,26 @@ module Kitchen
       when Clipboard
         name_or_object
       else
-        raise ArgumentError, "The provided argument (#{name_or_object}) is not "
+        raise ArgumentError, "The provided argument (#{name_or_object}) is not " \
                              "a clipboard name or a clipboard"
       end
     end
 
+    # Clean up some default namespace junk for cloned elements
+    #
+    # @param string [String] the string to clean
     def remove_default_namespaces_if_clone(string)
       if is_a_clone
-        string.gsub("xmlns:default=\"http://www.w3.org/1999/xhtml\"","").gsub("default:","")
+        string.gsub('xmlns:default="http://www.w3.org/1999/xhtml"', '').gsub('default:', '')
       else
         string
       end
     end
 
+    def require_one_of_child_or_sibling(child, sibling)
+      raise RecipeError, 'Only one of `child` or `sibling` can be specified' if child && sibling
+      raise RecipeError, 'One of `child` or `sibling` must be specified' if !child && !sibling
+    end
+
   end
 end