Metanorma for NIST markup

Introductory material

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.

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 AsciIDoc 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 lib/metanorma/nist/nist_intro.xml, 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.

: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 AsciIDoc 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

[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:

= 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:

[.executive-summary]
== Executive Summary

This is an executive summary

Errata

Errata are marked up as an AsciIDoc table with role attribute [.errata]. Errata tables must have a header row containing the headings Date, Type, Change, Pages:

[.errata]
|===
|Date |Type |Change |Page

|2019-01-01 |Minor |Repaginated |1-12
|===

As an alternative to this markup, semantic markup of document history can be added to the document, using Metanorma extension and Relaton YAML [added in https://github.com/metanorma/metanorma-nist/releases/tag/v2.4.0]. The change type is represented as amend classification type. The foregoing example would be marked up as follows:

[.preface]
== Misc container

=== document history

[source,yaml]
----
- date:
  - type: updated
    value: 2019-01-01
  amend:
    description: Repaginated
    classification:
      - tag: type
        value: Minor
    location:
      - page=1-12

Clauses

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.

Glossaries

Glossaries are given as definition lists with role attribute [.glossary]:

[.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:

[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.

Blocks

Pseudocode

Pseudocode shall be marked up as an example, with style attribute [pseudocode] (implemented as a macro):

[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:

[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":

[[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]
----
<xccdf:check system="{{{http://oval.mitre.org/XMLSchema/oval-definitions-5}}}">
----
---

In the rest of Metanorma, {{{ …​ }}} is used to introduce AsciiDoc markup into sourcecode. In the NIST flavour, this is done through {{{{ …​ }}}}

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:

[class=steps]
. First Step
. Second Step
. Third Step

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 AsciIDoc, using the alt attribute of tables, as illustrated in the following:

[[table-crossreference-id]]
.Table caption
[alt="Table summary, for use in accessible media"]
|===
| Head | Head

| Body | Body
| Body | Body
|===

Inline markup

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 AsciIDoc, using the title attribute of hyperlinks, as illustrated in the following:

http://www.example.com[See the example.com link,title=tooltip text]