diff --git a/.vscode/configurationCache.log b/.vscode/configurationCache.log new file mode 100644 index 0000000..48e2bc2 --- /dev/null +++ b/.vscode/configurationCache.log @@ -0,0 +1 @@ +{"buildTargets":["_site","all","bundle","clean","open","serve"],"launchTargets":[],"customConfigurationProvider":{"workspaceBrowse":{"browsePath":[],"compilerArgs":[]},"fileIndex":[]}} \ No newline at end of file diff --git a/nav-links.html b/nav-links.html index 3cf98d6..61705b8 100644 --- a/nav-links.html +++ b/nav-links.html @@ -14,7 +14,7 @@ {% 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="standards" url="/docs/" title="Standards" active_for_nested=true %} {% include nav-page-link.html htmlclass="references" url="/references/" title="References" active_for_nested=true %} diff --git a/standards/annotated-express.adoc b/standards/annotated-express.adoc deleted file mode 100644 index 47380f8..0000000 --- a/standards/annotated-express.adoc +++ /dev/null @@ -1,240 +0,0 @@ ---- -layout: docs-base ---- -:stem: - -== Annotated EXPRESS syntax (draft) - -This is a living specification for Annotated EXPRESS. - -=== 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 deleted file mode 100644 index 6d08a78..0000000 --- a/standards/conversion-guide.adoc +++ /dev/null @@ -1,646 +0,0 @@ ---- -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.