metanorma-mpfd 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfc1b89acbeb299bef9437ea614dd60ffb37dae39c15cfb97bfe6c6f10dd96d9
-  data.tar.gz: 613740b76c6fb47a0a2f0d3169211dddd067457f9ddbc4f88bd1a7482125a5bf
+  metadata.gz: 16aa0d3330809464979d425181b5ecbdaa5d24b5f38a4c6ed29cfc7376291b28
+  data.tar.gz: 05b5d56e2ab0edbbf69373c85ddd1bd8070dc06683fe15214ad04eca897abe4c
 SHA512:
-  metadata.gz: 753b6939a96a5f666b6540ffbce379d26d5200530dc2b3a4a81e8eda2df343c51a890dead4c455723392191a481a7f83e8a8fc2a39d5e3e9765e77da91b87ade
-  data.tar.gz: e72ba32a437526c8e047bddadde880a37a34a836d8b20cd2a7601e96232d3591ed3319633e1452775e788b6afaf4e98ad3c56f206b903e2ad2d4521b3c6c550b
+  metadata.gz: 92d22d04a12532be21d51535b68da3cf3d4df3a49cf0c9fd853975e4479fa30ad34bb5e1329c59d6f22ff991371c1017e91f8b09a0c70654dfc2c0da038909b8
+  data.tar.gz: 5b77a57e4e14e78ba2fbb34c4def5cf53ae7871f5987cd16a9ca1b3ceeb0f5f52c6c87edcfe7e2847845d7a78783f9a0e40b47ba0f8a4f124ec5c1554c5d4ccf

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/README.adoc

@@ -1 +1,302 @@
-= metanorma-mpfd
+= Metanorma-MPFD: Metanorma processor for MPFA documents
+
+image:https://img.shields.io/gem/v/metanorma-mpfd.svg["Gem Version", link="https://rubygems.org/gems/metanorma-mpfd"]
+image:https://img.shields.io/travis/riboseinc/metanorma-mpfd/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-mpfd"]
+image:https://codeclimate.com/github/riboseinc/metanorma-mpfd/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/metanorma-mpfd"]
+
+WARNING: This gem is still under development. Moreover, unlike other Metanorma gems, 
+there is no formal MPFD specification, and this work is still currently exploratory.
+
+== Functionality
+
+This gem processes http://asciidoctor.org/[Asciidoctor] documents following
+a template for generating documents for the http://www.mpfa.org.hk[Mandatory Provident Fund Schemes Authority of Hong Kong]
+(MPFA). (MPFD stands for Mandatory Provident Fund Schemes Authority Documents.)
+
+The gem currently inherits from the https://github.com/riboseinc/metanorma-standoc
+gem, and aligns closely to it. Refer to the ISO gem documentation
+for guidance, including https://github.com/riboseinc/metanorma-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 MPFD
+International Standards.
+* The XML representation is processed in turn to generate the following outputs
+as end deliverable MPFD standard drafts.
+** DOC
+** HTML
+
+== Usage
+
+The preferred way to invoke this gem is via the `metanorma` script:
+
+[source,console]
+----
+$ metanorma --type mpfd a.adoc                   # output HTML and DOC
+$ metanorma --type mpfd --extensions html a.adoc # output just HTML
+$ metanorma --type mpfd --extensions doc a.adoc  # output just DOC
+$ metanorma --type mpfd --extensions xml a.adoc  # output MPFD XML
+----
+
+The gem translates the document into Metanorma XML format, and then
+validates its output against the Metanorma 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.
+
+The gem then converts the XML into HTML and DOC.
+
+Sample documents are available at http://github.com/riboseinc/mpfd-documents/
+
+=== Installation
+
+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-mpfd
+$ gem install metanorma-cli
+----
+
+The metanorma-cli gem is the command-line interface for the Metanorma tool suite
+(incorporating the `metanorma` executable seen above).
+
+== Approach
+
+=== Document model
+
+The MPFD model is an instance of the
+https://github.com/riboseinc/isodoc-models[StandardDocument model].
+
+The Metanorma XML format intends to introduce rigor into the MPFD
+standards authoring process, and is prescribed in a separate document.
+
+=== Asciidoctor
+
+Asciidoctor has been selected as the authoring tool to generate the document
+model representation of MPFD documents. 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.
+
+[[model_additions]]
+== Asciidoctor model additions
+
+Refer also to https://github.com/riboseinc/metanorma-standoc/blob/master/README.adoc; this section lists additions specific only to metanorma-mpfd
+
+All the following modifications to the basic Metanorma model are provisional, as a full analysis of the
+formatting requirements of MPFD has not yet been conducted.
+
+=== Glossary
+
+Sections with the title `glossary` are treated as equivalent to `Terms and Definitions`
+in other Metanorma docuemnts.
+
+[source,asciidoctor]
+--
+== Glossary
+=== Term
+
+Definition
+
+=== Term 2
+
+Definition 2
+--
+
+Also unlike other Metanorma documents, the glossary is considererd part of the document
+preface, along with the foreword and introduction, and is moved to the preface regardless
+of where it appears in the source Asciidoctor document.
+
+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.
+
+[source,asciidoctor]
+--
+[preface]
+== Initial Discussion
+This section will be moved to the document preface, after the foreword, introduction,
+and glossary.
+--
+
+=== Guidance clauses
+
+Compliance documents in the MPFA (e.g. https://github.com/riboseinc/mpfd-documents/blob/master/compliance/mpfd-compliance.adoc)
+present compliance standards, following by an "Explanatory Notes and Guidance" clause. That clause is nested within the
+standards clause, and has a special identifier: the standards clause identifier, followed by E.
+
+In MPFD Asciidoctor, the "Explanatory Notes and Guidance" clause is tagged with a `.guidance` role attribute,
+and should be entered as a sibling clause to the standard clause it elaborates on:
+
+[source,asciidoctor]
+--
+== Compliance Programme to Address Statutory Obligations
+
+An approved trustee should have in place a compliance programme to help it meet its statutory obligations.
+
+[.guidance]
+== Explanatory Notes and Guidance
+
+An approved trustee must comply with obligations under the Legislation, including the general trustee duties as well as specific requirements relating to the operation of MPF schemes.
+--
+
+This will be rendered as follows:
+
+____
+*1. Compliance Programme to Address Statutory Obligations*
+
+An approved trustee should have in place a compliance programme to help it meet its statutory obligations.
+
+_1E. Explanatory Notes and Guidance_
+
+An approved trustee must comply with obligations under the Legislation, including the general trustee duties as well as specific requirements relating to the operation of MPF schemes.
+____
+
+=== Container clauses
+
+MPFD docuemnts follow a hierarchically numbered clause structure. However, there are some floating titles
+in MPFD which group clauses together, but are not numbered themselves. These are tagged in MPFD Asciidoctor
+with a `.container` role attribute. When the gem numbers clauses, these containers are ignored.
+
+[source,asciidoctor]
+--
+== MPFD Structure
+
+[.container]
+=== Benefits
+
+==== Autonumbering
+
+==== Automaated cross-references
+
+[.container]
+=== Challenges
+
+==== No WYSIWYG
+
+==== Command Line Interface
+--
+
+Without the `.container` tags, the foregoing example would be rendered in HTML as:
+
+[source,html]
+--
+<h1>1. MPFD Structure</h1>
+
+<h2>1.1. Benefits</h2>
+
+<h3>1.1.1. Autonumbering</h3>
+
+<h3>1.1.2. Automated cross-references</h3>
+
+<h2>1.2. Challenges</h2>
+
+<h3>1.2.1. No WYSIWYG</h3>
+
+<h3>1.2.2. Command Line Interface</h3>
+--
+
+With the `.container` tags, the nesting of clauses is the same, but the container titles
+are at the same level as their parent sections, and are ignored in numbering:
+
+[source,html]
+--
+<h1>1. MPFD Structure</h1>
+
+<h1>Benefits</h1>
+
+<h3>1.1. Autonumbering</h3>
+
+<h3>1.2. Automated cross-references</h3>
+
+<h1>Challenges</h1>
+
+<h3>1.3. No WYSIWYG</h3>
+
+<h3>1.4. Command Line Interface</h3>
+--
+
+=== Paragraph numbering
+
+Currently paragraph numbering at the terminal node level is implemented by giving the paragraph a blank section title,
+at the appropriate nesting level, which makes it a separate subclause. with an inline clause number.
+
+[source,asciidoctor]
+--
+[[clause1]]
+== Relationship between MPF trustees and promoters
+
+[[clause1-1]]
+=== {blank}
+
+The Authority imposes a number of conditions when approving applications to become an approved MPF trustee. 
+--
+
+This is rendered as
+
+[source,html]
+--
+<div id="clause1">
+        <h1>1.&#xA0; Relationship between MPF trustees and promoters</h1>
+        <div id="clause1-1"><h2>1.1. </h2>
+
+  <p id="_">The Authority imposes a number of conditions when approving applications to become an approved MPF trustee.</p>
+</div>
+</div>
+--
+
+== Document Attributes
+
+The gem uses the document attributes defined for metanorma-standoc (see
+the https://github.com/riboseinc/metanorma-model-standoc/blob/master/README.adoc[metanorma-standoc README]).
+
+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 RSD deliverables: The different types of
+MPFD publications) (mandatory). 
+
+`:status:`:: The document status; e.g. `published`, `draft`.
+
+`:committee:`:: The name of the relevant authoring committee 
+`:committee-type:`:: The type of the relevant authoring committee
+
+`: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.
+
+== Data Models
+
+The MPFD 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. 
+
+== Examples
+
+Sample documents are available at http://github.com/riboseinc/mpfd-documents/

data/lib/asciidoctor/mpfd/biblio.rng

@@ -259,6 +259,9 @@
   </define>
   <define name="uri">
     <element name="uri">
+      <optional>
+        <attribute name="type"/>
+      </optional>
       <data type="anyURI"/>
     </element>
   </define>
@@ -384,7 +387,7 @@
   </define>
   <define name="LocalityType">
     <data type="string">
-      <param name="pattern">section|clause|part|paragraph|chapter|page|whole|table|annex|figure|note|example|volume|issue|locality:[a-zA-Z0-9_]+</param>
+      <param name="pattern">section|clause|part|paragraph|chapter|page|whole|table|annex|figure|note|list|example|volume|issue|locality:[a-zA-Z0-9_]+</param>
     </data>
   </define>
   <define name="referenceFrom">
@@ -411,6 +414,20 @@
       <ref name="BibliographicItem"/>
     </element>
   </define>
+  <define name="relaton_collection">
+    <element name="relaton-collection">
+      <optional>
+        <attribute name="type"/>
+      </optional>
+      <ref name="btitle"/>
+      <zeroOrMore>
+        <ref name="contributor"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="docrelation"/>
+      </zeroOrMore>
+    </element>
+  </define>
   <define name="BibItemType" combine="choice">
     <choice>
       <value>article</value>
@@ -444,6 +461,9 @@
         <ref name="BibItemType"/>
       </attribute>
     </optional>
+    <optional>
+      <ref name="fetched"/>
+    </optional>
     <choice>
       <oneOrMore>
         <ref name="btitle"/>
@@ -456,6 +476,9 @@
     <zeroOrMore>
       <ref name="docidentifier"/>
     </zeroOrMore>
+    <optional>
+      <ref name="docnumber"/>
+    </optional>
     <zeroOrMore>
       <ref name="bdate"/>
     </zeroOrMore>
@@ -523,6 +546,14 @@
       <ref name="FormattedString"/>
     </element>
   </define>
+  <define name="fetched">
+    <element name="fetched">
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
+    </element>
+  </define>
   <define name="validity">
     <element name="validity">
       <optional>
@@ -538,17 +569,26 @@
   </define>
   <define name="validityBegins">
     <element name="validityBegins">
-      <data type="dateTime"/>
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
     </element>
   </define>
   <define name="validityEnds">
     <element name="validityEnds">
-      <data type="dateTime"/>
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
     </element>
   </define>
   <define name="validityRevision">
     <element name="revision">
-      <data type="dateTime"/>
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
     </element>
   </define>
   <define name="TypedTitleString">
@@ -599,6 +639,9 @@
           <value>issued</value>
           <value>transmitted</value>
           <value>copied</value>
+          <value>unchanged</value>
+          <value>circulated</value>
+          <text/>
         </choice>
       </attribute>
       <choice>
@@ -635,6 +678,11 @@
       <text/>
     </element>
   </define>
+  <define name="docnumber">
+    <element name="docnumber">
+      <text/>
+    </element>
+  </define>
   <define name="bclassification">
     <element name="classification">
       <optional>
@@ -700,8 +748,12 @@
         <ref name="btitle"/>
         <ref name="formattedref"/>
       </choice>
-      <ref name="bplace"/>
-      <ref name="seriesorganization"/>
+      <optional>
+        <ref name="bplace"/>
+      </optional>
+      <optional>
+        <ref name="seriesorganization"/>
+      </optional>
       <optional>
         <ref name="abbreviation"/>
       </optional>
@@ -728,6 +780,7 @@
     <element name="from">
       <choice>
         <data type="dateTime"/>
+        <data type="date"/>
         <data type="gYear"/>
       </choice>
     </element>
@@ -736,6 +789,7 @@
     <element name="to">
       <choice>
         <data type="dateTime"/>
+        <data type="date"/>
         <data type="gYear"/>
       </choice>
     </element>

data/lib/asciidoctor/mpfd/converter.rb

@@ -49,20 +49,13 @@ module Asciidoctor
         end
       end
 
-      def title(node, xml)
-        ["en"].each do |lang|
-          xml.title **{ language: lang, format: "plain" } do |t|
-            t << asciidoc_sub(node.attr("title"))
-          end
-        end
-      end
-
       def metadata_status(node, xml)
         xml.status(**{ format: "plain" }) { |s| s << node.attr("status") }
       end
 
       def metadata_id(node, xml)
         xml.docidentifier { |i| i << node.attr("docnumber") }
+        xml.docnumber { |i| i << node.attr("docnumber") }
       end
 
       def metadata_copyright(node, xml)
@@ -135,10 +128,6 @@ module Asciidoctor
                         File.join(File.dirname(__FILE__), "mpfd.rng"))
       end
 
-      def rsd_html_path(file)
-        File.join(File.dirname(__FILE__), File.join("html", file))
-      end
-
       def literal(node)
         noko do |xml|
           xml.figure **id_attr(node) do |f|
@@ -148,13 +137,6 @@ module Asciidoctor
         end
       end
 
-      def sections_cleanup(x)
-        super
-        x.xpath("//*[@inline-header]").each do |h|
-          h.delete("inline-header")
-        end
-      end
-
       def style(n, t)
         return
       end

data/lib/asciidoctor/mpfd/isodoc.rng

@@ -18,7 +18,21 @@
   of this.
 -->
 <grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
-  <include href="biblio.rng"/>
+  <include href="biblio.rng">
+    <define name="status">
+      <element name="status">
+        <choice>
+          <value>proposal</value>
+          <value>working_draft</value>
+          <value>committee_draft</value>
+          <value>draft_standard</value>
+          <value>final_draft</value>
+          <value>published</value>
+          <value>withdrawn</value>
+        </choice>
+      </element>
+    </define>
+  </include>
   <start>
     <ref name="standard-document"/>
   </start>
@@ -28,9 +42,10 @@
       <optional>
         <ref name="version"/>
       </optional>
-      <oneOrMore>
-        <ref name="sections"/>
-      </oneOrMore>
+      <optional>
+        <ref name="preface"/>
+      </optional>
+      <ref name="sections"/>
       <zeroOrMore>
         <ref name="annex"/>
       </zeroOrMore>
@@ -44,11 +59,6 @@
       <ref name="BibData"/>
     </element>
   </define>
-  <define name="status">
-    <element name="status">
-      <ref name="FormattedString"/>
-    </element>
-  </define>
   <define name="version">
     <element name="version">
       <optional>
@@ -77,6 +87,13 @@
       <text/>
     </element>
   </define>
+  <define name="preface">
+    <element name="preface">
+      <oneOrMore>
+        <ref name="content"/>
+      </oneOrMore>
+    </element>
+  </define>
   <define name="sections">
     <element name="sections">
       <oneOrMore>
@@ -104,7 +121,9 @@
   </define>
   <define name="section-title">
     <element name="title">
-      <text/>
+      <zeroOrMore>
+        <ref name="TextElement"/>
+      </zeroOrMore>
     </element>
   </define>
   <define name="content">
@@ -324,7 +343,7 @@
       <attribute name="id">
         <data type="ID"/>
       </attribute>
-      <ref name="BasicBlock"/>
+      <ref name="paragraph"/>
     </element>
   </define>
   <define name="termsource">
@@ -423,7 +442,7 @@
         <data type="ID"/>
       </attribute>
       <oneOrMore>
-        <ref name="paragraph-with-footnote"/>
+        <ref name="paragraph"/>
       </oneOrMore>
     </element>
   </define>
@@ -690,21 +709,20 @@
         <ref name="tname"/>
       </optional>
       <choice>
-        <oneOrMore>
+        <ref name="image"/>
+        <zeroOrMore>
           <ref name="figure"/>
-        </oneOrMore>
-        <group>
-          <zeroOrMore>
-            <ref name="TextElement"/>
-          </zeroOrMore>
-          <zeroOrMore>
-            <ref name="note"/>
-          </zeroOrMore>
-          <optional>
-            <ref name="dl"/>
-          </optional>
-        </group>
+        </zeroOrMore>
       </choice>
+      <zeroOrMore>
+        <ref name="fn"/>
+      </zeroOrMore>
+      <optional>
+        <ref name="dl"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
     </element>
   </define>
   <define name="TextElement">
@@ -938,6 +956,11 @@
   </define>
   <define name="li">
     <element name="li">
+      <optional>
+        <attribute name="id">
+          <data type="ID"/>
+        </attribute>
+      </optional>
       <oneOrMore>
         <ref name="paragraph-with-footnote"/>
       </oneOrMore>
@@ -981,7 +1004,9 @@
   </define>
   <define name="dt">
     <element name="dt">
-      <ref name="TextElement"/>
+      <zeroOrMore>
+        <ref name="TextElement"/>
+      </zeroOrMore>
     </element>
   </define>
   <define name="dd">
@@ -1009,6 +1034,9 @@
     <zeroOrMore>
       <ref name="docidentifier"/>
     </zeroOrMore>
+    <optional>
+      <ref name="docnumber"/>
+    </optional>
     <zeroOrMore>
       <ref name="bdate"/>
     </zeroOrMore>