From a6f6d406e12361fa6743d578f220f82fa7474c58 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Wed, 15 May 2024 23:29:35 +0900 Subject: [PATCH] feat: add annotated express doc --- _pages/specs.html | 6 - _pages/standards.adoc | 12 + nav-links.html | 2 + standards/annotated-express.adoc | 238 ++++++++++++ standards/conversion-guide.adoc | 646 +++++++++++++++++++++++++++++++ 5 files changed, 898 insertions(+), 6 deletions(-) delete mode 100644 _pages/specs.html create mode 100644 _pages/standards.adoc create mode 100644 standards/annotated-express.adoc create mode 100644 standards/conversion-guide.adoc diff --git a/_pages/specs.html b/_pages/specs.html deleted file mode 100644 index 839df9a..0000000 --- a/_pages/specs.html +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: ELF specifications -description: Open specifications for the EXPRESS language family -layout: spec-index -hero_include: index-page-hero.html ---- diff --git a/_pages/standards.adoc b/_pages/standards.adoc new file mode 100644 index 0000000..4dc8805 --- /dev/null +++ b/_pages/standards.adoc @@ -0,0 +1,12 @@ +--- +layout: docs-base +html-class: docs-page +title: ELF standards +article_header_title: ELF standards +--- +:page-liquid: + +== ELF standards + +* link:/standards/annotated-express[Annotated EXPRESS] +* link:/standards/conversion-guide[Model-based EXPRESS documentation] diff --git a/nav-links.html b/nav-links.html index 8f3c964..3cf98d6 100644 --- a/nav-links.html +++ b/nav-links.html @@ -14,6 +14,8 @@ {% include nav-page-link.html htmlclass="learn" url="/learn/" title="Learn" active_for_nested=true %} +{% include nav-page-link.html htmlclass="standards" url="/standards/" title="Standards" active_for_nested=true %} + {% include nav-page-link.html htmlclass="references" url="/references/" title="References" active_for_nested=true %} {% include nav-page-link.html htmlclass="shop" url="https://express-language-foundation-2.creator-spring.com" title="Shop" active_for_nested=true %} diff --git a/standards/annotated-express.adoc b/standards/annotated-express.adoc new file mode 100644 index 0000000..6a1b65e --- /dev/null +++ b/standards/annotated-express.adoc @@ -0,0 +1,238 @@ +--- +layout: docs-base +--- +:stem: + +== Annotated EXPRESS syntax + +=== General + +EXPRESS is a data modelling language offered in a code-like syntax. + +As in typical source code, you can insert comments that do not get parsed or +interpreted by the compiler. +For example, in C, block comments are realized wth `/* ... */`. + +In EXPRESS, the remark tag syntax is `(* ... *)`, indicating that anything in +the `...` is considered documentation. + +Annotated EXPRESS is a set of rules that build on top of the EXPRESS remark tag +syntax for documentation and description of EXPRESS code. It can be considered in the same +category of Doxygen for C, JavaDoc for Java, RubyDoc for Ruby. + +Annotated EXPRESS accepts Metanorma AsciiDoc as content. + +=== Basic syntax + +Annotated EXPRESS uses the "named remark tag" syntax described in the EXPRESS +language manual. + +---- +(*"NAME" +... +*) +---- + +Where: +* `NAME` is a "tag" that references an EXPRESS object, such as a schema, +entity, property, function, or rule. + +A tag looks like `schema_name.entity_name.property_name`. + +[example] +==== +Given this schema `action_schema`: +---- +SCHEMA action_schema; + ENTITY action; + name : label; + description : OPTIONAL text; + chosen_method : action_method; + DERIVE + id : identifier := get_id_value(SELF); + WHERE + WR1: SIZEOF(USEDIN(SELF, 'BASIC_ATTRIBUTE_SCHEMA.' + 'ID_ATTRIBUTE.IDENTIFIED_ITEM')) <= 1; + END_ENTITY; +END_SCHEMA; +---- + +The tag references would be: + +* to the schema: `"action_schema"` +* to the entity `action`: `"action_schema.action"` +* to the property `name`: `"action_schema.action.name"` +* to the derived property `id`: `"action_schema.action.id"` +* to the where rule `WR1`: `"action_schema.action.wr:WR1"` +==== + +=== Types of remarks + +==== Basic objects + +In Annotated EXPRESS, there are a few types of named remarks: + +* `(*"{TAG}" ... *)` refers to the description of EXPRESS object `{TAG}` + +* `(*"{TAG}.__note" ... *)` refers to a note that applies to EXPRESS object +`{TAG}` + +* `(*"{TAG}.__example" ... *)` refers to a usage example that applies to the +EXPRESS object `{TAG}` + +* `(*"{TAG}.__figure" ... *)` refers to a figure that applies to the EXPRESS +object `{TAG}`, which can be re-used within its notes or examples. + +* `(*"{TAG}.__table" ... *)` refers to a table that applies to the EXPRESS +object `{TAG}`, which can be re-used within its notes or examples. + +These different types of remarks can be in multiple instances, for example, +multiple `(*"{TAG}" ... *)` remarks can be made in an EXPRESS file to describe +the particular object. + +These named remarks are not bound to any particular location in an EXPRESS file. +For example, they can be made immediately after the declaration of the EXPRESS +object, or collected at the top or bottom of the EXPRESS file. + +==== STEPmod remarks + +In STEPmod, which is the STEP modules library, two additional types of +named remarks are used. + +* `(*"{SCHEMA_TAG}.__fund_cons" ... *)` describes the +"Fundamental concepts and assumptions" of a schema. It is a ISO 10303 convention +to describe the concepts and assumptions of the schema. The tag must reference +an EXPRESS schema. + +* `(*"{SCHEMA_TAG}.__expressg" ... *)` provides EXPRESS-G diagrams relevant +to the EXPRESS schema. These diagrams can describe an architecture view that +involves the named schema. The tag must reference an EXPRESS schema. + + +=== Content syntax + +==== General + +Annotated EXPRESS (in its current form) accepts Metanorma AsciiDoc. +The syntax of Metanorma AsciiDoc is described at https://www.metanorma.org. + +There are several extensions to Metanorma AsciiDoc for the documentation of +EXPRESS. + +==== EXPRESS object cross-references + +In Annotated EXPRESS remark content, it is often necessary to cross-reference +other EXPRESS objects. + +In the generated EXPRESS documentation, these references become links to the +definition of the target EXPRESS objects. + +The syntax is: + +---- +<> +---- + +or + +---- +<> +---- + +Where: + +* `{TAG}` is the EXPRESS named tag, e.g. `action_schema.action_method` +* `{RENDER TEXT}` is the desired rendering text, if different from the named tag, + e.g. `action methods` + + + +== Usage + +=== Application on schemas + +Let's take +https://github.com/metanorma/annotated-express/blob/main/data/resources/action_schema/action_schema_annotated.exp[`action_schema.exp`] +as an example. + +---- +(*"action_schema" +The subject of the *action_schema* is the description of actions, the reasons +for these actions, and the status of these actions. +*) + +(*"action_schema.__fund_cons" +Action information can be attached to any aspect of product data. +*) + +(*"action_schema.__example" +Reasons for action include evolving user requirements, manufacturing problems +and difficulties that arise when a product is in use. +*) + +(*"action_schema.__expressg" +[.svgmap] +==== +image::action_schemaexpg1.svg[] + +* <>; 1 +* <>; 2 +* <>; 3 +==== +*) +---- + +* Content in `(*"action_schema" ... *)` provides a basic description (and +purpose) of the schema. + +* Content in `(*"action_schema.__fund_cons" ... *)` describes the concepts and +assumptions in creating this schema. + +* Content in `(*"action_schema.__example" ... *)` describes an example on how +the schema can be used. + +* Content in `(*"action_schema.__expressg" ... *)` provides a graphical +diagram (in Metanorma AsciiDoc syntax with an `svg` here) relevant to the +understanding of the schema. + + +=== Application on entities + +Entities inside the schema are accessed using the `{schema}.{entity}` syntax +(potentially multiple dots). + +For example, the `action_schema.supported_item` entity is documented like this: + +---- +(*"action_schema.supported_item" +The *supported_item* allows for the designation of an +<>, an +<>, or an +<>. +*) + +(*"action_schema.supported_item.__note" +This specifies the use of an +<>. +*) +---- + +Notice that within the named remark `action_schema.supported_item.__note`, +there is an `<>` link which references another EXPRESS object +`action_schema.action_resource`. + + +=== Application on other EXPRESS objects + +Annotations can be made to any EXPRESS objects that are referencable, +including: + +* ENTITY +** properties +** DERIVE properties +** WHERE rules +** IP: Informal proposition rules +* TYPE +* FUNCTION +** LOCAL variables + + diff --git a/standards/conversion-guide.adoc b/standards/conversion-guide.adoc new file mode 100644 index 0000000..6d08a78 --- /dev/null +++ b/standards/conversion-guide.adoc @@ -0,0 +1,646 @@ +--- +layout: docs-base +--- +:stem: + +== 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: + +[source,adoc] +---- +{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: + +[source,adoc] +---- +{EXPRESS schema content} + +(* +{document content} +*) + +{EXPRESS schema content continued} +---- + +Now, anything outside the remarks is in plain EXPRESS. + + +==== Example + +We take +https://github.com/metanorma/iso-10303-detached-docs/blob/main/sources/iso-10303-49/sections/04-method_definition.adoc[ISO 10303-49, Clause 4] +as an example. + +This file `sections/04-method_definition.adoc` contains this content +(partial copy): + +[source] +------ +[[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:: <> +document_schema:: <> +... +==== + +NOTE: See <>, <>, 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`): + +[source] +---- +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:: <> +document_schema:: <> +... +*) + +(*"method_definition_schema.__note +See <>, <>, for a graphical presentation of this schema. +*) +---- + +Then, this content goes into a Annotated EXPRESS block: + +[source,adoc] +---- +=== Introduction + +The subject of ... +---- + +becomes: + +[source] +---- +(*"method_definition_schema" +The subject of ... +*) +---- + +This content goes into `__fund_cons`: + +[source,adoc] +---- +=== Fundamental concepts and assumptions + +The *method_definition_schema* provides ... +---- + +becomes: + +---- +(*"method_definition_schema.__fund_cons" + +The *method_definition_schema* provides ... +*) +---- + +Then this text: + +[source,adoc] +------ +=== 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: + +[source] +---- +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: + +[source,adoc] +---- +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: + +[source,adoc] +---- +An *action_method* defines a potential means of satisfying an *action*. +An <>, +an <>, +and an +<>, +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: + +[source,adoc] +---- +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: + +[source,adoc] +---- +An <> +defines a potential means of satisfying an +<>. +An *action_method_to_select_from*, an **action_method_with_associated_document**s, +and an *action_method_associated_documents_constrained*, specify different types of +<> 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 <> +defines a potential means of satisfying an +<>. +An <>, +an <>, +and an +<>, +specify different types of <> +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:: <> +document_schema:: <> +... +*) + +(*"method_definition_schema.__note +See <>, <>, 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] +------ +[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: + +[source] +---- +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: + +[source] +---- +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: + +[source] +---- +(*"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] +------ +[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: + +[source] +---- +(*"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: + +[source,adoc] +------ +==== sequential_method + +A *sequential_method* is ... + +NOTE: See <> 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: + +[source] +---- +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.