metanorma-nist 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60f08c6613780e3f28e0a30e97558f614ee950036e0bb08c27e8c7537eac7a12
-  data.tar.gz: a9211b80a708af85e81670d41142be5c1c91257726ba6981af1b5ddbff61bd5c
+  metadata.gz: 553e8bf36b10720beecc7e76b0bf8cc2141ea7dfa18b9389adb2355521df72cb
+  data.tar.gz: 4d050660b0d6954dd58bbee575fd62374bcdb2c931b9cce5f4271f30a79a6ecb
 SHA512:
-  metadata.gz: a64343cb90f467279fa9907d4dd621b1463ad295df7ffd9c0dd71968a4442f18ea1dd77ee2a9adaff775a6922cadcc270a73580d676791cfc32e6d8b78fd2f3c
-  data.tar.gz: 6ccc7daaa4b771614234baa28de2891063c750310283f7df32c33037bc37728810b93d09cdfa30ef1ae4b45762a91c1d253ae88e67c7010f70853f16093d60c1
+  metadata.gz: 84ae66bfe9a43d1e79f65c9532116c73eec1a562020e206ce05883391e049dc46fe44a73f60d1ab66396eac6406065d5c36cc84a51b0c927f30b885c33aeee24
+  data.tar.gz: e7bf0c5bc1e70fab341d8c98f0cef3194e3795bae8c705b38bec555822a670b6a4c5682e4663dfbcc8663969b7bc7fe307856f97ba5e9274e261e2893464ce2c

data/README.adoc

@@ -130,9 +130,15 @@ introduced with `=`, is used.
 
 `:technical-committee:`:: The name of the relevant committee producing the document.
 
-`:published-date:`:: The publication date for the document. Only applies to public documents;
+`:issued-date:`:: The date on which the document was authorised to be published.
+Referred to within NIST as the "Publication Date". This is the date used on the document
+cover page. Only applies to public documents;
 drafts instead have a `:circulated-date:` attribute.
 
+`:published-date:`:: The publication date for the document, when it was physically released.
+Referred to within NIST as the "Release Date". This date is not used on the document cover
+page; `:issued-date:` is used instead. The Release Date is included in NIST bibliographic metadata.
+
 `:uri:`:: The URI to which this standard is published.
 
 `:docnumber:`:: The internal identifier referring to this document. The identifier is a number;
@@ -141,7 +147,7 @@ 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, document volume,
-and edition/revision (e.g. _NIST SP 800 Revision 1_). 
+and edition/revision (e.g. _NIST SP 800 Revision 1_).
 If the `:docidentifier:` value is provided, it will override this composed value.
 
 `:edition:`:: Edition (revision) of the document. The value of
@@ -158,7 +164,7 @@ this attribute will be displayed as part of the heading, prefixed with "Revision
 * `final-review`
 --
 
-`:substage:`:: Document substage. Indicates active status of draft or publication. 
+`: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:
 +
@@ -166,7 +172,7 @@ 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, 
+* `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.
 --
 
@@ -253,7 +259,7 @@ e.g. "Computer Security" for SP 800.
 `: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, 
+`:call-for-patent-claims:`:: Include the Call for Patent Claims in document drafts,
 and the Patent Disclosure Notice in finalised documents.
 
 `:commitment-to-licence:`:: Indicate in the Patent Disclosure Notice that
@@ -268,26 +274,26 @@ 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 
+* 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
 --
 
@@ -345,45 +351,54 @@ 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.
+The name of the organization that has sponsored the document, if applicable. The attribute can
+contain multiple lines and Metanorma formatting.
 
 `:sponsor-logo:`::
 The logo of the sponsoring organization, if applicable.
 
-`:superseding-status`: Document status/stage of the superseding document, if this document is
+`: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. 
+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.
+
+`:superseding-issued-date:`::
+The date at which the document superseding this document was authorised to be 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
@@ -391,7 +406,9 @@ 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
@@ -402,20 +419,20 @@ The following markup is specific to this gem:
 
 === Authority statement
 
-The authority statement in NIST consists of five sections, and these are marked up in
-Metanorma XML with the tags `<authority1>, <authority2>, <authority3>, <authority4>, <authority5>`:
+The authority statement in NIST consists of five sections. They are semantically encoded in Metanorma
+XML under the `boilerplate` tag, as subclauses:
 
-`authority1`:: The initial section of the authority section ("This publication has been developed
+`boilerplate/legal-statement/clause[@id = 'authority1']`:: The initial section of the authority section ("This publication has been developed
 by NIST...").
-`authority2`:: The identifier, revision date, and URL of the document.
-`authority3`:: The boxed disclaimer statement ("Any mention of commercial products or reference to commercial organizations...")
-`authority4`:: The public comment period, for drafts
-`authority5`:: The contact details for comments
+`boilerplate/legal-statement/clause[@id = 'authority2']`:: The identifier, revision date, and URL of the document.
+`boilerplate/legal-statement/clasue[@id = 'authority3']`:: The boxed disclaimer statement ("Any mention of commercial products or reference to commercial organizations...")
+`boilerplate/feedback-statement/clause[@id = 'authority4']`:: The public comment period, for drafts
+`boilerplate/feedback-statement/clause[@id = 'authority5']`:: The contact details for comments
 
 The authority statement has been marked up in Metanorma XML rather than Asciidoctor because of its complexity.
 If you wish to supply a different authority statement, you will need to provide a piece of Metanorma XML corresponding
 to the existing default statement (available from link:lib/asciidoctor/nist/nist_intro.xml[]), and containing
-text corresponding to the sections given above. You can give the location of your own authority statement file 
+text corresponding to the sections given above. You can give the location of your own authority statement file
 relative to the current document through the document attribute `:boilerplate-authority:`.
 
 === Author affiliations
@@ -603,7 +620,7 @@ stem:[A= {x_1, x_2, ..., x_k}]:: The alphabet, i.e., the set of all possible sym
 === Document status
 
 The following table illustrates how transitions between stages of NIST documents are indicated
-using `:status:`, `:substage:`, `:iteration:`, and `:confirmed-date`. 
+using `:status:`, `:substage:`, `:iteration:`, and `:confirmed-date`.
 
 |===
 | ISO stage | NIST | 93 Repeat current phase | 98 Abandon | 99 Proceed
@@ -615,30 +632,103 @@ using `:status:`, `:substage:`, `:iteration:`, and `:confirmed-date`.
 | 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` | | | 
+| 95 Withdrawal | `:status: final`, `:substage: withdrawn` | | |
 |===
 
 In the following, parentheses indicate optional attributes.
 
-* For retired drafts, the following attributes must be provided: `:circulated-date:`, 
+* 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-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
+* For withdrawn published documents, the following attributes must be provided: `:issued-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), 
+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:`, 
+be provided: `:superseding-title:`, (`:superseding-subtitle:`), `:superseding-issued-date:`, `:superseding-status:`,
 `:superseding-doi:`, `:superseding-url:`.
 
+=== Document identifier
+
+There are three identifiers automatically generated by Metanorma for NIST documents; they
+can be overridden by providing a `:docidentifier:` value.
+
+* The NIST identifier is composed as follows:
+** The Abbreviated NIST Series that the document belong to
+** The document identifier within the series
+** "Volume " followed by the volume number, if present
+** A comma, if there is both a volume number and a revision number
+** "Revision " followed by the revision number, if present
+** The draft abbreviation in parentheses, if present:
+*** The iteration number. For public drafts, the first iteration is abbreviated I, the final iteration as F.
+For work-in-progress and preliminary drafts, the first iteration is not shown.
+*** The abbreviation of the draft stage: WD for Work-In-Progress, PreD for Preliminary, PD for public.
+*** So: WD, 2WD, 3WD, FWD; PreD, 2PreD, 3PreD, FPreD; IPD, 2PD, 3PD, FPD
+** The update date, in parentheses, MMM dd, yyyy format, if present. The update date is:
+*** If the document is published (`:status:` starts with `final`), the date of an errata release (`:update-date:`).
+If there is a revision published for the document, that revision is by default now identified by a revision
+number, rather than a publication date; but NIST practice varies, and this can be overridden by providing
+a full identifier in `:docidentifier:`.
+*** If the document is a draft (`:status:` starts with `draft`), the date at which the draft was circulated
+(`:circulated-date:`). If `:circulated-date:` is not provided, the date the document was last revised,
+`:revdate:`, may be used instead; but document citation assumes that the document is stable enough to be cited
+only at the time it is formally released.
+
+=== Hyperlinks
+
+For accessibility, NIST authors are expected to insert tool tips into the hyperlinks they generate in Word documents.
+The equivalent in Metanorma is to include alt text in any hyperlinks in Asciidoctor, using the `title` attribute
+of hyperlinks, as illustrated in the following:
+
+[source,asciidoctor]
+--
+http://www.example.com[See the example.com link,title=tooltip text]
+--
+
+=== Tables
+
+For accessibility, NIST authors are expected to insert titles into tables in Word documents as summaries.
+The equivalent in Metanorma is to include alt text in any hyperlinks in Asciidoctor, using the `alt` attribute
+of tables, as illustrated in the following:
+
+[source,asciidoctor]
+--
+[[table-crossreference-id]]
+.Table caption
+[alt="Table summary, for use in accessible media"]
+|===
+| Head | Head
+
+| Body | Body
+| Body | Body
+|===
+--
 
 
 ////
+=== Sponsor
+
+The title page templates cater for at most one sponsoring organization and its logo. If more than one
+sponsor is involved, manual intervention will be required on the title page.
+
+The sponsor logo (`:sponsor-logo:`) is an image file, and it appears on the left hand side of the Word
+title page, oppose the NIST logo. The sponsor name (`:sponsor:`) appears underneath the logo. The attribute
+can be just the name, or it can be a multi-line attribute, containing Asciidoctor markup. In that case,
+it should be entered using Asciidoctor conventions for multi-line document attributes, with `\ +` used for
+line breaks:
+
+[source,asciidoctor]
+----
+:sponsor-logo:fema.gif
+:sponsor: *Department of Homeland Security* \ + Janet Napolitano, _Secretary_ \ + *Federal Emergency Management Association* \ + Craig Fugate, _Administrator_ \ + *United States Fire Administration* \+ Kelvin J. Cochran, _Assistant Administrator_
+----
+////
+
 
 == Examples
 

data/lib/asciidoctor/nist/biblio.rng

@@ -35,7 +35,28 @@
   </define>
   <define name="status">
     <element name="status">
-      <ref name="LocalizedString"/>
+      <ref name="stage"/>
+      <optional>
+        <ref name="substage"/>
+      </optional>
+      <optional>
+        <ref name="iteration"/>
+      </optional>
+    </element>
+  </define>
+  <define name="stage">
+    <element name="stage">
+      <text/>
+    </element>
+  </define>
+  <define name="substage">
+    <element name="substage">
+      <text/>
+    </element>
+  </define>
+  <define name="iteration">
+    <element name="iteration">
+      <text/>
     </element>
   </define>
   <define name="language">

data/lib/asciidoctor/nist/cleanup.rb

@@ -48,17 +48,17 @@ module Asciidoctor
         end
       end
 
-      def move_authority_into_preface(x, preface)
-        if x.at("//authority")
-          boilerplate = x.at("//authority")
-          preface.add_child boilerplate.remove
+      def move_authority_before_preface(x, preface)
+        if x.at("//boilerplate")
+          boilerplate = x.at("//boilerplate")
+          preface.previous = boilerplate.remove
         else
-          preface.add_child boilerplate(x)
+          preface.previous = boilerplate(x)
         end
       end
 
       def move_sections_into_preface(x, preface)
-        move_authority_into_preface(x, preface)
+        move_authority_before_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

data/lib/asciidoctor/nist/converter.rb

@@ -176,7 +176,7 @@ module Asciidoctor
         a = { id: Asciidoctor::Standoc::Utils::anchor_or_uuid(node) }
         noko do |xml|
           case sectiontype(node)
-          when "normative references" then norm_ref_parse(a, xml, 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

data/lib/asciidoctor/nist/front.rb

@@ -78,34 +78,54 @@ module Asciidoctor
         did
       end
 
+      def id_args(node, dn0)
+        {
+          id: dn0,
+          series: node.attr("series"),
+          revision: node.attr("revision"),
+          vol: node.attr("volume"),
+          stage: node.attr("status") || node.attr("docstage"),
+          iter: node.attr("iteration"),
+          date: /^draft/.match(node.attr("status") || node.attr("docstage")) ?
+          (node.attr("circulated-date") || node.attr("revdate")) :
+          node.attr("updated-date")
+        }
+      end
+
       def metadata_id_compose(node, xml, dn0)
         return unless dn0
-        s = node.attr("series")
-        e = node.attr("revision")
-        v = node.attr("volume")
-        xml.docidentifier add_id_parts(dn0, s, e, v, false),
-          **attr_code(type: "nist")
-        xml.docidentifier add_id_parts(dn0, s, e, v, true),
+        args = id_args(node, dn0)
+        xml.docidentifier add_id_parts(args, false), **attr_code(type: "nist")
+        xml.docidentifier add_id_parts(args, true),
           **attr_code(type: "nist-long")
-        xml.docidentifier add_id_parts_mr(dn0, s, e, v, node.attr("revdate")),
-          **attr_code(type: "nist-mr")
+        xml.docidentifier add_id_parts_mr(args), **attr_code(type: "nist-mr")
+      end
+
+      def MMMddyyyy(isodate)
+        return nil if isodate.nil?
+        Date.parse(isodate).strftime("%B %d, %Y")
       end
 
-      def add_id_parts(dn, series, revision, vol, long)
+      def add_id_parts(args, long)
         vol_delim = " Volume "
         ed_delim = " Revision "
-        series and series_name = long ? SERIES.dig(series.to_sym) :
-          SERIES_ABBR.dig(series.to_sym)
-        dn = (series_name || "NIST #{series}")  + " " + dn
-        dn += "#{vol_delim}#{vol}" if vol
-        dn += "," if vol && revision
-        dn += "#{ed_delim}#{revision}" if revision
+        args[:series] and series_name = long ?
+          SERIES.dig(args[:series].to_sym) :
+          SERIES_ABBR.dig(args[:series].to_sym)
+        dn = (series_name || "NIST #{args[:series]}")  + " " + args[:id]
+        dn += "#{vol_delim}#{args[:vol]}" if args[:vol]
+        dn += "," if args[:vol] && args[:revision]
+        dn += "#{ed_delim}#{args[:revision]}" if args[:revision]
+        stage = IsoDoc::NIST::Metadata.new(nil, nil, {}).stage_abbr(args[:stage], args[:iter])
+        dn += " (#{stage})" if stage
+        dn += " (#{MMMddyyyy(args[:date])})" if args[:date]
         dn
       end
 
-      def add_id_parts_mr(dn, series, revision, vol, revdate)
-        series and name = SERIES_ABBR.dig(series.to_sym).sub(/^NIST /, "")
-        "NIST.#{name}.#{vol}.#{revision}.#{revdate}"
+      def add_id_parts_mr(args)
+        args[:series] and
+          name = SERIES_ABBR.dig(args[:series].to_sym).sub(/^NIST /, "")
+        "NIST.#{name}.#{args[:vol]}.#{args[:revision]}.#{args[:date]}"
       end
 
       def metadata_author(node, xml)
@@ -141,7 +161,7 @@ module Asciidoctor
       end
 
       def metadata_status(node, xml)
-        status = node.attr("status") || "final"
+        status = node.attr("status") || node.attr("docstage") || "final"
         xml.status do |s|
           s.stage status 
           s.substage (node.attr("substage") || "active")
@@ -238,8 +258,8 @@ module Asciidoctor
           b.date **{ type: "circulated" } do |d|
           d.on cdate
         end
-        cdate = node.attr("superseding-published-date") and
-          b.date **{ type: "published" } do |d|
+        cdate = node.attr("superseding-issued-date") and
+          b.date **{ type: "issued" } do |d|
           d.on cdate
         end
       end