metanorma-nist 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d4336b5e5cd72fefe2e42d96ffdc559a438aad39e71e3f8dca8bed5c6a926c9
+  data.tar.gz: 4a926e7415482403215b1bc1f6d1b80b642cfc484b0484bea918bbe670fb0716
+SHA512:
+  metadata.gz: 80c9d531f6c049b6a786127c3e1ed4826a1fe65a67a2d15464abe957827b270e01a1723792f5f279021853a8d17234b737b0e9a21d9ff70a61028ab88ddf1622
+  data.tar.gz: 49393e419f14a068b5cb92aec30ad00422195da412ffd6bdab43e4eead7e3ea726efd18d91e1c61d186614a0f351963db545e3751efff958a420ffb4647a9b18

data/.hound.yml

@@ -0,0 +1,3 @@
+ruby:
+  Enabled: true
+  config_file: .rubocop.yml

data/.rubocop.yml

@@ -0,0 +1,10 @@
+# This project follows the Ribose OSS style guide.
+# https://github.com/riboseinc/oss-guides
+# All project-specific additions and overrides should be specified in this file.
+
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+AllCops:
+  TargetRubyVersion: 2.3
+Rails:
+  Enabled: true

data/.travis.yml

@@ -0,0 +1,16 @@
+dist: trusty
+sudo: false
+language: ruby
+rvm:
+  - 2.5
+  - 2.4
+  - 2.3
+  - ruby-head
+before_install:
+  - gem install bundler -v 2.0.1
+  - npm install -g puppeteer
+  - npm install
+  - unset _JAVA_OPTIONS
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at ronald.tse@ribose.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+git_source(:github) {|repo| "https://github.com/#{repo}" }
+
+gemspec

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2018, Ribose
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,358 @@
+= 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/riboseinc/metanorma-nist/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-nist"]
+image:https://codeclimate.com/github/riboseinc/metanorma-nist/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/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/riboseinc/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/riboseinc/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/riboseinc/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/
+
+
+////
+** http://asciimath.org[AsciiMathML] is used for mathematical formatting.
+The gem uses the https://github.com/asciidoctor/asciimath[Ruby AsciiMath parser],
+which is syntactically stricter than the common MathJax processor;
+if you do not get expected results, try bracketing terms your in AsciiMathML
+expressions.
+////
+
+
+== Approach
+
+=== Document model
+
+The NIST SP 800 document model is detailed here:
+
+* https://github.com/riboseinc/metanorma-model-nist[NIST SP 800 document model]
+
+It is an instance of the
+https://github.com/riboseinc/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/riboseinc/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 OGC 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:`:: The main component of the English title of the document
+(mandatory). (The first line of the AsciiDoc document, which contains the title
+introduced with `=`, is ignored)
+
+`:technical-committee:`:: The name of the relevant committee producing the document (mandatory). 
+
+`: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.
+
+`:draft:`:: If present, review notes are included in the
+Metanorma XML output; otherwise they are suppressed. The value of
+this attribute will be displayed as part of the heading, prefixed with "Revision".
+
+////
+
+`:doctype:`:: The document type (mandatory). The permitted types are:
++
+--
+* Standards
+`standard`::: Implementation Standard
+`standard-with-suite`::: Implementation Standard with Compliance Suite
+`abstract-specification`::: Abstract Specification
+`community-standard`::: Community Standard
+`profile`::: Profile / Application Profile
+`best-practice`::: Best Practices Document
+
+* Other
+`engineering-report`::: Engineering Report
+`discussion-paper`::: Discussion Paper
+`reference-model`::: OGC Reference Model
+`user-guide`::: User Guide
+`policy`::: OGC Policy Document
+`guide`::: Guide
+`amendment`::: Technical Amendment
+`technical-corrigendum`::: Corrigendum (errata) Changes to OGC Standards
+`administrative`::: Internal administrative documents
+--
+
+`:status:`:: Document status/stage. The permitted types are:
++
+`rfc`::: OGC RFC (proposal)
+`candidate`::: Candidate Standard
+`published`::: Published
+`deprecated`::: Deprecated
+`retired`::: Retired
+
+`:committee:`:: The name of the relevant committee producing the document (mandatory). The legal values are:
+`technical`, `planning`, `strategic-member-advisory`
+`:subcommittee:`:: The name of the relevant subcommittee producing the document
+`:workgroup:` (OGC: `:workingGroup:`):: The name of the relevant working group producing the document (mandatory)
+
+`:published-date:` (OGC: `:publicationDate:`):: The publication date for the document.
+`:issued-date:`  (OGC: `:approvalDate:`):: The approval date for the document.
+`:created-date:`:: The creation date for the document.
+`:received-date:`  (OGC: `:submissionDate:`):: The date at which the document was submitted to the standards body.
+
+////
+
+=== NIST-specific attributes
+
+The following document attributes are specific to this document class:
+
+`:subtitle:`:: Document subtitle.
+
+`:keywords:`:: Comma-delimited list of the keywords associated with the document.
+
+`:fullname{_i}:`:: The full name of a person who is a contributor to the document.
+A second person is indicated by using a numeric suffix: `:fullname:`, `:fullname_2:`, `fullname_3:`, &c.
+
+`:surname{_i}:`:: The surname of a person who is a contributor to the document.
+`:givenname{_i}:`:: The given name(s) of a person who is a contributor to the document.
+`: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`.
+
+`:email:`:: Email contact for document
+
+== Asciidoctor features specific to NIST
+
+The https://github.com/riboseinc/metanorma-standoc[metanorma-standoc]
+gem documents the customisations of Asciidoctor markup common to all metanorma gems.
+The following markup is specific to this gem:
+
+=== Preface
+
+The following sections are automatically moved to the document preface.
+
+* 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`.
+
+=== 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
+
+NIST documents do not provide for an extensive Terms & Definitions structure, as seen
+in ISO and ISO-derived standards. Instead, they use acronyms and glossary appendixes.
+These should be given as simple definition lists, without extensive embedded notes, examples,
+or sources.
+
+=== 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]
+----
+<xccdf:check system="{{{http://oval.mitre.org/XMLSchema/oval-definitions-5}}}">
+----
+---
+
+=== 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.
+
+////
+