Metanorma for NIST markup

Introductory material

Document status

Stage progression

The following table illustrates how transitions between stages of NIST documents are indicated using a combination of:

• :status:

• :substage:

• :iteration:

• :confirmed-date

ISO stage	NIST stage	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 in order to handle retired drafts:

:circulated-date:

The date when the draft was circulated.

:abandoned-date:

The date when the draft was abandoned.

The following attributes are optional:

:bib-additional-note:

Additional notes related to the draft. (Optional)

For withdrawn drafts

The following attributes must be provided in order to handle withdrawn drafts:

:circulated-date:

The date when the draft was circulated.

:obsoleted-date:

The date when the draft was obsoleted.

:superseding-status:

The status of the superseding document.

The following attributes are optional:

:superseding-iteration:

The iteration number of the superseding document. (Optional)

:superseding-title:

The title of the superseding document. (Optional)

:superseding-subtitle:

The subtitle of the superseding document. (Optional)

:superseding-circulated-date:

The date when the superseding document was circulated. (Optional)

:superseding-doi:

The DOI of the superseding document. (Optional)

:superseding-url:

The URL of the superseding document. (Optional)

:bib-additional-note:

Additional notes related to the withdrawn draft. (Optional)

For withdrawn published documents

The following attributes must be provided in order to handle withdrawn published documents:

:issued-date:

The date when the document was issued.

:obsoleted-date:

The date when the document became obsolete.

:superseded-date:

The date when the transition period started, during which both the current and superseding documents were in effect, if applicable. If not applicable, this has the same value as :obsoleted-date:.

:revdate:

The date when the withdrawal notice was added to the document.

:obsoleted-by:

The identifier of the superseding document.

:nist-division:

The division within NIST responsible for the document.

The following attributes are optional:

:bib-additional-note:

Additional notes related to the withdrawn document. The "Related Information" section in the withdrawn document cover page. (Optional)

:bib-withdrawal-note:

The withdrawal note to be included in the document bibliography. (Optional)

:bib-withdrawal-announcement-link:

The link to the withdrawal announcement. (Optional)

If details of the superseding document are not available to be retrieved from Relaton NIST data through auto-fetching from the metadata referenced by :obsoleted-by:, the following attributes must be provided:

:superseding-title:

The title of the superseding document.

:superseding-subtitle:

The subtitle of the superseding document. (Optional)

:superseding-issued-date:

The date when the superseding document was issued.

:superseding-status:

The status of the superseding document.

:superseding-doi:

The DOI of the superseding document.

:superseding-url:

The URL of the superseding document.

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 applicable to CSWPs.)

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/metanorma/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 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]
=== Acknowledgments
This section will be moved to the document preface, after the abstract and keywords.

Note	Any clause titled "Note to Reviewers" will be removed from rendering unless the document is in draft (has a :draft: attribute).

Abstract

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

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 as shown below.

= 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

The Executive Summary section is encoded using the role attribute [.executive-summary].

It is rendered after all other preface sections:

[.executive-summary]
== Executive Summary

This is an executive summary

Errata / Revision history

Revision history can be encoded using detailed change history [added in https://github.com/metanorma/metanorma-nist/releases/tag/v2.4.0].

The change type is represented as amend classification type.

Example 1. Errata of a NIST document encoding using detailed change history

[.preface]
== metanorma-extension

=== document history

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

Alternatively, Metanorma for NIST supports the "Errata" encoding, which is a table with role attribute [.errata].

Errata tables must have a header row containing the headings: Date, Type, Change, Pages.

The previous example would be encoded as:

Example 2. Encoding changes using the errata table

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

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

Clauses

Terms and definitions

Glossaries in NIST documents correspond to "Terms and 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 and 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 are encoded as examples, with the style attributes recommendation, requirement, permission.

Example 3. Example of encoding a recommendation in NIST

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

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

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 multi-line AsciiDoc markup encoded in one line. In that case, it should be entered using AsciiDoc conventions for multi-line document attributes, with \ + used for line breaks.

Example 4. Sponsorship information with multi-line sponsor name

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