= 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://github.com/metanorma/metanorma-nist/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-nist/actions?workflow=rake"] image:https://codeclimate.com/github/metanorma/metanorma-nist/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/metanorma-nist"] image:https://img.shields.io/github/issues-pr-raw/metanorma/metanorma-nist.svg["Pull Requests", link="https://github.com/metanorma/metanorma-nist/pulls"] image:https://img.shields.io/github/commits-since/metanorma/metanorma-nist/latest.svg["Commits since latest",link="https://github.com/metanorma/metanorma-nist/releases"] == Functionality This gem processes https://www.metanorma.com[Metanorma documents] following a template for generating NIST standards. It provides the following functions: . Compiles Metanorma input into the Metanorma-NIST XML format . Validates XML output against the Metanorma-NIST document model ** Errors are reported to console against the XML, and are intended for users to check that they have provided all necessary components of the document. . Metanorma-NIST XML is then converted into desired output formats. The following outputs are supported: * Primary: the canonical Metanorma-NIST XML representation (`.xml`). * Secondary: the Metanorma-NIST XML representation is processed to generate the following outputs as end deliverable NIST documents. ** HTML (`.html`) ** PDF (`.pdf`) ** Word (`.doc`) == Structure This gem inherits from the https://github.com/metanorma/metanorma-standoc gem, and aligns closely to it. === Quickstart Please see https://www.metanorma.com for instructions to get started. 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/metanorma/metanorma-macos-setup/master/metanorma-setup) $ gem install metanorma-cli $ gem install metanorma-nist ---- == Usage Using the `metanorma` CLI: [source,console] ---- $ metanorma --type nist a.adoc # output HTML $ metanorma --type nist --extensions html a.adoc # output just HTML $ metanorma --type nist --extensions xml a.adoc # output Metanorma XML ---- == Authoring Please refer to the Metanorma-ISO documentation for general documentation. * Metanorma-ISO general documentation: https://www.metanorma.com/software/metanorma-iso/ * Metanorma-ISO guidance: https://www.metanorma.com/software/metanorma-iso/docs/guidance/ == Approach === Document model The NIST SP 800 document model is detailed here: * https://github.com/metanorma/metanorma-model-nist[NIST SP 800 document model] It is an instance of the https://github.com/metanorma/metanorma-model-standoc[StandardDocument model]. === Document input Document input to Metanorma is for the compilation of content into the Metanorma XML document. The Metanorma-NIST processor supports AsciiDoc input. Similar to Markdown, AsciiDoc is a lightweight markup format, but combines the rigor and expressivity of DocBook. A number of editors (through plugins) support preview of AsciiDoc files, so textual content can be previewed without running the Metanorma toolchain. The Metanorma processor automates numbering of headings, figures, tables etc, automatically generates references and citations, and the resulting output presentations. NOTE: The Asciidoctor gem is used for AsciiDoc input parsing. == Document attributes === Common attributes Metadata of the document is provided through AsciiDoc document attributes. https://github.com/metanorma/metanorma-standoc[Metanorma-Standoc] documents all common Metanorma document attributes. Where these preexisting metanorma attributes correspond to attributes already used by NIST in their Asciidoctor template, they are treated as synonyms of the Metanorma attributes. The attributes relevant to NIST documents include: `:edition:`:: The document version; e.g. `2.0`. `:revdate:`:: The date the document was last updated. `:copyright-year:`:: The year which will be claimed as when the copyright for the document was issued. `: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. `:technical-committee:`:: The name of the relevant committee producing the document. `: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; 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, document volume, and edition/revision (e.g. _NIST SP 800 Revision 1_). If the `:docidentifier:` value is provided, it will override this composed value. CSWP publications do not have a distinct `:docidentifier:` or `:docnumber:`: they are identified by their `:issued-date:`. `:status:`:: Document status/stage. The permitted types are: + -- * `draft-internal` * `draft-wip` * `draft-prelim` * `draft-public` * `draft-approval` * `final` (default: document is published) * `final-review` -- `: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}`:: The full name of a person who is a contributor to the document, their organization, and the address of that person or organization. In NIST, only the city is given as the address. A second person is indicated by using a numeric suffix: `:fullname:`, `:fullname_2:`, `fullname_3:`, &c. The same convention applies to all the following attributes. [[surname]] `:surname{_i}:`:: The surname of a person who is a contributor to the document. [[givenname]] `:givenname{_i}:`:: The given name(s) of a person who is a contributor to the document. `:initials{_i}:`:: The initials(s) of a person who is a contributor to the document. [[role]] `:role{_i}:`:: The role of a a person who is a contributor to the document. By default, they are coded as an `editor`; they can also be represented as an `author`. `:affiliation{_i}:`:: The organizational affiliation of a person who is a contributor to the document. `:address{_i}:`:: 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 `: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. `:language:`:: Two-letter code (ISO 639-1) of the language the document is written in. Defaults to `en`. If multiple languages are used in the document, comma-delimited; e.g. `en,fr`. === 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). Will be stored in Metanorma XML under the `` tag, with the prefix `Revision `. `:version:`:: The document version, when titled as version. Will be stored in Metanorma XML under the `` tag, with the prefix `Version `. `: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. `:part:`:: The part number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). `:section:`:: The section number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). `:supplement:`:: The supplement number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). `:index:`:: The index number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). `:update:`:: The update number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). `: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. `:keywords:`:: Comma-delimited list of the keywords associated with the document. `: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. (Not applicable to CSWP.) `:commitment-to-licence:`:: Indicate in the Patent Disclosure Notice that notice and commitment to license have been received. (Not applicable to CSWP.) `:patent-contact:`:: Contact for the Call for Patent Claims or Patent Disclosure Notice. If not supplied, `:doc-email:` is used. (Not applicable to CSWP.) `: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 * nist-cswp * nist-csts -- Documents belonging to different series are expected to be rendered differently. As of this writing, styling has been provided for `nist-cswp` (Cybersecurity White Papers), `nist-csts` (Cybersecurity Technical Specifications, added in v1.2.10), and for `nist-sp` (SP-800). `:series-title:`:: (Added in v1.2.10) `:series-mrprefix:`:: (Added in v1.2.10) `:series-abbrev:`:: (Added in v1.2.10) The formal documents published by NIST belong to a registered list of series, each with a predefined title and abbreviation. Non-formal documents instead belong to ad hoc series defined for the purposes of Metanorma, such as `nist-csts`. That particular series acts as an umbrella for user-defined series of publications; so when it is used, the user needs to provide a title (e.g. "Automated Cryptographic Validation Protocol") and abbreviation (e.g. ACVP) for the user-defined series. The user also needs to provide the prefix by which the series will be identified in the machine-readable NIST identifier, when it is at variance with the abbreviation. + -- In this case, CSTS is retained as the primary series of the publication (and all CSTS documents are rendered the same way), and ACVP is modelled as a secondary series specific to CSTS. However, the series information rendered for the document involves the user-defined series, not CSTS itself. -- `: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. `:boilerplate-authority:`:: Nominate a Metanorma XML file encoding the authority statement of the document, to overwrite the default authority statement included in the gem (link:lib/asciidoctor/nist/nist_intro.xml[], link:lib/asciidoctor/nist/nist_intro_cswp.xml[]), in case the document is historical, and needs to be generated with a previous authority statement. `:obsoletes:`:: One or more NIST document that this NIST document standard renders obsolete; implies that the obsoleted document is withdrawn, and no longer in effect. Comma delimited. 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_. 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 document may still remain in effect. Comma delimited. Format is document identifier, e.g. _SP 800-53A Rev. 1_ NOTE: The distinction between `obsoletes` and `supersedes` is the withdrawal date of the original document (`obsoleted-date`); that means that the distinction is predictable given that external information. The distinction between `obsoleted-by` and `superseded-by`, in the same way, is made by the withdrawal date of the current document. Relaton does not differentiate between the two relations for that reason. `:superseded-by`:: 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 (`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. 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 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-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 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] gem documents the customisations of Asciidoctor markup common to all metanorma gems. The following markup is specific to this gem: === Authority statement The authority statement in NIST consists of five sections. They are semantically encoded in Metanorma XML under the `boilerplate` tag, as subclauses: `boilerplate/legal-statement/clause[@id = 'authority1']`:: The initial section of the authority section ("This publication has been developed by NIST..."). (Not applicable to CSWP.) `boilerplate/legal-statement/clause[@id = 'authority2']`:: The identifier, revision date, and URL of the document. (Not applicanble to CSWP.) `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 link:lib/asciidoctor/nist/nist_intro_cswp.xml[]), and containing 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 Each author of a NIST document may have their own organizational affiliation, and optionally a city for that organization. This information is given using the `:fullname:`, `:affiliation:`, and `:address:` document attributes, with separate organization and address listings for each author. Metanorma will take care of grouping authors together by organization. [source,asciidoctor] -- :fullname: Hildegard Ferraiolo :affiliation: Computer Security Division, Information Technology Laboratory :fullname_2: Ketan Mehta :affiliation_2: Computer Security Division, Information Technology Laboratory :fullname_3: Nabil Ghadiali :affiliation_3: National Gallery of Art :address_3: Washington, DC :fullname_4: Jason Mohler :affiliation_4: Electrosoft Services, Inc. :address_4: Reston, Virginia :fullname_5: Vincent Johnson :affiliation_5: Electrosoft Services, Inc. :address_5: Reston, Virginia :fullname_6: Steven Brady :affiliation_6: Electrosoft Services, Inc. :address_6: Reston, Virginia -- Note that the organization location must be given for every author it applies to; rendering will differentiate between different locations of the same organization. === Preface The following sections are automatically moved to the document preface. * Foreword * Abstract * Keywords (drawn from document attribute, see above) In addition, any clause that has the `preface` style attribute is also moved to the document preface, regardless of where it appears in the source Asciidoctor document. These clauses appear in the document preface in the order they are given in the source document. Examples of preface clauses include: * Supplemental Content * Acknowledgements * Audience * Document Conventions * Compliance with NIST Standards and Guidelines * Conformance Testing * Note to Reviewers * Note to Readers * Trademark Information [source,asciidoctor] -- [preface] == Acknowledgemnts This section will be moved to the document preface, after the abstract and keywords. -- Note that any clause titled "Note to Reviewers" will be removed from rendering unless 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 `[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 with the role 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 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 Pseudocode shall be marked up as an example, with style attribute `[pseudocode]` (implemented as a macro): [source,asciidoctor] ---- [pseudocode] ==== _Input: S=(s1,...,sL)_ _Output:_ Shuffled _S=(s1,...,sL)_ . *for* _i_ *from* _L_ *downto* 1 *do* .. Generate a random integer _j_ such that 1<=_j_<=_i_ .. Swap _s~j~_ and _s~i~_ ==== ---- Pseudocode will respect initial indentation in paragraph lines, with line breaks: [source,asciidoctor] ---- [pseudocode] ==== *def* __increment__(x) + x = x + 1 + *enddef* ==== ---- They will be rendered as figures, but are not included in the count of figures of the document. (If they must be included, embed them within another figure.) === Recommendations, requirements, and permissions Recommendations, requirements, and permissions shall be marked up as examples, with style attribute "recommendation", "requirement", "permission": [source,asciidoctor] ---- [[recommend63]] [recommendation] ==== Because having on-card role and permission information would raise difficult challenges concerning update and revocation, PACS permissions should generally be stored in a PACS facilities-based component, such as a panel or controller database. ==== ---- Recommendations, requirements, and permissions are treated like other assets in text, and automatically numbered and labelled: do not include a "Recommendation" etc. label with them. === Variables within sourcecode Variables within sourcecode are rendered as non-monospace italicised text. To indicate such variables, `{{{ ... }}}` shall be used as markup within the sourcecode block, which will be converted to the tag `nistvariable` in Metanorma XML: [source,asciidoctor] --- [source] ---- ---- --- === Errata Errata are marked up as an Asciidoctor table with role attribute `[.errata]`. Errata tables must have a header row containing the headings _Date, Type, Change, Pages_: [source, asciidoctor] ---- [.errata] |=== |Date |Type |Change |Page |2019-01-01 |Minor |Repaginated |1-12 |=== ---- === Lists If an ordered list is intended to describe “steps” within a process, it should start with Arabic numbers and should be encoded with the class `steps`: Encoding an ordered list as steps: [source, asciidoctor] ---- [class=steps] . First Step . Second Step . Third Step ---- === Glosaries Glossaries are given as definition lists with role attribute `[.glossary]`: [source,asciidoctor] ---- [.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. ---- === References Bibliographies in NIST are contained within annexes: [source,asciidoctor] ---- [appendix] == References LAWS, POLICIES, DIRECTIVES, REGULATIONS, MEMORANDA, STANDARDS, AND GUIDELINES [bibliography] === Legislation and Executive Orders * [[[ref1,1]]] E-Government Act [includes FISMA] (P.L. 107-347), December 2002. ---- Provided there is only one bibliography in the document, it is automatically titled _References_. If an annex contains a single bibliography, then the annex and the bibliography are treated as equivalent: the bibliography does not have a distinct title. === 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` or `status: draft-prelim` | 20 Preparatory | `status: draft-prelim` | | `status: draft-prelim`, `substage: retired` | `status: draft-prelim`, `substage: withdrawn` or `status: draft-public` | 40 Enquiry | `status: draft-public` | `status: draft-public`, `:iteration: 2`, `:iteration: 3` ... `:iteration: final` | `:status: draft-public`, `:substage: retired` | `:status: draft-public`, `:substage: withdrawn` or `draft-approval` | 50 Approval | `status: draft-approval` | | `:status: draft-approval`, `: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: `: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), `: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-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 See https://gitlab.com/metanorma/mn-samples-nist (private repository)