Metanorma: Aequitate Verum

Learning Metanorma

Assigning metadata in the document header

The header contains information about the document (metadata). You specify these metadata by using predefined document attributes, that look like this: :document-attribute:. Most of the attributes take a value, while others are simple flags without a value, like :draft:.

Some of the metadata will be visible in your document, such as :title:, while others are not visible but still affect how your document is generated. The order of attributes doesn’t matter to Metanorma. You can specify metadata about:

  • Authors: Issuing organization, authors, and their location

  • Document info: Language, document stages (draft, published, etc.) copyright holder, etc.

  • Dates: Draft dates, revision dates, publishing date, copyright year, etc.

  • Identifiers: Document numbers, ISBNs, URIs (Uniform Resource Identifiers)

Note
 Other metadata influence how the document is generated and should only be used by advanced users. Often, they will require familiarity with your organization’s structures and processes.

Here’s an example:

= Document title (1)
:docnumber: 12345 (2)
:doctype: standard (3)
:copyright-year: 2022
:language: en
:mn-document-class: ogc (4)
:technical-committee: Committee name  (5)
:fullname: Your Name (6)
:fullname_2: Co-Authors Name
:address: Address line 1+ \ (7)
Zip code + \
City + \
Country
:draft: (8)
:mn-output-extensions: xml,html,doc,html_alt (9)

  1. A document always begins with the document title.

  2. :docnumber: defines the formal number of the document.

  3. :doctype: defines the type of document, for example standard, report, guide, etc. The allowed values for this attribute are specific to each SDO.

  4. :mn-document-class: indicates the Metanorma flavor the document should be checked against.

  5. The committee responsible for the document

  6. The author’s name. You can add co-authors by appending the attribute with a number: _2, _3, and so on.

  7. When you add an address that contains multiple lines, end each line except for the last with + \. Alternatively, you can enter each line into its own attribute, such as :street:, :postcode:, :city:, :country:.

  8. :draft: renders comments as well. The attribute does not take any values: it is either present or not.

  9. mn-output-extensions specifies the generated outputs. It can take several values that must be comma-delimited.

Practice time

The code for this exercise is available on GitHub.

The corresponding file is named exercise-2-1.adoc

Now it’s your turn. Fill the document with the following attributes:

  • Document title

  • Your name

  • Your organization using the :publisher: attribute

  • Your organization’s address

  • The document class: ogc

  • The document type: standard

  • The language

  • The copyright year

Hint

To declare an attribute, follow the syntax :attribute: value.

For example: :publisher: Ribose Inc.

Start next lesson »