ISO 10303 Annotated EXPRESS templates

Purpose

This repository contains a set of Metanorma liquid templates for rendering Annotated EXPRESS schemas, as used in ISO 10303.

Usage

Note	Due to current limitations in the metanorma-plugin-lutaml plugin with liquid, TWO symbolic links need to be made to this repository’s content: at the directory of the root document; at the directory of the file that includes a template (typically sections/)

In a Metanorma document it is used like this:

= Integrated generic resource: Fundamentals of product description and support
:docnumber: 10303
:tc-docnumber: 10681
:partnumber: 41
:copyright-year: 2022
:language: en
:publish-date: 2022
:edition: 7
:title-intro-en: Industrial automation systems and integration
:title-intro-fr: Systèmes d’automatisation industrielle et intégration
:mn-document-class: iso
:lutaml-express-index: schemas; schemas.yaml;

[lutaml_express, schemas, repo, leveloffset=+1]
----
 include::templates/_schemas.liquid[]
----

One of the following directory structures is to be used.

Type 1: include:: block is at the same level as the including document:

document.adoc

The document that includes the lutaml_express block.

templates/

A check-out of the iso-10303-templates repository.

Type 2: include:: block in another file (e.g. under sections/):

document.adoc

The root document file.

templates/

A check-out of the iso-10303-templates repository.

sections/xxx.adoc

The document that includes the lutaml_express block.

sections/templates/

A check-out of the iso-10303-templates repository.

Note	The templates/ directory can be a symbolic link.

Structure explanation

General structure

The templates for ISO 10303 are consist of three folders: resources/, modules/, and common_files/

resources/ contains file templates to encode content related to resource documents.

modules/ contains file templates to encode content related to module documents.

common_files/ contains file templates to encode content related to both resource and module documents. In other words, these files are referenced somewhere in the code of the resources/ and modules/ or directly in the document to build.

All templates are written in Liquid, an open-source template language written in Ruby.

The render tag is used extensively to organize and reuse code. See render for detailed information.

Almost all .liquid files are reserved to generate schema-related sections. In this regard, the encoding begins with a lutaml_express block from a schema.adoc file:

  [lutaml_express, schemas, repo, leveloffset=+1,config_yaml=schemas.yaml]
  ---
  include::../modules/_schemas.liquid[]
  ---

In this block, the attribute:

schemas

refers to a YAML file containing a list of EXPRESS schemas, established by the :lutaml-express-index: attribute.

For example, the line:

:lutaml-express-index: schemas; ../../schemas-srl.yml;

Makes the schemas parameter equal to ../../schemas-srl.yml

repo

is the name of the variable that contains all the LutaML objects of the EXPRESS files (.exp) that schemas points to.

leveloffset

pushes down the hierarchy level of the headings inside the lutaml_express block.

config_yaml

receives a YAML file that is supposed to be a selection of the schemas covered by the current document. For example, config_yaml=schemas.yaml means that schema.yaml is the file to contain only the schemas covered by the current document, located in the same folder as the document. The distinction is made between schemas and config_yaml, so that schemas in other documents in a collection can still be referenced by the current document, even if they are not expanded out within it.

The following sections describe the file structure of each folder.

resources/ folder

Resource templates are meant to generate part of the content of resource documents, starting from the schema sections, to almost all annex sections. The following table lists the templates of this folder along with the section each one encodes.

Table 1. List of templates from resources/ and the corresponding section to encode

File template	Encodes
schema.adoc and .liquid files	Schema sections
resource_annex_short_names.adoc	Annex A, "Short names of entities"
resource_annex_identifier.adoc	Annex B, "Information object registration"
resource_annex_listings.adoc	Annex C, "Computer interpretable listings"
resource_annex_diagrams.adoc	Annex D, "EXPRESS-G diagrams"
resource_annex_change_history.adoc	Annex E, "Change history"

Schema sections

Execution begins with a lutaml_express block from schema.adoc, as explained before. From there, we pass to _schemas.liquid file where we iterate over a selected list of schemas.

_schema.liquid

handles the encoding of each schema. The code is divided into multiple render tags that import the liquid files described below.

_intro.liquid

encodes the first subsection, "General", consisting of an introductory explanation of the schema, the EXPRESS code, and two NOTE blocks.

_fund_cons.liquid

encodes the "Fundamental concepts and assumptions" subsection.

The next part is the schema definitions, consisting of: constants, types, entities, subtype constraints, functions, procedures, and rules:

_constant.liquid

encodes constant definitions.

_types.liquid

encodes type definitions.

_entities.liquid

encodes entity definitions.

_subtype_constraints.liquid

encodes subtype constraint definitions.

_functions.liquid

encodes function definitions.

_procedures.liquid

encodes procedure definitions. These are very similar to function definitions.

_rules.liquid

encodes rule definitions.

The following two files recur among the definition templates:

_basic_thing.liquid

corresponds to the basic rendering of any definition. It provides the title, description, boilerplate (if required), body remarks (i.e. NOTEs, EXAMPLEs, figures), and EXPRESS code.

_basic_title.liquid

allows encoding the heading of any definition given the title, depth, namespace (thing_prefix), and anchor.

After this, follows the encoding of attributes: where rules, informal propositions, etc.

Every schema section ends with an END_SCHEMA; code line.

modules folder

Module templates are meant to generate ARM and MIM sections, and almost all annex sections. The following table lists the templates of this folder along with the section each one encodes.

Table 2. List of templates from modules/ and the corresponding section to encode

File template	Encodes
schema.adoc and .liquid files.	"Information requirements" and "Module interpreted model" sections
module_annex_short_names.adoc	Annex A, "MIM short names"
module_annex_identifier.adoc	Annex B, "Information object registration"
module_annex_diagrams_arm.adoc	Annex C, "ARM EXPRESS-G"
module_annex_diagrams_mim.adoc	Annex D, "MIN EXPRESS-G"
module_annex_listings.adoc	Annex E, "Computer interpretable listings"
module_annex_change_history.adoc	Annex G, "Change history"

Note	Section numbering may vary according the document.

Schema sections

Like in resource templates, execution begins with a lutaml_express block from schema.adoc, as explained before. From there, we pass to _schemas.liquid where we iterate over a selected list of schemas.

Relevant templates are described below:

_schemas.liquid

iterates over a selected list of schemas via for loop.

_schema.liquid

determines if the schema is ARM type or MIM type and applies the code accordingly.

_arm.liquid

handles the encoding of the "Information requirements" section. This file defines the encoding of each definition. It is composed of multiple render blocks, described below.

_arm_intro.liquid

contains the introductory text of the section.

_arm_required_am_arms.liquid

encodes "Required AM ARMs" subsection.

_definitions.liquid

encodes ARM/MIM type, entity, subtype constraint, function definitions, etc.

_mim.liquid

handles the encoding of the "Module interpreted model" section.

_mim_mapping_specification.liquid

encodes the "Mapping specification" subsection.

_mim_short_listing.liquid

encodes the "MIM EXPRESS short listing" subsection. It is composed of multiple render blocks, most of them already described above.

_bolilerplates

contains all the boilerplate content present in a module document.

_interface_notes

encodes the first two NOTEs of a schema section. The first is a list of referenced schemas, and the second, a reference to the EXPRESS diagrams.

common_files folder

common_files/ contains templates used by both resource and module templates. These are:

_body_remarks.liquid

to encode remark items like NOTEs, EXAMPLES, and figures.

_referenced_schemas_note.liquid

to specifically encode NOTE 1 from the schema introductory content, which is a list of referenced schemas.

_source_code.liquid

to place source code in EXPRESS format.

diagrams.liquid

to encode the "EXPRESS-G diagrams" annex section for both resource and module documents.

expg.gif

a gif image used as an icon for the EXPRESS-G diagrams cross-references.

schema_identifers.adoc

contains a lutaml block to encode part of the "Information object registration" annex section (typically, Annex B).

usage_guide_annex.adoc

contains a boilerplate for "Application module implementation and usage guide" annex section (typically, Annex F) to be used directly in the document when applies.

License

Copyright Ribose.