EXPRESS schema documentation should follow SC 4 Supplementary Directives

[opoudjis]

I noticed this when reviewing the prototype part 41 document. There were missing descriptions for TYPES. The SC4 supplementary directives require descriptions for all declarations except CONSTANT and interfaces.

If no text is provided in descriptions.xml for SELECT and ENUMERATION types, the XSLT pastes boilerplate descriptions in the document.

That boilerplate will need to be inserted by the metanorma-based tooling to cover that use case.

Which means that stepmod2mn will need to insert them as remarks, if there are none present. @ronaldtse and/or @TRThurman, you will need to direct @Intelligent2013 to where the XSLT resides, so he can replicate it.

[ronaldtse]

@Intelligent2013 all the XSLT boilerplate content is under “xsl”

[TRThurman]

I sent Ron a copy of the supplementary directives that contains the boilerplate in one document.

[ronaldtse]

The Supplementary Directives text for 5.3, 6.7 and 8 which relate to ISO 10303 is provided here: https://github.com/metanorma/iso-tc184-sc4-directives/blob/master/supplementary-directives.adoc

The exact XSL transformations are available here:

• https://github.com/metanorma/iso-10303-stepmod/blob/master/xsl/sect_4_express.xsl
• https://github.com/metanorma/iso-10303-stepmod/blob/master/xsl/bom_doc/sect_4_express.xsl (for docs under business_object_model/)
• https://github.com/metanorma/iso-10303-stepmod/blob/master/xsl/res_doc/sect_4_express.xsl (for docs under resource_docs/)

[ronaldtse]

Related to https://github.com/metanorma/iso-tc184-sc4-boilerplate/issues/1

[Intelligent2013]

I need some clarification.

1. If no text is provided in descriptions.xml for SELECT and ENUMERATION types, the XSLT pastes boilerplate descriptions in the document.

What is descriptions.xml? Do you mean, for example, like this \data\resources\action_schema\action_schema.xml ?

2. Let's take a look at html view for document ISO 10303-41:

Section 5 Application context has subsection 5.3 Application context type definitions. Section 6 Approval has subsection 6.3 Approval type definitions. Section 7 Basic attribute has subsection 7.3 Basic attribute type definitions. Section 8 Certification doesn't have ... type definitions sections.

That means xslt should put placeholder in the section 8? Or xslt should check type definitions only for section 5?

3. The Supplementary Directives text for 5.3, 6.7 and 8 which relate to ISO 10303 is provided here: https://github.com/metanorma/iso-tc184-sc4-directives/blob/master/supplementary-directives.adoc

I don't understand when xslt should put 6.7 and 8 boilerplates? What are the conditions for this?

[ronaldtse]

descriptions.xml is like this file: https://github.com/metanorma/iso-10303-stepmod/blob/master/data/resources/action_schema/descriptions.xml

[ronaldtse]

Section 8 Certification doesn't have ... type definitions sections.

Because this schema does not have EXPRESS "type" and EXPRESS "function" content.

See https://github.com/metanorma/iso-tc184-sc4-directives/blob/master/supplementary-directives.adoc#672-components-of-a-clause-that-specifies-an-express-schema

[Intelligent2013]

@ronaldtse thank you for explanation, I've thought about something else...

1. sect_4_express.xsl generates some text yet, for example

   
   [[types]]
   == action_schema type definitions

[[action_schema.as_description_attribute_select]] ==== as_description_attribute_select

The as_description_attribute_select type is an extension of the description_attribute_select type. It adds the data type action_request_solution to the list of alternate data types.

In this case should stepmod2mn put boilerplate remark after that additionally?

[General:SC4_xxxx] ... [end_General]

2. How would you like to put the boilerplate:
- as link to boilerplate adoc  or 
- put boilerplate adoc content inside main adoc file? (it seems it is possible via xslt+java extension)

[TRThurman]

sect_4_express.xsl generates some text yet, for example

[[types]] == action_schema type definitions

[[action_schema.as_description_attribute_select]] ==== as_description_attribute_select

The as_description_attribute_select type is an extension of the description_attribute_select type. It adds the data type action_request_solution to the list of alternate data types.

In this case should stepmod2mn put boilerplate remark after that additionally?

No, the above text is the boilerplate.

[Intelligent2013]

I've added boilerplate displaying in https://github.com/metanorma/stepmod2mn/blob/master/src/main/resources/stepmod2mn.adoc.xsl (code must be changed for real values). In boilerplate we can display:

• just text (parameter text)
• content of an external text file (parameter file), file must be accessible
• both text and content of an external text file.

<xsl:call-template name="insertBoilerplate">
  <xsl:with-param name="folder" select="'General'"/>
  <xsl:with-param name="identifier" select="'SC4_xxxx'"/>
  <xsl:with-param name="text">Example: Put boilerplate for type select, see https://github.com/metanorma/iso-tc184-sc4-directives/blob/master/supplementary-directives.adoc</xsl:with-param>
  <xsl:with-param name="file">https://raw.githubusercontent.com/metanorma/stepmod2mn/master/README.adoc</xsl:with-param>
</xsl:call-template>

On next step I need to know how to determine values for folder, identifier.

No, the above text is the boilerplate.

It means that we need to enclose it in

[General:SC4_xxxx]
 ...
 [end_General]

or leave as is?

[TRThurman]

As I understand it, the intent was to make the boilerplate text available at a URI. For now, leave as is since you have a local copy.

[ronaldtse]

@Intelligent2013 I've discussed with @opoudjis , we are envisioning that:

1. We will encode the boilerplate text as liquid templates for adoc includes
2. We will use a git submodule to include boilerplate text inside iso-10303-stepmod

i.e. no remote boilerplate fetches needed in rendering.

Thoughts?

[Intelligent2013]

@ronaldtse

1. We will encode the boilerplate text as liquid templates for adoc includes

To parse liquid templates in stepmod2mn I see two options:

• call (from stepmod2mn) some ruby liquid parser via command line, for example ruby script.rb and put output string in resulted adoc via xslt, or
• parse liquid templates in stepmod2mn with using of Liqp library (https://github.com/bkiers/Liqp)

2. We will use a git submodule to include boilerplate text inside iso-10303-stepmod

I've added boilerplatepath parameter to stepmod2mn command line.

[ronaldtse]

@Intelligent2013 I think stepmod2mn only needs to point to the liquid templates (via AsciiDoc include), Metanorma can read in those liquid templates instead.

Reason is:

1. We don't want to render the boilerplate content in adoc files as static text
2. The authors will want to change the boilerplate text in the future

Thoughts @opoudjis ?

[opoudjis]

It's a vulnerability, so I'm not in love with it, and people really will need to ensure that the submodules are in the right place, but ok. I see that @Intelligent2013 has already added a command line parameter to configure the boilerplate path; that will still be needed to populate any include paths.

[ronaldtse]

Vulnerability in the general sense because a change in that repo may affect the build, right. I assume we’re going to create the repo and submodule anyway so it will be at the right place.

[Intelligent2013]

Currently, the text Error: boilerplate text is empty. presents in the output adoc always when no text is provided in descriptions.xml. For instance iso-10303-srl\documents\modules\maths_value\sections\04-info_reqs.adoc:

[[maths_value_arm.maths_atom]]
===== maths_atom (((maths_atom,ARM object definition)))

A *maths_value* is a single Boolean, real integer or complex value.

Error: boilerplate text is empty.

[.underline]#EXPRESS specification:#

As noticed in https://github.com/metanorma/stepmod2mn/issues/105:

the stepmod2mn migration process triggers several errors. We need to fix ALL of them.

therefore I'll move the message Error: boilerplate text is empty. from the adoc to the console log.

To put the boilerplate:

1. We will encode the boilerplate text as liquid templates for adoc includes
2. We will use a git submodule to include boilerplate text inside iso-10303-stepmod

we need to pass the submodule's path into stepmod2mn via the command line parameter --boilerplatepath <path>, or I need to hardcode this path in the XSLT as static value.

[ronaldtse]

What is the boilerplate? What exactly is missing?

[Intelligent2013]

What is the boilerplate? What exactly is missing?

@ronaldtse

for example, let's take a look at the document iso-10303-stepmod-wg12\data\modules\shape_appearance_layers.

The output adoc iso-10303-srl\documents\modules\shape_appearance_layers\sections\04-info_reqs.adoc doesn't contain the description (after ===== title and before [.underline]#EXPRESS specification:#):

[[shape_appearance_layers_arm.sal_appearance_context]]
===== sal_appearance_context (((sal_appearance_context,ARM object definition)))

WE NEED DESCRIPTION (OR BOILERPLATE TEXT) HERE

[.underline]#EXPRESS specification:#

[source%unnumbered]
--
TYPE sal_appearance_context = SELECT BASED_ON appearance_contextWITH 
   (Geometric_model_relationship, 
    Group, 
    Layer);
END_TYPE;
--

The reason - in the 10303-stepmod-wg12\data\modules\shape_appearance_layers\arm_descriptions.xml:

<?xml version="1.0" encoding="utf-8"?>
...
<ext_descriptions module_directory="shape_appearance_layers" schema_file="arm.xml" rcs.date="$Date: 2009/12/03 13:09:58 $" rcs.revision="$Revision: 1.5 $">

  <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
   Schema: Shape_appearance_layers_arm 
  ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
   <ext_description linkend="Shape_appearance_layers_arm"/>

</ext_descriptions>

there isn't description like this:

<ext_description linkend="Shape_appearance_layers_arm.sal_appearance_context">
Description text...
</ext_description>

From the initial post:

The SC4 supplementary directives require descriptions for all declarations except CONSTANT and interfaces.

If no text is provided in descriptions.xml for SELECT and ENUMERATION types, the XSLT pastes boilerplate descriptions in the document.

The requirements: https://github.com/metanorma/iso-tc184-sc4-directives/blob/main/sources/supplementary-directives/document.adoc#components-of-a-clause-that-specifies-an-express-schema

https://github.com/metanorma/iso-tc184-sc4-directives/blob/main/sources/supplementary-directives/document.adoc#components-of-a-clause-that-specifies-an-express-schema

In the 2.5 years ago post https://github.com/metanorma/stepmod2mn/issues/10#issuecomment-778532763

@Intelligent2013 I've discussed with @opoudjis , we are envisioning that:

1. We will encode the boilerplate text as liquid templates for adoc includes
2. We will use a git submodule to include boilerplate text inside iso-10303-stepmod

Is there such submodule with boilerplate text as liquid templates?