Syntax for writing UN documents using Metanorma

Document header attributes

Note

The document attributes listed below are unique to Metanorma’s processing of UN 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 UN.

For an introduction to Metanorma AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.

:doctype:

The document type (see UN deliverables: The different types of UN publications) (mandatory). Note that the document types are reflected in the document identifier.

The permitted types for UN are:

recommendation: UN Recommendation
plenary: UN Plenary document
plenary-attachment: Attachment to UN Plenary document
addendum: Addendum
communication: Communication
corrigendum: Corrigendum
reissue: Reissue (of something)
agenda: Documents relating to agendas of principal organs
budgetary: Documents relating to programme budget implications
sec-gen-notes: Notes by the Secretary-General
expert-report: Reports of intergovernmental and expert bodies
resolution: Resolutions and other formal decisions of United Nations organs

Paragraph numbering is enabled for all documents types except for plenary, agenda, budgetary [added in https://github.com/metanorma/metanorma-un/releases/tag/v0.3.4].

The “plenary” cover page is used if the document type is plenary, agenda, budgetary, or if any of the plenary_metadata metadata attributes are given [added in https://github.com/metanorma/metanorma-un/releases/tag/v0.3.4].

:status:: The document status. Synonym: :docstage:. The permitted types are: proposal, working-draft, committee-draft, draft-standard, final-draft, published, withdrawn.
:committee:: The name of the relevant UN committee (mandatory).

Example 1. Example of specifying a UN committee

United Nations Centre for Trade Facilitation and Electronic Business (UN/CEFACT)
:language:: The language(s) of the document in ISO 639-1 codes, comma-delimited. The language in which the document has been issued, not the language(s) in which it has been submitted. This value defaults to the six official languages of the UN: Arabic, Chinese, English, French, Russian and Spanish (i.e. ar,zh,en,fr,ru,es).
:toc:: Include table of contents in Word output. (The “Table of contents” is always included in HTML output.)
:distribution:: Extent of distribution allowed.

Example 2. Example of specifying a UN distribution class

General

Recommendations

:docnumber:: The document number if the document is a Recommendation (required only for Recommendations).

Example 3. Example of specifying a Recommendation document number

Specify 42 for Recommendation 42.
:submissionlanguage:: The language(s) in which the document was originally submitted. ISO-639-1 codes are used for languages. Multiple languages can be comma-delimited.

Plenary documents

:session-date:

The session where this document will be discussed.

Example 4. Example of specifying a session date of the document

Geneva, 30 April — 1 May 2018

:item-number:

Number of the agenda item this document belongs to.

If the document corresponds to multiple items, they are comma-delimited.
If the document belongs to multiple subitems under a single item, following editorial practice of th UN, give the item and subitems identifiers here.

Example 5. Example of specifying the agenda item number of the document

Specify 6 for Item 6 of the provisional agenda.

:item-name:

Name of the agenda item this document belongs to. If the document corresponds to multiple items, they are comma-delimited.

:subitem-name:

Name of the agenda subitem this document belongs to. If the document corresponds to multiple subitems, they are comma-delimited.

:collaborator:

Collaborator of this document, if any.

Example 6. Example of specifying a collaborator of the document

World Economic Forum

:agenda-id:

The unique identifier of this agenda item. If there are multiple agenda items or subitems, give them comma-delimited.

Example 7. Example of specifying the UN unique identifier of the agenda item

ECE/TRADE/C/CEFACT/2018/6

:item-footnote:

Footnoted reference to item, if item is on the preliminary list or the provisional agenda.

General

:do-not-number-subheadings:: If this attribute is present, headings are numbered in the document, but subheadings are not [added in https://github.com/metanorma/metanorma-un/releases/tag/v0.3.9].

Preface

General

The Foreword and Introduction are not recognised as part of the document preface by default [added in https://github.com/metanorma/metanorma-un/releases/tag/v0.3.4].

Abstract

Abstracts are moved to the front page in Plenary documents. In Recommendation documents, they appear in the document preface, before the foreword and introduction.

Paragraph numbering

Paragraphs are automatically numbered — paragraph numbers should not be entered in the Metanorma AsciiDoc source.

Paragraphs are numbered by treating each paragraph in the Metanorma XML as a separate clause; all terminal clauses in UN Metanorma XML are rendered as a numbered paragraph.

Non-paragraph blocks (tables, figures, admonitions, lists) are not numbered; nor are paragraphs in prefatory material (introduction, foreword, abstract).

Notes

Different note types can be entered [added in https://github.com/metanorma/metanorma-un/releases/tag/v0.3.11]:

Source notes using the note type source;
Abbreviation notes using the note type abbreviation.

Example 8. Example of specifying a source NOTE in a UN document

[type=source]
NOTE
====
This is a source note
====

Footnotes

Titles may be entered with footnotes [added in https://github.com/metanorma/metanorma-un/releases/tag/v0.5.5]:

:title: Paperless Trade White Paper footnote:[text1], footnote:[text2]

Admonitions

The admonition container IMPORTANT is used to render UN document boxes.

Unlike normal Metanorma admonitions, UN admonitions can have titles, and can be numbered in output. As with other assets in Metanorma, the option attribute unnumbered can be applied to prevent an admonition being numbered. (So [IMPORTANT%unnumbered] or [IMPORTANT,options="unnumbered"].)

Example 9. Example of specifying a UN document box

[IMPORTANT%unnumbered]
.Business Process Analysis Plus (BPA+)   (<==== This is the box title)
====
Business Process Analysis was initially designed to document and
evaluate an import/export process at a given point time and its
relative simplicity. It also specifically includes a measurement of the
time and cost of the complete range of procedures as one of the main
outputs of the analysis. This combination makes it suitable as the
basis/core of a trade facilitation monitoring and improvement system.
====