EXPRESS Language Foundation

Conversion guide: "Metanorma with EXPRESS content" to "Model-based EXPRESS documentation in Metanorma"

Purpose

This guide describes how to convert a "Metanorma document that contains EXPRESS" to a "Metanorma document with Annotated EXPRESS" which is the model-based method.

For example, this is to be applied to the PDF parts after converting into Metanorma.

Structure conversion

General

In the current ISO documents, the role of Metanorma is reversed with EXPRESS.

Text is handled in the blocks like this:

{document content}
*)

{EXPRESS schema content}

(*
{document content continued}

Notice that this is in the syntax of an EXPRESS comment. The intention here is to reverse the structure, where the {document content} exists as Annotated EXPRESS objects within the EXPRESS schema.

Let’s reverse this so that we have:

{EXPRESS schema content}

(*
{document content}
*)

{EXPRESS schema content continued}

Now, anything outside the remarks is in plain EXPRESS.

Example

We take ISO 10303-49, Clause 4 as an example.

This file sections/04-method_definition.adoc contains this content (partial copy):

[[method_definition]]
== Method definition

The following EXPRESS declaration begins the *method_definition_schema* and
identifies the necessary external references.

EXPRESS specification:

[%unnumbered]
[source,html]
----
*)
SCHEMA method_definition_schema;

REFERENCE FROM action_schema
    (action_method,
     action_method_relationship,
     action_relationship);

...
(*
----

[NOTE]
====
The schemas referenced above can be found in the following parts of ISO 10303:

action_schema:: <<iso10303-41>>
document_schema:: <<iso10303-41>>
...
====

NOTE: See <<annexD>>, <<figD1>>, for a graphical presentation of this schema.

=== Introduction

The subject of the ...

=== Fundamental concepts and assumptions

The *method_definition_schema* provides ...

=== method_definition_schema type definitions

==== relationship_with_condition

A *relationship_with_condition* type ...


EXPRESS specification:

[%unnumbered]
[source,html]
----
*)

TYPE relationship_with_condition = SELECT
  (action_method_relationship,
   action_relationship,
   context_dependent_action_method_relationship,
   context_dependent_action_relationship);
END_TYPE;

(*
----

==== process_or_process_relationship

A *process_or_process_relationship* type ...

EXPRESS specification:

[%unnumbered]
[source,html]
----
*)
TYPE process_or_process_relationship = SELECT
  (product_definition_process,
   property_process,
   relationship_with_condition);
END_TYPE;
(*
----

Given this input, we want to reverse the roles to obtain a new file: method_definition_schema.exp.

The resulting file looks like this (method_definition_schema.exp):

SCHEMA method_definition_schema;

REFERENCE FROM action_schema
    (action_method,
     action_method_relationship,
     action_relationship);

...

This content is auto-generated in Metanorma Annotated EXPRESS so we don’t need to convert:

The NOTEs goes into a __note remark tag:

(*"method_definition_schema.__note
The schemas referenced above can be found in the following parts of ISO 10303:

action_schema:: <<iso10303-41>>
document_schema:: <<iso10303-41>>
...
*)

(*"method_definition_schema.__note
See <<annexD>>, <<figD1>>, for a graphical presentation of this schema.
*)

Then, this content goes into a Annotated EXPRESS block:

=== Introduction

The subject of ...

becomes:

(*"method_definition_schema"
The subject of ...
*)

This content goes into __fund_cons:

=== Fundamental concepts and assumptions

The *method_definition_schema* provides ...

becomes:

(*"method_definition_schema.__fund_cons"

The *method_definition_schema* provides ...
*)

Then this text:

=== method_definition_schema type definitions

==== relationship_with_condition

A *relationship_with_condition* type ...

EXPRESS specification:

[%unnumbered]
[source,html]
----
*)
TYPE relationship_with_condition = SELECT
  (action_method_relationship,
   action_relationship,
   context_dependent_action_method_relationship,
   context_dependent_action_relationship);
END_TYPE;
(*
----

==== process_or_process_relationship

A *process_or_process_relationship* type ...

EXPRESS specification:

[%unnumbered]
[source,html]
----
*)
TYPE process_or_process_relationship = SELECT
  (product_definition_process,
   property_process,
   relationship_with_condition);
END_TYPE;
(*
----

⇒ becomes:

(*"method_definition_schema.relationship_with_condition"
A *relationship_with_condition* type ...
*)

TYPE relationship_with_condition = SELECT
  (action_method_relationship,
   action_relationship,
   context_dependent_action_method_relationship,
   context_dependent_action_relationship);
END_TYPE;

(*"method_definition_schema.process_or_process_relationship"
A *process_or_process_relationship* type...
*)

TYPE process_or_process_relationship = SELECT
  (product_definition_process,
   property_process,
   relationship_with_condition);
END_TYPE;

Content conversion

Schema information conversion

General

In a schema if there are lines like this:

ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;

It means that action_method_with_associated_documents is defined in the current schema.

Given a text like this, we need to convert them:

An *action_method* defines a potential means of satisfying an *action*.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*,
specify different types of **action_method**s
that may be used to satisfy an action.

To reflect the actual EXPRESS entity with schema information:

An *action_method* defines a potential means of satisfying an *action*.
An <<express:method_definition_schema.action_method_to_select_from,action_method_to_select_from>>,
an <<express:method_definition_schema.action_method_with_associated_document,action_method_with_associated_documents>>,
and an
<<express:method_definition_schema.action_method_associated_documents_constrained,action_method_associated_documents_constrained>>,
specify different types of **action_method**s that may be used to satisfy an action.

References to external schema

In a schema if there are lines like this:

REFERENCE FROM action_schema
    (action_method,
     action_method_relationship,
     action_relationship);

This means that the entities called action_method, action_method_relationship and action_relationship come from the schema action_schema.

Given a text like this, we need to convert them:

An *action_method* defines a potential means of satisfying an *action*.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*,
specify different types of **action_method**s
that may be used to satisfy an action.

To reflect the actual EXPRESS entity with fully resolved schema information:

An <<express:action_schema.action_method,action_method>>
defines a potential means of satisfying an
<<express:action_schema.action,action>>.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*, specify different types of
<<express:action_schema.action_method,action_methods>> that may be used to satisfy an action.

Fully expressed references

Combining the above two approaches, from this text:

An *action_method* defines a potential means of satisfying an *action*.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*,
specify different types of **action_method**s
that may be used to satisfy an action.

We get:

An <<express:action_schema.action_method,action_method>>
defines a potential means of satisfying an
<<express:action_schema.action,action>>.
An <<express:method_definition_schema.action_method_to_select_from,action_method_to_select_from>>,
an <<express:method_definition_schema.action_method_with_associated_document,action_method_with_associated_documents>>,
and an
<<express:method_definition_schema.action_method_associated_documents_constrained,action_method_associated_documents_constrained>>,
specify different types of <<express:action_schema.action_method,action_methods>>
that may be used to satisfy an action.

Example

The converted method_definition_schema.exp would look like this:

SCHEMA method_definition_schema;

REFERENCE FROM action_schema
    (action_method,
     action_method_relationship,
     action_relationship);

...

(*"method_definition_schema.__note
The schemas referenced above can be found in the following parts of ISO 10303:

action_schema:: <<iso10303-41>>
document_schema:: <<iso10303-41>>
...
*)

(*"method_definition_schema.__note
See <<annexD>>, <<figD1>>, for a graphical presentation of this schema.
*)

(*"method_definition_schema"
The subject of ...
*)

(*"method_definition_schema.__fund_cons"
The *method_definition_schema* provides...
*)

(*"method_definition_schema.relationship_with_condition"
A *relationship_with_condition* type ...
*)

TYPE relationship_with_condition = SELECT
  (action_method_relationship,
   action_relationship,
   context_dependent_action_method_relationship,
   context_dependent_action_relationship);
END_TYPE;

(*"method_definition_schema.process_or_process_relationship"
A *process_or_process_relationship* type ...
*)

TYPE process_or_process_relationship = SELECT
  (product_definition_process,
   property_process,
   relationship_with_condition);
END_TYPE;

(*"method_definition_schema.action_method_with_associated_documents"
An **action_method_with_associated_document**s is a type ...
*)

(*"method_definition_schema.action_method_with_associated_documents.__example"
A process specification document that ...
*)

ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;

...

END_SCHEMA; -- method_definition_schema

Attribute conversion

Given this text:

[source]
----
ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;
----

...

Attribute definitions:

**document**s:: the set of one or more documents that identifies the *action_method*.

It should be converted into:

ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;

(*"method_definition_schema.action_method_with_associated_documents.documents"
the set of one or more documents that identifies the *action_method*.
*)

Formal propositions conversion

Given this text:

Formal propositions:

*WR1*:: The *number_of_elements* shall be greater than or equal to one.
*WR2*:: The value of the *number_of_elements* shall ...

It should be converted into:

(*"method_definition_schema.action_method_to_select_from.WR1"
The *number_of_elements* shall be greater than or equal to one.
*)

(*"method_definition_schema.action_method_to_select_from.WR2"
The value of the *number_of_elements* shall ...
*)

Informal propositions conversion

Given this text:

[source]
----
ENTITY serial_action_method
  SUBTYPE OF (action_method_relationship);
END_ENTITY;
----
...

Informal propositions:

*IP1*:: Individual **action_method**s in a collection...

It should be converted into:

(*"method_definition_schema.serial_action_method.IP1"
Individual **action_method**s in a collection...
*)

Notes, examples, figures and tables

These objects are to be converted into native Annotated EXPRESS remarks.

For example, this content:

==== sequential_method

A *sequential_method* is ...

NOTE: See <<annexE>> for an extended example using indexes for *sequential_method*.

EXPRESS specification:

[%unnumbered]
[source]
----
*)
ENTITY sequential_method
  SUBTYPE OF (serial_action_method);
  sequence_position : count_measure;
END_ENTITY ;
(*
----

Attribute definitions:

*sequence_position*:: the position of ...

Informal propositions:

*IP1*:: There shall be ...

NOTE: This proposition...

NOTE: If the *sequential_method* ...

NOTE: The context ...

Needs to become:

ENTITY sequential_method
  SUBTYPE OF (serial_action_method);
  sequence_position : count_measure;
END_ENTITY ;

(*"method_definition_schema.sequential_method"
A *sequential_method* is ...
*)

(*"method_definition_schema.sequential_method.__note"
This proposition ...
*)

(*"method_definition_schema.sequential_method.__note"
If the *sequential_method* ...
*)

(*"method_definition_schema.sequential_method.__note"
The context ...
*)

(*"method_definition_schema.sequential_method.sequence_position"
the position of ...
*)

(*"method_definition_schema.sequential_method.wr:IP1"
There shall be ...
*)

Note	Place the annotations after the EXPRESS declarations.