metanorma-nist 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c33703816b129a163ed528ae9f88590992ed9af79ec108551e2ee830b88182a9
-  data.tar.gz: 3c56c38e0c20b61fe99743d29cf537f886082f4310c2e4941ad53912d7495b24
+  metadata.gz: 60f08c6613780e3f28e0a30e97558f614ee950036e0bb08c27e8c7537eac7a12
+  data.tar.gz: a9211b80a708af85e81670d41142be5c1c91257726ba6981af1b5ddbff61bd5c
 SHA512:
-  metadata.gz: b2d94690c495ca2172d024ea3f9200dd879170f1f880b6840ab9195dea195da63fc515fbb8395877725ba839249186d7b43979d75afc7345ecc456fcb68ee47b
-  data.tar.gz: b858e830d7ac872bd5cbbf3aff5aa8ecfbd8d5fa37fbd95d2a979fce4c8eafcf8352eb2c4f9e52b3026930e99e2b775480eebfff3b2b947b37943f97825df2fa
+  metadata.gz: a64343cb90f467279fa9907d4dd621b1463ad295df7ffd9c0dd71968a4442f18ea1dd77ee2a9adaff775a6922cadcc270a73580d676791cfc32e6d8b78fd2f3c
+  data.tar.gz: 6ccc7daaa4b771614234baa28de2891063c750310283f7df32c33037bc37728810b93d09cdfa30ef1ae4b45762a91c1d253ae88e67c7010f70853f16093d60c1

data/README.adoc

@@ -130,7 +130,8 @@ introduced with `=`, is used.
 
 `:technical-committee:`:: The name of the relevant committee producing the document.
 
-`:published-date:`:: The publication date for the document.
+`:published-date:`:: The publication date for the document. Only applies to public documents;
+drafts instead have a `:circulated-date:` attribute.
 
 `:uri:`:: The URI to which this standard is published.
 
@@ -139,7 +140,7 @@ the prefix, e.g. "NIST SP", is supplied by the `:series:` attribute. The NIST id
 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, 
+as the document identifier is composed from the document series, document number, document volume,
 and edition/revision (e.g. _NIST SP 800 Revision 1_). 
 If the `:docidentifier:` value is provided, it will override this composed value.
 
@@ -153,11 +154,20 @@ this attribute will be displayed as part of the heading, prefixed with "Revision
 * `draft-wip`
 * `draft-prelim`
 * `draft-public`
-* `draft-withdrawn`
-* `draft-retire`
 * `final` (default: document is published)
 * `final-review`
-* `final-withdrawn`
+--
+
+`:substage:`:: Document substage. Indicates active status of draft or publication. 
+If a draft or publication is inactive, that is reflected in the coverpage. The
+permitted types are:
++
+--
+* `active` (default)
+* `retired` (applies only to drafts, when they are abandoned). The `:abandoned-date:` must
+be provided, to indicate when the draft was abandoned.
+* `withdrawn` (applies to drafts, when when they are superseded by the next draft stage, 
+and to published documents when they are superseded or no longer valid.
 --
 
 `:fullname{_i}:`, `:affiliation{_i}:`, `:address{_i}`::
@@ -188,14 +198,51 @@ The organizational address of a person who is a contributor to the document.
 
 `:obsoleted-date:`::
 The date at which a document is considered no longer valid (withdrawn). If a document
-is not currently withdrawn (as indicated through `:status: draft-withdrawn`, `status: final-withdrawn`),
+is not currently withdrawn (as indicated through `:substage: withdrawn`),
 but will be in the future, that is still indicated in the rendering of the document.
 
+`:confirmed-date:`::
+The date at which a document has been reviewed according to the NIST ERB 5-year review process,
+and has been confirmed to be relevant and valid to date. If this attribute is present,
+the date is included in the cover page.
+
+`:updated-date:`::
+The date at which a document has been updated without being considered a distinct new publication.
+Used to indicate the date of errata releases.
+
+`:circulated-date:`::
+The date at which a draft is circulated. Displayed on the cover page of drafts.
+MANDATORY FOR DRAFTS.
+
 === NIST-specific attributes
 
 The following document attributes are specific to this document class:
 
+`:nist-division:`:: Name of NIST division responsible for document. Added to authority
+statement as document contact, and to coverage of withdrawn published document.
+Default value is "Computer Security Division, Information Technology Laboratory".
+
+`:nist-division-address`:: Address of NIST division responsible for document.
+Added to authority statement as document contact. Use line breaks (in Asciidoctor:
+` + \`) if necessary. Default value is
+"100 Bureau Drive (Mail Stop 8930) Gaithersburg, MD 20899-8930"
+
+`:revision:`:: The document revision; e.g. `1` (Revision 1).
+
+`:volume:`::
+The number of the volume of a standard. Is ignored if a precomposed
+document identifier (`:docidentifier:`) is supplied.
+Is prefixed with "Volume" or "Vol." in display.
+
+`:title-main:`:: The title of the document.
 `:title-sub:`:: The subtitle of the document.
+
+`:title-main-short:`:: Shortened form of the title of the document. For use in Word header.
+If not provided, `:title-main:` is used.
+
+`:title-sub-short:`:: Shortened form of The subtitle of the document. For use in Word header.
+If not provided, `:title-sub:` is used.
+
 `:title-document-class:`:: The title of the document class that the document belongs to;
 e.g. "Computer Security" for SP 800.
 
@@ -244,13 +291,6 @@ Can be a number, or text (e.g. "initial", "final").
 *  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.
 
@@ -277,7 +317,8 @@ Format is document identifier, e.g. _SP 800-53A Rev. 1_
 `:obsoleted-by:`::
 One or more corresponding NIST document that this NIST document standard is obsoleted by; requires that
 this document is withdrawn, and no longer in effect. Comma delimited.
-Format is document identifier, e.g. _SP 800-53A Rev. 1_
+Format is document identifier, e.g. _SP 800-53A Rev. 1_.
+Is the relation between a withdrawn draft, and the next draft in the approval process.
 
 `:supersedes:`::
 One or more NIST document that this NIST document standard supersedes; the superseded
@@ -288,13 +329,71 @@ Format is document identifier, e.g. _SP 800-53A Rev. 1_
 One or more corresponding NIST document that this NIST document standard is superseded by;
 this document may still remain in effect. Comma delimited.
 Format is document identifier, e.g. _SP 800-53A Rev. 1_
+Is *not* the relation between a withdrawn draft, and the next draft in the approval process
+(since the earlier draft is automatically no longer in effect).
+
+`:superseded-date:`::
+The date at which both this document and the document superseding it  come into effect,
+as a transition period before this document is withdrawn. May be identical to `:obsoleted-date:`,
+in which case there is no such transition period. Is indicated in withdrawn publication
+cover page; if not provided, the value of `:obsoleted-date:` is given.
 
 `:abandoned-date:`::
 The date at which work on a document is abandoned. At that date, the document is considered
-retired (`status: draft-retired`). In NIST, only drafts may be retired. If the document
-is not currently retired (as indicated through `:status: draft-retired`),
+retired (`substage: retired`). In NIST, only drafts may be retired. If the document
+is not currently retired (as indicated through `:substage: retired`),
 but will be in the future, that is still indicated in the rendering of the document.
 
+`:sponsor:`::
+The name of the organization that has sponsored the document, if applicable.
+
+`:sponsor-logo:`::
+The logo of the sponsoring organization, if applicable.
+
+`:superseding-status`: Document status/stage of the superseding document, if this document is
+superseded or withdrawn. Used for withdrawn drafts. Used for withdrawn published documents,
+if an entry for the superseding document is not available on the CSRC website (where it can be
+retrieved through the `:obsoleted-by:` document attribute.)
+`:superseding-iteration:`:: The iteration of the stage of the superseding document,
+in case there have been multiple drafts.  Can be a number, or text (e.g. "initial", "final").
+Used for withdrawn drafts. 
+`:superseding-title:`:: The title of the draft document superseding this document.
+If not supplied, the current title is assumed to have been retained. Used for withdrawn drafts.
+Used for withdrawn published documents,
+if an entry for the superseding document is not available on the CSRC website (where it can be
+retrieved through the `:obsoleted-by:` document attribute.)
+`:superseding-subtitle:`:: The subtitle of the draft document superseding this document.
+If not supplied, the current subtitle is assumed to have been retained. Used for withdrawn drafts.
+Used for withdrawn published documents,
+if an entry for the superseding document is not available on the CSRC website (where it can be
+retrieved through the `:obsoleted-by:` document attribute.)
+`:superseding-circulated-date:`::
+The date at which the draft document superseding this document is circulated. Used for withdrawn drafts.
+`:superseding-published-date:`::
+The date at which the document superseding this document is published.
+Used for withdrawn published documents,
+if an entry for the superseding document is not available on the CSRC website (where it can be
+retrieved through the `:obsoleted-by:` document attribute.)
+`:superseding-doi:`::
+The DOI of the document superseding this document. Used for withdrawn drafts.
+Used for withdrawn published documents,
+if an entry for the superseding document is not available on the CSRC website (where it can be
+retrieved through the `:obsoleted-by:` document attribute.)
+`:superseding-url:`::
+The URL of the document superseding this document. Used for withdrawn drafts.
+Used for withdrawn published documents,
+if an entry for the superseding document is not available on the CSRC website (where it can be
+retrieved through the `:obsoleted-by:` document attribute.)
+`:superseding-authors:`::
+The authors of the superseding document. Comma-delimited. Used for withdrawn published documents,
+if an entry for the superseding document is not available on the CSRC website (where it can be
+retrieved through the `:obsoleted-by:` document attribute.)
+
+`:bib-additional-note:`:: Additional note (optional), used on coverpage of withdrawn and retired drafts, and as
+"Related Information" on coverpage of withdrawn published documents.
+`:bib-withdrawal-note:`:: Withdrawal note, used on coverpage of withdrawn published documents.
+`:bib-withdrawal-announcement-link:`:: Hyperlink to announcement of withdrawal, used on coverpage of withdrawn published documents.
+
 == Asciidoctor features specific to NIST
 
 The https://github.com/metanorma/metanorma-standoc[metanorma-standoc]
@@ -407,8 +506,16 @@ 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.
-It is rendered after all other preface sections.
+This is any section that appears with the style attribute `[executive-summary]`.
+It is rendered after all other preface sections:
+
+[source,asciidoctor]
+----
+[executive-summary]
+== Executive Summary
+
+This is an executive summary
+----
 
 === Terms and definitions
 
@@ -493,6 +600,44 @@ Glossaries are given as definition lists with style attribute `glossary`:
 stem:[A= {x_1, x_2, ..., x_k}]:: The alphabet, i.e., the set of all possible symbols that a (digitized) noise source produces.
 ----
 
+=== Document status
+
+The following table illustrates how transitions between stages of NIST documents are indicated
+using `:status:`, `:substage:`, `:iteration:`, and `:confirmed-date`. 
+
+|===
+| ISO stage | NIST | 93 Repeat current phase | 98 Abandon | 99 Proceed
+
+| 00 Preliminary | `:status: draft-internal` | | (stop work) | `:status: draft-wip`, `:status: draft-public`, or `:status: final` (amend)
+| 10 Proposal | `:status: draft-wip` | | `:status: draft-wip`, `:substage: retired` | `:status: draft-wip`, `:substage: withdrawn`
+| 20 Preparatory | `status: draft-prelim` | | `status: draft-prelim`, `substage: retired` | `status: draft-prelim`, `substage: withdrawn`
+| 40 Enquiry | `status: draft-public` | `status: draft-public`, `:iteration: 2`, `:iteration: 3` ... `:iteration: final` | `:status: draft-public`, `:substage: retired` | `:status: draft-public`, `:substage: withdrawn`
+| 50 Approval | (NIST ERB review) | | `:status: draft-public`, `:substage: retired` | `:status: final`
+| 60 Publication | `:status: final`
+| 90 Review | `:status: final-review` | `:status: final`, `:confirmed-date: XXXX-XX-XX` | `:status: final`, `:substage: withdrawn` | `:status: draft-internal` (revise or amend)
+| 95 Withdrawal | `:status: final`, `:substage: withdrawn` | | | 
+|===
+
+In the following, parentheses indicate optional attributes.
+
+* For retired drafts, the following attributes must be provided: `:circulated-date:`, 
+`:abandoned-date:`, (`:bib-additional-note:`)
+* For withdrawn drafts, the following attributes must be provided: `:circulated-date:`, `:obsoleted-date:`,
+`:superseding-status:`, (`:superseding-iteration:`), (`:superseding-title:`), 
+(`:superseding-subtitle:`), `:superseding-circulated-date:`, (`:superseding-doi:`), 
+(`:superseding-url:`), (`:bib-additional-note:`)
+* For withdrawn published documents, the following attributes must be provided: `:published-date:`, `:obsoleted-date:` (when
+the current document is no longer in effect), `:superseded-date:` (when the transition period started, during which both
+documents were in effect, if applicable; if not, this has the same value as `:obsoleted-date:`), `:revdate:` (for
+when the withdrawal notice was added to the document), (`:bib-additional-note:`) 
+("Related Information" in the withdrawn document coverpage), `:obsoleted-by:` (giving the superseding document identifier), 
+`:nist-division:`, (`:bib-withdrawal-note:`), (`:bib-withdrawal-announcement-link:`). If the details
+of the superseding document are not available to be retrieved from the CSRC website), the following attributes must
+be provided: `:superseding-title:`, (`:superseding-subtitle:`), `:superseding-published-date:`, `:superseding-status:`, 
+`:superseding-doi:`, `:superseding-url:`.
+
+
+
 ////
 
 == Examples

data/lib/asciidoctor/nist/biblio.rng

@@ -810,6 +810,9 @@
   </define>
   <define name="biblionote">
     <element name="note">
+      <optional>
+        <attribute name="type"/>
+      </optional>
       <ref name="FormattedString"/>
     </element>
   </define>

data/lib/asciidoctor/nist/boilerplate.rb

@@ -1,17 +1,65 @@
 module Asciidoctor
   module NIST
     class Converter < Standoc::Converter
+      SERIES = {
+        "nist-ams": "NIST Advanced Manufacturing Series",
+        "building-science": "NIST Building Science Series",
+        "nist-fips": "NIST Federal Information Processing Standards",
+        "nist-gcr": "NIST Grant/Contract Reports",
+        "nist-hb": "NIST Handbook",
+        "itl-bulletin": "ITL Bulletin",
+        "jpcrd": "Journal of Physical and Chemical Reference Data",
+        "nist-jres": "NIST Journal of Research",
+        "letter-circular": "NIST Letter Circular",
+        "nist-monograph": "NIST Monograph",
+        "nist-ncstar": "NIST National Construction Safety Team Act Reports",
+        "nist-nsrds": "NIST National Standard Reference Data Series",
+        "nistir": "NIST Interagency/Internal Report",
+        "product-standards": "NIST Product Standards",
+        "nist-sp": "NIST Special Publication",
+        "nist-tn": "NIST Technical Note",
+        "other": "NIST Other",
+        "csrc-white-paper": "CSRC White Paper",
+        "csrc-book": "CSRC Book",
+        "csrc-use-case": "CSRC Use Case",
+        "csrc-building-block": "CSRC Building Block",
+      }.freeze
+
+      SERIES_ABBR = {
+        "nist-ams": "NIST AMS",
+        "building-science": "NIST Building Science Series",
+        "nist-fips": "NIST FIPS",
+        "nist-gcr": "NISTGCR",
+        "nist-hb": "NIST HB",
+        "itl-bulletin": "ITL Bulletin",
+        "jpcrd": "JPCRD",
+        "nist-jres": "NIST JRES",
+        "letter-circular": "NIST Letter Circular",
+        "nist-monograph": "NIST MN",
+        "nist-ncstar": "NIST NCSTAR",
+        "nist-nsrds": "NIST NSRDS",
+        "nistir": "NISTIR",
+        "product-standards": "NIST Product Standards",
+        "nist-sp": "NIST SP",
+        "nist-tn": "NIST TN",
+        "other": "NIST Other",
+        "csrc-white-paper": "CSRC White Paper",
+        "csrc-book": "CSRC Book",
+        "csrc-use-case": "CSRC Use Case",
+        "csrc-building-block": "CSRC Building Block",
+      }.freeze
+
       CALL_FOR_PATENT_CLAIMS = <<~END.freeze
       <clause><title>Call for Patent Claims</title>
       <p>This public review includes a call for information on essential patent claims (claims whose use would be required for compliance with the guidance or requirements in this Information Technology Laboratory (ITL) draft publication). Such guidance and/or requirements may be directly stated in this ITL Publication or by reference to another publication. This call also includes disclosure, where known, of the existence of pending U.S. or foreign patent applications relating to this ITL draft publication and of any relevant unexpired U.S. or foreign patents.</p>
 
 <p>ITL may require from the patent holder, or a party authorized to make assurances on its behalf, in written or electronic form, either:</p>
 
-<ol><li><p>assurance in the form of a general disclaimer to the effect that such party does not hold and does not currently intend holding any essential patent claim(s); or</p></li>
+<ol type="arabic"><li><p>assurance in the form of a general disclaimer to the effect that such party does not hold and does not currently intend holding any essential patent claim(s); or</p></li>
 
 <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 type="roman"><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>
@@ -49,9 +97,11 @@ module Asciidoctor
         conv = IsoDoc::NIST::HtmlConvert.new({})
         conv.metadata_init("en", "Latn", {})
         conv.info(x, nil)
+        conv.labels = {nist_division: @nistdivision,
+                       nist_division_address: @nistdivisionaddress}
         file = @boilerplateauthority ? "#{@localdir}/#{@boilerplateauthority}" :
           File.join(File.dirname(__FILE__),"nist_intro.xml")
-        conv.populate_template((File.read(file, encoding: "UTF-8")), nil)
+          conv.populate_template((File.read(file, encoding: "UTF-8")), nil)
       end
     end
   end

data/lib/asciidoctor/nist/cleanup.rb

@@ -40,6 +40,12 @@ module Asciidoctor
           c.name = "executivesummary" if title == "executive summary"
           preface.add_child c.remove
         end
+        x.xpath("//clause[@executivesummary]").each do |c|
+          c.delete("executivesummary")
+          title = c&.at("./title")&.text.downcase
+          c.name = "executivesummary"
+          preface.add_child c.remove
+        end
       end
 
       def move_authority_into_preface(x, preface)
@@ -52,8 +58,8 @@ module Asciidoctor
       end
 
       def move_sections_into_preface(x, preface)
-        abstract = x.at("//abstract") and preface.add_child abstract.remove
         move_authority_into_preface(x, preface)
+        abstract = x.at("//abstract") and preface.add_child abstract.remove
         foreword = x.at("//foreword") and preface.add_child foreword.remove
         intro = x.at("//introduction") and preface.add_child intro.remove
         move_clauses_into_preface(x, preface)
@@ -87,6 +93,40 @@ module Asciidoctor
         summ = x.at("//executivesummary") and preface.add_child summ.remove
         #end
       end
+
+
+      # handle NIST references separately
+      # doc identifier format, NIST: NIST SP 800-87-1 {Vol./Volume 8}|
+      # {Rev./Revision 8}|(Month YYYY)
+      def reference_names(docxml)
+        super
+        ret = get_all_nist_refs(docxml)
+        tallies = ret.inject(Hash.new(0)) do |memo, (k, v)|
+          memo[v[:trunc]] += 1
+          memo
+        end
+        ret.each do |k, v|
+          tallies[v[:trunc]] == 1 and @anchors[k][:xref] = v[:trunc]
+          @anchors[k][:xref].sub!(/^NIST /, "")
+        end
+      end
+
+      def truncate_nist_ref(text)
+        #text.sub(/\s\((January|February|March|April|May|June|July|August|
+        #                September|October|November|December)\s\d\d\d\d\).*$/x, "")
+        text
+      end
+
+      def get_all_nist_refs(docxml)
+        ret = {}
+        docxml.xpath("//bibitem[not(ancestor::bibitem)]").each do |ref|
+          #next unless ref.at("./docidentifier[@type = 'NIST']")
+          ret[ref["id"]] = {}
+          ret[ref["id"]][:xref] = ref&.at("./docidentifier[not(@type = 'DOI')]")&.text or next
+          ret[ref["id"]][:trunc] = truncate_nist_ref(ret[ref["id"]][:xref])
+        end
+        ret
+      end
     end
   end
 end

data/lib/asciidoctor/nist/converter.rb

@@ -121,6 +121,10 @@ module Asciidoctor
         @patentcontact = node.attr("patent-contact")
         @biblioasappendix = node.attr("biblio-as-appendix")
         @boilerplateauthority = node.attr("boilerplate-authority")
+        @nistdivision = node.attr("nist-division") ||
+          "Computer Security Division, Information Technology Laboratory"
+        @nistdivisionaddress = node.attr("nist-division-address") ||
+          "100 Bureau Drive (Mail Stop 8930) Gaithersburg, MD 20899-8930"
         super
       end
 
@@ -142,6 +146,7 @@ module Asciidoctor
 
       def clause_parse(attrs, xml, node)
         attrs[:preface] = true if node.attr("style") == "preface"
+        attrs[:executivesummary] = true if node.attr("style") == "executive-summary"
         super
       end
 
@@ -228,12 +233,6 @@ module Asciidoctor
         end
       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)
         IsoDoc::NIST::HtmlConvert.new(html_extract_attributes(node))
       end