= 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
Due to current limitations in the metanorma-plugin-lutaml plugin with liquid, TWO symbolic links need to be made to this repository's content:
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;
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 https://shopify.github.io/liquid/[Liquid], an open-source template language written in Ruby.
The render tag is used extensively to organize and reuse code. See https://shopify.dev/docs/api/liquid/tags/render[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:
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;
schemas parameter equal to ../../schemas-srl.ymlrepo:: 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.
.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.
.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.