Metanorma: Aequitate Verum

Author's documentation

Collections configuration

General

Metanorma supports collections: groupings of individual Metanorma documents into a whole.

Collections are of particular use when the component documents are tightly linked with each other. For example:

  • multilingual documents: where each component document has the same content in a different language

  • documents that extensively cross-reference each other, for instance, definitions of an informational model spanning multiple documents.

A collection can rendered into the following output formats (other than in Metanorma XML):

HTML

treated as a single web site, with each Metanorma document a component web site.

PDF

treated as a single document, composed of the individual Metanorma documents.

Word DOC

treated as a single document, composed of the individual Metanorma documents. [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5]

Compiling collections

Collections are compiled using the metanorma executable, as follows:

Usage:
  metanorma collection FILENAME [..options]

Options:
  -x, [--extensions=EXTENSIONS]     # Type of extension to generate
  -w, [--output-folder=FOLDER]      # Folder to generate collection in
  -c, [--coverpage=COVERPAGE]       # Cover page as Liquid template for collection (currently HTML only)

Where:

FILENAME

The collection manifest. This is a YAML file, outlining the structure of the collection, including the location and identifier for each of the component files.

COVERPAGE

A Liquid template file for the index page to the collection in HTML.

Both are described further below.

Example 1. Example command for generating a Metanorma collection

The command below compiles the collection described in the collection manifest si-brochure-bilingual.yml:

bundle exec metanorma collection si-brochure-bilingual.yml \
  -x xml,html,presentation,pdf \
  -w bilingual-brochure \
  -c collection_cover.html

Specifically, it:

  • generates the collection as XML, Presentation XML, HTML and PDF in the folder bilingual-brochure; and

  • uses the HTML index page template collection_cover.html.

The metanorma collection executable presupposes that the individual metanorma collections are already compiled into XML.

The compilation of the collection resolves any cross-references between files in the collection during preprocessing, so those inter-document links become simple hyperlinks.

The output folder contains those preprocessed individual files, and files named collection in the target formats.

Specifying collections

Collection manifest

The collection manifest contains the following keys. The format has been streamlined [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0], but is backwards compatible with earlier instances of the manifest; the legacy equivalent keys are given in [brackets].

directives

Directives on how the collection should be generated. Accepted values are listed below.

documents-inline

(default) Indicates that the files should be concatenated into a single XML file for processing. If neither documents-inline nor documents-external is supplied, documents-inline is presupposed.

Currently, if you are generating PDF or DOC output, you can only specify documents-inline.

documents-external

Indicates that the files are kept separate in processing, and the overall collection XML file does not contain the XML of the individual documents.

presentation-xml

Indicates that the XML supplied is in Metanorma Presentation XML format, and does not need to be converted to Presentation XML by Metanorma [added in https://github.com/metanorma/metanorma/releases/tag/v1.3.5].

This is automatically included when sectionsplit is set in the Metanorma file, to break a single document up into multiple HTML files.

coverpage: {file-path}

Gives the location of the HTML coverpage, as an alternative to the -c argument of metanorma collection [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.7].

Any locally specified coverpage will be treated as a Liquid template, which can be populated with metadata extracted from the bibliographic metadata about the collection; refer to Metadata and boilerplate.

collection-word-coverpage: {file-path}

Gives the location of the Word DOC coverpage for the entire collection [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].

If left out, or given as null, no such coverpage is added.

collection-word-intropage: {file-path}

Gives the location of the Word DOC introductory section for the entire collection [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].

As with HTML and Word DOC output of standalone documents, this is intended for prefatory material appearing before user-specified prefatory content: typically boilerplate content, and a placeholder for the table of contents.

If left out, or given as null, no such introductory material is added.

document-word-coverpage: {file-path}

Gives the location of the Word DOC coverpage for each individual document [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].

If left out, or given as null, the default cover page that would appear in a standalone document is used. If given as "", no such coverpage is added.

document-word-intropage: {file-path}

Gives the location of the DOC introductory section for each individual document [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].

If left out, or given as null, the default introductory section that would appear in a standalone document is used. If given as "", no such introductory section is added.

coverpage-style

Gives the style of the PDF and HTML coverpage, if multiple styles are offered [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.7].

bare-after-first

Compiles the first HTML document in the collection complete (with coverpage and boilerplate), and all subsequent files with the bare option (i.e. without coverpage and boilerplate) [added in https://github.com/metanorma/metanorma/releases/tag/v1.3.5].

This is automatically included when sectionsplit is set in the Metanorma file, to break a single document up into multiple HTML files.

recompile-xml

If a file is specified as being *.adoc, always recompile it into XML, whether or not a corresponding XML file is already there. This document attribute is only used to refresh XML files: by default, the last AsciiDoc-generated XML is cached for time savings [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6].

flavor

The flavor of Metanorma to use in processing the collection metadata and (by default) the documents it contains [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6]. The corresponding value of flavor is described in the Metanorma document attribute :mn-document-class:.

format

Specifies the possible output formats for the collection as a list, as an alternative to the -f argument of metanorma collection. Allowed values are:

xml

Metanorma Semantic XML

presentation

Metanorma Presentation XML. This is added automatically if any of the following formats is specified.

html

HTML.

doc

Word DOC.

pdf

PDF.

bibdata

Metadata about the collection. Entered in the Relaton format.

docid
type

(mandatory) docid/type is used by Metanorma to determine the flavour of the collection. Currently a collection can only contain documents of one flavour.

entry [manifest]

A manifest listing the documents contained in the collection, in nested hierarchy.

entry can appear recursively in a entry. This allows users to specify hierarchic levels of documents in the collection. That hierarchy will be reflected in the index page navigation for the collection.

type [level]

Names the current hierarchical level of the manifest.

title

Gives the title of the current level of the manifest.

file [fileref]

The file path of a document in the collection relative to the manifest file. file and entry are mutually exclusive: file indicates the leaf nodes of the manifest entries.

  • The documents are expected to be Metanorma Semantic XML documents (.xml), Metanorma Presentation XML documents (.xml), attachments (see below), YAML files (.yml, .yaml), or AsciiDoc source files (*.adoc).

  • If the file is in AsciiDoc format:

    • The file is compiled to a Metanorma Semantic XML document in preprocessing [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].

    • By default, for caching reasons, the document is not recompiled to a Metanorma Semantic XML document if a corresponding XML document has already been generated in the same directory [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6].

    • If the document attribute of recompile-xml is set, The document is always recompiled to a Metanorma Semantic XML document, even if a corresponding XML document has already been generated.

  • If a document is a YAML file, it is assumed to be a collection manifest itself, and its manifest is recursively read into the current manifest at that point of the entry [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].

    • This allows manifests to include other manifests. If the YAML file is in a different directory, the file locations of any files it references are updated to be relative to the current manifest.

  • A manifest can have both files and nested manifests as its children [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.7].

identifier

The document identifier, used to index the document in processing. It is also the identifier used to reference this document from other documents in the same collection, using bibliographic references ([collection-cross-references]). If the identifier is not supplied, and this is a Metanorma document, the identifier will be extracted from the document [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].

attachment

When set to true, the file is not a Metanorma document but an attachment, and therefore will not be compiled but directly included by Metanorma [added in https://github.com/metanorma/metanorma/releases/tag/v1.2.9].

url

Provides the external URL to link to for references to this document, replacing any links to the locally generated file [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.7]. Is not currently intended to replace locally included files: fileref is still required for any such files to be processed.

sectionsplit

When set to true, the HTML output for the specified file is arranged as one HTML file per clause, with an index page created for the overall document.

The index page for the entire document links to the index page for the sectionsplit document.

index

Defaults to true. When set to false, the file is not to be included in any listing of manifest contents (i.e. in the collection cover page).

Note

Boolean attributes of files (attachment, sectionsplit, index) can be inherited from entry to all their file descendants [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].
Note

In the old manifest format, information about files as opposed to manifests needed to be stored under a separate docref container.

Before:

manifest:
  level: collection
  docrefs:
    - fileref: file1.xml
      identifier: ISO 123
    - fileref: file2.txt
      identifier: file2
      attachment: true
    - manifest
      level: annexes
      title: Annex set
      docrefs:
      - fileref: annex1.xml
        identifier: ISO 123 Annex 1
        sectionsplit: true
      - fileref: annex2.xml
        identifier: ISO 123 Annex 2
        sectionsplit: true

After:

entry:
  type: collection
  entry:
    - file: file1.adoc
    - file: file2.txt
      identifier: file2
      attachment: true
    - type: annexes
      title: Annex set
      sectionsplit: true
      entry:
      - file: annex1.adoc
      - file: annex2.adoc
prefatory-content

Content to put at the beginning of the collection container.

final-content

Content to put at the end of the collection container.

Example 2. Example collection manifest
directives:
  - documents-inline
  - coverpage: index.html
  - coverpage-style: JACK
bibdata:
  title:
    type: title-main
    language: en
    content: ISO Collection 1
  type: collection
  docid:
    type: iso
    id: ISO 12345
  edition: 1
  date:
    - type: created
      value: "2020"
    - type: issued
      value: "2020"
  copyright:
    owner:
      name: International Organization for Standardization
      abbreviation: ISO
    from: "2020"
format:
  - xml
  - presentation
  - pdf
entry:
  type: collection
  title: ISO Collection
  entry:
    - file: rice-en.final.xml
      identifier: ISO 17301-1:2016
    - type: amendments
      title: Amendments
      entry:
        - file: rice-amd.final.xml
          identifier: ISO 17301-1:2016/Amd 1:2017
        - entry:
            - type: attachments
              title: Attachments
              attachment: true
              entry:
                - file: pics/action_schemaexpg1.svg
                  identifier: action_schemaexpg1.svg
                - file: ../../assets/rice_image1.png
                  identifier: rice_image1.png
    - file: dummy.xml
      identifier: ISO 17302
      url: /example/dummy
    - file: rice1-en.final.adoc
prefatory-content:
|
  == Clause
  Welcome to our collection

final-content:
|
  == Exordium
  Hic explicit

Manifest hooks

If the collection is being processed programmatically, in a Ruby script, it is possible to intervene in that processing, to change the content of the manifests it reads in. This may be needed, for example, if a collection YAML points to certain files by default, but those file locations need to be different for distribution.

my_fileref_proc = Proc.new do |ref_folder, fileref|
  ...
end

my_identifier_proc = Proc.new do |identifier|
  ...
end

my_pre_parse_model = Proc.new do |collection_model|
  ...
end

Metanorma::Collection.tap do |mn|
  mn.set_identifier_resolver(&my_identifier_proc)
  mn.set_fileref_resolver(&my_fileref_proc)
  mn.set_pre_parse_model(&my_pre_parse_model)
end

The hooks provided [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0] are:

  • set_fileref_resolver: given ref_folder (the folder containing the manifest file) and fileref (the path to a file from within the manifest file), generate a new path to the file, redirecting the file reference. The generated path needs to be either absolute, or relative to ref_folder.

  • set_identifier_resolver: given identifier, the identifier of a file in the collection, generate a new identifier.

  • pre_parse_model: given a collection manifest (as parsed by YAML into a Ruby hash), return a new collection manifest.

Site manifest

The collection manifest is expected to reference Metanorma Semantic XML documents.

The starting point for generating a collection is Metanorma AsciiDoc documents. In order to specify a collection and generate it as straightforwardly as possible, the collection manifest should be accompanied by a site manifest, named metanorma.yml, specifying both the component AsciiDoc files, and the collection manifest, as dependency files.

Site compilation will compile both the component files, and the collection depending on them. This is done by running metanorma site generate in the same directory as metanorma.yml.

Since Metanorma site compilation compiles documents to a _site/documents directory, the collection manifest needs to reference the Semantic XML documents in that same _site/documents directory.

Example 3. Example site manifest

The following two files are examples of a site manifest and a collection manifest compiled through metanorma site generate.

metanorma.yml:

---
metanorma:
  source:
    files:
      - document.1.adoc
      - document.2.adoc
      - collection.yml

  collection:
    organization: "British Standards Institute"
    name: "Retrofitting dwellings for improved energy efficiency -- Specification and guidance"

In the site manifest, the files to be compiled are listed under metanorma.source.files; any YAML file in the list is assumed to be a collection manifest.

The collection is specified in the site manifest with two attributes: a name for the collection document, and an organization treated as the corporate author of the collection. Both will feature in the index file of the documents generated in the site (_site/index.html), and correspond to bibdata.title.content and bibdata.copyright.owner.name in the collection manifest.

Example 4. Example collection manifest

collection.yml:

---
directives:
  - documents-inline
bibdata:
  type: collection
  docid:
    type: bsi
    id: bsidocs
format:
  - xml
  - html
  - presentation
  - pdf
entry:
  - file: _site/documents/document.1.xml
    identifier: bsidocs-1
  - file: _site/documents/document.2.xml
    identifier: bsidocs-2
Note
 document.1.adoc and document.2.adoc are compiled to _site as part of site compilation (although the new manifest format processing would take care of that anyway, if the collection manifest specified the files as adoc.) If the files to be processed in the collection are to be generated by the site manifest, then the file attributes in the collection manifest need to point to the Semantic XML where the site compilation deposits them — i.e. under _site/documents. The collection generation also generates the collection in the same location, so there is no need to specify a collection destination directory, --output-folder under metanorma collection.

Index page template

The HTML index page template is currently realised as a Liquid template, which forms a sidebar for the display of the HTML content of each file.

The following fields are defined:

doctitle, docnumber, etc.

Information derived from the Relaton YAML description in the manifest of the entire collection.

The field names are as defined for Liquid templates in Metanorma: see Metadata and Boilerplate.

navigation

A nested list giving hyperlinks to the constituent documents, following the specification in the manifest field of the collection manifest.

nav_object

The same nested list, presented as a recursive object, in order to allow users to select only a subset of the navigation list for presentation [added in https://github.com/metanorma/metanorma/releases/tag/v1.6.4].

It contains the following fields:

title

The list title.

type

The list type (from entry.type in the manifest) [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].

docrefs

A hyperlinked list of the documents at that level of the manifest.

children

An array of child manifests. This list can be recursive.

prefatory-content

Prefatory content from the collection manifest [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.6].

final-content

Final content from the collection manifest [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.6].

Multilingual documents

Metanorma currently supports multilingual documents in its PDF output, as document collections.

  • By default, Metanorma treats multilingual documents as a concatenation of documents, each in its own language;

  • Metanorma also supports rendering multilingual documents as parallel columns of aligned text.

In order to control such alignment, Metanorma supports the following markup [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.8]:

  • An attribute tag can be added to any block.

    This is used to indicate that blocks with the same tag value across documents in different languages are to be aligned in parallel columns, subject to the multilingual-rendering attribute.

  • An attribute multilingual-rendering can be added to any block.

    This indicates how that block is to be rendered in a multilingual columnar text.

    The options are:

    • common for blocks that are shared across all languages;

    • all-columns for blocks that span all columns of text, and are displayed consecutively;

    • parallel for a block that is to be aligned to the block occupying the same position in the document hierarchy in each language;

    • tag for all blocks sharing the same tag attribute as the current block.

  • The document attribute align-cross-elements indicates the Metanorma XML elements that are always to be aligned in multilingual text. It consists of a comma-delimited list of Metanorma XML tags; e.g. p,note,term.