= 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/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. == Functionality This gem processes Metanorma documents into the NIST document class. 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. `:published-date:`:: The publication date for the document. `: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, 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 this attribute will be displayed as part of the heading, prefixed with "Revision". `:status:`:: Document status/stage. The permitted types are: + -- * `draft-internal` * `draft-wip` * `draft-prelim` * `draft-public` * `draft-withdrawn` * `draft-retire` * `final` (default: document is published) * `final-review` * `final-withdrawn` -- `: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 `:status: draft-withdrawn`, `status: final-withdrawn`), but will be in the future, that is still indicated in the rendering of the document. === NIST-specific attributes The following document attributes are specific to this document class: `:title-sub:`:: The subtitle of the document. `: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. `:commitment-to-licence:`:: Indicate in the Patent Disclosure Notice that 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. `: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[]), 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_ `: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_ `: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_ `: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`), but will be in the future, that is still indicated in the rendering of the document. == 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, and these are marked up in Metanorma XML with the tags `, , , , `: `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 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 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 in the preface with the title Executive Summary. It is rendered after all other preface sections. === 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": [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~_ ==== ---- They will be rendered as figures, and included in the count of figures of the document. === 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 style 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 |=== ---- === Glosaries Glossaries are given as definition lists with style 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. ---- //// == Examples //// * link:spec/examples/rfc6350.adoc[] is an Metanorma AsciiDoc version of https://tools.ietf.org/html/rfc6350[RFC 6350]. * link:spec/examples/rfc6350.html[] is an HTML file generated from the Asciidoctor. * link:spec/examples/rfc6350.doc[] is a Word document generated from the Asciidoctor. ////