asciidoctor-m3d 0.2.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 842e662db881efd542ce7d9212b641a29f7d0e09
+  data.tar.gz: 726174ec00747868c445e860e4ee14823496d3d9
+SHA512:
+  metadata.gz: 47d301acc7da5911dcc256392ebbb85c5fd84f305127f5a5bdca58aac7b489f03110ab90391495a80572778cfb67f36d083a3d79f05a7e913e0f07be996be1a8
+  data.tar.gz: ac46f2e039e772a2056c71e76573cfa82d795617365ab5e5b850eef524f3238baa4987af58fa60f49eb3ceeb43d439428b15f31b5ff002a7c30d9cf5174fb740

data/.gitignore

@@ -0,0 +1 @@
+.DS_Store

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 open.source@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,7 @@
+source "https://rubygems.org"
+git_source(:github) {|repo| "https://github.com/#{repo}" }
+
+gem "isodoc", github: "riboseinc/isodoc"
+gem "asciidoctor-iso", github: "riboseinc/asciidoctor-iso"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,182 @@
+GIT
+  remote: https://github.com/riboseinc/asciidoctor-iso
+  revision: acb439aa79a102bff01f876b6f19bdf468a47861
+  specs:
+    asciidoctor-iso (0.7.5)
+      asciidoctor (~> 1.5.6)
+      html2doc
+      htmlentities (~> 4.3.4)
+      isodoc
+      nokogiri
+      ruby-jing
+      sass
+      thread_safe
+      uuidtools
+
+GIT
+  remote: https://github.com/riboseinc/isodoc
+  revision: 71a0d3a0f6ed4c001968949187103247de97a879
+  specs:
+    isodoc (0.5.9)
+      asciimath
+      html2doc
+      htmlentities (~> 4.3.4)
+      image_size
+      liquid
+      mime-types
+      nokogiri
+      roman-numerals
+      ruby-xslt
+      thread_safe
+      uuidtools
+
+PATH
+  remote: .
+  specs:
+    asciidoctor-m3d (0.2.5)
+      asciidoctor (~> 1.5.7)
+      asciidoctor-iso (>= 0.7.5)
+      asciimath
+      htmlentities (~> 4.3.4)
+      image_size
+      isodoc
+      mime-types
+      nokogiri
+      ruby-jing
+      ruby-xslt
+      thread_safe
+      uuidtools
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    asciidoctor (1.5.7.1)
+    asciimath (1.0.4)
+    ast (2.4.0)
+    byebug (9.1.0)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    docile (1.3.0)
+    equivalent-xml (0.6.0)
+      nokogiri (>= 1.4.3)
+    ffi (1.9.23)
+    formatador (0.2.5)
+    guard (2.14.2)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    html2doc (0.7.0)
+      asciimath
+      htmlentities (~> 4.3.4)
+      image_size
+      mime-types
+      nokogiri
+      ruby-xslt
+      thread_safe
+      uuidtools
+    htmlentities (4.3.4)
+    image_size (2.0.0)
+    json (2.1.0)
+    liquid (4.0.0)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.13)
+    method_source (0.9.0)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
+    mini_portile2 (2.3.0)
+    nenv (0.3.0)
+    nokogiri (1.8.2)
+      mini_portile2 (~> 2.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    optout (0.0.2)
+    parallel (1.12.1)
+    parser (2.5.1.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.1)
+    pry (0.11.3)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rainbow (3.0.0)
+    rake (12.3.1)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    roman-numerals (0.3.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    rubocop (0.56.0)
+      parallel (~> 1.10)
+      parser (>= 2.5)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-jing (0.0.1)
+      optout (>= 0.0.2)
+    ruby-progressbar (1.9.0)
+    ruby-xslt (0.9.10)
+    ruby_dep (1.5.0)
+    sass (3.5.6)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    shellany (0.0.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    thor (0.20.0)
+    thread_safe (0.3.6)
+    timecop (0.9.1)
+    unicode-display_width (1.3.2)
+    uuidtools (2.1.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  asciidoctor-m3d!
+  asciidoctor-iso!
+  bundler (~> 1.15)
+  byebug (~> 9.1)
+  equivalent-xml (~> 0.6)
+  guard (~> 2.14)
+  guard-rspec (~> 4.7)
+  isodoc!
+  rake (~> 12.0)
+  rspec (~> 3.6)
+  rubocop (~> 0.50)
+  simplecov (~> 0.15)
+  timecop (~> 0.9)
+
+BUNDLED WITH
+   1.16.1

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,275 @@
+= AsciiM3D: Asciidoctor processor for Ribose Standard Documents (M3D)
+
+image:https://img.shields.io/gem/v/asciidoctor-m3d.svg["Gem Version", link="https://rubygems.org/gems/asciidoctor-m3d"]
+image:https://img.shields.io/travis/riboseinc/asciidoctor-m3d/master.svg["Build Status", link="https://travis-ci.org/riboseinc/asciidoctor-m3d"]
+image:https://codeclimate.com/github/riboseinc/asciidoctor-m3d/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/asciidoctor-m3d"]
+
+WARNING: This gem is still under development.
+
+== Functionality
+
+This gem processes http://asciidoctor.org/[Asciidoctor] documents following
+a template for generating M3D documents.
+
+The gem currently inherits from the https://github.com/riboseinc/asciidoctor-iso
+gem, and aligns closely to it. Refer to the ISO gem
+for guidance, including https://github.com/riboseinc/asciidoctor-iso/wiki/Guidance-for-authoring
+
+The following outputs are generated.
+
+* (Optional) An HTML preview generated directly from the Asciidoctor document,
+using native Asciidoctor formatting.
+** http://asciimath.org[AsciiMathML] is to be 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.
+* an XML representation of the document, intended as a document model for M3D
+International Standards.
+* The XML representation is processed in turn to generate the following outputs
+as end deliverable M3D standard drafts.
+** Microsoft Word output (`.doc`), following the style conventions of the
+https://www.m3d.org/m3d-templates.html[M3D Standard Microsoft Word template].
+(In development)
+** PDF (forthcoming)
+** HTML (forthcoming)
+
+This AsciiDoc syntax for writing M3D standards is hereby named "AsciiM3D".
+
+== Usage
+
+[source,console]
+----
+$ asciidoctor a.adoc  # HTML output of Asciidoc file
+$ asciidoctor -b m3d -r 'asciidoctor-m3d' a.adoc  # M3D XML output
+----
+
+The gem translates the document into M3D XML format, and then
+validates its output against the M3D XML 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.
+
+TODO: The gem will then convert the XML to Word Document, HTML, and
+PDF, and output those files with the appropriate file suffixes.
+`lib/asciidoctor/m3d/m3d2wordhtml.rb` is work in progress, and not yet
+integrated into the executable.
+
+=== Content Warnings
+
+The gem also realises several format checks as prescribed in ISO/IEC
+DIR 2, and warns the user about them in the console:
+
+* Numbers with what looks like dots instead of commas for decimal points.
+
+* Groups of numbers without spacing for every three digits. (The gem attempts
+to ignore M3D references.)
+
+* No space before percent sign.
+
+* No bracketing of tolerance in percentage (e.g. `15 ± 7 % .`)
+
+* No recommendations, permissions or requirements (detected by keyword) in:
+foreword, scope, introduction, term examples and examples, notes, footnotes.
+
+* No subclauses that are the only child of a clause. (In clauses, annexes, or
+scopes.)
+
+* 5 levels of subclause nesting. (Never actuated, AsciiDoc only permits 4
+levels of subsections.)
+
+* Non-M3D/IEC reference turning up as normative.
+
+* Term definition starts with an article, or ends with a period.
+
+* Title intro or title part appears in only one of French or English.
+
+== Approach
+
+=== Document model
+
+The Ribose Standard Document model is an instance of the
+https://github.com/riboseinc/isodoc-models[StandardDocument model].
+
+The M3D format ("M3D XML") intends to introduce rigor into the M3D
+standards authoring process, and is prescribed in a separate document.
+
+M3D XML is still under development, but it already contains all the markup
+needed to render a M3D document into HTML.
+
+WARNING: The current RNG model of M3D XML is out of sync with the UML.
+
+=== Asciidoctor
+
+Asciidoctor has been selected as the authoring tool to generate the document
+model representation of M3D standards. It is a document formatting tool like
+Markdown and DocBook, which combines the relative ease of use of the former
+(using relatively lightweight markup), and the rigor and expressively of the
+latter (it has a well-defined syntax, and was in fact initially developed as a
+DocBook document authoring tool). Asciidoctor has built-in capability to output
+Text, DocBook and HTML; so it can be used to preview the file as it is being
+authored.
+
+Note that in order to generate HTML preview output close to what is intended
+in the M3D standard, the Asciidoc
+document includes a fair amount of formatting instructions (e.g. disabling
+section numbering where appropriate, the titling of Appendixes as Annexes), as
+well as M3D boilerplate text, and predefined section headers (sections are
+recognised by fixed titles such as `Normative References`). Authoring M3D
+standards in this fashion assumes that users will be populating an Asciidoc
+template, and not removing needed formatting instructions.
+
+=== Features not visible in HTML preview
+
+The gem uses built-in Asciidoc formatting as much as possible, so that users
+can retain the ability to preview documents; for _Terms and Definitions_
+clauses, which have a good deal of explicit structure, macros have been
+introduced for semantic markup (admitted terms, deprecated terms, etc). The
+default HTML output of an Asciidoc-formatted M3D document is quite close to the
+intended final output, with the following exceptions. Note that the final
+outputs of the conversion (Microsoft Word, PDF, HTML) do not have these exceptions,
+and comply with the M3D Standard specifications.
+
+* _Terms and Definitions_: each term is marked up as an unnumbered subclause,
+the semantic markup of alternate and other terms is not rendered visually.
+
+* _Formulas_: Asciidoctor has no provision for the automated numbering of
+isolated block formulas ("stem"), and does not display the number assigned a
+block formula in its default HTML processor—although it does provide automated
+numbering of examples. Formula numbering is provided in the final outputs
+of the conversion.
+
+* _Missing elements_: The document model does not yet include Asciidoc elements
+that do not appear to be relevant to M3D Standards; these will be ignored in
+generating M3D XML. Those elements include:
+* sidebars (`aside`) (as distinct from warnings),
+* ASCII art/preformatted text (`literal`) (as distinct from sourcecode listings),
+* page breaks (`thematic break`).
+
+* _Markup_: Some connecting text which is used to convey markup structure is
+left out: in particular, `DEPRECATED` and `SOURCE` (replaced by formatting
+macros).
+
+* _Tables_: Table footnotes are treated like all other footnotes: they are
+rendered at the bottom of the document, rather than the bottom of the table,
+and they are not numbered separately.
+
+* _Cross-references_: Footnoted cross-references are indicated with the reference
+text `fn` in m3dlation, or `fn:` as a prefix to the reference text. The default
+HTML processor leaves these as is: if no reference text is given, only `fn`
+will be displayed (though it will still hyperlink to the right reference).
+
+* _References_: The convention for references is that M3D documents are cited
+without brackets by M3D number, and optionally year, whether they are normative
+or in the bibliography (e.g. `M3D 20483:2013`); while all other references are
+cited by bracketed number in the bibliography (e.g. `[1]`). The default HTML
+processor treats all references the same, and will bracket them (e.g. `[M3D
+20483:2013]`). For the same reason, M3D references listed in the bibliography
+will be listed under an M3D reference, rather than a bracketed number.
+
+* _References_: References are rendered cited throughout, since they are
+automated. For that reason, if reference is to be made to both an undated and a
+dated version of an M3D reference, these need to be explicitly listed as
+separate references. (This is not done in the Rice model document, which lists
+M3D 6646, but under _Terms and Definitions_ cites the dated M3D 6646:2011.
+
+* _References_: M3D references that are undated but published have their date
+indicated under the M3D standards format in an explanatory footnote. Because of
+constraints introduced by Asciidoctor, that explanation is instead given in
+square brackets in Asciidoc format.
+
+* _Annexes_: Subheadings cannot preserve subsection numbering, while also
+appearing inline with their text (e.g. Rice document, Annex B.2): they appear
+as headings in separate lines.
+
+* _Annexes_: Cross-references to Annex subclauses are automatically prefixed
+with `Clause` rather than `Annex` or nothing.
+
+* _Metadata_: Document metadata such as document numbers, technical committees
+and title wording are not rendered in the default HTML output.
+
+* _Patent Notice_: Patent notices are treated and rendered as a subsection of
+the introduction, with an explicit subheading.
+
+* _Numbering_: The numbering of figures and tables is sequential in the default
+HTML processor: it does not include the Clause or Annex number. This,
+_Figure 1_, not _Figure A.1_.
+
+* _Notes_: There is no automatic note numbering by the default HTML processor.
+
+* _Review Notes_: The reviewer on the review note is not displayed.
+
+* _Keys_: Keys to formulas and figures are expected to be marked up as
+definition lists consistently, rather than as inline prose.
+
+* _Figures_: Simple figures are marked up as images, figures containing
+subfigures as examples. Numbering by the default HTML processor may be
+inconsistent. Subfigures are automatically numbered as independent figures.
+
+* _Markup_: The default HTML processor does not support CSS extensions such as
+small caps or strike through, though these can be marked up as CSS classes
+through custom macros in Asciidoctor: a custom CSS stylesheet will be needed to
+render them.
+
+
+
+TODO: May need to only encode figures as examples.
+
+== Document Attributes
+
+The gem relies on Asciidoctor document attributes to provide necessary
+metadata about the document. These include:
+
+`:edition:`:: The document edition
+
+`: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)
+
+`:doctype:`:: The document type (see M3D deliverables: The different types of
+M3D publications) (mandatory). The permitted types are:
++
+--
+code:: Code Artifact
+presentation:: Presentation
+proposal:: Proposal; includes IETF DRAFT
+standard:: Recommendation; includes IETF RFC
+report:: report
+--
+
+`:status:``:: The document status. The permitted types are: `proposal`,
+`working-draft`, `committee-draft`, `draft-standard`, `final-draft`,
+`published`, `withdrawn`.
+
+`:technical-committee:`:: The name of the relevant M3D technical committee
+(mandatory)
+
+`:language:` :: The language of the document (only `en` for now)  (mandatory)
+
+
+The attribute `:draft:`, if present, includes review notes in the XML output;
+these are otherwise suppressed.
+
+== AsciiM3D features not also present in AsciiISO
+
+* `+[keyword]#...#+`: encodes keywords, such as "MUST", "MUST NOT". (Encoded as
+`<span class="keyword">...</span>`.
+
+== Data Models
+
+The M3D Standard Document format is an instance of the
+https://github.com/riboseinc/isodoc-models[StandardDocument model]. Details of
+this general model can be found on its page. Details of the M3D modifications
+to this general model can be found on the https://github.com/riboseinc/m3d[M3D model]
+repository.
+
+== Examples
+
+* link:spec/examples/rfc6350.adoc[] is an AsciiM3D version of https://tools.ietf.org/html/rfc6350[RFC 6350].
+* link:spec/examples/rfc6350.html[] is an HTML file generated from the AsciiM3D.
+* link:spec/examples/rfc6350.doc[] is a Word document generated from the AsciiM3D.