metanorma-iso 1.0.0

data/lib/asciidoctor/iso/section.rb

@@ -0,0 +1,72 @@
+require "htmlentities"
+require "uri"
+
+module Asciidoctor
+  module ISO
+    class Converter < Standoc::Converter
+      def section(node)
+        a = { id: Standoc::Utils::anchor_or_uuid(node) }
+        noko do |xml|
+          case sectiontype(node)
+          when "introduction" then
+            if node.level == 1 then introduction_parse(a, xml, node)
+            else
+              clause_parse(a, xml, node)
+            end
+          when "patent notice" then patent_notice_parse(xml, node)
+          when "scope" then scope_parse(a, xml, node)
+          when "normative references" then norm_ref_parse(a, xml, node)
+          when "terms and definitions",
+            "terms, definitions, symbols and abbreviated terms",
+            "terms, definitions, symbols and abbreviations",
+            "terms, definitions and symbols",
+            "terms, definitions and abbreviations",
+            "terms, definitions and abbreviated terms"
+            @term_def = true
+            term_def_parse(a, xml, node, true)
+            @term_def = false
+          when "symbols and abbreviated terms"
+            symbols_parse(a, xml, node)
+          when "bibliography" then bibliography_parse(a, xml, node)
+          else
+            if @term_def then term_def_subclause_parse(a, xml, node)
+            elsif @biblio then bibliography_parse(a, xml, node)
+            elsif node.attr("style") == "bibliography" && node.level == 1
+              bibliography_parse(a, xml, node)
+            elsif node.attr("style") == "appendix" && node.level == 1
+              annex_parse(a, xml, node)
+            elsif node.option? "appendix"
+              appendix_parse(a, xml, node)
+            else
+              clause_parse(a, xml, node)
+            end
+          end
+        end.join("\n")
+      end
+
+      def appendix_parse(attrs, xml, node)
+        attrs["inline-header".to_sym] = node.option? "inline-header"
+        set_obligation(attrs, node)
+        xml.appendix **attr_code(attrs) do |xml_section|
+          xml_section.title { |name| name << node.title }
+          xml_section << node.content
+        end
+      end
+
+      def patent_notice_parse(xml, node)
+        # xml.patent_notice do |xml_section|
+        #  xml_section << node.content
+        # end
+        xml << node.content
+      end
+
+      def scope_parse(attrs, xml, node)
+        xml.clause **attr_code(attrs) do |xml_section|
+          xml_section.title { |t| t << "Scope" }
+          content = node.content
+          xml_section << content
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/iso/validate.rb

@@ -0,0 +1,190 @@
+require "metanorma-standoc"
+require_relative "./validate_style.rb"
+require_relative "./validate_requirements.rb"
+require_relative "./validate_section.rb"
+require "nokogiri"
+require "jing"
+require "pp"
+require "iev"
+
+module Asciidoctor
+  module ISO
+    class Converter < Standoc::Converter
+      def title_intro_validate(root)
+        title_intro_en = root.at("//title-intro[@language='en']")
+        title_intro_fr = root.at("//title-intro[@language='fr']")
+        if title_intro_en.nil? && !title_intro_fr.nil?
+          warn "No English Title Intro!"
+        end
+        if !title_intro_en.nil? && title_intro_fr.nil?
+          warn "No French Title Intro!"
+        end
+      end
+
+      def title_main_validate(root)
+        title_main_en = root.at("//title-main[@language='en']")
+        title_main_fr = root.at("//title-main[@language='fr']")
+        if title_main_en.nil? && !title_main_fr.nil?
+          warn "No English Title!"
+        end
+        if !title_main_en.nil? && title_main_fr.nil?
+          warn "No French Title!"
+        end
+      end
+
+      def title_part_validate(root)
+        title_part_en = root.at("//title-part[@language='en']")
+        title_part_fr = root.at("//title-part[@language='fr']")
+        (title_part_en.nil? && !title_part_fr.nil?) &&
+          warn("No English Title Part!")
+        (!title_part_en.nil? && title_part_fr.nil?) &&
+          warn("No French Title Part!")
+      end
+
+      def title_subpart_validate(root)
+        subpart = root.at("//bibdata/docidentifier/project-number[@subpart]")
+        iec = root.at("//bibdata/contributor[role/@type = 'publisher']/"\
+                      "organization[abbreviation = 'IEC' or "\
+                      "name = 'International Electrotechnical Commission']")
+        warn("Subpart defined on non-IEC document!") if subpart && !iec
+      end
+
+      def title_names_type_validate(root)
+        doctypes = /International\sStandard | Technical\sSpecification |
+        Publicly\sAvailable\sSpecification | Technical\sReport | Guide /xi
+        title_main_en = root.at("//title-main[@language='en']")
+        if !title_main_en.nil? && doctypes.match(title_main_en.text)
+          warn "Main Title may name document type"
+        end
+        title_intro_en = root.at("//title-intro[@language='en']")
+        if !title_intro_en.nil? && doctypes.match(title_intro_en.text)
+          warn "Title Intro may name document type"
+        end
+      end
+
+      def title_first_level_validate(root)
+        root.xpath(SECTIONS_XPATH).each do |s|
+          title = s&.at("./title")&.text || s.name
+          s.xpath("./clause | ./terms | ./references").each do |ss|
+            subtitle = ss.at("./title")
+            !subtitle.nil? && !subtitle&.text&.empty? ||
+              warn("#{title}: each first-level subclause must have a title")
+      end
+    end
+  end
+
+  def title_all_siblings(xpath, label)
+    notitle = false
+    withtitle = false
+    xpath.each do |s|
+      title_all_siblings(s.xpath("./clause | ./terms | ./references"),
+                         s&.at("./title")&.text || s["id"])
+      subtitle = s.at("./title")
+      notitle = notitle || (!subtitle || subtitle.text.empty?)
+      withtitle = withtitle || (subtitle && !subtitle.text.empty?)
+    end
+    notitle && withtitle &&
+      warn("#{label}: all subclauses must have a title, or none")
+  end
+
+  def title_validate(root)
+    title_intro_validate(root)
+    title_main_validate(root)
+    title_part_validate(root)
+    title_subpart_validate(root)
+    title_names_type_validate(root)
+    title_first_level_validate(root)
+    title_all_siblings(root.xpath(SECTIONS_XPATH), "(top level)")
+  end
+
+  def onlychild_clause_validate(root)
+    root.xpath(Standoc::Utils::SUBCLAUSE_XPATH).each do |c|
+      next unless c.xpath("../clause").size == 1
+      title = c.at("./title")
+      location = c["id"] || c.text[0..60] + "..."
+      location += ":#{title.text}" if c["id"] && !title.nil?
+      warn "ISO style: #{location}: subclause is only child"
+    end
+  end
+
+  def isosubgroup_validate(root)
+    root.xpath("//technical-committee/@type").each do |t|
+      unless %w{TC PC JTC JPC}.include? t.text
+        warn "ISO: invalid technical committee type #{t}"
+      end
+    end
+    root.xpath("//subcommittee/@type").each do |t|
+      unless %w{SC JSC}.include? t.text
+        warn "ISO: invalid subcommittee type #{t}"
+      end
+    end
+  end
+
+  def see_xrefs_validate(root)
+    root.xpath("//xref").each do |t|
+      # does not deal with preceding text marked up
+      preceding = t.at("./preceding-sibling::text()[last()]")
+      next unless !preceding.nil? && /\bsee\s*$/mi.match(preceding)
+      (target = root.at("//*[@id = '#{t['target']}']")) || next
+      if target&.at("./ancestor-or-self::*[@obligation = 'normative']")
+        warn "ISO: 'see #{t['target']}' is pointing to a normative section"
+      end
+    end
+  end
+
+  def see_erefs_validate(root)
+    root.xpath("//eref").each do |t|
+      preceding = t.at("./preceding-sibling::text()[last()]")
+      next unless !preceding.nil? && /\bsee\s*$/mi.match(preceding)
+      target = root.at("//*[@id = '#{t['bibitemid']}']")
+      if target.at("./ancestor::references"\
+          "[title = 'Normative References']")
+        warn "ISO: 'see #{t}' is pointing to a normative reference"
+      end
+    end
+  end
+
+  def locality_erefs_validate(root)
+    root.xpath("//eref[locality]").each do |t|
+      unless /:[ ]?\d+{4}$/.match t["citeas"]
+        warn "ISO: undated reference #{t['citeas']} should not contain "\
+          "specific elements"
+      end
+    end
+  end
+
+  def termdef_warn(text, re, term, msg)
+    re.match(text) && warn("ISO style: #{term}: #{msg}")
+  end
+
+  def termdef_style(xmldoc)
+    xmldoc.xpath("//term").each do |t|
+      para = t.at("./definition") || return
+      term = t.at("./preferred").text
+      termdef_warn(para.text, /^(the|a)\b/i, term,
+                   "term definition starts with article")
+      termdef_warn(para.text, /\.$/i, term,
+                   "term definition ends with period")
+    end
+  end
+
+  def content_validate(doc)
+    super
+    title_validate(doc.root)
+    isosubgroup_validate(doc.root)
+    onlychild_clause_validate(doc.root)
+    termdef_style(doc.root)
+    iev_validate(doc.root)
+    see_xrefs_validate(doc.root)
+    see_erefs_validate(doc.root)
+    locality_erefs_validate(doc.root)
+  end
+
+  def validate(doc)
+    content_validate(doc)
+    schema_validate(formattedstr_strip(doc.dup),
+                    File.join(File.dirname(__FILE__), "isostandard.rng"))
+  end
+    end
+  end
+end

data/lib/asciidoctor/iso/validate_requirements.rb

@@ -0,0 +1,105 @@
+require "metanorma-standoc"
+require "nokogiri"
+require "pp"
+
+module Asciidoctor
+  module ISO
+    class Converter < Standoc::Converter
+      REQUIREMENT_RE_STR = <<~REGEXP.freeze
+        \\b
+         ( shall | (is|are)_to |
+           (is|are)_required_(not_)?to |
+           (is|are)_required_that |
+           has_to |
+           only\\b[^.,]+\\b(is|are)_permitted |
+           it_is_necessary |
+           (is|are)_not_(allowed | permitted |
+                         acceptable | permissible) |
+           (is|are)_not_to_be |
+           do_not )
+        \\b
+      REGEXP
+      REQUIREMENT_RE =
+        Regexp.new(REQUIREMENT_RE_STR.gsub(/\s/, "").gsub(/_/, "\\s"),
+                   Regexp::IGNORECASE)
+
+      def requirement(text)
+        text.split(/\.\s+/).each do |t|
+          return t if REQUIREMENT_RE.match t
+        end
+        nil
+      end
+
+      RECOMMENDATION_RE_STR = <<~REGEXP.freeze
+        \\b
+            should |
+            ought_(not_)?to |
+            it_is_(not_)?recommended_that
+        \\b
+      REGEXP
+      RECOMMENDATION_RE =
+        Regexp.new(RECOMMENDATION_RE_STR.gsub(/\s/, "").gsub(/_/, "\\s"),
+                   Regexp::IGNORECASE)
+
+      def recommendation(text)
+        text.split(/\.\s+/).each do |t|
+          return t if RECOMMENDATION_RE.match t
+        end
+        nil
+      end
+
+      PERMISSION_RE_STR = <<~REGEXP.freeze
+        \\b
+             may |
+            (is|are)_(permitted | allowed | permissible ) |
+            it_is_not_required_that |
+            no\\b[^.,]+\\b(is|are)_required
+        \\b
+      REGEXP
+      PERMISSION_RE =
+        Regexp.new(PERMISSION_RE_STR.gsub(/\s/, "").gsub(/_/, "\\s"),
+                   Regexp::IGNORECASE)
+
+      def permission(text)
+        text.split(/\.\s+/).each do |t|
+          return t if PERMISSION_RE.match t
+        end
+        nil
+      end
+
+      POSSIBILITY_RE_STR = <<~REGEXP.freeze
+        \\b
+           can | cannot | be_able_to |
+           there_is_a_possibility_of |
+           it_is_possible_to | be_unable_to |
+           there_is_no_possibility_of |
+           it_is_not_possible_to
+        \\b
+      REGEXP
+      POSSIBILITY_RE =
+        Regexp.new(POSSIBILITY_RE_STR.gsub(/\s/, "").gsub(/_/, "\\s"),
+                   Regexp::IGNORECASE)
+
+      def possibility(text)
+        text.split(/\.\s+/).each { |t| return t if POSSIBILITY_RE.match t }
+        nil
+      end
+
+      def external_constraint(text)
+        text.split(/\.\s+/).each do |t|
+          return t if /\b(must)\b/xi.match t
+        end
+        nil
+      end
+
+      def style_no_guidance(node, text, docpart)
+        r = requirement(text)
+        style_warning(node, "#{docpart} may contain requirement", r) if r
+        r = permission(text)
+        style_warning(node, "#{docpart} may contain permission", r) if r
+        r = recommendation(text)
+        style_warning(node, "#{docpart} may contain recommendation", r) if r
+      end
+    end
+  end
+end

data/lib/asciidoctor/iso/validate_section.rb

@@ -0,0 +1,214 @@
+require "nokogiri"
+
+module Asciidoctor
+  module ISO
+    class Converter < Standoc::Converter
+      def section_validate(doc)
+        foreword_validate(doc.root)
+        normref_validate(doc.root)
+        symbols_validate(doc.root)
+        sections_sequence_validate(doc.root)
+        section_style(doc.root)
+        subclause_validate(doc.root)
+        super
+      end
+
+      def foreword_validate(root)
+        f = root.at("//foreword") || return
+        s = f.at("./clause")
+        warn "ISO style: foreword contains subclauses" unless s.nil?
+      end
+
+      def normref_validate(root)
+        f = root.at("//references[title = 'Normative References']") || return
+        f.at("./references | ./clause") &&
+          warn("ISO style: normative references contains subclauses")
+      end
+
+      ONE_SYMBOLS_WARNING = "ISO style: only one Symbols and Abbreviated "\
+        "Terms section in the standard".freeze
+
+      NON_DL_SYMBOLS_WARNING = "ISO style: Symbols and Abbreviated Terms can "\
+        "only contain a definition list".freeze
+
+      def symbols_validate(root)
+        f = root.xpath("//definitions")
+        f.empty? && return
+        (f.size == 1) || warn(ONE_SYMBOLS_WARNING)
+        f.first.elements.each do |e|
+          unless e.name == "dl"
+            warn(NON_DL_SYMBOLS_WARNING)
+            return
+          end
+        end
+      end
+
+      def seqcheck(names, msg, accepted)
+        n = names.shift
+        unless accepted.include? n
+          warn "ISO style: #{msg}"
+          names = []
+        end
+        names
+      end
+
+      # spec of permissible section sequence
+      # we skip normative references, it goes to end of list
+      SEQ =
+        [
+          {
+            msg: "Initial section must be (content) Foreword",
+            val:  [{ tag: "foreword", title: "Foreword" }],
+          },
+          {
+            msg: "Prefatory material must be followed by (clause) Scope",
+            val:  [{ tag: "introduction", title: "Introduction" },
+                   { tag: "clause", title: "Scope" }],
+          },
+          {
+            msg: "Prefatory material must be followed by (clause) Scope",
+            val: [{ tag: "clause", title: "Scope" }],
+          },
+          {
+            msg: "Normative References must be followed by "\
+            "Terms and Definitions",
+            val: [
+              { tag: "terms", title: "Terms and definitions" },
+              { tag: "clause", title: "Terms and definitions" },
+              {
+                tag: "terms",
+                title: "Terms, definitions, symbols and abbreviated terms",
+              },
+              {
+                tag: "clause",
+                title: "Terms, definitions, symbols and abbreviated terms",
+              },
+            ],
+          },
+      ].freeze
+
+      SECTIONS_XPATH =
+        "//foreword | //introduction | //sections/terms | .//annex | "\
+        "//sections/definitions | //sections/clause | //references[not(parent::clause)] | "\
+        "//clause[descendant::references][not(parent::clause)]".freeze
+
+      def sections_sequence_validate(root)
+        f = root.xpath(SECTIONS_XPATH)
+        names = f.map { |s| { tag: s.name, title: s&.at("./title")&.text } }
+        names = seqcheck(names, SEQ[0][:msg], SEQ[0][:val]) || return
+        n = names[0]
+        names = seqcheck(names, SEQ[1][:msg], SEQ[1][:val]) || return
+        if n == { tag: "introduction", title: "Introduction" }
+          names = seqcheck(names, SEQ[2][:msg], SEQ[2][:val]) || return
+        end
+        names = seqcheck(names, SEQ[3][:msg], SEQ[3][:val]) || return
+        n = names.shift
+        if n == { tag: "definitions", title: nil }
+          n = names.shift || return
+        end
+        unless n
+          warn "ISO style: Document must contain at least one clause"
+          return
+        end
+        n[:tag] == "clause" ||
+          warn("ISO style: Document must contain clause after "\
+               "Terms and Definitions")
+        n == { tag: "clause", title: "Scope" } &&
+          warn("ISO style: Scope must occur before Terms and Definitions")
+        n = names.shift || return
+        while n[:tag] == "clause"
+          n[:title] == "Scope" &&
+            warn("ISO style: Scope must occur before Terms and Definitions")
+          n = names.shift || return
+        end
+        unless n[:tag] == "annex" || n[:tag] == "references"
+          warn "ISO style: Only annexes and references can follow clauses"
+        end
+        while n[:tag] == "annex"
+          n = names.shift
+          if n.nil?
+            warn("ISO style: Document must include (references) "\
+                 "Normative References")
+            return
+          end
+        end
+        n == { tag: "references", title: "Normative References" } ||
+          warn("ISO style: Document must include (references) "\
+               "Normative References")
+        n = names.shift
+        n == { tag: "references", title: "Bibliography" } ||
+          warn("ISO style: Final section must be (references) Bibliography")
+        names.empty? ||
+          warn("ISO style: There are sections after the final Bibliography")
+      end
+
+      def style_warning(node, msg, text)
+        return if @novalid
+        w = "ISO style: WARNING (#{Standoc::Utils::current_location(node)}): #{msg}"
+        w += ": #{text}" if text
+        warn w
+      end
+
+      NORM_ISO_WARN = "non-ISO/IEC reference not expected as normative".freeze
+      SCOPE_WARN = "Scope contains subclauses: should be succint".freeze
+
+      def section_style(root)
+        foreword_style(root.at("//foreword"))
+        introduction_style(root.at("//introduction"))
+        scope_style(root.at("//clause[title = 'Scope']"))
+        scope = root.at("//clause[title = 'Scope']/clause")
+        scope.nil? || style_warning(scope, SCOPE_WARN, nil)
+      end
+
+      def sourcecode_style(root)
+        root.xpath("//sourcecode").each do |x|
+          callouts = x.elements.select { |e| e.name == "callout" }
+          annotations = x.elements.select { |e| e.name == "annotation" }
+          if callouts.size != annotations.size
+            warn "#{x['id']}: mismatch of callouts and annotations"
+          end
+        end
+      end
+
+      ASSETS_TO_STYLE =
+        "//termsource | //formula | //termnote | //p | //li[not(p)] | "\
+        "//dt | //dd[not(p)] | //td[not(p)] | //th[not(p)]".freeze
+
+      NORM_BIBITEMS =
+        "//references[title = 'Normative References']/bibitem".freeze
+
+      def asset_title_style(root)
+        root.xpath("//figure[image][not(title)]").each do |node|
+          style_warning(node, "Figure should have title", nil)
+        end
+        root.xpath("//table[not(title)]").each do |node|
+          style_warning(node, "Table should have title", nil)
+        end
+      end
+
+      def norm_bibitem_style(root)
+        root.xpath(NORM_BIBITEMS).each do |b|
+          if b.at(Standoc::Converter::ISO_PUBLISHER_XPATH).nil?
+            Standoc::Utils::warning(b, NORM_ISO_WARN, b.text)
+          end
+        end
+      end
+
+      def asset_style(root)
+        root.xpath("//example | //termexample").each { |e| example_style(e) }
+        root.xpath("//definition").each { |e| definition_style(e) }
+        root.xpath("//note").each { |e| note_style(e) }
+        root.xpath("//fn").each { |e| footnote_style(e) }
+        root.xpath(ASSETS_TO_STYLE).each { |e| style(e, extract_text(e)) }
+        norm_bibitem_style(root)
+        super
+      end
+
+      def subclause_validate(root)
+        root.xpath("//clause/clause/clause/clause/clause/clause/clause/clause").each do |c|
+          style_warning(c, "Exceeds the maximum clause depth of 7", nil)
+        end
+      end
+    end
+  end
+end