Authoring MPFA documents with Metanorma

All the following modifications to the basic Metanorma model are provisional, as a full analysis of the formatting requirements of MPFA has not yet been conducted.

Document attributes

Note

The document attributes listed below are unique to Metanorma’s processing of MPFA documents. For common document attributes, see Document attributes reference in general Metanorma author’s documentation. That page describes attributes that apply to all Metanorma flavors, not just MPFA. For an introduction to Metanorma AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.

:committee:

Name of relevant authoring committee

:committee-type:

Type of relevant authoring committee

Text markup

Glossary

Sections with the title glossary are treated as equivalent to Terms and Definitions in other Metanorma documents.

== Glossary
=== Term

Definition

=== Term 2

Definition 2

Also unlike other Metanorma documents, the glossary is considered 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 AsciiDoc document.

Any clause that has the preface style attribute is also moved to the document preface, regardless of where it appears in the source AsciiDoc 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/metanorma/samples-mpf/blob/main/compliance/mpfa-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 MPFA AsciiDoc, 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

MPFA documents follow a hierarchically numbered clause structure. However, there are some floating titles in MPFA which group clauses together, but are not numbered themselves. These are tagged in MPFA AsciiDoc with a .container role attribute. When the gem numbers clauses, these containers are ignored.

== MPFA Structure

[.container]
=== Benefits

==== Auto-numbering

==== 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. MPFA Structure</h1>

<h2>1.1. Benefits</h2>

<h3>1.1.1. Auto-numbering</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. MPFA Structure</h1>

<h1>Benefits</h1>

<h3>1.1. Auto-numbering</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>