Gem Version Build Status Code Climate

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 Asciidoctor documents following a template for generating documents for the 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.

    • AsciiMathML is to be used for mathematical formatting. The gem uses the 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:

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

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

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.

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

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

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

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

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

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

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

<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 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 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/