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.
-
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.
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
nordocuments-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: …
-
Gives the location of the HTML coverpage, as an alternative to the
-c
argument ofmetanorma 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: …
-
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: …
-
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: …
-
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: …
-
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.
format
-
Specifies the possible output formats for the collection as a list, as an alternative to the
-f
argument ofmetanorma 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 aentry
. 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
andentry
are mutually exclusive:file
indicates the leaf nodes of the manifest entries.-
The documents are expected to be Metanorma Semantic XML documents; they can also be Metanorma Presentation XML documents, attachments (see below), YAML files, or AsciiDoc documents.
-
If a document is a AsciiDoc documents, it is compiled to a Metanorma Semantic XML document in preprocessing [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].
-
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 tofalse
, the file is not to be included in any listing of manifest contents (i.e. in the collection cover page).NoteBoolean attributes of files (
attachment
,sectionsplit
,index
) can be inherited fromentry
to all theirfile
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 Before:
After:
|
prefatory-content
-
Content to put at the beginning of the collection container.
final-content
-
Content to put at the end of the collection container.
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
: givenref_folder
(the folder containing the manifest file) andfileref
(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 toref_folder
. -
set_identifier_resolver
: givenidentifier
, 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.
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.
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 sametag
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
.