RubyGems - asciidoctor-iso - Versions diffs - 0.6.1 → 0.7.0 - Mend

asciidoctor-iso 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

checksums.yaml +4 -4
data/.gitattributes +2 -0
data/.travis.yml +5 -0
data/Gemfile.lock +12 -10
data/README.adoc +113 -16
data/bin/rspec +18 -0
data/lib/asciidoctor/iso/base.rb +30 -28
data/lib/asciidoctor/iso/blocks.rb +33 -33
data/lib/asciidoctor/iso/cleanup.rb +79 -33
data/lib/asciidoctor/iso/cleanup_block.rb +71 -18
data/lib/asciidoctor/iso/cleanup_ref.rb +35 -30
data/lib/asciidoctor/iso/converter.rb +0 -3
data/lib/asciidoctor/iso/front.rb +29 -16
data/lib/asciidoctor/iso/html/isodoc.css +34 -0
data/lib/asciidoctor/iso/html/wordstyle.css +138 -6
data/lib/asciidoctor/iso/inline.rb +10 -22
data/lib/asciidoctor/iso/isodoc.rng +66 -16
data/lib/asciidoctor/iso/isostandard.rng +129 -15
data/lib/asciidoctor/iso/lists.rb +49 -42
data/lib/asciidoctor/iso/macros.rb +12 -8
data/lib/asciidoctor/iso/section.rb +53 -37
data/lib/asciidoctor/iso/table.rb +9 -1
data/lib/asciidoctor/iso/utils.rb +18 -13
data/lib/asciidoctor/iso/validate.rb +100 -24
data/lib/asciidoctor/iso/validate_requirements.rb +106 -0
data/lib/asciidoctor/iso/validate_section.rb +85 -65
data/lib/asciidoctor/iso/validate_style.rb +68 -115
data/lib/asciidoctor/iso/version.rb +1 -1
data/spec/asciidoctor-iso/base_spec.rb +193 -0
data/spec/asciidoctor-iso/blocks_spec.rb +426 -0
data/spec/asciidoctor-iso/cleanup_spec.rb +687 -0
data/spec/asciidoctor-iso/inline_spec.rb +159 -0
data/spec/asciidoctor-iso/lists_spec.rb +189 -0
data/spec/asciidoctor-iso/macros_spec.rb +20 -0
data/spec/asciidoctor-iso/refs_spec.rb +194 -0
data/spec/asciidoctor-iso/section_spec.rb +301 -0
data/spec/asciidoctor-iso/table_spec.rb +307 -0
data/spec/asciidoctor-iso/validate_spec.rb +749 -0
data/spec/examples/english.yaml +69 -0
data/spec/examples/rice.adoc +30 -28
data/spec/examples/rice.doc +3035 -2865
data/spec/examples/rice.html +281 -234
data/spec/examples/rice.preview.html +30 -20
data/spec/examples/rice.xml +250 -282
data/spec/spec_helper.rb +87 -0
metadata +17 -2

data/lib/asciidoctor/iso/table.rb CHANGED

@@ -10,10 +10,10 @@ module Asciidoctor
         @table_fn_number = "a"
         noko do |xml|
           xml.table **attr_code(table_attrs(node)) do |xml_table|
+            table_name(node, xml_table)
             %i(head body foot).reject do |tblsec|
               node.rows[tblsec].empty?
             end
-            xml_table.name node.title if node.title?
             table_head_body_and_foot node, xml_table
           end
         end
@@ -21,6 +21,14 @@ module Asciidoctor
       private
+      def table_name(node, xml_table)
+        if node.title?
+          xml_table.name node.title
+        else
+          style_warning(node, "Table should have title", nil)
+        end
+      end
       def table_cell1(cell, thd)
         if cell.style == :asciidoc
           thd << cell.content

data/lib/asciidoctor/iso/utils.rb CHANGED

@@ -24,18 +24,33 @@ module Asciidoctor
               (!n.respond_to?(:level) || n.level.positive?) &&
               (!n.respond_to?(:context) || n.context != :section)
             n = n.parent
-            return "Section: #{n.title}" if !n.nil? && n.context == :section
+            return "Section: #{n.title}" if n&.respond_to?(:context) &&
+              n&.context == :section
           end
           "??"
         end
         def warning(node, msg, text)
+          return if @novalid
           warntext = "asciidoctor: WARNING"\
             "(#{current_location(node)}): #{msg}"
           warntext += ": #{text}" if text
           warn warntext
         end
+        def flatten_rawtext_lines(node, result)
+          node.lines.each do |x|
+            if node.respond_to?(:context) && (node.context == :literal ||
+                node.context == :listing)
+              result << x.gsub(/</, "&lt;").gsub(/>/, "&gt;")
+            else
+              # strip not only HTML <tag>, and Asciidoc xrefs <<xref>>
+              result << x.gsub(/<[^>]*>+/, "")
+            end
+          end
+          result
+        end
         # if node contains blocks, flatten them into a single line;
         # and extract only raw text
         def flatten_rawtext(node)
@@ -43,16 +58,7 @@ module Asciidoctor
           if node.respond_to?(:blocks) && node.blocks?
             node.blocks.each { |b| result << flatten_rawtext(b) }
           elsif node.respond_to?(:lines)
-            node.lines.each do |x|
-              if node.respond_to?(:context) && (node.context == :literal ||
-                  node.context == :listing)
-                result << x.gsub(/</, "&lt;").gsub(/>/, "&gt;")
-              else
-                # strip not only HTML tags <tag>,
-                # but also Asciidoc crossreferences <<xref>>
-                result << x.gsub(/<[^>]*>+/, "")
-              end
-            end
+            result = flatten_rawtext_lines(node, result)
           elsif node.respond_to?(:text)
             result << node.text.gsub(/<[^>]*>+/, "")
           else
@@ -71,7 +77,7 @@ module Asciidoctor
         nil
       end
-      NOKOHEAD = <<~HERE
+      NOKOHEAD = <<~HERE.freeze
           <!DOCTYPE html SYSTEM
           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
           <html xmlns="http://www.w3.org/1999/xhtml">
@@ -105,7 +111,6 @@ module Asciidoctor
           out.p { |p| p << node.content }
         end
       end
     end
   end
 end

data/lib/asciidoctor/iso/validate.rb CHANGED

@@ -1,5 +1,6 @@
 require "asciidoctor/iso/utils"
 require_relative "./validate_style.rb"
+require_relative "./validate_requirements.rb"
 require_relative "./validate_section.rb"
 require "nokogiri"
 require "jing"
@@ -19,39 +20,83 @@ module Asciidoctor
         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']")
-        if title_part_en.nil? && !title_part_fr.nil?
-          warn "No English Title Part!"
-        end
-        if !title_part_en.nil? && title_part_fr.nil?
-          warn "No French Title Part!"
-        end
+        (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[name = 'IEC']")
+        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 doctypes.match? title_main_en.text
+        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 "Part Title may name document type"
+          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("./subsection | ./terms").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|
+          sublabel = s&.at("./title")&.text || s["id"]
+          title_all_siblings(s.xpath("./subsection | ./terms"), sublabel)
+          subtitle = s.at("./title")
+          notitle = notitle || (!subtitle || subtitle.text.empty?)
+          withtitle = withtitle || !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)
-        q = "//subsection"
-        root.xpath(q).each do |c|
+        root.xpath("//subsection").each do |c|
           next unless c.xpath("../subsection").size == 1
           title = c.at("./title")
           location = c["id"] || c.text[0..60] + "..."
@@ -60,13 +105,6 @@ module Asciidoctor
         end
       end
-      def iso8601_validate(root)
-        root.xpath("//review/@date | //revision-date").each do |d|
-          /^\d{8}(T\d{4,6})?$/.match? d.text or
-            warn "ISO style: #{d.text} is not an ISO 8601 date"
-        end
-      end
       def isosubgroup_validate(root)
         root.xpath("//technical-committee/@type").each do |t|
           unless %w{TC PC JTC JPC}.include? t.text
@@ -80,15 +118,53 @@ module Asciidoctor
         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 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)
         title_validate(doc.root)
         isosubgroup_validate(doc.root)
-        foreword_validate(doc.root)
-        normref_validate(doc.root)
-        symbols_validate(doc.root)
-        iso8601_validate(doc.root)
+        section_validate(doc)
         onlychild_clause_validate(doc.root)
-        sections_sequence_validate(doc.root)
+        termdef_style(doc.root)
+        see_xrefs_validate(doc.root)
+        see_erefs_validate(doc.root)
       end
       def schema_validate(doc, filename)
@@ -112,7 +188,7 @@ module Asciidoctor
           n.elements.each do |e|
             e.traverse do |e1|
               next unless e1.element?
-              e1.each { |k, v| e.delete(k) }
+              e1.each { |k, _v| e.delete(k) }
             end
           end
         end
@@ -121,7 +197,7 @@ module Asciidoctor
       def validate(doc)
         content_validate(doc)
-        schema_validate(formattedstr_strip(doc.dup),
+        schema_validate(formattedstr_strip(doc.dup),
                         File.join(File.dirname(__FILE__), "isostandard.rng"))
       end
     end

data/lib/asciidoctor/iso/validate_requirements.rb ADDED

@@ -0,0 +1,106 @@
+require "asciidoctor/iso/utils"
+require "nokogiri"
+require "pp"
+module Asciidoctor
+  module ISO
+    module Validate
+      REQUIREMENT_RE_STR = <<~REGEXP.freeze
+        \\b
+         ( shall | (is|are)_to |
+           (is|are)_required_(not_)?to |
+           has_to |
+           only\\b[^.,]+\\b(is|are)_permitted |
+           it_is_necessary |
+           (needs|need)_to |
+           (is|are)_not_(allowed | permitted |
+                         acceptable | permissible) |
+           (is|are)_not_to_be |
+           (need|needs)_not |
+           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 CHANGED

@@ -1,28 +1,40 @@
 require "nokogiri"
-require "pp"
 module Asciidoctor
   module ISO
     module Validate
+      def section_validate(doc)
+        foreword_validate(doc.root)
+        normref_validate(doc.root)
+        symbols_validate(doc.root)
+        sections_sequence_validate(doc.root)
+      end
       def foreword_validate(root)
-        f = root.at("//foreword")
+        f = root.at("//foreword") || return
         s = f.at("./subsection")
         warn "ISO style: foreword contains subsections" unless s.nil?
       end
       def normref_validate(root)
-        f = root.at("//references[title = 'Normative References']")
-        f.at("./references") and
-          warn "ISO style: normative references contains subsections"
+        f = root.at("//references[title = 'Normative References']") || return
+        f.at("./references") &&
+          warn("ISO style: normative references contains subsections")
       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.at("//clause[title = 'Symbols and Abbreviations']")
-        return if f.nil?
-        f.elements do |e|
+        f = root.xpath("//symbols-abbrevs")
+        f.empty? && return
+        (f.size == 1) || warn(ONE_SYMBOLS_WARNING)
+        f.first.elements.each do |e|
           unless e.name == "dl"
-            warn "ISO style: Symbols and Abbreviations can only contain "\
-              "a definition list"
+            warn(NON_DL_SYMBOLS_WARNING)
             return
           end
         end
@@ -38,79 +50,87 @@ module Asciidoctor
       end
       # spec of permissible section sequence
-      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" }],
-        },
-        # we skip normative references, it goes to end of list
-        {
-          msg: "Normative References must be followed by "\
-          "Terms and Definitions",
-          val: [
-            { tag: "terms", title: "Terms and Definitions" },
-            { tag: "terms",
-              title: "Terms, Definitions, Symbols and Abbreviations" }
-          ]
-        },
-      ]
+      # 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: "terms",
+                title: "Terms, Definitions, Symbols and Abbreviated Terms"
+              },
+            ],
+          },
+      ].freeze
+      SECTIONS_XPATH =
+        " //foreword | //introduction | //sections/terms | "\
+        "//symbols-abbrevs | "\
+        "//sections/clause | ./references | ./annex".freeze
       def sections_sequence_validate(root)
-        f = root.xpath(" //foreword | //introduction | //sections/terms | "\
-                       "//sections/clause | ./references | "\
-                       "./annex")
-        names = f.map { |s| { tag: s.name, title: s.at("./title").text } }
-        names = seqcheck(names, SEQ[0][:msg], SEQ[0][:val]) or return
+        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]) or return
+        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]) or return
+          names = seqcheck(names, SEQ[2][:msg], SEQ[2][:val]) || return
         end
-        names = seqcheck(names, SEQ[3][:msg], SEQ[3][:val]) or return
+        names = seqcheck(names, SEQ[3][:msg], SEQ[3][:val]) || return
         n = names.shift
-        if n == { tag: "clause", title: "Symbols and Abbreviations" }
-          n = names.shift or return
+        if n == { tag: "symbols-abbrevs", title: nil }
+          n = names.shift || return
         end
         unless n
           warn "ISO style: Document must contain at least one clause"
           return
         end
-        n[:tag] == "clause" or
-          warn "ISO style: Document must contain at least one clause"
-        n == { tag: "clause", title: "Scope" } and
-          warn "ISO style: Scope must occur before Terms and Definitions"
-        n = names.shift or return
+        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" and
-            warn "ISO style: Scope must occur before Terms and Definitions"
-          n[:title] == "Symbols and Abbreviations" and
-            warn "ISO style: Symbols and Abbreviations must occur "\
-            "right after Terms and Definitions"
-          n = names.shift or return
+          n[:title] == "Scope" &&
+            warn("ISO style: Scope must occur before Terms and Definitions")
+          n = names.shift || return
         end
-        unless n[:tag] == "annex" or n[:tag] == "references"
+        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 or return
+          n = names.shift
+          if n.nil?
+            warn("ISO style: Document must include (references) "\
+                 "Normative References")
+            return
+          end
         end
-        n == { tag: "references", title: "Normative References" } or
-          warn "ISO style: Document must include (references) "\
-          "Normative References"
+        n == { tag: "references", title: "Normative References" } ||
+          warn("ISO style: Document must include (references) "\
+               "Normative References")
         n = names.shift
-        n == { tag: "references", title: "Bibliography" } or
-          warn "ISO style: Final section must be (references) Bibliography"
-        names.empty? or
-          warn "ISO style: There are sections after the final Bibliography"
+        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
     end
   end