metanorma-nist 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30193344892f68ba4a979316250fe4e6268cdbbe1ae476b48169f34d5ebcfcf6
-  data.tar.gz: 5a2165e97b94d197e9e5247b7fdb21bdc33c38041da812824f5298452f6a0512
+  metadata.gz: ed6d6518c86f59d927b205f623877b3e860e6874d561e1748b53142ee6d26d25
+  data.tar.gz: 881aa89fd9aeceea3216f116fb5465fd2082bd636f77d6f4dbf6b15ef08a7ba6
 SHA512:
-  metadata.gz: 1fb5c7754d436c24af54b760c3cbb9b8561ada612d8aa022c709b651eb8bf8f16fc43d4f2fc7efb65de9743c0167a85f86fc58816f9b3b8b250da380e4f98fd4
-  data.tar.gz: d0ed65e3f7cb8cf0abd6e9235522faaf2e4fc14d2d0d77b8b51a678719d081caa02403de3b9b7b37f52e1f33f1395440006fe14b33278900bf8311f2e1d0079d
+  metadata.gz: b468ba8980ad51e00d0ffddc0d09b3440fe6d1d2d381df330f2807cfdb476d460469a62fb36be75e0b031950a99394f0458236d442030540c5787bfcb51cde4d
+  data.tar.gz: '0012912ef3a4dc926c45432ab69c30af5dd771b3042ca86e30615d892ca1eb1281d06dff0dc8372697e3a9b8e2f164ec3b2cbcf7447a1b8191e36a30632bfa23'

data/.travis.yml

@@ -8,9 +8,9 @@ rvm:
   - ruby-head
 before_install:
   - gem install bundler -v 2.0.1
-  - npm install -g puppeteer
-  - npm install
-  - unset _JAVA_OPTIONS
+  - travis_retry sudo apt-get update
+  - curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/ubuntu-install-puppeteer.sh | bash
 matrix:
   allow_failures:
     - rvm: ruby-head
+

data/README.adoc

@@ -1,8 +1,9 @@
 = metanorma-nist: Metanorma processor for the NIST SP 800 document classes
 
 image:https://img.shields.io/gem/v/metanorma-nist.svg["Gem Version", link="https://rubygems.org/gems/metanorma-nist"]
-image:https://img.shields.io/travis/riboseinc/metanorma-nist/master.svg["Build Status", link="https://travis-ci.com/riboseinc/metanorma-nist"]
-image:https://codeclimate.com/github/riboseinc/metanorma-nist/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/metanorma-nist"]
+image:https://img.shields.io/travis/metanorma/metanorma-nist/master.svg["Build Status", link="https://travis-ci.com/metanorma/metanorma-nist"]
+image:https://ci.appveyor.com/api/projects/status/c5e8e3qtn689a5h0?svg=true["Appveyor Build Status", link="https://ci.appveyor.com/project/ribose/metanorma-nist"]
+image:https://codeclimate.com/github/metanorma/metanorma-nist/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/metanorma-nist"]
 
 WARNING: This gem is still under development.
 
@@ -30,7 +31,7 @@ as end deliverable NIST documents.
 
 == Structure
 
-This gem inherits from the https://github.com/riboseinc/metanorma-standoc
+This gem inherits from the https://github.com/metanorma/metanorma-standoc
 gem, and aligns closely to it.
 
 
@@ -38,13 +39,13 @@ gem, and aligns closely to it.
 
 Please see https://www.metanorma.com for instructions to get started.
 
-If you are using a Mac, the https://github.com/riboseinc/metanorma-macos-setup
+If you are using a Mac, the https://github.com/metanorma/metanorma-macos-setup
 repository has instructions on setting up your machine to run Metanorma
 scripts such as this one. You need only run the following in a Terminal console:
 
 [source,console]
 ----
-$ bash <(curl -s https://raw.githubusercontent.com/riboseinc/metanorma-macos-setup/master/metanorma-setup)
+$ bash <(curl -s https://raw.githubusercontent.com/metanorma/metanorma-macos-setup/master/metanorma-setup)
 $ gem install metanorma-cli
 $ gem install metanorma-nist
 ----
@@ -70,26 +71,16 @@ Please refer to the Metanorma-ISO documentation for general documentation.
 
 * Metanorma-ISO guidance: https://www.metanorma.com/software/metanorma-iso/docs/guidance/
 
-
-////
-** http://asciimath.org[AsciiMathML] is used for mathematical formatting.
-The gem uses the https://github.com/asciidoctor/asciimath[Ruby AsciiMath parser],
-which is syntactically stricter than the common MathJax processor;
-if you do not get expected results, try bracketing terms your in AsciiMathML
-expressions.
-////
-
-
 == Approach
 
 === Document model
 
 The NIST SP 800 document model is detailed here:
 
-* https://github.com/riboseinc/metanorma-model-nist[NIST SP 800 document model]
+* https://github.com/metanorma/metanorma-model-nist[NIST SP 800 document model]
 
 It is an instance of the
-https://github.com/riboseinc/metanorma-model-standoc[StandardDocument model].
+https://github.com/metanorma/metanorma-model-standoc[StandardDocument model].
 
 
 === Document input
@@ -117,7 +108,7 @@ NOTE: The Asciidoctor gem is used for AsciiDoc input parsing.
 
 Metadata of the document is provided through AsciiDoc document attributes.
 
-https://github.com/riboseinc/metanorma-standoc[Metanorma-Standoc]
+https://github.com/metanorma/metanorma-standoc[Metanorma-Standoc]
 documents all common Metanorma document attributes.
 
 Where these preexisting metanorma attributes correspond to attributes already used
@@ -133,9 +124,11 @@ The attributes relevant to NIST documents include:
 `:copyright-year:`:: The year which will be claimed as when the copyright for
 the document was issued.
 
-`:title:`:: The main component of the English title of the document
-(mandatory). (The first line of the AsciiDoc document, which contains the title
-introduced with `=`, is ignored)
+`:title-main:`:: The main component of the title of the document
+(mandatory). If absent, the first line of the AsciiDoc document, which contains the title
+introduced with `=`, is used.
+
+`:title-sub:`:: The subtitle of the document.
 
 `:technical-committee:`:: The name of the relevant committee producing the document (mandatory). 
 
@@ -143,11 +136,28 @@ introduced with `=`, is ignored)
 
 `:uri:`:: The URI to which this standard is published.
 
-`:docnumber:`:: The internal identifier referring to this document.
+`:docnumber:`:: The internal identifier referring to this document. The identifier is a number;
+the prefix, e.g. "NIST SP", is supplied by the `:series:` attribute. The NIST identifier is
+docnumber-edition (if edition is present)
+
+`:docidentifier:`:: The document identifier for the document. Normally this should not be supplied,
+as the document identifier is composed from the document series, document number, 
+and edition/revision. If the `:docidentifier:` value is provided, it will override this composed
+value.
 
 `:edition:`:: Edition (revision) of the document. The value of
 this attribute will be displayed as part of the heading, prefixed with "Revision".
 
+`:status:`:: Document status/stage. The permitted types are:
++
+--
+* `internal-draft`
+* `public-draft`
+* `final`
+* `retired-draft`
+* `withdrawn`
+--
+
 ////
 
 `:doctype:`:: The document type (mandatory). The permitted types are:
@@ -173,14 +183,6 @@ this attribute will be displayed as part of the heading, prefixed with "Revision
 `administrative`::: Internal administrative documents
 --
 
-`:status:`:: Document status/stage. The permitted types are:
-+
-`rfc`::: OGC RFC (proposal)
-`candidate`::: Candidate Standard
-`published`::: Published
-`deprecated`::: Deprecated
-`retired`::: Retired
-
 `:committee:`:: The name of the relevant committee producing the document (mandatory). The legal values are:
 `technical`, `planning`, `strategic-member-advisory`
 `:subcommittee:`:: The name of the relevant subcommittee producing the document
@@ -203,6 +205,9 @@ The following document attributes are specific to this document class:
 
 `:doc-email:`:: Email contact for document
 
+`:doi:`:: DOI URL for document (distinct from `:uri:`, which is the URL that NIST
+publishes the document under.)
+
 `:call-for-patent-claims:`:: Include the Call for Patent Claims in document drafts, 
 and the Patent Disclosure Notice in finalised documents.
 
@@ -212,9 +217,59 @@ notice and commitment to license have been received.
 `:patent-contact:`:: Contact for the Call for Patent Claims or Patent Disclosure Notice.
 If not supplied, `:doc-email:` is used.
 
+`:iteration:`:: The iteration of a stage, in case there have been multiple drafts.
+Can be a number, or text (e.g. "initial", "final").
+
+`:series:`:: The publication series that the document belongs to. Legal values are:
++
+--
+* nist-ams 
+*  building-science 
+*  nist-fips 
+*  nist-gcr 
+*  nist-hb 
+*  itl-bulletin 
+*  jpcrd 
+*  nist-jres 
+*  letter-circular 
+*  nist-monograph 
+*  nist-ncstar 
+*  nist-nsrds 
+*  nistir 
+*  product-stadnards 
+*  nist-sp  
+*  nist-tn 
+*  other 
+*  csrc-white-paper 
+*  csrc-book 
+*  csrc-use-case 
+*  csrc-building-block
+--
+
+`:subseries:`:: The secondary publication series that the document belongs to. Legal values are:
++
+--
+* computer-security (for NIST SP)
+* information-security (for NIST SP)
+--
+
+`:comment-from:`:: The beginning of the period during which comments may be submitted to the NIST
+document draft. ISO-8601 date.
+
+`:comment-to:`:: The end of the period during which comments may be submitted to the NIST document
+draft. The end of the period may change, and may be left open-ended (omitted). ISO-8601 date.
+
+`:comment-extended:`:: The date on which the during which comments may be submitted to the NIST document
+draft was extended.
+
+`:biblio-as-appendix:`:: By default, bibliographies are treated as separate from appendixes in output:
+they are published in front of any appendixes. This is the prescribed behaviour for NIST documents moving
+forward. If present, bibliographies are treated in the legacy manner: they are treated like appendixes,
+and are given an appendix number according to where in the document they occur.
+
 == Asciidoctor features specific to NIST
 
-The https://github.com/riboseinc/metanorma-standoc[metanorma-standoc]
+The https://github.com/metanorma/metanorma-standoc[metanorma-standoc]
 gem documents the customisations of Asciidoctor markup common to all metanorma gems.
 The following markup is specific to this gem:
 
@@ -222,6 +277,7 @@ The following markup is specific to this gem:
 
 The following sections are automatically moved to the document preface.
 
+* Foreword
 * Abstract
 * Keywords (drawn from document attribute, see above)
 
@@ -253,9 +309,26 @@ the document is in draft (has a `:draft:` attribute).
 
 ==== Abstract
 
-As with all metanorma gems, Abstracts are recognised as any clause with the style attribute
+As with all Metanorma gems, Abstracts are recognised as any clause with the style attribute
 `[abstract]`. They are rendered in the document preface, under the Metanorma XML tag `abstract`.
 
+==== Foreword
+
+As with all Metanorma gems, the foreword is considered to be any text before the first
+section title. The foreword is used to capture the introductory statement on the publication
+series that precedes the abstract, and its title is entered as a caption:
+
+[source,asciidoctor]
+----
+= Document
+:title-main: NIST Report
+:title-sub: Subtitle of Report
+
+.Reports on Computer Systems Technology
+The Information Technology Laboratory (ITL) at the National Institute
+of Standards and Technology (NIST) promotes the U.S. economy and public welfare...
+----
+
 === Executive Summary
 
 This is any section that appears in the preface with the title Executive Summary.
@@ -263,10 +336,9 @@ It is rendered after all other preface sections.
 
 === Terms and definitions
 
-NIST documents do not provide for an extensive Terms & Definitions structure, as seen
-in ISO and ISO-derived standards. Instead, they use acronyms and glossary appendixes.
-These should be given as simple definition lists, without extensive embedded notes, examples,
-or sources.
+Glossaries in NIST documents correspond to Terms & Definitions sections elsewhere in
+Metanorma. They are appendices in NIST, and any appendix in NIST Metanorma with the
+title "Glossary" or "Terminology" is treated as a Terms & Definitions section.
 
 === Pseudocode
 

data/appveyor.yml

@@ -0,0 +1,30 @@
+version: '{build}'
+
+environment:
+  matrix:
+    - RUBY_VERSION: 25
+    - RUBY_VERSION: 24
+    - RUBY_VERSION: 23
+    - RUBY_VERSION: _trunk
+
+matrix:
+  allow_failures:
+    - RUBY_VERSION: _trunk
+
+install:
+  - ps: . { iwr -useb https://raw.githubusercontent.com/metanorma/metanorma-build-scripts/master/appveyor.ps1 } | iex
+  - refreshenv
+
+build_script:
+  - set PATH=C:\Ruby%RUBY_VERSION%\bin;%PATH%
+  - bundle update
+  - bundle install
+
+before_test:
+  - ruby -v
+  - gem -v
+  - bundle -v
+
+test_script:
+  - bundle exec rake
+

data/lib/asciidoctor/nist/biblio.rng

@@ -156,9 +156,9 @@
       <zeroOrMore>
         <ref name="contact"/>
       </zeroOrMore>
-      <optional>
+      <zeroOrMore>
         <ref name="uri"/>
-      </optional>
+      </zeroOrMore>
     </element>
   </define>
   <define name="fullname">
@@ -246,9 +246,9 @@
       <optional>
         <ref name="abbreviation"/>
       </optional>
-      <optional>
+      <zeroOrMore>
         <ref name="uri"/>
-      </optional>
+      </zeroOrMore>
       <zeroOrMore>
         <ref name="org-identifier"/>
       </zeroOrMore>
@@ -469,12 +469,13 @@
       <value>film</value>
       <value>video</value>
       <value>broadcast</value>
-      <value>graphic work</value>
+      <value>graphic_work</value>
       <value>music</value>
       <value>patent</value>
       <value>inbook</value>
       <value>incollection</value>
       <value>inproceedings</value>
+      <value>journal</value>
     </choice>
   </define>
   <define name="BibliographicItem">
@@ -739,39 +740,44 @@
     <element name="series">
       <optional>
         <attribute name="type">
-          <choice>
-            <value>main</value>
-            <value>alt</value>
-          </choice>
+          <ref name="SeriesType"/>
         </attribute>
       </optional>
       <choice>
-        <ref name="btitle"/>
         <ref name="formattedref"/>
+        <group>
+          <ref name="btitle"/>
+          <optional>
+            <ref name="bplace"/>
+          </optional>
+          <optional>
+            <ref name="seriesorganization"/>
+          </optional>
+          <optional>
+            <ref name="abbreviation"/>
+          </optional>
+          <optional>
+            <ref name="seriesfrom"/>
+          </optional>
+          <optional>
+            <ref name="seriesto"/>
+          </optional>
+          <optional>
+            <ref name="seriesnumber"/>
+          </optional>
+          <optional>
+            <ref name="seriespartnumber"/>
+          </optional>
+        </group>
       </choice>
-      <optional>
-        <ref name="bplace"/>
-      </optional>
-      <optional>
-        <ref name="seriesorganization"/>
-      </optional>
-      <optional>
-        <ref name="abbreviation"/>
-      </optional>
-      <optional>
-        <ref name="seriesfrom"/>
-      </optional>
-      <optional>
-        <ref name="seriesto"/>
-      </optional>
-      <optional>
-        <ref name="seriesnumber"/>
-      </optional>
-      <optional>
-        <ref name="seriespartnumber"/>
-      </optional>
     </element>
   </define>
+  <define name="SeriesType">
+    <choice>
+      <value>main</value>
+      <value>alt</value>
+    </choice>
+  </define>
   <define name="seriesorganization">
     <element name="organization">
       <text/>
@@ -849,6 +855,7 @@
           <value>includes</value>
           <value>instance</value>
           <value>partOf</value>
+          <value>hasDraft</value>
         </choice>
       </attribute>
       <element name="bibitem">
@@ -861,9 +868,6 @@
   </define>
   <define name="version">
     <element name="version">
-      <optional>
-        <ref name="vedition"/>
-      </optional>
       <optional>
         <ref name="revision-date"/>
       </optional>

data/lib/asciidoctor/nist/converter.rb

@@ -18,9 +18,6 @@ module Asciidoctor
 
       def example(node)
         return pseudocode_example(node) if node.attr("style") == "pseudocode"
-        return recommendation(node) if node.attr("style") == "recommendation"
-        return requirement(node) if node.attr("style") == "requirement"
-        return permission(node) if node.attr("style") == "permission"
         super
       end
 
@@ -34,30 +31,6 @@ module Asciidoctor
         end.join("\n")
       end
 
-      def recommendation(node)
-        noko do |xml|
-          xml.recommendation **id_attr(node) do |ex|
-            wrap_in_para(node, ex)
-          end
-        end.join("\n")
-      end
-
-      def requirement(node)
-        noko do |xml|
-          xml.requirement **id_attr(node) do |ex|
-            wrap_in_para(node, ex)
-          end
-        end.join("\n")
-      end
-
-      def permission(node)
-        noko do |xml|
-          xml.permission **id_attr(node) do |ex|
-            wrap_in_para(node, ex)
-          end
-        end.join("\n")
-      end
-
       def table(node)
         return errata(node) if node.attr("style") == "errata"
         super
@@ -132,6 +105,15 @@ module Asciidoctor
         end
       end
 
+      # skip annex/terms/terms, which is empty node
+       def termdef_subclause_cleanup(xmldoc)
+        xmldoc.xpath("//terms[terms]").each do |t|
+          next if t.parent.name == "terms"
+          t.children.each { |n| n.parent = t.parent }
+          t.remove
+        end
+      end
+
       def makexml(node)
         result = ["<?xml version='1.0' encoding='UTF-8'?>\n<nist-standard>"]
         @draft = node.attributes.has_key?("draft")
@@ -140,7 +122,7 @@ module Asciidoctor
         result << "</nist-standard>"
         result = textcleanup(result)
         ret1 = cleanup(Nokogiri::XML(result))
-        validate(ret1)
+        validate(ret1) unless @novalid
         ret1.root.add_namespace(nil, EXAMPLE_NAMESPACE)
         ret1
       end
@@ -160,6 +142,7 @@ module Asciidoctor
         @callforpatentclaims = node.attr("call-for-patent-claims")
         @commitmenttolicence = node.attr("commitment-to-licence")
         @patentcontact = node.attr("patent-contact")
+        @biblioasappendix = node.attr("biblio-as-appendix")
         super
       end
 
@@ -201,8 +184,9 @@ module Asciidoctor
         preface.add_child introduction.remove if introduction
         x.xpath("//clause[@preface]").each do |c|
           c.delete("preface")
-          c.name = "reviewernote" if c&.at("./title")&.text.downcase == "note to reviewers"
-          c.name = "executivesummary" if c&.at("./title")&.text.downcase == "executive summary"
+          title = c&.at("./title")&.text.downcase
+          c.name = "reviewernote" if title == "note to reviewers"
+          c.name = "executivesummary" if title == "executive summary"
           preface.add_child c.remove
         end
         callforpatentclaims(x, preface)
@@ -218,7 +202,7 @@ module Asciidoctor
 
 <li><p>assurance that a license to such essential patent claim(s) will be made available to applicants desiring to utilize the license for the purpose of complying with the guidance or requirements in this ITL draft publication either:</p>
 
-	<ol><li><p>under reasonable terms and conditions that are demonstrably free of any unfair discrimination; or</p></li>
+        <ol><li><p>under reasonable terms and conditions that are demonstrably free of any unfair discrimination; or</p></li>
 
         <li><p>without compensation and under reasonable terms and conditions that are demonstrably free of any unfair discrimination.</p></li></ol>
 </li></ol>
@@ -253,8 +237,8 @@ module Asciidoctor
         if @callforpatentclaims
           docemail = x&.at("//uri[@type = 'email']")&.text || "???"
           docnumber = x&.at("//docnumber")&.text || "???"
-          status = x&.at("//bibdata/status")&.text 
-          published = status.nil? || status == "published"
+          status = x&.at("//bibdata/status/stage")&.text 
+          published = status.nil? || status == "final"
           preface.add_child patent_text(published, docemail, docnumber)
         end
       end
@@ -311,8 +295,17 @@ module Asciidoctor
         noko do |xml|
           case sectiontype(node)
           when "normative references" then norm_ref_parse(a, xml, node)
+          when "glossary", "terminology"
+            if node.attr("style") == "appendix" && node.level == 1
+              @term_def = true
+              terms_annex_parse(a, xml, node)
+              @term_def = false
+            else
+              clause_parse(a, xml, node)
+            end
           else
-            if @term_def then term_def_subclause_parse(a, xml, node)
+            if @term_def 
+              term_def_subclause_parse(a, xml, node)
             elsif @biblio then bibliography_parse(a, xml, node)
             elsif node.attr("style") == "bibliography"
               bibliography_parse(a, xml, node)
@@ -327,15 +320,56 @@ module Asciidoctor
         end.join("\n")
       end
 
+      def bibliography_parse(a, xml, node)
+        @biblioasappendix and node.level == 1 and
+          return bibliography_annex_parse(a, xml, node)
+        super
+      end
+
+      def bibliography_annex_parse(attrs, xml, node)
+        attrs1 = attrs.merge(id: "_" + UUIDTools::UUID.random_create)
+        xml.annex **attr_code(attrs1) do |xml_section|
+          xml_section.title { |t| t << "Bibliography" }
+          @biblio = true
+          xml.references **attr_code(attrs) do |xml_section|
+            xml_section << node.content
+          end
+        end
+        @biblio = false
+      end
+
+      def terms_annex_parse(attrs, xml, node)
+        attrs1 = attrs.merge(id: "_" + UUIDTools::UUID.random_create)
+        xml.annex **attr_code(attrs1) do |xml_section|
+          xml_section.title { |name| name << node.title }
+          xml_section.terms **attr_code(attrs) do |terms|
+            (s = node.attr("source")) && s.split(/,/).each do |s1|
+              terms.termdocsource(nil, **attr_code(bibitemid: s1))
+            end
+            terms << node.content
+          end
+        end
+      end
+
+      SECTIONS_TO_VALIDATE = "//references[not(parent::clause)]/title | "\
+        "//clause[descendant::references][not(parent::clause)]/title".freeze
+
       def section_validate(doc)
         super
-        f = doc.xpath("//references[not(parent::clause)]/title | //clause[descendant::references][not(parent::clause)]/title")
+        f = doc.xpath(SECTIONS_TO_VALIDATE)
         names = f.map { |s| s&.text }
         return if names.empty?
         return if names == ["References"]
         return if names == ["Bibliography"]
         return if names == ["References", "Bibliography"]
-        warn "Reference clauses #{names.join(', ')} do not follow expected pattern in NIST"
+        warn "Reference clauses #{names.join(', ')} do not follow expected "\
+          "pattern in NIST"
+      end
+
+      def sections_order_cleanup(x)
+        s = x.at("//sections")
+        make_preface(x, s)
+        x.xpath("//sections/annex").reverse_each { |r| s.next = r.remove }
       end
 
       def html_converter(node)