metanorma-plugin-lutaml 0.4.6 → 0.4.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 636e4bec2488f6e9044ab15915f37485cf08ddcec31e2e852c9d381188b2d99e
-  data.tar.gz: c9c0e74be3a5d5856336f5202c7cb18e442d18548e1a29f476b72694d767eac5
+  metadata.gz: 241b12b07d457ea48176e22ce2cacc4a533c2ffc5435465637d51d37d6da1e80
+  data.tar.gz: 2a2bd1fe63f4febdae9ce40679f525cfe476f2a773ab15c5de9622145dbdbd7f
 SHA512:
-  metadata.gz: 0e15f9f636f56f0f110baaec844dde2691aefbc882d3be878abe4ccd57e917472847ceb7dcca32f41c1d713d202f4e5caed0530171aad7d368fdde16431fdaee
-  data.tar.gz: 623fb7a37ad8be5e2aac50bbb32be6f366c75abeb47226800af1ae3ec88e24e6c024b7f57016862791f3fa89f4e8181a5c55710f71ab557d25f13480e88e53d9
+  metadata.gz: 33ef546ecbc2929104ccda434021ef50afbd067d5f466b7d07181aea92415a15aaad67fdf3848b4bd0cf93878e032b007b437a630b1d5ea87398396b446b622f
+  data.tar.gz: 7373d126f78af6063dbfea6076018712f4185a6c0e75e50309befc23bf1e34beeec86ab80d8b36f9c73eb7e5ae238b0522e85ec307ee434538222790cc05d8c3

data/README.adoc

@@ -1,21 +1,36 @@
-= metanorma-plugin-lutaml
+= Metanorma LutaML plugin (metanorma-plugin-lutaml)
 
 image:https://github.com/metanorma/metanorma-plugin-lutaml/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-plugin-lutaml/actions?workflow=rake"]
 
-== Functionality
+== Purpose
 
-Metanorma plugin that allows you to access lutaml objects from a Metanorma document
+LutaML is a data model accessor that supports various data model formats,
+including:
 
-=== Installation
+* EXPRESS (`*.exp` files)
+* OMG UML in XMI format (`*.xmi` files)
+
+This plugin allows you to access LutaML models from within a Metanorma document.
+
+== Installation
 
 [source,console]
 ----
 $ gem install metanorma-plugin-lutaml
 ----
 
-=== Usage, `lutaml` macro
 
-Given `example.exp` file with the content:
+== Usage with EXPRESS
+
+=== General
+
+LutaML supports accessing EXPRESS models via the
+https://github.com/lutaml/expressir[Expressir] parser.
+
+
+=== Usage of the `lutaml` macro
+
+Given an `example.exp` EXPRESS file with the content:
 
 [source,exp]
 ----
@@ -71,17 +86,18 @@ source directory that `[lutaml]` is used (e.g., if
 `/foo/bar/doc.adoc`, the data file is expected to be found at
 `/foo/bar/example.exp`);
 
-* `{my_context}` is the name where the EXPRESS Repository read from the .exp
-file can be accessed with. Context object is a serialized
-`Expressir::Model::Repository` object with all variable names available. See
+* `{my_context}` is the name where the EXPRESS Repository read from the `.exp`
+file can be accessed with.
+
+** The `context` object is a serialized `Expressir::Model::Repository` object
+with all variable names available. See
 https://github.com/lutaml/expressir[Expressir] docs for reference.
 `{my_context}` has `schemas` method to access Expressir
 https://github.com/lutaml/expressir/blob/master/lib/expressir/model/schema.rb[schemas]
 
 Will produce this output:
 
-[source,adoc]
------
+____
 == test_schema
 
 === my_type1
@@ -89,9 +105,9 @@ Will produce this output:
 === my_type3
 === my_type4
 === my_type5
------
+____
 
-This macro also supports `.lutaml` files.
+This command also supports `.lutaml` files.
 
 Instead of using the direct path to the file one can use `lutaml-express-index`
 document attribute to supply directory with express files or YAML index file to
@@ -120,19 +136,22 @@ Example of usage:
 -----
 = Document title
 Author
-:lutaml-express-index: my_custom_name; /path/to/express_files; cache=/path/to/cache_file.yaml
-[lutaml,my_custom_name,my_context]
+:lutaml-express-index: index_name; /path/to/express_files; cache=/path/to/cache_file.yaml
+[lutaml,index_name,context]
 ----
-{% for schema in my_context.schemas %}
+{% for schema in context.schemas %}
 == {{schema.id}}
 {% endfor %}
 ----
 -----
 
-=== Usage, `lutaml_diagram` macro
+== Usage with UML
 
-This macro allows to quickly render lutaml file as diagram image.
-Given `example.lutaml` file with the content:
+=== Rendering a LutaML view: `lutaml_diagram`
+
+This command allows to quickly render a LutaML view as an image file.
+
+Given a file `example.lutaml` file with content:
 
 [source,java]
 ----
@@ -142,7 +161,7 @@ diagram MyView {
   enum AddressClassProfile {
     imlicistAttributeProfile: CharacterString [0..1] {
       definition
-        this is multiline with `ascidoc`
+        this is multiline with `asciidoc`
       end definition
     }
   }
@@ -156,16 +175,17 @@ diagram MyView {
 }
 ----
 
-And the `lutaml_diagram` macro:
+The `lutaml_diagram` command will add the image to the document.
 
 [source,adoc]
 -----
 lutaml_diagram::example.lutaml[]
 -----
 
-Will add diagram image to the document
+The `lutaml_diagram` command can also be used to denote a block with an embedded
+LutaML view.
 
-Also one can use `lutaml_diagram` block with embed lutaml code instead of block macro. Example:
+For example:
 
 [source,java]
 ----
@@ -176,9 +196,9 @@ diagram MyView {
 
   enum AddressClassProfile {
     imlicistAttributeProfile: CharacterString [0..1] {
-      definition
-        this is multiline with `ascidoc`
-      end definition
+      definition {
+        This is multiline AsciiDoc content.
+      }
     }
   }
 
@@ -193,9 +213,9 @@ diagram MyView {
 ----
 
 
-=== Usage, `lutaml_uml_attributes_table` macro
+=== `lutaml_uml_attributes_table`
 
-This macro allows to quickly render data model attributes/values tables.
+This command allows rendering definition tables for a UML model.
 
 Given `example.lutaml` file with the content:
 
@@ -230,23 +250,22 @@ And the `lutaml_uml_attributes_table` macro:
 
 Will produce this output:
 
-[source,adoc]
------
+____
 === AttributeProfile
 
-
 .AttributeProfile attributes
 |===
 |Name |Definition |Mandatory/ Optional/ Conditional |Max Occur |Data Type
 
-|addressClassProfile |TODO: enum 's definition |M |1 | `CharacterString`
+|addressClassProfile |TODO: enum's definition |M |1 | `CharacterString`
 
 |imlicistAttributeProfile |this is attribute definition with multiply lines |M |1 | `CharacterString`
 
 |===
------
+____
 
-In case of "enumeration"(AddressClassProfile) entity:
+
+In case of "enumeration" (AddressClassProfile) entity:
 
 [source,adoc]
 -----
@@ -255,23 +274,21 @@ In case of "enumeration"(AddressClassProfile) entity:
 
 Will produce this output:
 
-[source,adoc]
------
+____
 === AddressClassProfile
 
-
 .AddressClassProfile values
 |===
 |Name |Definition
 
-|imlicistAttributeProfile |this is multiline with `ascidoc`
+|imlicistAttributeProfile |this is multiline with `asciidoc`
 
 |===
------
+____
 
-=== Usage, `lutaml_uml_datamodel_description` macro
+=== Usage of `lutaml_uml_datamodel_description` macro
 
-This macro allows to quickly render data model packages and its dependent
+This command allows to quickly render data model packages and its dependent
 objects for supplied XMI file.
 
 Given an Enterprise Architect `example.xmi` file with 2 packages:
@@ -290,7 +307,7 @@ The `lutaml_uml_datamodel_description` macro can be used:
 my text
 ....
 
-[.diagram_include_block, base_path="requirements/"]
+[.diagram_include_block, base_path="requirements/", format="emf"]
 ....
 Diagram text
 ....
@@ -332,41 +349,67 @@ Where:
 
 * `path/to/example.xmi` - required, path to the XMI file to render
 
-* `[.before]` - macro to add additional text before the rendered output, can be used only once, additional occurrences of macro will overwrite text, not that `literal` block style must be used in there(eg `....`)
+* `[.before]` - block text that adds additional text before the rendered output, can be used only once, additional occurrences of macro will overwrite text, not that `literal` block style must be used in there(eg `....`)
+
+* `[.after]` - block text that adds additional text after the rendered output, can be used only once, additional occurrences of macro will overwrite text
 
-* `[.after]` - macro to add additional text after the rendered output, can be used only once, additional occurrences of macro will overwrite text
+* `[.after, package="Another"]` - block text to be inserted before(after in case of `.before` name) the package
 
-* `[.after, package="Another"]` - macro with text to be inserted before(after in case of `.before` name) the package
+* `[.package_text, position="after", package="Another"]` - include custom adoc code into package rendered body, `position` is a arequired attribute which tells where to insert the code.
 
-* `[.diagram_include_block]` - macro to automatically include diagram images. Attribute `base_path` is a required attribute to supply path prefix where to look for a digram image. The logic is as follows:
+* `[.package_text, package="Another"]` - same as above, but include block will be included only for supplied package name
+
+* `[.diagram_include_block]` - block text to automatically include diagram images. Attribute `base_path` is a required attribute to supply path prefix where to look for a diagram image. `format` is an optional attribute that tells what file extension to use when including diagram file.
++
+The logic is as follows:
 [source,adoc]
 -----
 {% for diagram in package.diagrams %}
 [[figure-{{ diagram.xmi_id }}]]
 .{{ diagram.name }}
-image::{{ image_base_path }}/{{ diagram.xmi_id }}.png[]
+image::{{ image_base_path }}/{{ diagram.xmi_id }}.{{ format | default: 'png' }}[]
 
 {% if diagram.definition %}
 {{ diagram.definition | html2adoc }}
 {% endif %}
 {% endfor %}
 -----
-Eg: script will take package diagrams supplied in xmi file and will try to include `image` with the name equal to diagram' xmi_id attribute plus `.png`. Also one can add any text to the macro text, it will be added as paragraph before each image include.
+
+For instance, the script will take package diagrams supplied in the XMI file and will try to include `image` with the name equal to diagram' xmi_id attribute plus `.png`. Also one can add any text to the macro text, it will be added as paragraph before each image include.
 
 * `[.diagram_include_block, package="Another"]` - same as above, but diagram will be included only for supplied package name
 
-* `[.include_block, base_path="spec/fixtures"]` - macro to inlude files(adoc/liquid) for each package name. Attribute `base_path` is a required attribute to supply path prefix where to look for file to include. Macro will look for a file called `base_path` + `/` `_package_name`(downcase, replace : -> '', ' ' -> '_') + `.adoc`[`.liquid`], eg for package 'My Package name' and `base_path` eq to `my/path`, macro will look for the following file path: `my/path/_my_package_name.adoc`.
+* `[.include_block, base_path="spec/fixtures"]` - macro to include files (`*.adoc` or `*.liquid`) for each package name. Attribute `base_path` is a required attribute to supply path prefix where to look for file to include. Macro will look for a file called `base_path` + `/` `_package_name`(downcase, replace : -> '', ' ' -> '_') + `.adoc`[`.liquid`], eg for package 'My Package name' and `base_path` eq to `my/path`, macro will look for the following file path: `my/path/_my_package_name.adoc`.
 
 * `[.include_block, package="Another", base_path="spec/fixtures"]` - same as above, but include block will be included only for supplied package name
 
-In addition to macroses listed above that can be used only inside `lutaml_uml_datamodel_description` macro there is another macro called `lutaml_figure`. `lutaml_figure` is used to lookup and reference xmi package diagrams. The syntax is as follows:
+
+NOTE: .after, .before, package_text and include_block macroses all can be used with additional option - `liquid`, if this option is supplied then the code inside block will be interpolated in liquid context
+
+
+There are two other commands that are used to refer to LutaML generated document elements:
+
+* `lutaml_figure`. Provides a reference anchor to a figure defined in the XMI
+  file, using its XMI ID for reference.
+
+* `lutaml_table`. Provides a reference anchor to the definition tables of a
+  particular package, class, enumeration or data type object in the XMI.
+
+The syntax is as follows:
 
 [source,adoc]
 -----
+// For lutaml_figure
 This is lutaml_figure::[package="Wrapper root package", name="Fig B1 Full model"] figure
+
+// For lutaml_table
+This is lutaml_table::[package="Wrapper root package"] package
+This is lutaml_table::[package="Wrapper root package", class="my name"] class
+This is lutaml_table::[package="Wrapper root package", enum="my name"] enumeration
+This is lutaml_table::[package="Wrapper root package", data_type="my name"] data type
 -----
 
-This code will be transformed into `<<figure-{diagram.xmi_id}>>` and will point to diagram figure. One can only use this macro when document rendered `lutaml_uml_datamodel_description` macro as it needs diagram lookup table in order to refernce package diagram.
+This code will be transformed into `<<figure-{diagram.xmi_id}>>` and will point to diagram figure. One can only use this macro when document rendered `lutaml_uml_datamodel_description` macro as it needs diagram lookup table in order to reference package diagram.
 
 Will produce this output:
 
@@ -380,18 +423,17 @@ Diagram text
 
 [[figure-EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29]]
 .CityGML Package Diagram
-image::requirements//EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29.png[]
+image::requirements/EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29.png[]
 
 BuildingFurnitureFunctionValue is a code list that enumerates the different purposes of a BuildingFurniture.
 
 [[figure-EAID_938AE961_1C57_4052_B964_997D1894A58D]]
 .Use of ISO and OASIS standards in CityGML
-image::requirements//EAID_938AE961_1C57_4052_B964_997D1894A58D.png[]
+image::requirements/EAID_938AE961_1C57_4052_B964_997D1894A58D.png[]
 
 The CityGML package is organized into
 2 packages with 1 modules:
 
-[arabic]
 . Another package
 . CityTML package
 
@@ -401,18 +443,17 @@ Content for CityGML package
 
 ==== Defining tables
 
-[arabic]
-.<<tab-P-another-C-abstractatomictimeseries>> -- Elements of Another::AbstractAtomicTimeseries
+.<<section-EAPK_9C96A88B_E98B_490b_8A9C_24AEDAC64293>> -- Elements of &#8220;Another::AbstractAtomicTimeseries&#8221; (class)
 
-[[tab-P-another-C-abstractatomictimeseries]]
-.Elements of Another::AbstractAtomicTimeseries
+[[section-EAPK_9C96A88B_E98B_490b_8A9C_24AEDAC64293]]
+.Elements of &#8220;Another::AbstractAtomicTimeseries&#8221; (class)
 [width="100%",cols="a,a,a,a,a,a,a,a"]
 |===
 h|Name: 7+| AbstractAtomicTimeseries
 h|Definition: 7+|
 h|Stereotype: 7+| interface
 h|Abstract: 7+|
-.1+h|Associations: 7+| (none)
+h|Associations: 7+| (none)
 .4+h|Public attributes:
 | _Name_
 2+| _Definition_
@@ -446,13 +487,20 @@ h|Constraints: 7+| (none)
 text after CityGML package
 -----
 
-In addition to just supplying XMI file, this macro also supports YAML
-configuration file.
+In addition to the XMI file, this macro also supports a YAML configuration file
+that specifies:
+
+* What packages to include in the render;
+
+* What render style is desired;
 
-The format for using YAML is this:
+* Location of the root package (which package should the iterative process start
+  at).
+
+The format for using the YAML configuration file:
 
 [source,yaml]
------
+----
 ---
 packages:
   # includes these packages
@@ -461,34 +509,67 @@ packages:
   - three
   # skips these packages
   - skip: four
-render_style: entity_list|data_dictionary|default
+render_style: entity_list | data_dictionary | default
 section_depth: 2
------
+----
 
 Where:
 
 * `packages` - required, root element with the list of strings or objects
+
 * `Package *` - pattern matching, specifies lookup condition for packages to
 render.
 +
 NOTE: In this example, it is equal to the following regular expression: `/^Package.*$/`
 
 * `skip: four` - object with package name to skip
-* `render_style` - what template to use to render packages, can be: entity_list, data_dictionary or default
-* `section_depth` - what package to use as root package for render, eg `section_depth` equal to 2 tells processor to use first nested package of the first root packages in xmi file. Example: if xmi file has this package structure: [{ name: 'One', packages: [{ name: 'one-1' }, { name: 'one-2' }] }, { name: 'Two', packages: [{ name: 'two-1' }, { name: 'two-2' }] }] and we have `section_depth` equal to 2, root package will be `one-1`
+
+* `render_style` - what template to use to render packages, can be one of:
+
+** `entity_list`
+
+** `data_dictionary`; or
+
+** `default`
+
+* `section_depth` - what package to use as root package for render.
+e.g., a `section_depth` equal to `2` tells the processor to use the first
+nested package of the first root packages in XMI file.
++
+EXAMPLE: If the XMI file has this package structure, and we have `section_depth`
+equal to 2, root package will be `one-1`.
++
+[source,json]
+----
+[
+  {
+    name: 'One',
+    packages: [{ name: 'one-1' }, { name: 'one-2' }]
+  },
+  {
+    name: 'Two',
+    packages: [{ name: 'two-1' }, { name: 'two-2' }]
+  }
+]
+----
 
 Usage with macro:
 
 [source,adoc]
------
+--
 [lutaml_uml_datamodel_description, path/to/example.xmi, path/to/config.yml]
-....
------
+----
+[.diagram_include_block, base_path="models/Images", format="png"]
+...
+...
+----
+--
 
-The macro processor will read supplied YAML file and arrange packages according
-to the order supplied in the config file, also all packages supplied as `skip`
-will be skipped during render
+The processor will read the supplied YAML config file (`path/to/config.yml`),
+and iterate through packages according to the order supplied in the file. All
+packages that matches `skip` in the YAML config file will be skipped during
+render.
 
 == Documentation
 
-Please refer to https://www.metanorma.com.
+Please refer to https://www.metanorma.oeg.