Embedded documents

General

Metanorma documents supports embedding of a document within another Metanorma document.

Use case

National standards bodies (NSBs) often re-publish international standards as national standards through the process of "adoption".

When adopting an international standard identically, the international standard is typically embedded within a national standard, with the outer document providing additional information, such as a national foreword or national annexes.

Note	The process of adoption is described in ISO Guide 2.

In the case of adoption by members of CEN/CENELEC, this adoption process could be the NSB adopting an European standard (EN), where the EN adopts an international standard. Hence embedding can be of multiple-levels.

Usage

Metanorma documents supports embedding of a document within another Metanorma document, using the embed:: command [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.2].

The embed:: command acts similar to the AsciiDoc include:: macro, taking as its target argument the name of the file to be included.

embed::received.adoc[]

The named file is included at the location of the embed:: command, with the following consequences:

Certain metadata of the document header of the embedded document will be utilized by the including document. The rest of the embedded document’s document header will be ignored. The embedded document’s document header will have no effect to the including document.
If any top-level headings of the embedded document are identical to headings in the including document, the entire clause in the embedded document is skipped.
Documents can be embedded within other documents, at multiple levels.

The embedding documents can only involve substituted clauses or prefatory clauses. For example, a document could have an original foreword, supplemented by a regional foreword, and/or a national foreword.

Example 1. Example of embedding another document

The following document embeds another document.

= Document 1
Local Secretariat
:docnumber: 123A

[[id2]]
[language=en-UK]
== Introduction

This is an introduction added to the Received document

embed::received.adoc[]

== Colophon

The embedded document is:

= Document 1
Central Secretariat
:no-pdf:
:docnumber: 123
:issued-date: 2017-06-29

== Foreword

This is the foreword

[[id2]]
== Introduction

Original introduction

== Introduction Subclause

Introduction subclause

== Content

This is content

The resulting document is:

= Document 1
Local Secretariat
:docnumber: 123A

[[id2]]
[language=en-UK]
== Introduction

This is an introduction added to the Received document

== Foreword

This is the foreword

== Content

This is content

== Colophon

Note the following behavior:

The resulting document uses the including document header (so the :docnumber: value will be 123A instead of 123, and the :issued-date: value will be ignored).
As both documents have a top-level clause labelled Introduction, the matching clause in the included document, and all its subclauses, are ignored.

Referencing an embedded document

The embedding document can include a cross-reference to the embedded document by referencing an anchor on the embed:: directive.

If no display text is provided for the cross-reference, the link text will be the document identifier of the embedded document. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.10]:

Example 2. Example of embedding another document

For example, if the including document is as follows:

= Document 1
:docidentifier: SHQ XYZ 123A

== Introduction

This is an introduction added to the Received document <<id>>

[[id]]
embed::received.adoc[]

And the embedded document is:

= Document 1
:docidentifier: XYZ 123

== Foreword

This is the foreword

The reference [id] will be rendered as XYZ 123, which is the embedded document identifier. The [id] cross-reference will hyperlink to the first header within the embedded document (the Foreword, in this case).

Limitations

Embedding documents with assets

If you embed documents that reference files, you will need to put both documents in the same folder, in a flat hierarchy.

Warning

This behavior is due to AsciiDoc’s inability to locate assets from directories different from the including document. As with AsciiDoc include::[], AsciiDoc lacks a mechanism of specifying asset location relative to the current document, as opposed to the initial document.

Only one `embed:` command allowed in a document

The current implementation only allows a single document to be embedded within another document, hence only one embed: command is allowed.